# ox agent (https://sageox.ai/docs/cli/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

<Terminal>
  <TerminalCommand>ox agent &lt;subcommand&gt; [flags]</TerminalCommand>
</Terminal>

## 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

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

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

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 &lt;id&gt; 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 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

<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

<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

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

Append a conversation entry to the active session.

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

### 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 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 stale or crashed session.

<Terminal>
  <TerminalCommand>ox agent Oxa7b3 session recover</TerminalCommand>
  <TerminalOutput>Recovered session: ses_01JQ2X3Y4Z</TerminalOutput>
</Terminal>

### 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 completed session.

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

## 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

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

Handle agent lifecycle events (called by orchestration systems).

<Terminal>
  <TerminalCommand>ox agent hook &lt;event&gt;</TerminalCommand>
</Terminal>

Events include session start, stop, and error conditions.

## 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

View and test the redaction policy that filters sensitive information.

### View policy

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

### 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

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

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

- [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