Open Orchestrator maintains a status tracking system that monitors AI activity across all your worktrees, providing visibility into what each AI session is doing.

How Status Tracking Works

Status Store

AI status is persisted in ~/.open-orchestrator/status.db, a SQLite database. This file is the single source of truth for all worktree status information.

Concurrency (SQLite WAL)

The status database uses SQLite WAL (Write-Ahead Logging) mode for safe concurrent access. When multiple worktrees update their status simultaneously (which is common in parallel development), WAL mode enables concurrent reads and writes without corruption or race conditions.

This means:

• Multiple owt processes can safely read and write status concurrently
• No data loss when several AI agents update their status at the same time
• The Control Plane can read status while agents write to it
• A 5-second busy timeout prevents lock contention under heavy load
• Legacy ai_status.json files are automatically migrated to SQLite on first run

Status Values

Status	Symbol	Description
IDLE	○	AI is ready for new tasks
WORKING	●	AI is actively processing
BLOCKED	⚠	Waiting for input or clarification
WAITING	-	Paused, awaiting external dependency
COMPLETED	✓	Task finished successfully
ERROR	-	Something went wrong
UNKNOWN	?	Status cannot be determined

Data Model

Each worktree entry in the status store is a WorktreeAIStatus with the following fields:

Field	Type	Description
worktree_name	string	The worktree identifier
branch	string	Git branch name
status	enum	One of the status values above
ai_tool	string	Which AI tool is running (claude, pi, opencode, droid)
task	string	Current task description
last_active	timestamp	When the status was last updated

Database Schema

The status database (~/.open-orchestrator/status.db) contains three tables:

Table	Purpose
worktree_status	Per-worktree AI status (name, branch, status, ai_tool, task, last_active)
shared_notes	Cross-worktree notes created with owt note
metadata	Key-value store for schema version, migration tracking, and DAG progress

The worktree_status table stores the same fields as the data model above: worktree_name, branch, status, ai_tool, task, and last_active.

Viewing Status

Control Plane

The primary way to view status is through the Control Plane:

owt

The Control Plane groups worktrees into prioritized sections (NEEDS YOU / READY TO SHIP / IN FLIGHT), each row showing its status, branch, AI tool, and current task. See The Control Plane for details.

List Command

For a quick text-based view:

owt list

Push-Based Status Detection (Hooks)

For Claude Code and Droid, Open Orchestrator installs lifecycle hooks into each worktree that push real-time status updates. This replaces fragile tmux pane scraping with direct event-driven detection.

Pane-Based Detection (Fallback)

For tools without hook support (Pi and OpenCode), status is detected by reading the tmux pane content. The detector recognizes:

• Known prompt patterns — regex-matched prompt indicators (no length limit)
• Shell prompt endings — common shell suffixes ($, %, #, ❯, ➜, >) indicate the agent has exited or is idle
• Tool activity headers — detects active tool use in recent pane output to avoid false idle detection

How Hooks Work

When owt new creates a worktree, hooks are installed into the worktree's local settings file:

• Claude Code: .claude/settings.local.json
• Droid: .factory/settings.json

Three hooks cover the full agent lifecycle:

Hook Event	Status Set	Meaning
UserPromptSubmit	WORKING	User sent a prompt, agent starts processing
Stop	WAITING	Agent finished, waiting for next input
Notification (permission_prompt)	BLOCKED	Agent needs permission approval

Hooks call owt hook --event <status> --worktree <name> which writes directly to the status file. The Control Plane trusts hook-set status when fresh (under 10 seconds) and falls back to pane scraping for tools without hook support (Pi and OpenCode).

Per-Worktree Isolation

Hooks are installed in the worktree's local settings, not the global config. This means:

• Only OWT-managed sessions report status
• Your global Claude Code / Droid config remains untouched
• Hooks are cleaned up when the worktree is deleted

Status Lifecycle

A typical status lifecycle for a worktree:

IDLE → WORKING → COMPLETED
         │
         ├── BLOCKED (waiting for input) → WORKING → COMPLETED
         │
         └── ERROR (something failed)

1. IDLE -- Worktree is created, AI tool is started but no task given
2. WORKING -- AI is actively processing a task
3. BLOCKED -- AI needs input or clarification from the developer
4. COMPLETED -- Task finished successfully
5. ERROR -- Something went wrong during execution
6. UNKNOWN -- Status file exists but cannot determine actual state

Concurrency Safety

The status tracking system is designed for concurrent access:

• SQLite WAL mode enables concurrent reads and writes between multiple owt processes
• Atomic updates ensure the status file is never in a partially-written state
• Read-after-write consistency guarantees that reading status immediately after updating it returns the new value
• The Control Plane reads status on a refresh cycle without blocking writers

Best Practices

1. Use Descriptive Tasks

When sending commands, be descriptive:

# Good -- clear and informative
owt send feat/auth "Implement JWT authentication with refresh tokens"

# Less informative
owt send feat/auth "do auth"

2. Use the Control Plane for Monitoring

During parallel development, keep the Control Plane open to monitor all agents:

owt

3. Check Status Before Patching In

Look at the status light on a card before patching in:

• ● WORKING -- AI is busy, you may want to wait
• ○ IDLE or ✓ COMPLETED -- safe to review
• ⚠ BLOCKED -- AI needs your input

Troubleshooting

Status Not Updating

1. Check the status database exists:

   ls -la ~/.open-orchestrator/status.db

2. Verify worktrees are tracked:

   owt list

Stale Status Data

If a worktree shows an incorrect status (e.g., WORKING when the AI has finished), the status will update on the next activity in that worktree.

Next Steps

• Learn about the Control Plane
• Explore Parallel Features Workflow
• Configure worktree settings