ox agent
Commands for AI coding assistants. Provides session management, Team Context access, and diagnostics.
These commands are designed for AI coworkers, not humans. Your AI coworker runs these commands automatically when configured via CLAUDE.md or AGENTS.md hooks.
Usage
Subcommands
| Command | Description |
|---|---|
ox agent prime | Initialize agent session, inject Team Context |
ox agent list | List active AI coworkers and session state |
ox agent <id> doctor | Check session health and find incomplete sessions |
ox agent <id> session | Manage sessions (start, stop, summarize, etc.) |
ox agent <id> tasks | Execute scheduled work (list, next, done, cancel, extend) |
ox agent <id> heartbeat | Send a heartbeat and receive pending whispers |
ox agent <id> whisper | Check for pending whispers |
ox agent <id> query | Semantic search across Team Context |
ox agent <id> context | Report which surfaced context you used |
ox agent hook | Handle coding agent hook events |
ox agent team-ctx | Read Team Context content |
ox agent redact | View and test redaction policy |
How it works
When an AI coworker starts working in a repository:
- Prime - The agent runs
ox agent primeto get anagent_idand load Team Context - Session start - Optionally starts a session to track the conversation
- Work - The agent performs tasks
- Session stop - Saves the session for future reference
The agent_id (e.g., Oxa7b3) identifies the agent throughout its session and is used as a prefix for subsequent commands.
ox agent prime
Initialize an agent session and inject Team Context. This is the most common agent command.
Output is XML by default; pass --format json for JSON. With --text, the output starts with the agent ID, for example Agent: Oxa7b3.
The returned agent_id is used as a prefix for all subsequent agent commands in that session.
For detailed coverage of context injection, see ox prime.
ox agent list
List all active AI coworkers and their session state.
ox agent <id> doctor
Check session health for a specific agent and find incomplete sessions.
Session management
Session commands track AI coworker conversations for future reference and team visibility.
Session subcommands
| Command | Description |
|---|---|
start | Begin recording a new session |
stop | End recording and save |
log | Append a conversation entry |
summarize | Generate session summary |
import | Import a prior session |
capture-prior | Capture untracked history |
recover | Recover stale/crashed session |
abort | Discard active session |
delete | Delete a completed session |
remind | Emit reminder info for active session |
record | Record batch session entries |
plan | Save plan document to session |
context-trace | Access context trace events |
subagent-complete | Report subagent completion to parent |
subagent-list | List subagent sessions |
Start a session
| Flag | Description |
|---|---|
--title | Human-readable session title |
Stop a session
Stop recording and save the session.
Summarize a session
Generate a summary of the session content.
| Flag | Description |
|---|---|
--file | Session file to summarize |
Log a conversation entry
Append a conversation entry to the active session.
Import a prior session
Import a session from another source, on stdin or with --file.
| Flag | Description |
|---|---|
--title | Session title |
--file | Path to session file |
Capture prior history
Capture conversation history from a previous session that wasn't tracked. The input is schema-validated.
| Flag | Description |
|---|---|
--title | Session title |
--file | Path to history file |
--session-id | Specific session ID to capture |
--adapter | Adapter for history format |
Recover a session
Recover a stale or crashed session.
Abort a session
Discard the active session without saving. This is destructive.
Delete a session
Delete a completed session. This is destructive.
Scheduled tasks
Execute scheduled work. Run each task in a fresh-context subagent.
| Command | Description |
|---|---|
ox agent <id> tasks list | List ready agent tasks |
ox agent <id> tasks next | Claim the top ready task |
ox agent <id> tasks done <task-id> | Mark a task completed |
ox agent <id> tasks cancel <task-id> | Mark a task canceled |
ox agent <id> tasks extend <task-id> | Extend the lease on long work |
Whispers
Check for pending whispers (messages from humans or other AI coworkers).
During long tasks, send a heartbeat to stay in sync. The heartbeat also delivers pending whispers.
Semantic search
Query Team Context and repository knowledge.
| Flag | Description |
|---|---|
--limit | Maximum number of results |
--team | Filter by team ID |
--repo | Filter by repo ID |
Report context you used
Report which surfaced context changed your work. Record an item when it changes what you do, or report that nothing did.
| Flag | Description |
|---|---|
--why | One line on how the context changed your work |
--none | Report that no surfaced context was used |
Lifecycle hooks
Handle coding agent hook events. Your coding agent's hooks call this command; it needs no agent ID.
The event is the coding agent's own hook event name, such as SessionStart, UserPromptSubmit, PostToolUse, or Stop.
Team Context access
Read Team Context content directly.
Without a slug, returns the full Team Context. With a slug, returns a specific section.
Redaction
View and test the redaction policy that filters sensitive information.
View policy
Test redaction
Test how a sample string would be redacted. Pass - to read the text from stdin.
Flags
These flags work with all ox agent commands:
| Flag | Description |
|---|---|
--review | Security audit mode: human summary plus machine output |
--text | Human-readable text output instead of the default machine output (JSON; ox agent prime defaults to XML) |
--force | Skip confirmation for destructive operations, such as session abort and session delete |
CLAUDE.md integration
AI coworkers like Claude Code are configured to run ox agent prime automatically via CLAUDE.md:
<!-- ox:prime --> Run `ox agent prime` on session start, after compaction, or clear.This ensures the agent has Team Context loaded before starting work. The agent should re-prime after /clear or /compact commands that may clear context.
What's next
- ox prime - Detailed guide to context injection
- ox doctor - Diagnose setup issues
- Team Context - Understanding Team Context