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

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

| 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

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

Remove SageOx integration from AI coworkers.

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

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

| 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

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

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

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

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