AI导哈

终端清理规则集

auto-kill-terminal 是一套面向 AI 编程代理的终端管理规则集，通过强制使用后台终端、任务完成后立即关闭以及重建无响应终端等策略，防止 GitHub Codespaces 和 VS Code 中出现僵尸终端并减少命令超时重试。

  • by nirholas
  • Shell
  • 本地部署
  • 22 星标
  • 更新于
在 GitHub 查看 nirholas/auto-kill-terminal

使用说明

   █████╗ ██╗   ██╗████████╗ ██████╗       ██╗  ██╗██╗██╗     ██╗     
  ██╔══██╗██║   ██║╚══██╔══╝██╔═══██╗      ██║ ██╔╝██║██║     ██║     
  ███████║██║   ██║   ██║   ██║   ██║█████╗█████╔╝ ██║██║     ██║     
  ██╔══██║██║   ██║   ██║   ██║   ██║╚════╝██╔═██╗ ██║██║     ██║     
  ██║  ██║╚██████╔╝   ██║   ╚██████╔╝      ██║  ██╗██║███████╗███████╗
  ╚═╝  ╚═╝ ╚═════╝    ╚═╝    ╚═════╝       ╚═╝  ╚═╝╚═╝╚══════╝╚══════╝
                    ████████╗███████╗██████╗ ███╗   ███╗██╗███╗   ██╗ █████╗ ██╗     
                    ╚══██╔══╝██╔════╝██╔══██╗████╗ ████║██║████╗  ██║██╔══██╗██║     
                       ██║   █████╗  ██████╔╝██╔████╔██║██║██╔██╗ ██║███████║██║     
                       ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║██║██║╚██╗██║██╔══██║██║     
                       ██║   ███████╗██║  ██║██║ ╚═╝ ██║██║██║ ╚████║██║  ██║███████╗
                       ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝

💀 Stop AI agents from leaving zombie terminals in your Codespace




Problem · Fix · Quick Start · Setup · How it Works · FAQ


The Problem

AI coding agents (GitHub Copilot, Claude Code, Gemini, Cursor, etc.) spawn terminal sessions every time they run a command. They almost never clean up after themselves.

In GitHub Codespaces, this is catastrophic:

Symptom Cause
🧟 Ghost terminals Foreground terminals get reused — stale sessions persist and silently block new ones
👻 Invisible accumulation Background terminals in Codespaces aren't shown in the UI panel
🔄 Infinite retries Agents hammer the same dead session instead of killing it and starting fresh
🆔 Lost terminal IDs Without isBackground: true, no terminal ID is returned — cleanup is impossible

The result: your Codespace fills with orphaned terminals → commands timeout → the agent gets confused → you waste tokens on retries.

The Fix

Add terminal management rules to your agent instruction files. These five bullet points are all you need:

## Terminal Management

- **Always use background terminals** (`isBackground: true`) for every command so a terminal ID is returned
- **Always kill the terminal** after the command completes, whether it succeeds or fails — never leave terminals open
- Do not reuse foreground shell sessions — stale sessions block future terminal operations in Codespaces
- In GitHub Codespaces, agent-spawned terminals may be hidden — they still work. Do not assume a terminal is broken if you cannot see it
- If a terminal appears unresponsive, kill it and create a new one rather than retrying in the same terminal

That's it. Copy those 5 lines into whatever agent instruction file you use.

Quick Start

# Option 1: Clone and copy what you need
git clone https://github.com/nirholas/auto-kill-terminal.git
cp auto-kill-terminal/.github/copilot-instructions.md your-project/.github/

# Option 2: Just copy the 5 bullet points from "The Fix" into your existing instruction file

Setup by Agent

