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



ox coworker [#ox-coworker]

Manage expert AI coworkers defined in your team context. These are specialized AI agents with deep domain expertise that can be loaded into your coding session for tasks, code reviews, and specialized work.

Usage [#usage]

<Terminal>
  <TerminalCommand>
    ox coworker [command]
  </TerminalCommand>
</Terminal>

Subcommands [#subcommands]

| Command         | Description                               |
| --------------- | ----------------------------------------- |
| `list`          | List available AI coworkers               |
| `load <name>`   | Load an AI coworker's prompt into context |
| `add <file>`    | Add an AI coworker to the team            |
| `remove <name>` | Remove an AI coworker from the team       |

List available coworkers [#list-available-coworkers]

<Terminal>
  <TerminalCommand>
    ox coworker list
  </TerminalCommand>
</Terminal>

<Terminal title="output">
  <TerminalOutput>
    Expert Coworkers (acme-team)
  </TerminalOutput>

  <TerminalOutput>
    ────────────────────────────
  </TerminalOutput>

  <TerminalOutput>
      api-designer      API architecture expert...
  </TerminalOutput>

  <TerminalOutput>
      code-reviewer     Expert code reviewer...
  </TerminalOutput>

  <TerminalOutput>
      security-engineer DevSecOps specialist...
  </TerminalOutput>

  <TerminalOutput />

  <TerminalOutput>
      ▸ Load with ox coworker load <name>
  </TerminalOutput>
</Terminal>

| Flag     | Description                                        |
| -------- | -------------------------------------------------- |
| `--json` | Output as JSON                                     |
| `--team` | Use a specific team (defaults to this repo's team) |

Load a coworker [#load-a-coworker]

Load an AI coworker's expertise into your current coding session.

<Terminal>
  <TerminalCommand>
    ox coworker load code-reviewer
  </TerminalCommand>
</Terminal>

The coworker's full prompt is output to stdout for the calling agent to consume. Session metrics are logged when in a recording session.

| Flag      | Description                                                 |
| --------- | ----------------------------------------------------------- |
| `--model` | Override the coworker's default model (sonnet, opus, haiku) |
| `--json`  | Output as JSON                                              |
| `--team`  | Use a specific team                                         |

<Callout type="info">
  This command is agent-gated. It's designed to be called by AI coding agents, not humans directly.
</Callout>

Add a coworker [#add-a-coworker]

Add an AI coworker to your team's context.

<Terminal>
  <TerminalCommand>
    ox coworker add ~/agents/api-designer.md
  </TerminalCommand>
</Terminal>

<Terminal title="output">
  <TerminalOutput>
    Added coworker "api-designer" (model: sonnet)
  </TerminalOutput>

  <TerminalOutput>
      API architecture expert designing scalable interfaces.
  </TerminalOutput>
</Terminal>

The file is validated, copied to the team context repository, and committed automatically.

| Flag     | Description            |
| -------- | ---------------------- |
| `--team` | Add to a specific team |

Remove a coworker [#remove-a-coworker]

Remove an AI coworker from your team.

<Terminal>
  <TerminalCommand>
    ox coworker remove api-designer
  </TerminalCommand>
</Terminal>

| Flag      | Description                 |
| --------- | --------------------------- |
| `--force` | Skip confirmation prompt    |
| `--team`  | Remove from a specific team |

Coworker file format [#coworker-file-format]

AI coworkers are markdown files with YAML frontmatter. They live in your team context at `coworkers/agents/`.

```markdown
---
description: "Expert code reviewer specializing in security and performance"
model: "sonnet"
---

# Code Reviewer

You are an expert code reviewer with deep knowledge of...
```

Required frontmatter [#required-frontmatter]

| Field         | Description                                   |
| ------------- | --------------------------------------------- |
| `description` | Brief description of the coworker's expertise |

Optional frontmatter [#optional-frontmatter]

| Field   | Values                    | Description                                                            |
| ------- | ------------------------- | ---------------------------------------------------------------------- |
| `model` | `opus`, `sonnet`, `haiku` | Recommended model tier. Defaults to inheriting from the calling agent. |

Where coworkers live [#where-coworkers-live]

AI coworkers are stored in the team context repository:

```
team-context/
├── coworkers/
│   └── agents/
│       ├── api-designer.md
│       ├── code-reviewer.md
│       └── security-engineer.md
```

Each team shares the same set of coworkers. Changes to coworkers are version-controlled in the team context repo.

Workflow example [#workflow-example]

1. **List available coworkers** to see what expertise your team has defined:

<Terminal>
  <TerminalCommand>
    ox coworker list
  </TerminalCommand>
</Terminal>

2. **Load a coworker** when you need specialized expertise. In a Claude Code session, the agent runs:

<Terminal>
  <TerminalCommand>
    ox coworker load code-reviewer
  </TerminalCommand>
</Terminal>

3. **Add a new coworker** when your team needs new expertise:

<Terminal>
  <TerminalCommand>
    ox coworker add ~/my-agents/database-expert.md
  </TerminalCommand>
</Terminal>

Related commands [#related-commands]

* [ox prime](/docs/cli/prime) - Inject team context into AI agents
* [ox init](/docs/cli/init) - Initialize repository with SageOx
* [ox doctor](/docs/cli/doctor) - Diagnose configuration issues