Auto Kill Terminal

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

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:

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

## 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

### 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

### 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

### 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

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?

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

FAQ

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

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.

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

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.