🤖 GitHub Copilot — copilot-instructions.md 
## Terminal Management
- **Always use background terminals** (`isBackground: true`) for every command so a terminal ID is returned
- **Always kill the terminal** after the command completes, whether it succeeds or fails — never leave terminals open
- Do not reuse foreground shell sessions — stale sessions block future terminal operations in Codespaces
- In GitHub Codespaces, agent-spawned terminals may be hidden — they still work. Do not assume a terminal is broken if you cannot see it
- If a terminal appears unresponsive, kill it and create a new one rather than retrying in the same terminal
🧠 Claude Code — CLAUDE.md 
### Terminal Management
- **Always use background terminals** (`isBackground: true`) for every command so a terminal ID is returned
- **Always kill the terminal** after the command completes, whether it succeeds or fails — never leave terminals open
- Do not reuse foreground shell sessions — stale sessions block future terminal operations in Codespaces
- In GitHub Codespaces, agent-spawned terminals may be hidden — they still work. Do not assume a terminal is broken if you cannot see it
- If a terminal appears unresponsive, kill it and create a new one rather than retrying in the same terminal
💎 Gemini — GEMINI.md 
### Terminal Management
- **Always use background terminals** (`isBackground: true`) for every command so a terminal ID is returned
- **Always kill the terminal** after the command completes, whether it succeeds or fails — never leave terminals open
- Do not reuse foreground shell sessions — stale sessions block future terminal operations in Codespaces
- In GitHub Codespaces, agent-spawned terminals may be hidden — they still work. Do not assume a terminal is broken if you cannot see it
- If a terminal appears unresponsive, kill it and create a new one rather than retrying in the same terminal
🔮 Cursor / AGENTS.md — Multi-agent projects 
### Terminal Management
- **Always use background terminals** (`isBackground: true`) for every command so a terminal ID is returned
- **Always kill the terminal** after the command completes, whether it succeeds or fails — never leave terminals open
- Do not reuse foreground shell sessions — stale sessions block future terminal operations in Codespaces
- In GitHub Codespaces, agent-spawned terminals may be hidden — they still work. Do not assume a terminal is broken if you cannot see it
- If a terminal appears unresponsive, kill it and create a new one rather than retrying in the same terminal
⚡ One-liners — For inline prompt space

Short:

**Terminal rules:** Always use `isBackground: true` for every terminal command, then kill the terminal after.

Two-line:

**Terminal management**: Always use background terminals (`isBackground: true`). Always kill terminals after use.

Why Background Terminals?

Approach Terminal ID returned? Can be killed? Blocks shell?
isBackground: false ❌ ❌ ✅
isBackground: true ✅ ✅ (kill_terminal) ❌

Background terminals return an ID that the agent can pass to kill_terminal (or await_terminal → kill_terminal). Without that ID, there's no way to clean up.

  Agent                                Terminal
    |                                      |
    |-- run_in_terminal -----------------> | (isBackground: true)
    |   <-- terminal_id: a7b3c9d1          |
    |                                      |
    |-- await_terminal ------------------> | (wait for completion)
    |   <-- output + exit code             |
    |                                      |
    |-- kill_terminal -------------------> | x_x
    |                                      X
    |
    |-- (clean slate for next command)

Supported Environments

Environment Status
GitHub Codespaces ✅
VS Code (local) ✅
VS Code (remote SSH) ✅
VS Code (WSL) ✅
Any VS Code terminal API consumer ✅

Supported Agents

Agent Instruction File Status
GitHub Copilot copilot-instructions.md ✅
Claude Code CLAUDE.md ✅
Gemini GEMINI.md ✅
Cursor AGENTS.md / .cursorrules ✅
Windsurf AGENTS.md ✅
Aider .aider.conf.yml ✅
Any agent using VS Code terminals Any instruction file ✅

FAQ

Do I need to install anything?

No. This is just copy-paste text that goes into your agent instruction files. No packages, no extensions, no config.

Does this work outside Codespaces?

Yes. The terminal management rules work anywhere VS Code's terminal API is used. They're most critical in Codespaces because ghost terminals are invisible there, but they help everywhere.

What if my agent doesn't support instruction files?

You can include the rules in your prompt directly. Use the one-liner from the "One-liners" section above.

Will this break my agent's workflow?

No. Background terminals with isBackground: true behave the same as foreground terminals, except they don't block the shell and they return an ID for cleanup. The agent's commands still execute normally.

Contributing

Contributions are welcome! If you've found terminal management tricks for other agents or environments, please open a PR.

  1. Fork the repo
  2. Create your branch: git checkout -b feat/my-improvement
  3. Commit: git commit -m "✨ feat: add support for X agent"
  4. Push: git push origin feat/my-improvement
  5. Open a Pull Request

License

All rights reserved. See LICENSE.

Documentation

Full documentation site: https://nirholas.github.io/auto-kill-terminal/

Star History

Support the project

If auto-kill-terminal saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/auto-kill-terminal and it has the context it needs.

More from the same author

Contributors

相关 MCP