Torna alle skill
auto-kill-terminal
di nirholas
WindsurfโNon ancora valutato
La tua valutazione
Sintesi
๐คฏ Stop AI agents from leaving zombie terminals in GitHub Codespaces & 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.
Descrizione
<div align="center">
```
โโโโโโ โโโ โโโโโโโโโโโโ โโโโโโโ โโโ โโโโโโโโโ โโโ
โโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโ โโโ โโโโโโโโโโ โโโ
โโโโโโโโโโโ โโโ โโโ โโโ โโโโโโโโโโโโโโโโ โโโโโโ โโโ
โโโโโโโโโโโ โโโ โโโ โโโ โโโโโโโโโโโโโโโโ โโโโโโ โโโ
โโโ โโโโโโโโโโโโ โโโ โโโโโโโโโ โโโ โโโโโโโโโโโโโโโโโโโโโโ
โโโ โโโ โโโโโโโ โโโ โโโโโโโ โโโ โโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโโโโโโ โโโโ โโโโโโโโโโโ โโโ โโโโโโ โโโ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโ โโโโโโโโโโโโโโ
โโโ โโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโ
โโโ โโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโ โโโโโโโโโโโ โโโโโโ โโโ โโโโโโโโโ โโโโโโโโโ โโโโโโโโโโโ
โโโ โโโโโโโโโโโ โโโโโโ โโโโโโโโโ โโโโโโโโ โโโโโโโโโโโ
```
<h3>๐ Stop AI agents from leaving zombie terminals in your Codespace</h3>
<br>
<a href="https://github.com/nirholas/auto-kill-terminal/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge&labelColor=000" alt="MIT License" /></a>
<a href="https://github.com/nirholas/auto-kill-terminal/stargazers"><img src="https://img.shields.io/github/stars/nirholas/auto-kill-terminal?style=for-the-badge&logo=github&color=yellow&labelColor=000" alt="Stars" /></a>
<a href="https://github.com/nirholas/auto-kill-terminal/network/members"><img src="https://img.shields.io/github/forks/nirholas/auto-kill-terminal?style=for-the-badge&logo=github&color=purple&labelColor=000" alt="Forks" /></a>
<a href="#supported-agents"><img src="https://img.shields.io/badge/agents-Copilot%20ยท%20Claude%20ยท%20Gemini%20ยท%20Cursor-brightgreen?style=for-the-badge&labelColor=000" alt="Supported Agents" /></a>
<a href="https://github.com/nirholas/auto-kill-terminal/issues"><img src="https://img.shields.io/github/issues/nirholas/auto-kill-terminal?style=for-the-badge&labelColor=000" alt="Issues" /></a>
<a href="https://github.com/nirholas/auto-kill-terminal"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge&labelColor=000" alt="PRs Welcome" /></a>
<br><br>
<a href="#the-problem">Problem</a> ยท
<a href="#the-fix">Fix</a> ยท
<a href="#quick-start">Quick Start</a> ยท
<a href="#setup-by-agent">Setup</a> ยท
<a href="#why-background-terminals">How it Works</a> ยท
<a href="#faq">FAQ</a>
<br>
<img src=".github/demo.svg" alt="auto-kill-terminal demo" width="800" />
</div>
---
## 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:
```markdown
## 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
```bash
# 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
<details>
<summary><b>๐ค GitHub Copilot</b> โ <code>copilot-instructions.md</code></summary>
```markdown
## 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
```
</details>
<details>
<summary><b>๐ง Claude Code</b> โ <code>CLAUDE.md</code></summary>
```markdown
### 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
```
</details>
<details>
<summary><b>๐ Gemini</b> โ <code>GEMINI.md</code></summary>
```markdown
### 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
```
</details>
<details>
<summary><b>๐ฎ Cursor / AGENTS.md</b> โ Multi-agent projects</summary>
```markdown
### 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
```
</details>
<details>
<summary><b>โก One-liners</b> โ For inline prompt space</summary>
Short:
```markdown
**Terminal rules:** Always use `isBackground: true` for every terminal command, then kill the terminal after.
```
Two-line:
```markdown
**Terminal management**: Always use background terminals (`isBackground: true`). Always kill terminals after use.
```
</details>
## 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 | โ
|
<h2 id="supported-agents">Supported Agents</h2>
| 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
<details>
<summary><b>Do I need to install anything?</b></summary>
No. This is just copy-paste text that goes into your agent instruction files. No packages, no extensions, no config.
</details>
<details>
<summary><b>Does this work outside Codespaces?</b></summary>
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.
</details>
<details>
<summary><b>What if my agent doesn't support instruction files?</b></summary>
You can include the rules in your prompt directly. Use the one-liner from the "One-liners" section above.
</details>
<details>
<summary><b>Will this break my agent's workflow?</b></summary>
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.
</details>
## 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
MIT ยฉ [nirholas](https://github.com/nirholas)
---
<p align="center">
<b>Stop wasting tokens on zombie terminals.</b><br>
<sub>Made with ๐ for the AI agent community</sub>
</p>
<p align="center">
<br>
โญ <b>Found this useful? Star the repo!</b> โญ<br>
<sub>It helps others discover this project and keeps development active</sub><br><br>
<a href="https://github.com/nirholas/auto-kill-terminal/stargazers">
<img src="https://img.shields.io/github/stars/nirholas/auto-kill-terminal?style=social" alt="Star on GitHub">
</a>
</p>
<p align="center">
<a href="https://star-history.com/#nirholas/auto-kill-terminal&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nirholas/auto-kill-terminal&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nirholas/auto-kill-terminal&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=nirholas/auto-kill-terminal&type=Date" width="600" />
</picture>
</a>
</p>
Installazione
Installa la skill da https://github.com/nirholas/auto-kill-terminalQuesta skill non รจ pubblicata sul registro ClawHub. Incolla il prompt nel tuo agente di coding โ Claude Code, Cursor, Codex โ e installerร la skill direttamente dal repository sorgente.
Apri il repository