Programmatic CLI

Overview

tmux-ide provides a programmatic CLI designed for automation and Claude Code integration. Every command supports --json for structured output, and mutation commands let you build and modify configs without editing YAML directly.

JSON Output

Add --json to any command for structured output:

tmux-ide status --json
tmux-ide inspect --json
tmux-ide validate --json
tmux-ide detect --json
tmux-ide config --json
tmux-ide ls --json
tmux-ide doctor --json

Config Mutations

Set a value by dot path

tmux-ide config set name "my-app"
tmux-ide config set rows.0.size "70%"
tmux-ide config set rows.1.panes.0.command "npm run dev"
tmux-ide config set rows.0.panes.1.title "Claude 2 — review"

Add a pane

tmux-ide config add-pane --row 1 --title "Tests" --command "pnpm test"
tmux-ide config add-pane --row 0 --title "Claude 3" --command "claude"

Remove a pane

tmux-ide config remove-pane --row 1 --pane 2

Add a row

tmux-ide config add-row --size "30%"

Claude Code Integration

Setup workflow

The recommended flow for setting up tmux-ide in a new project:

Detect the project stack:
```
tmux-ide detect --json
```
Use the returned detected.reasons array to explain the recommendation before writing config.

Present layout options with ASCII diagrams. Before writing any config, show the user 2-3 layout options visually so they can pick or tweak:

Option A — Dual Claude + Dev

┌─────────────────┬─────────────────┐
│                 │                 │
│    Claude 1     │    Claude 2     │  70%
│                 │                 │
├────────┬────────┴────────┬────────┤
│Dev Srv │  Tests  │ Shell │        │  30%
└────────┴─────────┴───────┘────────┘

Option B — Triple Claude

┌───────────┬───────────┬───────────┐
│           │           │           │
│ Claude 1  │ Claude 2  │ Claude 3  │  70%
│           │           │           │
├───────────┴─────┬─────┴───────────┤
│    Dev Server    │     Shell       │  30%
└─────────────────┴─────────────────┘

Adapt pane names and commands to the detected stack (e.g., pnpm dev, cargo watch, go run).

Write the chosen config:
```
tmux-ide detect --write
```

Validate and launch:

tmux-ide validate --json
tmux-ide              # first launch
tmux-ide restart      # or restart to apply config changes

Custom config workflow

Build a config from scratch without touching YAML:

# Start with detection to get a base
tmux-ide detect --write

# Or build manually
tmux-ide config add-row --size "70%"
tmux-ide config add-pane --row 0 --title "Claude 1" --command "claude"
tmux-ide config add-pane --row 0 --title "Claude 2" --command "claude"
tmux-ide config add-row
tmux-ide config add-pane --row 1 --title "Dev" --command "pnpm dev"
tmux-ide config add-pane --row 1 --title "Shell"
tmux-ide config set name "my-project"
tmux-ide validate --json

Modification workflow

Modify an existing config:

# 1. Read current state
tmux-ide inspect --json

# 2. Make changes
tmux-ide config set rows.1.panes.0.command "bun dev"
tmux-ide config add-pane --row 1 --title "Tests" --command "bun test"

# 3. Validate
tmux-ide validate --json

Agent Teams workflow

Set up coordinated Claude Code instances:

# 1. Start with an existing config
tmux-ide config --json

# 2. Enable agent teams
tmux-ide config enable-team --name "my-team"

# 3. Assign tasks to teammates
tmux-ide config set rows.0.panes.1.task "Work on frontend components"
tmux-ide config set rows.0.panes.2.task "Work on API routes"

# 4. Validate and launch
tmux-ide validate --json
tmux-ide
tmux-ide restart      # or restart to apply config changes

The team lead can also reconfigure from within its session — see Agent Teams.

Missions API

Mission workflows are available programmatically from both the CLI and the Command Center.

Create a mission

Use the CLI to create a mission in planning state:

tmux-ide mission create "Ship auth v2" -d "JWT login, refresh, validation, and metrics"

Mission status

tmux-ide mission status --json

Command Center:

GET /api/project/:name/mission

Returns the mission plus a validation summary.

Mark planning complete

tmux-ide mission plan-complete --json

Command Center:

POST /api/project/:name/mission/plan-complete

This switches the mission from planning to active and activates the earliest milestone.

Milestone API

tmux-ide milestone create "Foundation" --sequence 1 --json
tmux-ide milestone list --json
tmux-ide milestone show M1 --json
tmux-ide milestone update M1 --status done --json

Command Center:

GET  /api/project/:name/milestones
GET  /api/project/:name/milestones/:id
POST /api/project/:name/milestones
POST /api/project/:name/milestones/:id

Validation API

tmux-ide validate show --json
tmux-ide validate assert VAL-AUTH-001 --status passing --evidence "API test passed" --json
tmux-ide validate report --json
tmux-ide validate coverage --json

Command Center:

GET  /api/project/:name/validation
GET  /api/project/:name/validation/coverage
POST /api/project/:name/validation/assert/:assertId

Skills API

tmux-ide skill list --json
tmux-ide skill show frontend --json
tmux-ide skill validate --json

Command Center:

GET /api/project/:name/skills
GET /api/project/:name/skills/:skillName

Metrics API

tmux-ide metrics --json
tmux-ide metrics agents --json
tmux-ide metrics timeline --json
tmux-ide metrics eval --json
tmux-ide metrics history --json

Command Center:

GET /api/project/:name/metrics
GET /api/project/:name/metrics/agents
GET /api/project/:name/metrics/timeline
GET /api/project/:name/metrics/history

Research API

tmux-ide research status --json
tmux-ide research trigger periodic --json

Command Center:

GET  /api/project/:name/research
POST /api/project/:name/research/trigger

The researcher can be triggered manually for mission_start, milestone_complete, periodic, retry_cluster, or other configured trigger names.

Best Practices

Always use --json for programmatic access — human output may change between versions
Prefer inspect --json when you need both config validity and runtime state
Always validate after mutations — tmux-ide validate --json catches errors before launch
Top row ~70% for Claude panes — gives editors enough space
2-3 Claude panes in the top row for parallel work (feature, review, explore)
Dev servers + shell in the bottom row
Use detect --json first to understand the project stack before suggesting a config
Use mission create + plan-complete when automating v2.0 mission startup
Pair validate coverage with planning so every assertion is claimed before execution
Use metrics + research endpoints together when building monitoring or dashboards

On this page