# ox agent (/docs/cli/commands/agent)



ox agent [#ox-agent]

Commands for AI coding assistants. Provides session management, Team Context access, and diagnostics.

<Callout type="info">
  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.
</Callout>

Usage [#usage]

<Terminal>
  <TerminalCommand>
    ox agent <subcommand> [flags]
  </TerminalCommand>
</Terminal>

Subcommands [#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 for a specific agent      |
| `ox agent <id> session` | Manage sessions (start, stop, summarize, etc.) |
| `ox agent <id> whisper` | Check for pending whispers                     |
| `ox agent <id> query`   | Semantic search across Team Context            |
| `ox agent hook`         | Handle agent lifecycle events                  |
| `ox agent team-ctx`     | Read Team Context content                      |
| `ox agent redact`       | View and test redaction policy                 |

How it works [#how-it-works]

When an AI coworker starts working in a repository:

1. **Prime** - The agent runs `ox agent prime` to get an `agent_id` and load Team Context
2. **Session start** - Optionally starts a session to track the conversation
3. **Work** - The agent performs tasks
4. **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 [#ox-agent-prime]

Initialize an agent session and inject Team Context. This is the most common agent command.

<Terminal>
  <TerminalCommand>
    ox agent prime
  </TerminalCommand>

  <TerminalOutput>
    agent_id: Oxa7b3
  </TerminalOutput>

  <TerminalOutput>
    context_version: 2024-01-15T10:30:00Z
  </TerminalOutput>

  <TerminalOutput>
    team: acme-engineering
  </TerminalOutput>

  <TerminalOutput>
    injected: true
  </TerminalOutput>
</Terminal>

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](/docs/cli/prime).

ox agent list [#ox-agent-list]

List all active AI coworkers and their session state.

<Terminal>
  <TerminalCommand>
    ox agent list
  </TerminalCommand>

  <TerminalOutput>
    AGENT_ID  STATUS   SESSION          STARTED
  </TerminalOutput>

  <TerminalOutput>
    Oxa7b3    active   fix-auth-bug     2024-01-15 10:30:00
  </TerminalOutput>

  <TerminalOutput>
    Oxf2c1    idle     -                2024-01-15 09:15:00
  </TerminalOutput>
</Terminal>

ox agent <id> doctor [#ox-agent-id-doctor]

Check session health for a specific agent.

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 doctor
  </TerminalCommand>

  <TerminalOutput>
    Agent Health: Oxa7b3
  </TerminalOutput>

  <TerminalOutput>
      \[OK] Session active
  </TerminalOutput>

  <TerminalOutput>
      \[OK] Team Context loaded
  </TerminalOutput>

  <TerminalOutput>
      \[OK] Daemon connected
  </TerminalOutput>
</Terminal>

Session management [#session-management]

Session commands track AI coworker conversations for future reference and team visibility.

Session subcommands [#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 [#start-a-session]

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 session start --title "Fix authentication bug"
  </TerminalCommand>

  <TerminalOutput>
    session_id: ses_01JQ2X3Y4Z
  </TerminalOutput>

  <TerminalOutput>
    status: recording
  </TerminalOutput>
</Terminal>

| Flag      | Description                  |
| --------- | ---------------------------- |
| `--title` | Human-readable session title |

Stop a session [#stop-a-session]

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 session stop
  </TerminalCommand>

  <TerminalOutput>
    session_id: ses_01JQ2X3Y4Z
  </TerminalOutput>

  <TerminalOutput>
    status: saved
  </TerminalOutput>

  <TerminalOutput>
    duration: 45m
  </TerminalOutput>
</Terminal>

Summarize a session [#summarize-a-session]

Generate a summary of the session content.

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 session summarize
  </TerminalCommand>
</Terminal>

| Flag     | Description              |
| -------- | ------------------------ |
| `--file` | Output summary to a file |

Log a conversation entry [#log-a-conversation-entry]

Append a conversation entry to the active session.

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 session log
  </TerminalCommand>
</Terminal>

Import a prior session [#import-a-prior-session]

Import a session from another source.

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 session import --title "Previous work" --file session.json
  </TerminalCommand>
</Terminal>

| Flag      | Description          |
| --------- | -------------------- |
| `--title` | Session title        |
| `--file`  | Path to session file |

Capture prior history [#capture-prior-history]

Capture conversation history from a previous session that wasn't tracked.

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 session capture-prior --title "Morning session" --file history.json
  </TerminalCommand>
</Terminal>

| 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-session]

Recover a stale or crashed session.

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 session recover
  </TerminalCommand>

  <TerminalOutput>
    Recovered session: ses_01JQ2X3Y4Z
  </TerminalOutput>
</Terminal>

Abort a session [#abort-a-session]

Discard the active session without saving.

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 session abort
  </TerminalCommand>

  <TerminalOutput>
    Session aborted: ses_01JQ2X3Y4Z
  </TerminalOutput>
</Terminal>

Delete a session [#delete-a-session]

Delete a completed session.

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 session delete fix-auth-bug
  </TerminalCommand>

  <TerminalOutput>
    Deleted session: fix-auth-bug
  </TerminalOutput>
</Terminal>

Whispers [#whispers]

Check for pending whispers (messages from humans or other AI coworkers).

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 whisper
  </TerminalCommand>

  <TerminalOutput>
    No pending whispers
  </TerminalOutput>
</Terminal>

Semantic search [#semantic-search]

Query Team Context and repository knowledge.

<Terminal>
  <TerminalCommand>
    ox agent Oxa7b3 query "How do we handle authentication errors?"
  </TerminalCommand>
</Terminal>

| Flag      | Description                        |
| --------- | ---------------------------------- |
| `--limit` | Maximum number of results          |
| `--team`  | Search team-wide context           |
| `--repo`  | Search repository-specific context |

Lifecycle hooks [#lifecycle-hooks]

Handle agent lifecycle events (called by orchestration systems).

<Terminal>
  <TerminalCommand>
    ox agent hook <event>
  </TerminalCommand>
</Terminal>

Events include session start, stop, and error conditions.

Team Context access [#team-context-access]

Read Team Context content directly.

<Terminal>
  <TerminalCommand>
    ox agent team-ctx [slug]
  </TerminalCommand>
</Terminal>

Without a slug, returns the full Team Context. With a slug, returns a specific section.

Redaction [#redaction]

View and test the redaction policy that filters sensitive information.

View policy [#view-policy]

<Terminal>
  <TerminalCommand>
    ox agent redact
  </TerminalCommand>
</Terminal>

Test redaction [#test-redaction]

Test how a sample string would be redacted.

<Terminal>
  <TerminalCommand>
    ox agent redact test "API_KEY=sk-abc123"
  </TerminalCommand>

  <TerminalOutput>
    API_KEY=[REDACTED]
  </TerminalOutput>
</Terminal>

Global flags [#global-flags]

These flags work with all `ox agent` commands:

| Flag       | Description                       |
| ---------- | --------------------------------- |
| `--review` | Preview changes without executing |
| `--text`   | Output in plain text format       |
| `--force`  | Skip confirmation prompts         |

CLAUDE.md integration [#claudemd-integration]

AI coworkers like Claude Code are configured to run `ox agent prime` automatically via CLAUDE.md:

```markdown
<!-- 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 [#whats-next]

* [ox prime](/docs/cli/prime) - Detailed guide to context injection
* [ox doctor](/docs/cli/doctor) - Diagnose setup issues
* [Team Context](/docs/features/team-context) - Understanding Team Context