claude-term

claude-term — Persistent Terminals

Use claude-term when you need a terminal that persists beyond a single command — long-running processes, interactive tools, or terminals you want to check back on later.

When to Use

• Use claude-term for: servers, watchers, builds, REPLs, SSH sessions, anything long-running or interactive
• Use the Bash tool for: quick one-shot commands (ls, git status, grep)

Quick Reference

# Spawn a terminal (returns term_id)
claude-term spawn --cwd /path/to/project

# Spawn with a specific command
claude-term spawn bash -c "npm run dev"

# List your terminals
claude-term list

# Run a command in a terminal
claude-term write t1 "npm test\n"

# Check output
claude-term read t1

# Kill when done
claude-term kill t1

Workflow Example

# 1. Start a dev server
TERM_ID=$(claude-term spawn --cwd ~/projects/myapp bash -c "npm run dev")

# 2. Wait for it to start, then check output
sleep 2
claude-term read "$TERM_ID"

# 3. Run tests in another terminal
TEST_ID=$(claude-term spawn --cwd ~/projects/myapp bash -c "npm test")

# 4. Check test results
sleep 5
claude-term read "$TEST_ID"

# 5. Clean up
claude-term kill "$TERM_ID"
claude-term kill "$TEST_ID"

Owner Tracking

Terminal ownership is automatic. When you spawn a terminal, it's automatically associated with your session. claude-term list shows only your terminals by default. Use claude-term list --all to see all terminals.

Terminal Lifecycle

Terminals persist until explicitly killed or inactive for 24 hours (no reads, no writes, no output). They survive session disconnects and restarts.

Collaborating with the User

When you're doing work in a persistent terminal and want the user to see or interact with it, tell them to attach:

claude-term attach t1

This gives them a live, bidirectional view of the terminal — they see exactly what you see, and can type into it. Ctrl+] detaches without killing the terminal.

Common collaboration patterns:

• You start a dev server → user attaches to see logs and interact
• You run a debugging session → user attaches to inspect state
• You set up a REPL → user attaches to explore interactively

Notes:

• Multiple clients can attach simultaneously (read-only broadcast, last writer wins)
• Attach works best from a real terminal (Terminal.app, iTerm). In nested terminals (e.g., Open Cockpit tabs), it works but the output may render differently.
• The remote terminal auto-resizes to match the attaching terminal