{"id":51880566,"url":"https://github.com/nirholas/auto-kill-terminal","last_synced_at":"2026-07-25T12:04:07.494Z","repository":{"id":337265090,"uuid":"1152899592","full_name":"nirholas/auto-kill-terminal","owner":"nirholas","description":"🤯  Stop AI agents from leaving zombie terminals in GitHub Codespaces \u0026 VS Code. Copy-paste terminal management rules for Copilot, Claude, Gemini, Cursor, Windsurf, Cline, Aider. Fix \"terminal unresponsive\" errors, agent refusing to run commands, isBackground true, kill_terminal. Install script + dev container + templates.","archived":false,"fork":false,"pushed_at":"2026-02-08T16:45:27.000Z","size":82,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-08T22:26:27.562Z","etag":null,"topics":["agent-instructions","ai-agent","chatgpt","claude","codespaces","copilot","cursor","devcontainer","developer-tools","dx","gemini","git","github","grok","mcp","terminal","tips-and-tricks","vscode","windsurf","zombie-terminal"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nirholas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["nirholas"]}},"created_at":"2026-02-08T15:57:59.000Z","updated_at":"2026-02-08T19:19:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nirholas/auto-kill-terminal","commit_stats":null,"previous_names":["nirholas/auto-kill-terminal"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/nirholas/auto-kill-terminal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nirholas%2Fauto-kill-terminal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nirholas%2Fauto-kill-terminal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nirholas%2Fauto-kill-terminal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nirholas%2Fauto-kill-terminal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nirholas","download_url":"https://codeload.github.com/nirholas/auto-kill-terminal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nirholas%2Fauto-kill-terminal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35878279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-25T02:00:06.922Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-instructions","ai-agent","chatgpt","claude","codespaces","copilot","cursor","devcontainer","developer-tools","dx","gemini","git","github","grok","mcp","terminal","tips-and-tricks","vscode","windsurf","zombie-terminal"],"created_at":"2026-07-25T12:04:06.425Z","updated_at":"2026-07-25T12:04:07.488Z","avatar_url":"https://github.com/nirholas.png","language":"Shell","funding_links":["https://github.com/sponsors/nirholas"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e \n\n```\n   █████╗ ██╗   ██╗████████╗ ██████╗       ██╗  ██╗██╗██╗     ██╗     \n  ██╔══██╗██║   ██║╚══██╔══╝██╔═══██╗      ██║ ██╔╝██║██║     ██║     \n  ███████║██║   ██║   ██║   ██║   ██║█████╗█████╔╝ ██║██║     ██║     \n  ██╔══██║██║   ██║   ██║   ██║   ██║╚════╝██╔═██╗ ██║██║     ██║     \n  ██║  ██║╚██████╔╝   ██║   ╚██████╔╝      ██║  ██╗██║███████╗███████╗\n  ╚═╝  ╚═╝ ╚═════╝    ╚═╝    ╚═════╝       ╚═╝  ╚═╝╚═╝╚══════╝╚══════╝\n                    ████████╗███████╗██████╗ ███╗   ███╗██╗███╗   ██╗ █████╗ ██╗     \n                    ╚══██╔══╝██╔════╝██╔══██╗████╗ ████║██║████╗  ██║██╔══██╗██║     \n                       ██║   █████╗  ██████╔╝██╔████╔██║██║██╔██╗ ██║███████║██║     \n                       ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║██║██║╚██╗██║██╔══██║██║     \n                       ██║   ███████╗██║  ██║██║ ╚═╝ ██║██║██║ ╚████║██║  ██║███████╗\n                       ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝\n```\n\n\u003ch3\u003e💀 Stop AI agents from leaving zombie terminals in your Codespace\u003c/h3\u003e\n\n\u003cbr\u003e\n\n\u003ca href=\"https://github.com/nirholas/auto-kill-terminal/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge\u0026labelColor=000\" alt=\"MIT License\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/nirholas/auto-kill-terminal/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/nirholas/auto-kill-terminal?style=for-the-badge\u0026logo=github\u0026color=yellow\u0026labelColor=000\" alt=\"Stars\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/nirholas/auto-kill-terminal/network/members\"\u003e\u003cimg src=\"https://img.shields.io/github/forks/nirholas/auto-kill-terminal?style=for-the-badge\u0026logo=github\u0026color=purple\u0026labelColor=000\" alt=\"Forks\" /\u003e\u003c/a\u003e\n\u003ca href=\"#supported-agents\"\u003e\u003cimg src=\"https://img.shields.io/badge/agents-Copilot%20·%20Claude%20·%20Gemini%20·%20Cursor-brightgreen?style=for-the-badge\u0026labelColor=000\" alt=\"Supported Agents\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/nirholas/auto-kill-terminal/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/nirholas/auto-kill-terminal?style=for-the-badge\u0026labelColor=000\" alt=\"Issues\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/nirholas/auto-kill-terminal\"\u003e\u003cimg src=\"https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge\u0026labelColor=000\" alt=\"PRs Welcome\" /\u003e\u003c/a\u003e\n\n\u003cbr\u003e\u003cbr\u003e\n\n\u003ca href=\"#the-problem\"\u003eProblem\u003c/a\u003e · \n\u003ca href=\"#the-fix\"\u003eFix\u003c/a\u003e · \n\u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e · \n\u003ca href=\"#setup-by-agent\"\u003eSetup\u003c/a\u003e · \n\u003ca href=\"#why-background-terminals\"\u003eHow it Works\u003c/a\u003e · \n\u003ca href=\"#faq\"\u003eFAQ\u003c/a\u003e\n\n\u003cbr\u003e\n\n\u003cimg src=\".github/demo.svg\" alt=\"auto-kill-terminal demo\" width=\"800\" /\u003e\n\n\u003c/div\u003e\n\n---\n\n## The Problem\n\nAI 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.**\n\nIn GitHub Codespaces, this is catastrophic:\n\n| Symptom | Cause |\n|---|---|\n| 🧟 **Ghost terminals** | Foreground terminals get reused — stale sessions persist and silently block new ones |\n| 👻 **Invisible accumulation** | Background terminals in Codespaces aren't shown in the UI panel |\n| 🔄 **Infinite retries** | Agents hammer the same dead session instead of killing it and starting fresh |\n| 🆔 **Lost terminal IDs** | Without `isBackground: true`, no terminal ID is returned — cleanup is impossible |\n\n**The result:** your Codespace fills with orphaned terminals → commands timeout → the agent gets confused → you waste tokens on retries.\n\n## The Fix\n\nAdd terminal management rules to your agent instruction files. These **five bullet points** are all you need:\n\n```markdown\n## Terminal Management\n\n- **Always use background terminals** (`isBackground: true`) for every command so a terminal ID is returned\n- **Always kill the terminal** after the command completes, whether it succeeds or fails — never leave terminals open\n- Do not reuse foreground shell sessions — stale sessions block future terminal operations in Codespaces\n- In GitHub Codespaces, agent-spawned terminals may be hidden — they still work. Do not assume a terminal is broken if you cannot see it\n- If a terminal appears unresponsive, kill it and create a new one rather than retrying in the same terminal\n```\n\n\u003e **That's it.** Copy those 5 lines into whatever agent instruction file you use.\n\n## Quick Start\n\n```bash\n# Option 1: Clone and copy what you need\ngit clone https://github.com/nirholas/auto-kill-terminal.git\ncp auto-kill-terminal/.github/copilot-instructions.md your-project/.github/\n\n# Option 2: Just copy the 5 bullet points from \"The Fix\" into your existing instruction file\n```\n\n## Setup by Agent\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🤖 GitHub Copilot\u003c/b\u003e — \u003ccode\u003ecopilot-instructions.md\u003c/code\u003e\u003c/summary\u003e\n\n```markdown\n## Terminal Management\n- **Always use background terminals** (`isBackground: true`) for every command so a terminal ID is returned\n- **Always kill the terminal** after the command completes, whether it succeeds or fails — never leave terminals open\n- Do not reuse foreground shell sessions — stale sessions block future terminal operations in Codespaces\n- In GitHub Codespaces, agent-spawned terminals may be hidden — they still work. Do not assume a terminal is broken if you cannot see it\n- If a terminal appears unresponsive, kill it and create a new one rather than retrying in the same terminal\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🧠 Claude Code\u003c/b\u003e — \u003ccode\u003eCLAUDE.md\u003c/code\u003e\u003c/summary\u003e\n\n```markdown\n### Terminal Management\n- **Always use background terminals** (`isBackground: true`) for every command so a terminal ID is returned\n- **Always kill the terminal** after the command completes, whether it succeeds or fails — never leave terminals open\n- Do not reuse foreground shell sessions — stale sessions block future terminal operations in Codespaces\n- In GitHub Codespaces, agent-spawned terminals may be hidden — they still work. Do not assume a terminal is broken if you cannot see it\n- If a terminal appears unresponsive, kill it and create a new one rather than retrying in the same terminal\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e💎 Gemini\u003c/b\u003e — \u003ccode\u003eGEMINI.md\u003c/code\u003e\u003c/summary\u003e\n\n```markdown\n### Terminal Management\n- **Always use background terminals** (`isBackground: true`) for every command so a terminal ID is returned\n- **Always kill the terminal** after the command completes, whether it succeeds or fails — never leave terminals open\n- Do not reuse foreground shell sessions — stale sessions block future terminal operations in Codespaces\n- In GitHub Codespaces, agent-spawned terminals may be hidden — they still work. Do not assume a terminal is broken if you cannot see it\n- If a terminal appears unresponsive, kill it and create a new one rather than retrying in the same terminal\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔮 Cursor / AGENTS.md\u003c/b\u003e — Multi-agent projects\u003c/summary\u003e\n\n```markdown\n### Terminal Management\n- **Always use background terminals** (`isBackground: true`) for every command so a terminal ID is returned\n- **Always kill the terminal** after the command completes, whether it succeeds or fails — never leave terminals open\n- Do not reuse foreground shell sessions — stale sessions block future terminal operations in Codespaces\n- In GitHub Codespaces, agent-spawned terminals may be hidden — they still work. Do not assume a terminal is broken if you cannot see it\n- If a terminal appears unresponsive, kill it and create a new one rather than retrying in the same terminal\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e⚡ One-liners\u003c/b\u003e — For inline prompt space\u003c/summary\u003e\n\nShort:\n```markdown\n**Terminal rules:** Always use `isBackground: true` for every terminal command, then kill the terminal after.\n```\n\nTwo-line:\n```markdown\n**Terminal management**: Always use background terminals (`isBackground: true`). Always kill terminals after use.\n```\n\n\u003c/details\u003e\n\n## Why Background Terminals?\n\n| Approach | Terminal ID returned? | Can be killed? | Blocks shell? |\n|---|:---:|:---:|:---:|\n| `isBackground: false` | ❌ | ❌ | ✅ |\n| `isBackground: true` | ✅ | ✅ (`kill_terminal`) | ❌ |\n\nBackground 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.\n\n```\n  Agent                                Terminal\n    |                                      |\n    |-- run_in_terminal -----------------\u003e | (isBackground: true)\n    |   \u003c-- terminal_id: a7b3c9d1          |\n    |                                      |\n    |-- await_terminal ------------------\u003e | (wait for completion)\n    |   \u003c-- output + exit code             |\n    |                                      |\n    |-- kill_terminal -------------------\u003e | x_x\n    |                                      X\n    |\n    |-- (clean slate for next command)\n```\n\n## Supported Environments\n\n| Environment | Status |\n|---|:---:|\n| GitHub Codespaces | ✅ |\n| VS Code (local) | ✅ |\n| VS Code (remote SSH) | ✅ |\n| VS Code (WSL) | ✅ |\n| Any VS Code terminal API consumer | ✅ |\n\n\u003ch2 id=\"supported-agents\"\u003eSupported Agents\u003c/h2\u003e\n\n| Agent | Instruction File | Status |\n|---|---|:---:|\n| GitHub Copilot | `copilot-instructions.md` | ✅ |\n| Claude Code | `CLAUDE.md` | ✅ |\n| Gemini | `GEMINI.md` | ✅ |\n| Cursor | `AGENTS.md` / `.cursorrules` | ✅ |\n| Windsurf | `AGENTS.md` | ✅ |\n| Aider | `.aider.conf.yml` | ✅ |\n| Any agent using VS Code terminals | Any instruction file | ✅ |\n\n## FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDo I need to install anything?\u003c/b\u003e\u003c/summary\u003e\n\nNo. This is just copy-paste text that goes into your agent instruction files. No packages, no extensions, no config.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDoes this work outside Codespaces?\u003c/b\u003e\u003c/summary\u003e\n\nYes. 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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWhat if my agent doesn't support instruction files?\u003c/b\u003e\u003c/summary\u003e\n\nYou can include the rules in your prompt directly. Use the one-liner from the \"One-liners\" section above.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWill this break my agent's workflow?\u003c/b\u003e\u003c/summary\u003e\n\nNo. 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.\n\n\u003c/details\u003e\n\n## Contributing\n\nContributions are welcome! If you've found terminal management tricks for other agents or environments, please open a PR.\n\n1. Fork the repo\n2. Create your branch: `git checkout -b feat/my-improvement`\n3. Commit: `git commit -m \"✨ feat: add support for X agent\"`\n4. Push: `git push origin feat/my-improvement`\n5. Open a Pull Request\n\n## License\n\nAll rights reserved. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnirholas%2Fauto-kill-terminal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnirholas%2Fauto-kill-terminal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnirholas%2Fauto-kill-terminal/lists"}