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



ox integrate [#ox-integrate]

Install or manage SageOx integrations with AI coding agents. The integration ensures that `ox agent prime` runs when an AI coding session starts, giving AI coworkers access to team context.

Usage [#usage]

```bash
ox integrate                    # Show integration status
ox integrate install            # Install project-level hooks
ox integrate install --user     # Install user-level integration
ox integrate uninstall          # Remove project-level hooks
ox integrate list               # List all integration status
```

Supported agents [#supported-agents]

| Agent       | Integration method                     | Level           |
| ----------- | -------------------------------------- | --------------- |
| Claude Code | JSON hooks in `.claude/settings.json`  | Project or User |
| Gemini CLI  | Hooks (hidden, use `--gemini`)         | Project or User |
| Codex CLI   | Hooks (hidden, use `--codex`)          | Project or User |
| Amp CLI     | AGENTS.md marker (hidden, use `--amp`) | Project         |

Subcommands [#subcommands]

ox integrate install [#ox-integrate-install]

Install SageOx hooks for AI coworkers.

```bash
# Project-level (default) — adds hooks to .claude/settings.json
ox integrate install

# User-level — adds guidance to ~/.claude/CLAUDE.md for all projects
ox integrate install --user
```

**What gets installed (project-level):**

* Lifecycle hooks in `.claude/settings.json`:
  * `SessionStart` — Prime context on session start
  * `PreCompact` — Re-prime before context compaction
  * `PostToolUse` — Track tool usage
  * `Stop` — Clean up on stop
  * `SessionEnd` — Finalize session
  * `UserPromptSubmit` — Track prompts
* Git commit hooks (`prepare-commit-msg`) for attribution trailers

ox integrate uninstall [#ox-integrate-uninstall]

Remove SageOx integration from AI coworkers.

```bash
ox integrate uninstall          # Remove project hooks
ox integrate uninstall --user   # Remove user-level integration
```

ox integrate list [#ox-integrate-list]

Show the status of all SageOx integrations.

```bash
ox integrate list
```

```
Claude Code (project):
  ✓ hooks: installed (.claude/settings.json)
Claude Code (user):
  ✓ marker: enabled (~/.claude/CLAUDE.md)

Git commit hooks:
  ✓ prepare-commit-msg: installed
```

Flags [#flags]

| Flag       | Description                                    |
| ---------- | ---------------------------------------------- |
| `--user`   | Install/uninstall at user level (all projects) |
| `--gemini` | Target Gemini CLI instead of Claude Code       |
| `--codex`  | Target Codex CLI instead of Claude Code        |
| `--amp`    | Target Amp CLI instead of Claude Code          |

How integration works [#how-integration-works]

Project-level integration [#project-level-integration]

When you run `ox integrate install`, SageOx adds hooks to `.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "ox agent prime --force 2>&1",
        "matchers": ["startup", "resume", "clear", "compact"]
      }
    ],
    "PreCompact": [
      {
        "type": "command",
        "command": "ox agent prime --idempotent 2>&1"
      }
    ]
  }
}
```

This file should be committed to your repo so all team members get the integration.

User-level integration [#user-level-integration]

When you run `ox integrate install --user`, SageOx adds an `ox:prime` marker to `~/.claude/CLAUDE.md`. This enables priming for all projects without per-project setup.

Verifying integration [#verifying-integration]

After installing, start a Claude Code session. You should see:

```
agent_id: Oxa7b3
team: acme-eng
ledger: synced (2m ago)
```

If you don't see this, check:

```bash
ox integrate list   # Verify hooks are installed
ox status           # Verify authentication and sync
```

Related commands [#related-commands]

* [ox init](/docs/cli/init) — Initialize a project (includes integration)
* [ox agent prime](/docs/cli/agent) — Manually prime an AI coworker
* [ox status](/docs/cli/status) — Check integration and sync status