c9watch-cli

name

c9watch-cli

description

Use c9watch CLI to monitor, query, and coordinate Claude Code sessions. Trigger when the user asks about other running Claude Code sessions, wants to check what agents are doing, needs to find past session work, asks about Claude Code costs or spending, wants to stop or coordinate sibling sessions, or mentions "c9watch". Also trigger when the user says things like "check on my other sessions", "what's running", "any sessions stuck", "find that conversation where I...", "how much have I spent", or "what did I work on yesterday".

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.

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, 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. 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.

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

User wants to know...	Command
"What's running right now?"	c9watch list --compact
"Is anything stuck/waiting?"	c9watch status then check needsPermission
"What's session X doing?"	c9watch view <id> --last 3
"What did I work on recently?"	c9watch history -n 20
"Find that conversation where..."	c9watch search "<keywords>"
"How far along is that task?"	c9watch tasks <id>
"Who am I?"	c9watch self
"Stop that other session"	c9watch list to find PID, confirm, then c9watch stop <pid>

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).
• --pretty on any command gives indented JSON for human-readable output, but costs more tokens. Skip it when parsing programmatically.