How to Kill an OpenClaude Background Session: CLI and Manual Methods

Use the claude kill <session-id> command to terminate an OpenClaude background session safely, or run tmux kill-session -t claude-bg-<id> as a low-level fallback when the CLI registry is inaccessible.

OpenClaude, maintained in the Gitlawb/openclaude repository, executes long-running tasks in detached background sessions backed by tmux. When you need to stop a running job, properly killing an OpenClaude background session ensures the underlying tmux process terminates cleanly and the internal JSON registry stays synchronized.

Understanding OpenClaude Background Sessions

Every background session is a persistent tmux session managed through a centralized registry. The CLI tracks active sessions in [src/cli/bgRegistry.ts](https://github.com/Gitlawb/openclaude/blob/main/src/cli/bgRegistry.ts), which maintains a JSON file mapping session IDs to metadata including status ("running", "completed", or "killed"). When you initiate a kill command, the system updates this registry before terminating the actual tmux process.

The tmux sessions themselves are created with a standardized naming convention (claude-bg-<session-id>) defined in [src/utils/tmuxSocket.ts](https://github.com/Gitlawb/openclaude/blob/main/src/utils/tmuxSocket.ts), allowing both the CLI and manual tmux commands to target the correct process.

Listing Active Background Sessions

Before terminating a session, identify its ID using the built-in process status command:

claude ps

This queries the registry and outputs a table showing session IDs, titles, and current status. Note the ID of the session you wish to terminate for use in the kill command.

Killing a Session via the CLI

The recommended method uses the CLI's managed kill command, which handles both registry updates and tmux termination:

# Kill session with ID 42

claude kill 42

Upon execution, the command defined in [src/cli/bg.ts](https://github.com/Gitlawb/openclaude/blob/main/src/cli/bg.ts) invokes bgRegistry.killSession(id), which updates the JSON entry status to "killed".

The Kill Mechanism Under the Hood

When you run claude kill <id>, the following sequence executes according to the source code:

1. Registry Update: The killSession method in [src/cli/bgRegistry.ts](https://github.com/Gitlawb/openclaude/blob/main/src/cli/bgRegistry.ts) locates the session entry and sets status: "killed".
2. Process Termination: The CLI calls sessionManager.killSession(id) from [src/server/sessionManager.ts](https://github.com/Gitlawb/openclaude/blob/main/src/server/sessionManager.ts), which destroys the tmux session.
3. Cleanup: The tmux socket helper in [src/utils/tmuxSocket.ts](https://github.com/Gitlawb/openclaude/blob/main/src/utils/tmuxSocket.ts) executes the underlying tmux kill-session command and removes any associated socket files.

This two-phase approach ensures the registry reflects the termination even if the tmux process was already stopped externally.

Manual Termination with tmux

If the CLI cannot access the registry (for example, due to file corruption or permission locks), terminate the session directly through tmux:

# List all OpenClaude tmux sessions

tmux ls | grep claude-bg-

# Kill a specific session by ID (e.g., session 42)

tmux kill-session -t claude-bg-42

After manual termination, the registry entry may still show "running" until you either delete the stale entry from ~/.config/openclaude/bg-registry.json or run claude ps --clean if implemented in your version.

Summary

• Primary method: Run claude kill <session-id> to update the registry in [src/cli/bgRegistry.ts](https://github.com/Gitlawb/openclaude/blob/main/src/cli/bgRegistry.ts) and terminate the tmux process.
• Underlying technology: Sessions are tmux instances prefixed with claude-bg- and managed through [src/utils/tmuxSocket.ts](https://github.com/Gitlawb/openclaude/blob/main/src/utils/tmuxSocket.ts).
• Fallback method: Use tmux kill-session -t claude-bg-<id> when the CLI registry is inaccessible.
• State tracking: The registry JSON maintains status fields ("killed", "completed", "running") to persist session history across CLI restarts.

Frequently Asked Questions

What happens to running code when I kill an OpenClaude background session?

The tmux session terminates immediately, sending SIGHUP to all processes running within that session. Any unsaved work in memory will be lost, though files already written to disk remain intact.

Can I resume a session after it has been killed?

No. Once a session status is marked "killed" in the registry or the tmux session is destroyed, that session ID cannot be reattached. You must start a new background session using claude --bg <command> to resume similar work.

Where does OpenClaude store the background session registry?

The registry is typically stored at ~/.config/openclaude/bg-registry.json. The [src/cli/bgRegistry.ts](https://github.com/Gitlawb/openclaude/blob/main/src/cli/bgRegistry.ts) module handles all reads and writes to this file, ensuring thread-safe updates when multiple sessions start or stop concurrently.

Why does claude kill fail while tmux kill-session succeeds?

If the registry file is locked, corrupted, or has incorrect permissions, the CLI cannot update the session status in [src/cli/bgRegistry.ts](https://github.com/Gitlawb/openclaude/blob/main/src/cli/bgRegistry.ts), causing the command to fail even though the tmux process is still accessible. Direct tmux commands bypass the registry entirely, making them reliable fallback options when the CLI state manager is compromised.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}