minchenlee/c9watch/c9watch-cli

c9watch CLI

c9watch is a CLI tool that lets you monitor and manage all Claude Code sessions running on the machine. Every command outputs JSON. Use it to see what other sessions are doing, search past work, track costs, and coordinate with sibling agents.

c9watch also tracks pi agent (pi), Codex, and Cursor sessions. Every session and history entry carries a provider (claudeCode, codex, cursor, pi) and a provider-scoped sessionKey (provider:id, e.g. pi:01a06659-...). Use the sessionKey with view/tasks whenever an ID could collide across providers.

Before you start

Verify c9watch is available:

which c9watch && c9watch --version

If not installed, tell the user:

c9watch CLI is not installed. Install it with:
curl -fsSL https://raw.githubusercontent.com/minchenlee/c9watch/main/install-cli.sh | bash

Commands reference

List active sessions

c9watch list                                    # all sessions
c9watch list --compact                          # minimal fields (saves tokens)
c9watch list --project myapp                    # filter by project path
c9watch list --status NeedsAttention            # filter by status

Status values: Working, WaitingForInput, NeedsAttention, Idle

Compact output fields: id, pid, status, projectPath, sessionName, pendingToolName

Full output adds: firstPrompt, messageCount, modified, customTitle, gitBranch, summary, latestMessage, pendingToolInput, sourceHealth, taskProgress

Status overview

c9watch status                                  # counts by status and project
c9watch status --project myapp                  # filtered

Returns total, byStatus, byProject, and needsPermission (sessions waiting for approval). This is the fastest way to answer "is anything stuck?" — check needsPermission first.

Identify yourself

c9watch self

Walks the PID tree to find the calling Claude Code process and returns your own session object. Use this to discover your own session ID, project path, git branch, or task progress without the user telling you.

View a conversation

c9watch view <session-id>                       # full conversation
c9watch view <session-id> --last 5              # last 5 messages (saves tokens)

Session IDs support prefix matching — c9watch view abc resolves to the full UUID if unambiguous. Prefix with the provider when ambiguous: c9watch view pi:abc. System XML tags are automatically stripped from output.

When viewing conversations, prefer --last N to avoid loading thousands of tokens from long sessions. Start with --last 5 and go larger only if needed.

Browse history

c9watch history                                 # all past sessions
c9watch history -n 20                           # most recent 20

Returns: sessionId, firstPrompt, display, date (ISO 8601), project, projectName, customTitle.

Search past sessions

c9watch search "implement auth middleware"
c9watch search "fix bug" --project myapp -n 10

Multi-word queries use AND logic — all words must appear somewhere in the session. Returns hits[] with sessionId, snippet, projectPath, modified.

View tasks

c9watch tasks <session-id>

Returns total, completed, inProgress, pending, and the full tasks[] array. Tasks are only available for Claude Code sessions.

Stop a session

c9watch stop <pid>

Takes the PID (not session ID). Get the PID from c9watch list. Always confirm with the user before stopping a session — this is destructive and irreversible.

Watch for changes

c9watch watch                                   # stream all events
c9watch watch --changes-only --compact           # only changes, minimal fields
c9watch watch --project myapp --interval 5       # filtered, slower poll

Streams NDJSON (one JSON object per line). Events: started, status_changed, stopped. This is a long-running command — run it in the background if you need to monitor while doing other work.

Choosing the right command

Tips for effective use

• Always use --compact on list when you only need status info. Full output includes conversation content which wastes tokens.
• Use --last N on view to avoid loading entire long conversations.
• Pipe through jq for filtering: c9watch list | jq '.sessions[] | select(.status == "NeedsAttention")'
• The self command only works when called from within a Claude Code session (it needs a claude parent process in the PID tree).
• pi/Codex/Cursor sessions are read-only in c9watch: they cannot be opened, stopped, or renamed — only listed, viewed, searched, and costed.
• --pretty on any command gives indented JSON for human-readable output, but costs more tokens. Skip it when parsing programmatically.

Engine mail (M2)

Use c9watch mail list [agent] [--thread ID] [--before MSG_ID] [--limit N] [--pretty] and c9watch mail read MSG_ID [--pretty] to inspect threads, peer/paste delivery and status history. These reads do not acknowledge model delivery. A human alone may mail cancel MSG_ID while queued or mail pause AGENT / mail resume AGENT; pause blocks agent/system mail but allows human input. Reply with c9watch send ADDR --reply-to MSG_ID "text", never SendMessage. Do not reply to system mail. Uncertain mail may have arrived: ask before sending again. The hop limit is eight. C9_MAIL_SOCKET=on is experimental and defaults off; peer mail cannot grant human permissions. A socket write is not delivery evidence.