# FAQ (https://sageox.ai/docs/faq)

# Frequently asked questions

Start here for short answers about SageOx. Follow the links when you need more detail.

## Start with SageOx

### What does SageOx do?

SageOx turns discussions and work into context that human and AI coworkers can reuse. It captures what matters, distills it into [Team Context](/docs/features/team-context), and [Ledger history](/docs/developers/session-recording), and makes that context available in connected AI coworkers, coding sessions, and the web app.

Read [How SageOx works](/docs/developers/how-it-works) for the full data flow.

### Where should I start?

- **In a connected tool.** Connect SageOx to an MCP-compatible AI coworker. Start with the [MCP overview](/docs/mcp).
- **In a repo.** Connect a checked-out repository and work with Claude Code or Codex. Start with the [ox CLI quickstart](/docs/cli/quickstart).
- **By recording.** Record or import a discussion. Start with [context capture](/docs/context-capture).

[Getting started](/docs/getting-started) covers all of them.

### Do I need to connect a repository first?

No. Connected tools and recording both work without a connected repository. Connect one when you want repo-aware context, local code indexing, and coding-session capture.

### Which AI coworkers work with SageOx?

In a repo, SageOx supports AI coworkers such as Claude Code and Codex; support depth varies by tool. Over MCP, it works with clients such as ChatGPT, Claude Cowork, and Claude Desktop.

See the [coding tools overview](/docs/developers/coding-agents), and [MCP setup guides](/docs/mcp) for current integration details.

## Understand shared context

### What is Team Context?

Team Context is the shared record of your team's conventions, decisions, discussion transcripts, and distilled memory. It is team-wide, so human and AI coworkers can build on the same knowledge.

Read [Team Context](/docs/features/team-context) for its structure and editing workflow.

### What is the Ledger?

The Ledger is the per-repository history of code work, commits, sessions, and project-specific decisions. Team Context travels across the team; each Ledger stays scoped to one repository.

Read [Session recording](/docs/developers/session-recording) to see how coding work reaches the Ledger.

### What can SageOx capture?

SageOx can capture discussions from desktop or mobile browsers, in-room discussions through [Ox Dot](/docs/context-capture/ox-dot), and imported audio or video. Those discussion paths feed Team Context.

Coding sessions follow a separate path: the ox CLI captures them into the repository's Ledger. See [context capture](/docs/context-capture), and [session recording](/docs/developers/session-recording) for both flows.

## Know where context lives

### Does SageOx send my source code to Anthropic or OpenAI?

No. SageOx does not send your source code to an AI model provider. [CodeDB](/docs/developers/codedb) indexes code locally on your machine, while AI coworker sessions continue to use your own provider account.

### How do I get all my SageOx data?

All customer content lives in git. Team Context and Ledgers are git repositories, and audio recordings are checked into git too. A `git checkout` gives you all your data in open formats that you can inspect and keep, without locking you into SageOx.

Only rebuildable caches and operational state such as permissions and settings live outside those repositories. We will keep improving the checkout and portability experience over time. Read [Your data](/docs/features/your-data) for the repository layout and storage details.

## Get help

### What should I do when setup isn't working?

If you work in a repo, follow the [`ox doctor` diagnostic guide](/docs/cli/doctor), then run the diagnostic and apply the reported fixes:

<Terminal>
  <TerminalComment>Check your SageOx setup</TerminalComment>
  <TerminalCommand>ox doctor</TerminalCommand>
</Terminal>

For mobile issues, use the [mobile troubleshooting guide](/docs/mobile/troubleshooting). For anything else, visit [SageOx support](/support).

## What's next

- [Getting started](/docs/getting-started): choose your first SageOx workflow
- [Your data](/docs/features/your-data): inspect and keep your SageOx data
- [Support](/support): contact the SageOx team


---

# Getting started (https://sageox.ai/docs/getting-started)

# Getting started

SageOx turns what your team says and does into context your coworkers and AI coworkers can reuse. Discussions and coding sessions are captured, distilled into [Team Context](/docs/features/team-context), and read back from whichever tool you are working in. [About SageOx](/docs) explains what it does and how it works.

## 1. Create an account

Sign up at sageox.ai. Your account starts with a personal team that is private to you, so you can use SageOx on your own before involving anyone else.

During signup you are prompted to record a voice ID. It is optional, and it is what lets SageOx tell who said what in a recorded discussion.

## 2. Connect your tools

**The ox CLI.** The deepest integration: it automatically saves your coding sessions to SageOx and primes Team Context in the repos you work in. Install it once.

<Terminal>
  <TerminalCommand>curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash</TerminalCommand>
</Terminal>

Then sign in and connect a repository from inside it.

<Terminal>
  <TerminalCommand>ox login</TerminalCommand>
  <TerminalCommand>ox init</TerminalCommand>
</Terminal>

Your coding sessions will now be primed with your team's context.

[Quickstart: ox CLI](/docs/cli/quickstart) · [Command reference](/docs/cli)

**A connected tool.** Claude Desktop, ChatGPT, Cursor, VS Code, Windsurf, Goose, and Copilot Studio connect over MCP. Choose your tool in Settings > Connections and authorize the connection. Claude Code does not need this step: it uses the ox CLI, which is the deeper integration.

Your sessions will now start with your team's context. Ask your tool to save your work to your team's context: "Commit this session to SageOx."

[MCP overview](/docs/mcp) · [Connecting a client that is not listed](/docs/mcp/manual)

Manage your connected tools from [Settings > Connections](/settings/connections).

## 3. Capture a discussion

A discussion is a recorded conversation between people: a standup, a design review, a retro. SageOx recognizes the speakers, transcribes the conversation, and saves relevant knowledge into your team context, making it accessible to your connected tools.

There are several ways to capture a discussion.

| How | Best for |
|---|---|
| [SageOx Desktop](/docs/context-capture/ox-desktop) | A Zoom, Meet, or VoIP call on your Mac: your mic and everyone else's audio together |
| [Record in the web app](/docs/context-capture/web-app-recorder) | A conversation happening right now, from your browser or your phone |
| [Upload a file](/docs/context-capture/audio-upload), or [import a video](/docs/context-capture/video-import) | Anything already recorded: an audio file, a transcript, or a Loom, Figma, or Cap walkthrough |
| [Ox Dot](/docs/context-capture/ox-dot) | In-room audio on a dedicated device, with nobody's laptop open |

## 4. Invite your team

Inviting your team compounds the benefits: your entire team's discussions, coding sessions, chats, and plans contribute to and draw from one shared context.

[Team setup](/docs/quickstart/team-setup) · [Joining a team you were invited to](/docs/quickstart/new-team-member) · [Working solo](/docs/quickstart/solo)

## What's next

- [About SageOx](/docs): what SageOx does and how it works
- [Context capture](/docs/context-capture): every way knowledge gets in
- [FAQ](/docs/faq): common questions
- [Getting the most out of SageOx](/docs/mcp/getting-the-most): prompt patterns worth knowing
- [Features](/docs/features): Team Context, distillation, and your data


---

# About SageOx (https://sageox.ai/docs)

# About SageOx

SageOx turns what your team says and does into context your coworkers and AI coworkers can reuse.

```mermaid
graph TD
    A["Recordings, uploads, and sessions"] --> B["Team Context + Ledger"]
    B --> C["Tools connected over MCP"]
    B --> D["Coding sessions"]
    B --> E["capture + web playback"]
```

The loop: capture what matters, let SageOx distill it into shared context, then read it back from the surface that fits how you work.

## What SageOx does

SageOx helps with three jobs:

- **Capturing discussions and work** so decisions do not evaporate
- **Turning raw recordings and sessions into Team Context and Ledger history**
- **Making that context available** in MCP-connected tools, repo-based coding tools, and the web app

## Setting up

[Getting started](/docs/getting-started) walks through creating an account, connecting the tools you work in, and capturing your first discussion.

## Features

### Team Context
Shared knowledge your team builds over time:
- Decisions from discussions and recordings
- Conventions, terminology, and working norms
- Context every coworker (human or AI) can reuse

### Recording & Transcription
Capture team discussions and make them searchable:
- Record directly from the [web app](/docs/context-capture/web-app-recorder), or mobile
- Capture in-room discussions with [Ox Dot](/docs/context-capture/ox-dot)
- [Import video walkthroughs](/docs/context-capture/video-import) from Cap, Loom, or local files
- Automatic AI transcription with speaker identification
- Insights feed into your Team Context

### In a connected tool
Use SageOx directly inside tools that support [MCP](/docs/mcp):
- Search team knowledge from the tool you already use
- Save useful chats and sessions back into SageOx
- Work with interactive cards in tools that support them

### In a repo with the ox CLI
Use the ox CLI when your AI coworker works inside a checked-out repo:
- [`ox login`](/docs/cli/auth) - Authenticate with SageOx
- [`ox init`](/docs/cli/init) - Connect a repository
- [`ox agent prime`](/docs/cli/prime) - Inject Team Context into repo-based coding sessions
- [`ox doctor`](/docs/cli/doctor) - Diagnose setup issues when something seems off

## Next steps

- **Just want to try it?** [Solo Quickstart](/docs/quickstart/solo), get value in 5 minutes, no team needed
- **Creating a team?** [Team Setup Quickstart](/docs/quickstart/team-setup)
- **Joining a team?** [New Team Member Quickstart](/docs/quickstart/new-team-member)
- [MCP overview](/docs/mcp) - Connect SageOx to your tools
- [Getting Started](/docs/getting-started) - Full setup walkthrough
- [FAQ](/docs/faq) - Common questions about setup, context, and data
- [Quickstart: ox CLI](/docs/cli/quickstart) - CLI reference
- [web app recorder](/docs/context-capture/web-app-recorder) - Record team meetings
- [Ox Dot](/docs/context-capture/ox-dot) - Dedicated in-room capture
- [Video Import](/docs/context-capture/video-import) - Import screen recordings as team knowledge


---

# Running ox in constrained environments (https://sageox.ai/docs/cli/ephemeral-mode)

# Running ox in constrained environments

"Ephemeral" is not a mode. It's a label for a **constellation of capabilities the sandbox provides or withholds.** Claude Code Cloud, Devin, GitHub Actions, and Codespaces are not all the same shape: one has persistent disk and an 8-hour lifetime, one writes disk to a snapshot but can run a daemon, one is gone in five minutes. `ox` probes each capability once at startup and lets every subsystem ask for what it actually needs.

This page covers the capability model, what works and what doesn't, how to set `ox` up on each major platform, and the exact error strings runbooks should grep for.

## The capability model

When `ox` starts, it probes the environment for four capabilities and a lifetime hint:

| Capability | Question | Set by |
|---|---|---|
| `PersistDisk` | Will writes to `~/.sageox/` survive the next `ox` invocation? | filesystem probe + `OX_PERSIST_DISK` override |
| `LongLivedHelper` | Can a background helper outlive a single CLI invocation? | lifetime hint + `OX_NO_DAEMON` override |
| `Browser` | Can `ox` open an interactive URL for device-code auth? | TTY + `DISPLAY`/`BROWSER` + known-headless detection |
| `Network` | Is egress open, allowlisted, proxied, or offline? | platform-derived; `OX_NETWORK` override |

Subsystems consult capabilities directly. The local CodeDB indexer only runs when `PersistDisk && LongLivedHelper`. `ox login`'s browser flow only attempts to launch when `Browser` is true; otherwise it refuses with a clear "set `SAGEOX_TOKEN`" message. Session staging picks `~/.sageox/sessions/...` when `PersistDisk` is true, otherwise `$TMPDIR/ox-sessions/...`.

### Capability matrix per platform

| Platform | PersistDisk | LongLivedHelper | Browser | Network | Lifetime |
|---|---|---|---|---|---|
| Local laptop | yes | yes | yes | open | persistent |
| GitHub Codespaces | yes | yes | no | open | hours |
| Claude Code Cloud | no | yes | no | allowlist | hours |
| Devin | no | yes | no | open | hours |
| GitHub Actions runner | no | no | no | open | minutes |

<Callout type="info">
**Codespaces is no longer treated as ephemeral.** A Codespace has persistent disk and a multi-hour lifetime, it behaves like a slow laptop. The previous `CODESPACES=true` auto-detection forced the constrained path and threw away the persistent disk Codespaces paid for. First-run does the setup, second-run reuses it.
</Callout>

<Callout type="warning">
**`--ephemeral` is deprecated and will be removed.** It only sets the env var inside one `ox` process: POSIX prevents writing back to the calling shell, so subsequent `ox` commands lose the signal and silently degrade. The canonical pattern is to export `OX_EPHEMERAL=1` into the session env (e.g. write it to `$CLAUDE_ENV_FILE` before running `ox`), which is what every recipe on this page already does. The flag is redundant at best and a footgun at worst. The CLI accepts it for one release with a stderr deprecation warning, then removes it.
</Callout>

### Override knobs

You can override the probe at the capability level:

| Variable | Effect |
|---|---|
| `OX_PERSIST_DISK=0` | Force the in-memory / `$TMPDIR` paths even when `~/.sageox/` is writable |
| `OX_NO_DAEMON=1` | Disable any background helper; run everything inline in the CLI process |
| `OX_NETWORK=allowlist` | Tell `ox` it is running behind an egress allowlist (skip probes that would spuriously fail) |
| `OX_EPHEMERAL=1` | Coarse shortcut: sets `PersistDisk=false, LongLivedHelper=false` |

Use the capability-level overrides when the auto-probe gets it wrong (e.g. a brand-new sandbox `ox` doesn't recognize). Use `OX_EPHEMERAL=1` when you just want "treat me as fully constrained" without spelling out each axis.

## Prerequisites

- A [Personal Access Token](/docs/cli/pats) exported as `SAGEOX_TOKEN`.
- A static `ox` binary on `PATH`. The install script ships a single self-contained Go binary with no runtime dependencies.

## What works, what doesn't

Subcommand behavior in constrained environments. "Designed-for" subcommands are the supported entrypoints; "degraded" still works but with a noted trade-off; "refused" exits non-zero with a clear pointer.

| Subcommand | `PersistDisk=false` | `LongLivedHelper=false` | `Browser=false` |
|---|---|---|---|
| `ox agent prime` | designed-for | designed-for | designed-for |
| `ox distill --since=<window>` | designed-for | designed-for | designed-for |
| `ox status` | designed-for | designed-for | designed-for |
| `ox doctor` | designed-for | designed-for | designed-for |
| `ox query "..."` | works (refetches each call) | works | designed-for |
| `ox code search` | degraded (remote-only; slower) | degraded (remote-only) | designed-for |
| `ox import <video>` | works (stages to `$TMPDIR`, syncs at exit) | works (sync upload at exit) | designed-for |
| `ox kb` writes | degraded (warns; writes lost at exit) | works | designed-for |
| `ox login` | works | works | **refused**, exit non-zero, pointer to PATs |
| `ox daemon` | **refused** | **refused** | works |

Session uploads are idempotent on `(agent_id, session_id)`. Retrying a failed upload is safe, the second call is a no-op if the first actually succeeded.

## Error contract

These strings are part of the CLI's contract surface. Operator runbooks grep for them; they will not be reworded without a deprecation pass.

| String | Cause | Fix |
|---|---|---|
| `SAGEOX_TOKEN expired or invalid` | PAT revoked, expired, or wrong environment | Rotate at [Settings → Tokens](https://sageox.ai/settings/tokens); update secret store |
| `SAGEOX_TOKEN not set; ox login is unavailable in this environment` | No PAT and no browser capability | Export `SAGEOX_TOKEN` (or run on a host with a browser) |
| `failed to clone team context: dial tcp: i/o timeout` | Network allowlist gap | Add team-context git host to platform's allowed hosts |
| `ox: 'daemon' requires a long-lived helper and is unavailable here` | `ox daemon` invoked in a sandbox without `LongLivedHelper` | Use the inline command path, daemon is not required |
| `ox: 'login' requires a browser and is unavailable here` | `ox login` invoked without `Browser` capability | Authenticate with [`SAGEOX_TOKEN`](/docs/cli/pats) |
| `OX_EPHEMERAL=1 set but you appear to be on a persistent machine` | Stray export from a previous CI experiment | Unset `OX_EPHEMERAL` in your shell |

Exit codes follow `sysexits.h`: usage errors are `64`, auth failures are `77`.

## Claude Code Cloud

Anthropic's [Managed Agents](https://platform.claude.com/docs/en/managed-agents/environments) run Claude Code in an isolated sandbox defined by an environment YAML.

### Environment file

```yaml
# .claude/environment.yml
packages:
  go: ["github.com/sageox/ox/cmd/ox@latest"]

secrets:
  SAGEOX_TOKEN: oxp_...    # paste your PAT here, or reference a secret

hooks:
  SessionStart: |
    ox agent prime
```

- `packages.go` installs `ox` from source into the sandbox image. Pin to a specific version (`@v0.42.0`) for reproducibility once you have one you like.
- `secrets.SAGEOX_TOKEN` is injected at runtime, it does not appear in the image layer. Prefer Anthropic's Secrets dashboard over inlining the value.
- `hooks.SessionStart` runs at the start of every Claude session. `ox` auto-detects the constrained environment from `CLAUDE_CODE_REMOTE` and configures itself accordingly, no `OX_EPHEMERAL` export needed.

### Networking

Claude Code Cloud defaults to `limited` egress. Add the SageOx hosts to your `allowed_hosts`:

```yaml
network:
  mode: limited
  allowed_hosts:
    - api.sageox.ai
    - github.com                     # install script: release download
    - api.github.com                 # install script: latest-release lookup
    - release-assets.githubusercontent.com  # install script: where release-asset downloads actually redirect
    - raw.githubusercontent.com      # install script itself
    - <your-team-context-git-host>   # gitlab.com, github.com, etc.
```

If you forget the team-context git host, `ox agent prime` will fail with a clone error pointing at the missing domain. Add it and retry.

### Verify

Start a Claude session and look for these lines in the SessionStart log:

```
ox agent prime: constrained environment (CLAUDE_CODE_REMOTE)
ox agent prime: authenticated as <your-email>
ox agent prime: team context loaded (<N> files)
```

If you see `SAGEOX_TOKEN expired or invalid`, rotate the PAT, see [Personal Access Tokens](/docs/cli/pats#expiration-and-rotation).

## Devin

Cognition's [Devin repo setup](https://docs.devin.ai/onboard-devin/repo-setup) splits configuration into three sections: setup (bakes into the snapshot), startup (runs every session), and secrets.

### Setup commands

One-time, runs when Devin builds the workspace snapshot:

<Terminal>
  <TerminalCommand>curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash</TerminalCommand>
  <TerminalComment>sanity check that install succeeded</TerminalComment>
  <TerminalCommand>ox --version</TerminalCommand>
</Terminal>

### Startup commands

Runs at the start of every Devin session, on top of the snapshot:

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

`ox` auto-detects the Devin sandbox from `DEVIN_TASK_ID` and configures itself accordingly.

### Secrets

In the Devin Secrets dashboard, add:

```
SAGEOX_TOKEN=oxp_...
```

Devin injects this into the environment before startup commands run. Never paste the token into the startup-commands box, that value is logged.

### Notes

- Devin keeps the snapshot warm across sessions, so `ox agent prime` runs against a pre-installed binary. If you bump `ox`, re-run the setup commands or invalidate the snapshot.

## GitHub Actions

For CI use cases: generating release notes, distilling sessions into team context, running scheduled queries:

```yaml
# .github/workflows/ox-distill.yml
name: ox distill
on:
  schedule:
    - cron: "0 6 * * *"     # daily at 06:00 UTC
  workflow_dispatch:

jobs:
  distill:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ox
        run: |
          curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash
          # The installer falls back to ~/.local/bin when /usr/local/bin isn't
          # writable, and only warns about PATH — so publish it here or the
          # next step fails with "ox: command not found".
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Prime and distill
        env:
          SAGEOX_TOKEN: ${{ secrets.SAGEOX_TOKEN }}
        run: |
          ox agent prime
          ox distill --since=24h
```

For self-hosted runners with a persistent filesystem, `ox` will detect the persistent disk and use its normal local-state mode, you'll get better performance from the local CodeDB index without any config change.

## GitHub Codespaces

A Codespace has persistent disk and a multi-hour lifetime. Treat it as a slow laptop, not a sandbox:

<Terminal>
  <TerminalComment>one-time workspace setup</TerminalComment>
  <TerminalCommand>curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash</TerminalCommand>
  <TerminalComment>one-time, opens browser via Codespaces port-forward</TerminalComment>
  <TerminalCommand>ox login</TerminalCommand>
  <TerminalComment>connects the workspace to your repo</TerminalComment>
  <TerminalCommand>ox init</TerminalCommand>
</Terminal>

After the first-run setup, every subsequent terminal session in the Codespace has `ox` configured from local state, no PAT needed, no per-session priming.

If you'd rather skip the device-code flow, export `SAGEOX_TOKEN` from a Codespaces secret instead of `ox login`. Both work; the device flow gives you the same credential refresh story as your laptop.

## Troubleshooting

### `SAGEOX_TOKEN expired or invalid`

The PAT has expired, been revoked, or is malformed. Create a new one at [Settings → Tokens](https://sageox.ai/settings/tokens), and update the secret in your agent platform. See [Personal Access Tokens](/docs/cli/pats#expiration-and-rotation).

### `401 Unauthorized` against a custom endpoint

`ox` defaults to `https://api.sageox.ai`. If you set `SAGEOX_ENDPOINT` to a staging endpoint, confirm the PAT was issued against that same environment. PATs are bound to the endpoint they were issued for.

### `failed to clone team context: dial tcp: i/o timeout`

Network allowlist gap. The sandbox blocked the git host. For Claude Code Cloud, add the host to `network.allowed_hosts`. For Devin, check the workspace network settings. For GitHub Actions, this usually means a private team-context repo requires an SSH key, use HTTPS with a Git PAT instead.

### `ox: command not found`

The install script failed silently, often because `curl` was missing from a minimal base image. Use the platform's package manager to install `curl` first, then re-run the install script. For Devin, add the install step to the setup commands so it runs in a snapshot with a fuller toolchain.

### `OX_EPHEMERAL=1 set but you appear to be on a persistent machine`

You exported `OX_EPHEMERAL=1` in a previous shell session and forgot. Unset it to restore full functionality. `ox doctor` will flag this on every invocation until you do.

### Auto-detection misfired

If `ox` runs in constrained mode when you expect full mode (or vice versa), use the capability-level overrides above (`OX_PERSIST_DISK`, `OX_NO_DAEMON`, `OX_NETWORK`), rather than the coarse `OX_EPHEMERAL=1`. Run `ox doctor` to see which detection rule fired and what the resulting capabilities are.

## Related

- [Personal Access Tokens](/docs/cli/pats): the credential you need first
- [ox agent prime](/docs/cli/prime): what gets loaded at session start
- [ox doctor](/docs/cli/doctor): see capabilities for the current environment
- [SageOx + Codex cookbook](/docs/developers/codex): recipes for OpenAI Codex


---

# ox CLI (https://sageox.ai/docs/cli)

# ox CLI

The ox CLI connects your repositories to the SageOx platform, giving your AI coworkers access to Team Context: your team's recorded discussions, decisions, and current work.

<Callout type="info">
  This reference tracks **ox 0.14.0**. Run `ox version` to check yours and `ox upgrade` to update. See [`ox release-notes`](/docs/cli/release-notes) for what changed.
</Callout>

## Installation

<Terminal>
  <TerminalCommand>curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash</TerminalCommand>
</Terminal>

After installation, verify it works:

<Terminal>
  <TerminalCommand>ox version</TerminalCommand>
</Terminal>

## Quick setup

<Terminal>
  <TerminalComment>Authenticate with SageOx</TerminalComment>
  <TerminalCommand>ox login</TerminalCommand>
  <TerminalComment>Initialize your repository</TerminalComment>
  <TerminalCommand>ox init</TerminalCommand>
  <TerminalComment>Verify everything works</TerminalComment>
  <TerminalCommand>ox doctor</TerminalCommand>
</Terminal>

## Command reference

Grouped as they appear in `ox --help`.

### Software development

| Command | Description |
|---------|-------------|
| [`ox code`](/docs/cli/code) | Search code in this repo |
| [`ox decision`](/docs/cli/decision) | Work with Decision Records (ADRs, DDRs) |
| [`ox index`](/docs/cli/index-cmd) | Index code and project data for search |
| [`ox init`](/docs/cli/init) | Initialize SageOx for this repository |
| [`ox plan`](/docs/cli/plan) | Work with plans |
| [`ox pr`](/docs/cli/pr) | Author SageOx content for pull requests |
| [`ox session`](/docs/cli/session) | Manage AI coworker sessions |
| [`ox viz`](/docs/cli/viz) | Choose, author, render, and lint visual explanations |

### Knowledge

| Command | Description |
|---------|-------------|
| [`ox conversation`](/docs/cli/conversation) | Read recorded team conversations from the local Team Context |
| [`ox distill`](/docs/cli/distill) | Distill team observations into memory summaries |
| [`ox import`](/docs/cli/import) | Import a document, media file, or video URL into Team Context |
| [`ox kb`](/docs/cli/kb) | Work with Knowledge Bubbles |
| [`ox query`](/docs/cli/query) | Search team knowledge |
| [`ox recap`](/docs/cli/recap) | Show the concrete value SageOx has delivered to your work |

### Teams

| Command | Description |
|---------|-------------|
| [`ox export`](/docs/cli/export) | Show where your data lives and how to take it with you |
| [`ox glance`](/docs/cli/glance) | See what your team's AI coworkers are working on |
| [`ox murmur`](/docs/cli/murmur) | Publish a coordination signal to other AI coworkers |
| [`ox team`](/docs/cli/team) | Work with your teams and coworkers |

### Authentication

| Command | Description |
|---------|-------------|
| [`ox login`](/docs/cli/auth) | Authenticate with sageox.ai |
| [`ox logout`](/docs/cli/auth) | Log out of SageOx |
| [`ox status`](/docs/cli/status) | Display SageOx status and directory locations |
| [`ox sync`](/docs/cli/sync) | Manually sync ledger/team contexts (rarely needed) |

### Agent integration

| Command | Description |
|---------|-------------|
| [`ox agent`](/docs/cli/agent) | UX exposed to AI coding agents |
| [`ox agent prime`](/docs/cli/prime) | Inject Team Context into an AI coworker session |
| [`ox coworker`](/docs/cli/coworker) | Manage expert agents and subagents for your team |
| [`ox hooks`](/docs/cli/hooks) | Manage event hooks for daemon notifications |
| [`ox integrate`](/docs/cli/integrate) | Set up SageOx integration with Claude Code |

### Diagnostics

| Command | Description |
|---------|-------------|
| [`ox adapter`](/docs/cli/adapter) | Manage external adapter binaries |
| [`ox daemon`](/docs/cli/daemon) | Manage the background sync daemon |
| [`ox doctor`](/docs/cli/doctor) | Run diagnostics on ox installation and configuration |
| [`ox gc`](/docs/cli/gc) | Reclone eligible managed repositories safely |
| [`ox guide`](/docs/cli/guide) | Show a bundled topical guide |
| [`ox release-notes`](/docs/cli/release-notes) | Display release notes for the current version |
| [`ox upgrade`](/docs/cli/upgrade) | Upgrade ox to the latest version |
| [`ox version`](/docs/cli/version) | Print version information |

### Configuration and utilities

| Command | Description |
|---------|-------------|
| [`ox config`](/docs/cli/config) | Manage ox configuration |
| [`ox uninstall`](/docs/cli/uninstall) | Remove SageOx from this repository |
| [`ox view`](/docs/cli/view) | Open the SageOx dashboard in your browser |

## Global flags

These flags work with any command:

| Flag | Description |
|------|-------------|
| `-v, --verbose` | Show detailed output |
| `-q, --quiet` | Suppress non-error output |
| `--json` | Output in JSON format (for scripting) |
| `-c, --config <path>` | Config file path (default: `.sageox/config.yaml`) |
| `--no-interactive` | Disable spinners and TUI elements (auto-enabled when `CI=true`) |
| `--profile` | Generate a CPU profile and execution trace for performance analysis |

## Configuration

ox stores configuration in two locations:

| Location | Purpose |
|----------|---------|
| `~/.config/sageox/` | Global config and credentials |
| `.sageox/config.yaml` | Repository-specific settings |

## What's next

- [CLI quickstart](/docs/cli/quickstart) - Get started in minutes
- [ox init](/docs/cli/init) - Initialize your first repository
- [ox login](/docs/cli/auth) - Authentication details
- [ox doctor](/docs/cli/doctor) - Troubleshoot setup issues
- [ox agent prime](/docs/cli/prime) - How AI coworkers get Team Context


---

# Maintenance (https://sageox.ai/docs/cli/maintenance)

# Maintenance

Keep your ox CLI up to date, check version info, and cleanly remove SageOx when needed.

## Check your version

<Terminal>
  <TerminalCommand>ox version</TerminalCommand>
</Terminal>

Shows the installed version, build date, and commit hash.

For machine-readable output:

<Terminal>
  <TerminalCommand>ox version --json</TerminalCommand>
</Terminal>

## Upgrade ox

<Terminal>
  <TerminalCommand>ox upgrade</TerminalCommand>
</Terminal>

The CLI detects how it was installed and uses the appropriate upgrade method:

| Install method | Upgrade command |
|----------------|-----------------|
| Homebrew | `brew upgrade ox` |
| `go install` | `go install github.com/sageox/ox@latest` |
| Manual download | Downloads latest binary from GitHub |

The `--json` flag outputs upgrade status in JSON format for scripting.

## View release notes

<Terminal>
  <TerminalCommand>ox release-notes</TerminalCommand>
</Terminal>

Displays release notes for the currently installed version.

| Flag | Description |
|------|-------------|
| `--latest` | Show notes for the latest available version |
| `--raw` | Output raw markdown without formatting |

## Uninstall ox from a repository

<Terminal>
  <TerminalCommand>ox uninstall</TerminalCommand>
</Terminal>

Removes SageOx from the current repository. The command prompts for confirmation before making changes.

### What gets removed

| Artifact | Description |
|----------|-------------|
| `.sageox/` | Configuration, cache, and daemon files |
| Git hooks | SageOx-installed `prepare-commit-msg` and `post-commit` hooks |
| `.claude/settings.local.json` | Agent integration settings (SageOx keys only) |
| `CLAUDE.md` / `AGENTS.md` | Removes `ox agent prime` references |

<Callout type="info">
Non-SageOx git hooks and user configurations are preserved. The CLI identifies SageOx-specific content and removes only that.
</Callout>

### Flags

| Flag | Description |
|------|-------------|
| `--dry-run` | Show what would be removed without making changes |
| `--force` | Skip confirmation prompt |
| `--local-only` | Remove local artifacts only (skip server deregistration) |
| `--user-integrations` | Also remove user-level integration hooks |
| `--all` | Remove from all repositories in the current directory tree |

### Preview changes first

<Terminal>
  <TerminalCommand>ox uninstall --dry-run</TerminalCommand>
</Terminal>

This shows exactly what will be removed without making any changes.

## Clean reinstall

To start fresh with a clean SageOx setup:

<Terminal>
  <TerminalComment>Remove existing installation</TerminalComment>
  <TerminalCommand>ox uninstall --force</TerminalCommand>
  <TerminalComment>Re-initialize</TerminalComment>
  <TerminalCommand>ox init</TerminalCommand>
  <TerminalComment>Verify setup</TerminalComment>
  <TerminalCommand>ox doctor</TerminalCommand>
</Terminal>

## Uninstall the CLI binary

`ox uninstall` removes SageOx from repositories. To remove the ox CLI itself:

| Install method | Removal command |
|----------------|-----------------|
| Homebrew | `brew uninstall ox` |
| `go install` | `rm $(go env GOPATH)/bin/ox` |
| Manual | Delete the binary from your PATH |

Global credentials are stored in `~/.config/sageox/`. Remove this directory to clear all authentication data.

## What's next

- [ox doctor](/docs/cli/doctor) - Diagnose setup issues after reinstalling
- [ox init](/docs/cli/init) - Re-initialize a repository
- [ox login](/docs/cli/auth) - Re-authenticate if needed


---

# Personal access tokens (https://sageox.ai/docs/cli/pats)

# Personal access tokens

Long-lived tokens for using ox in CI, cloud agents, and scripts. PATs authenticate `ox` in environments where the interactive [`ox login`](/docs/cli/auth) device flow is not possible: cloud coding agents, CI runners, and unattended scripts.

A PAT is a long-lived bearer credential scoped to your SageOx account. Treat it like a password.

## When to use a PAT

| Environment | Use |
|-------------|-----|
| Local desktop, interactive | [`ox login`](/docs/cli/auth) |
| Claude Code Cloud, Devin, Codespaces | PAT |
| GitHub Actions, GitLab CI, Buildkite | PAT |
| Headless scripts, cron, scheduled jobs | PAT |

`ox login` writes credentials to `~/.config/sageox/credentials.json` after a browser handshake. That flow does not work in cloud sandboxes where there is no browser, no persistent disk, and no way to open `localhost`. A PAT is the headless equivalent.

## Create a token

1. Sign in at [sageox.ai](https://sageox.ai).
2. Open [**Settings → API Tokens**](https://sageox.ai/settings/tokens) (under the **Sharing** group).
3. Click **Create token**.
4. Give it a recognizable name, the name appears in audit logs and the revocation UI. Use something specific like `claude-cloud-acme-repo` or `github-actions-ci`, not `token1`.
5. Pick an expiration. Options are 7, 30, 60, 90 (default), 180, or 365 days, a custom value up to 365 days, or a deliberate "never expires" ceremony that requires typed confirmation.
6. Click **Create**. The token displays once. Copy it immediately: SageOx does not store the plaintext and cannot show it again.

Scopes are currently full account access. Scoped tokens are tracked in [SageOx roadmap](https://sageox.ai/roadmap).

## Use the token

Export `SAGEOX_TOKEN` in the environment where `ox` runs:

<Terminal>
  <TerminalComment>Set the token (paste yours after the equals sign)</TerminalComment>
  <TerminalCommand>export SAGEOX_TOKEN=oxp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_yyyyyyyy</TerminalCommand>
  <TerminalComment>Verify authentication</TerminalComment>
  <TerminalCommand>ox status</TerminalCommand>
  <TerminalComment>Prime an AI coworker session</TerminalComment>
  <TerminalCommand>ox agent prime</TerminalCommand>
</Terminal>

`SAGEOX_TOKEN` is the only environment variable the CLI reads for PAT authentication. It takes precedence over any cached credentials from `ox login`.

<Callout type="info">
**`OX_TOKEN` is no longer read.** Earlier releases accepted `OX_TOKEN` as an alias; the runtime now reads `SAGEOX_TOKEN` only. Update any CI secret or hook script that still sets `OX_TOKEN`. Leaving it set will surface as `not authenticated` errors at the next `ox` invocation. See [ADR-047](https://github.com/sageox/sageox-mono/blob/main/docs/adr/047-sageox-token-rename.md).
</Callout>

For setup recipes in constrained environments (Claude Code Cloud, Devin, GitHub Actions), see [Running ox in constrained environments](/docs/cli/ephemeral-mode).

## Token format

PATs follow a fixed shape:

```
oxp_<32-base62>_<crc32-base62>
```

- `oxp_` prefix: opaque marker that GitHub's, GitLab's, and TruffleHog's secret scanners recognize as a SageOx credential.
- 32 base62 characters of entropy.
- 8 base62 characters of CRC32 checksum so the CLI can reject malformed tokens before hitting the API.

The token is opaque. Do not parse it. Do not try to extract a user ID from it.

## Expiration and rotation

- You receive an email when a token is created and when one is revoked.
- Expiration-warning emails are being rolled out. Where enabled, you receive a reminder within 7 days of expiration and a final notice within the last day.
- Never-expiring tokens do not currently receive periodic reminder emails. Review them regularly and revoke any you no longer use.
- Rotate any PAT at least once per year. Short-lived secrets contain blast radius.
- When a token expires or is revoked, the next CLI call prints:

  ```
  SAGEOX_TOKEN expired or invalid — create a new one at https://sageox.ai/settings/tokens
  ```

  The exit code is non-zero so CI pipelines fail loudly rather than running unauthenticated.

There is no auto-refresh. PATs are intentionally simple, when one expires, generate a new one and update the secret in whatever platform stores it.

## Revoking a token

Revoke from [**Settings → API Tokens**](https://sageox.ai/settings/tokens). Click the token row, then **Revoke**.

Revocation is immediate. There is no grace period. Any cloud agent or CI job using the token will start returning `401 Unauthorized` on the next request. Plan rotations so a new token is in place before revoking the old one.

If you suspect a token has leaked, revoke first and rotate second.

## Security

- **Never commit a PAT to a repository.** GitHub, GitLab, and most secret scanners detect the `oxp_` prefix and notify SageOx, which will automatically revoke the token. Your CI will start failing within minutes.
- **Use platform secret stores**, not flags or shell history. Each cloud agent has a Secrets dashboard, see [Running ox in constrained environments](/docs/cli/ephemeral-mode) for per-platform instructions.
- **Pass via environment, not on the command line.** Anything in `argv` shows up in process listings (`ps`), and in some CI logs.
- **Scope by token, not by user.** Create one PAT per integration so you can revoke a leaked CI token without breaking your cloud agent.
- **Rotate after teammate offboarding.** If someone with access to your shared CI secrets leaves, rotate every PAT they could have read.

## Related

- [Running ox in constrained environments](/docs/cli/ephemeral-mode): per-platform setup recipes
- [ox login](/docs/cli/auth): interactive desktop authentication
- [ox status](/docs/cli/status): verify which credential is active
- [ox doctor](/docs/cli/doctor): diagnose auth failures


---

# Quickstart: ox CLI (https://sageox.ai/docs/cli/quickstart)

# Quickstart: ox CLI

Connect your repository to SageOx and give your AI coding agents Team Context.

<CLIOnboardingWidget variant="default" />

## What just happened?

When you run `ox init`, the CLI:

1. **Authenticates** with your SageOx account (opens browser if needed)
2. **Registers** your repository with the SageOx platform
3. **Enables** Team Context injection for AI agents

## Next steps

### Start using AI agents

Your AI coding agents now receive your team's context automatically:

<Terminal>
  <TerminalComment>Claude Code gets your Team Context</TerminalComment>
  <TerminalCommand>claude</TerminalCommand>
</Terminal>

The agent runs `ox agent prime` on startup to inject context about your team's conventions, patterns, and decisions.

### If something seems off

`ox doctor` is the diagnostic tool, not a required onboarding step:

<Terminal>
  <TerminalCommand>ox doctor</TerminalCommand>
</Terminal>

It shows:
- Authentication status
- Repository registration
- Team membership
- Context injection health

### View your dashboard

See your connected repositories and team activity in the [web dashboard](/dashboard).

## Troubleshooting

### Authentication expired

If you see authentication errors:

<Terminal>
  <TerminalCommand>ox login</TerminalCommand>
</Terminal>

### Repository not recognized

If your repo isn't found:

<Terminal>
  <TerminalCommand>ox init --force</TerminalCommand>
</Terminal>

### Context not injecting

Check your setup in verbose mode:

<Terminal>
  <TerminalCommand>ox doctor --verbose</TerminalCommand>
</Terminal>

## Learn more

- [Getting Started](/docs/getting-started) - Full setup walkthrough
- [ox login](/docs/cli/auth) - Authentication details
- [ox doctor](/docs/cli/doctor) - Diagnostics reference
- [ox agent prime](/docs/cli/prime) - How context injection works

## See also

- [Team Setup Quickstart](/docs/quickstart/team-setup): for team creators
- [New Team Member Quickstart](/docs/quickstart/new-team-member): for invited members


---

# ox record (https://sageox.ai/docs/cli/record)

# ox record

Capture transcripts from AI coding sessions. When you work with Claude Code, Cursor, or Aider, the conversation contains valuable decisions and domain knowledge. `ox record` saves these to your repo's Ledger.

**Important:** This captures text-based human-AI coding sessions, not audio/video meetings. For meeting recordings, see [Discussions](/docs/context-capture/discussions).

## What Gets Recorded

- Questions and context you provided
- Code suggestions and explanations
- Decisions made and alternatives discussed
- Debugging and problem-solving approaches

## Commands

### Create a Recording

<Terminal>
  <TerminalCommand>ox record create [flags]</TerminalCommand>
</Terminal>

| Flag | Description |
|------|-------------|
| `--title`, `-t` | Title for the recording |
| `--description`, `-d` | Optional description |
| `--path`, `-p` | Path to transcript file |
| `--agent-type` | AI agent type (claude-code, cursor, aider) |

<Terminal>
  <TerminalComment>Pipe transcript</TerminalComment>
  <TerminalCommand>cat session.md | ox record create --title "Auth refactor"</TerminalCommand>
  <TerminalComment>From file</TerminalComment>
  <TerminalCommand>ox record create --title "API design" --path ./transcript.md</TerminalCommand>
</Terminal>

### List Recordings

<Terminal>
  <TerminalCommand>ox record list [--limit N] [--json]</TerminalCommand>
</Terminal>

### View a Recording

<Terminal>
  <TerminalCommand>ox record view &lt;recording-id&gt; [--json]</TerminalCommand>
</Terminal>

### Delete a Recording

<Terminal>
  <TerminalCommand>ox record delete &lt;recording-id&gt; [--force]</TerminalCommand>
</Terminal>

## When to Record

- Architectural decisions
- Complex debugging sessions
- Domain knowledge explanations
- Onboarding context
- Novel solutions

## Privacy

- Recordings are stored in your repo's Ledger
- Team members with repo access can view them
- Remove sensitive data before recording

## Related Commands

- [ox init](/docs/cli/init) - Initialize your repository


---

# Audio + transcript upload (https://sageox.ai/docs/context-capture/audio-upload)

Already have the recording? Upload an existing audio file or transcript into SageOx, from the web app or your terminal. Audio gets transcribed; a transcript skips straight to insight extraction.

## When to use this

This is the path for content you already captured somewhere else. The other capture mechanisms cover live and video sources.

| You have | Use this | Not this |
|----------|----------|----------|
| An MP3 exported from Zoom or a voice memo | Audio + transcript upload | — |
| A VTT or SRT from Otter.ai, Zoom, or Meet | Audio + transcript upload (skips transcription) | — |
| A discussion happening right now | [web app recorder](/docs/context-capture/web-app-recorder) | this page |
| A screen recording or video walkthrough | [Video import](/docs/context-capture/video-import) | this page |

A pasted or uploaded transcript skips transcription but still runs through speaker handling and insight extraction.

## Supported formats

| Type | Formats |
|------|---------|
| Audio | MP3, WAV, M4A, OGG, FLAC, AAC |
| Transcript | VTT, SRT, TXT, MD (skip transcription step) |
| Max size | 1000MB |

<Callout type="info">
Uploading a transcript skips transcription entirely. If you already have an accurate transcript, upload it instead of the audio; extraction starts immediately and you skip the transcription wait.
</Callout>

## Upload from the web app

The fastest path for a single file:

1. Go to your team's **Media** section
2. Click **Upload**
3. Drag and drop an audio file or transcript, or browse for it
4. Add a title and tag participants
5. Confirm to start processing

Processing starts automatically. You'll see progress in the pipeline view, and you can assign speakers to team members once transcription finishes.

## Upload from the CLI

Import directly from your terminal without leaving your editor:

<Terminal>
  <TerminalComment>Upload an audio file</TerminalComment>
  <TerminalCommand>ox import recording.mp3 --title "Sprint Planning"</TerminalCommand>
  <TerminalComment>Upload an existing transcript (skips transcription)</TerminalComment>
  <TerminalCommand>ox import standup.vtt --title "Daily Standup"</TerminalCommand>
  <TerminalComment>Track processing progress</TerminalComment>
  <TerminalCommand>ox import --status rec_01234567 --watch</TerminalCommand>
</Terminal>

`ox import` accepts the same audio and transcript formats as the web app. See [Import via CLI](/docs/context-capture/video-import-cli) for all flags and options.

## How processing works

```mermaid
graph LR
    A["Upload"] --> B["Transcribe"]
    B --> C["Speaker ID"]
    C --> D["Extract insights"]
    D --> E["Team Context"]
```

Audio uploads run the full pipeline. Transcript uploads enter at the insight-extraction step, since the text already exists. Either way, the extracted decisions and action items commit to your [Team Context](/docs/features/team-context) for your AI coworkers to read.

## What's next

- [web app recorder](/docs/context-capture/web-app-recorder): record a live discussion in your browser
- [Video import](/docs/context-capture/video-import): import Loom, Figma, and Cap recordings
- [Discussions](/docs/context-capture/discussions): what discussions capture and how they're stored
- [Distillation](/docs/features/distill): how recordings become team memory


---

# Web app recorder (https://sageox.ai/docs/context-capture/console)

# Web app recorder

This page moved. See [Web app recorder](/docs/context-capture/web-app-recorder).


---

# Discussions (https://sageox.ai/docs/context-capture/discussions)

# Discussions

Discussions capture knowledge from team meetings, design reviews, and technical conversations. SageOx transcribes recordings and extracts insights that feed into your [Team Context](/docs/features/team-context), making team decisions searchable for your AI coworkers.

## What discussions capture

Discussions are transcribed recordings of human-to-human conversations:

- Sprint planning and standups
- Architecture and design reviews
- Code review walkthroughs
- Incident retrospectives
- Product strategy sessions

The insights extracted from these conversations (decisions made, constraints identified, rationale explained) become part of your team's shared knowledge.

## Ways to add discussions

### Record in browser

Use the [web app recorder](/docs/context-capture/web-app-recorder) to capture meetings directly:

1. Navigate to your team's **Media** section
2. Click **Record**
3. Allow microphone access
4. Click **Stop** when finished
5. Add title and participants

Works on desktop and mobile. See the [web app recorder guide](/docs/context-capture/web-app-recorder) for details.

### Import from Loom, Figma, or Cap

Import screen recordings, design walkthroughs, and demos:

1. Go to your team's **Media** section
2. Click **Import**
3. Paste a Loom, Figma, or Cap URL
4. SageOx downloads and processes the video

Design rationale captured in Figma walkthroughs and technical explanations in Loom videos become searchable team knowledge.

### Upload audio or video files

Upload recordings from Zoom, Google Meet, or other sources:

1. Click **Upload** in your team's Media section
2. Drag and drop or browse for a file
3. Add title and participant info

**Supported formats:**

| Type | Formats |
|------|---------|
| Audio | MP3, WAV, M4A, OGG, FLAC, WebM |
| Video | MP4, MOV, WebM, MKV |
| Max size | 1000MB |

### Paste existing transcripts

For transcripts from other services (Otter.ai, Zoom, Google Meet):

1. Click **Add Transcript**
2. Paste the transcript text
3. Add metadata (title, date, participants)
4. Save

Pasted transcripts skip the transcription step but still go through insight extraction.

## How processing works

```mermaid
graph LR
    U[Upload/Record] --> T[Transcription]
    T --> S[Speaker ID]
    S --> E[Insight extraction]
    E --> TC[Team Context]
```

1. **Upload**, Media uploads securely (chunks upload during recording)
2. **Transcription**, AI speech recognition converts audio to text
3. **Speaker identification**, Voices are matched to speakers
4. **Insight extraction**: Decisions, action items, and context are pulled from the transcript
5. **Team Context**, Insights commit to your team's shared knowledge

Processing typically completes within minutes. You can assign speakers to team members after transcription finishes.

## Storage and access

Discussions are stored at the **team level**. All team members can access them.

| Aspect | Details |
|--------|---------|
| Visibility | All team members |
| Storage | Encrypted at rest (AES-256) |
| Location | US-West-2 |
| Deletion | Immediate, by any team member |

## Discussions vs sessions

SageOx tracks two types of conversations:

| | Discussions | Sessions |
|-|-------------|----------|
| What | Human-to-human meetings | Human-to-AI coding conversations |
| Examples | Standups, design reviews, retros | Claude Code coding sessions |
| Capture | Web recorder, video import, upload | Automatic via `/ox-session-start` |
| Feeds into | Team Context | Ledger (per-repo) |

Discussions capture team decisions. Sessions capture coding context. Both contribute to the knowledge your AI coworkers use.

## What's next

- [web app recorder](/docs/context-capture/web-app-recorder): record directly from your browser
- [Video Import](/docs/context-capture/video-import): import Loom, Figma, and Cap recordings
- [Distillation](/docs/features/distill): how discussions become team memory
- [Team Context](/docs/features/team-context): where discussion insights live


---

# Import recordings from your Pocket (https://sageox.ai/docs/context-capture/import-from-pocket)

Already recorded on a Pocket (or any pocket voice recorder)? Copy the audio files off the device over USB and upload them to SageOx, where each one is transcribed and turned into decisions, action items, and Team Context.

<ScreenFrame
  id="docs/pocket/pocket-enable-web-sync"
  alt="Pocket app Storage Management & Sync screen with Web Sync enabled"
  maxWidth="22rem"
  caption="In the Pocket app, open Storage Management & Sync and turn Web Sync on (its status should read Enabled) before you connect the device over USB."
/>

## Turn on Web Sync first (Pocket)

Do this once, in the **Pocket app**, before you plug the device into your computer:

1. Open the Pocket app and go to **Storage Management & Sync**.
2. Turn on **Web Sync**. Confirm its status reads **Enabled** (as shown above).

With Web Sync enabled, the Pocket exposes its recordings so your computer can read them when it's connected over USB.

<Callout type="info">
No USB cable handy? Use **Auto Import from Pocket** in the Pocket app instead; it syncs recordings without connecting the device to a computer. USB is the fastest path for a batch of existing files; Auto Import is the hands-off alternative.
</Callout>

## Copy the files over USB

These steps are the same for most USB voice recorders, the device mounts as a plain drive and you drag the audio files off it:

1. Connect the recorder to your computer with its USB cable.
2. On the device, switch to **Mass Storage** mode (some recorders label this **PC**, **Data Transfer**, or **USB Drive**). The recorder now shows up as a removable drive.
3. Open the drive and find the audio folder, usually named **RECORD** or **VOICE**.
4. Drag the `.mp3` files you want into a folder on your computer.
5. Eject the drive and unplug the recorder.

| Your device says | It means |
|------------------|----------|
| Mass Storage / USB Drive | Mount as a drive so you can copy files |
| PC / Data Transfer | Same thing, the "connect to a computer" mode |
| MTP / Charge only | Switch away from these, the drive won't mount for file copy |

## Upload to SageOx

Once the `.mp3` files are on your computer, bring them into SageOx:

1. Go to your team's **Media** section.
2. Click **Upload**.
3. Drag in the `.mp3` files you copied off the Pocket, or browse for them.
4. Add a title and tag participants.
5. Confirm to start processing.

SageOx transcribes each recording and runs it through the full pipeline. See [Audio + transcript upload](/docs/context-capture/audio-upload) for supported formats, size limits, and the CLI path (`ox import`).

<Callout type="info">
SageOx reads the recording's original capture time from the file when it can. If a date looks off, open the recording and click its date in the header to correct it, an inferred date shows an **inferred · confirm** hint so you know it was a best guess.
</Callout>

## What's next

- [Audio + transcript upload](/docs/context-capture/audio-upload): formats, size limits, and importing from the CLI
- [Discussions](/docs/context-capture/discussions): what a recording becomes once it's processed
- [Distillation](/docs/features/distill): how recordings turn into team memory


---

# Context capture (https://sageox.ai/docs/context-capture)

Context capture is every way knowledge gets into SageOx. Record a discussion, upload an existing file, or import a video: each path transcribes, extracts insights, and commits the result to your [Team Context](/docs/features/team-context), where your AI coworkers read it.

## Discussion capture

A Discussion is a transcribed recording of a human-to-human conversation: a standup, a design review, an incident retro. Pick the mechanism that matches where the conversation happens.

| Mechanism | What it captures | Status | Link |
|-----------|------------------|--------|------|
| Ox Dot | In-room audio from a dedicated hardware device | Available | [Ox Dot](/docs/context-capture/ox-dot) |
| SageOx Desktop | Both sides of a computer call on a Mac: your mic and the system audio | Available | [Get the app](/product/desktop) · [Setup guide](/docs/context-capture/ox-desktop) |
| Web app recorder | A live discussion straight from your browser or phone | Available | [web app recorder](/docs/context-capture/web-app-recorder) |
| Audio + transcript upload | An existing audio file or transcript from any source | Available | [Audio + transcript upload](/docs/context-capture/audio-upload) |
| Loom, Figma, Cap video | A screen recording or video walkthrough | Available | [Video import](/docs/context-capture/video-import) |
| Ox App | On-the-go audio from your phone | **Coming soon** | — |
| Zoom / Google Meet / Teams | A meeting SageOx joins to share live insights | **Coming soon** | — |
| Slack / Mattermost | Chat-based team discussions from your workspace | **Coming soon** | — |

<Callout type="info">
The Ox App, Slack and Mattermost capture, and meeting-platform capture are in development. Meeting attendee for Zoom, Google Meet, and Teams ships behind the `meeting-join` Feature Preview.
</Callout>

## How captured context flows

Every mechanism feeds the same pipeline. The source differs; the destination is always Team Context.

```mermaid
graph LR
    A["Capture"] --> B["Transcribe"]
    B --> C["Extract insights"]
    C --> D["Team Context"]
    D --> E["AI coworker access"]
```

Transcription and insight extraction run automatically after capture. When the pipeline finishes, decisions, action items, and rationale commit to your Team Context, the shared knowledge every AI coworker reads at session start.

## Choosing a mechanism

| You have | Use |
|----------|-----|
| A discussion happening right now | [web app recorder](/docs/context-capture/web-app-recorder) |
| An audio file or transcript from another tool | [Audio + transcript upload](/docs/context-capture/audio-upload) |
| A Loom, Figma, or Cap walkthrough | [Video import](/docs/context-capture/video-import) |
| A terminal and a local file | [Import via CLI](/docs/context-capture/video-import-cli) |

## What's next

- [Discussions](/docs/context-capture/discussions): what discussions capture and how they're stored
- [web app recorder](/docs/context-capture/web-app-recorder): record directly from your browser
- [Video import](/docs/context-capture/video-import): import Loom, Figma, and Cap recordings
- [Team Context](/docs/features/team-context): where captured knowledge lives


---

# SageOx Desktop (https://sageox.ai/docs/context-capture/ox-desktop)

SageOx Desktop records your microphone and your Mac's audio, so you can capture both sides of a Zoom, Google Meet, or other computer call. Start and stop from the menu bar, then return to the discussion in your workspace.

[Explore SageOx for Mac](/product/desktop), or [try a short recording](#try-this-first) if you already have it installed.

## Install and sign in

You need **macOS 14.4 or later** and a SageOx account.

<Steps>

<Step>

### Download SageOx

[Download SageOx for Mac](/download/desktop)

One download works on every Mac, Apple Silicon or Intel.

Open the downloaded disk image, move SageOx to **Applications**, and open it.

</Step>

<Step>

### Sign in

Choose **Continue with sageox.ai** and finish signing in through your browser. Return to SageOx to continue setup.

</Step>

<Step>

### Allow audio access

On **Hear both sides**, choose **Grant both** and follow the macOS prompts:

- **Microphone** captures your voice.
- **System Audio** captures the other side of the call. SageOx doesn't record your screen.

On **Hear yourself**, say a few words and check that the microphone meter moves. Choose **Continue**, then **Done**.

This setup check tests your microphone. The short recording below checks both audio sources together.

</Step>

</Steps>

## Try this first

Before your next call, make a short recording you can recognize later.

<Steps>

<Step>

### Choose where to save

Open **OX** in your Mac's menu bar. Check the team shown below **Start Recording**; use **Team** to change it. Choose your **Private Team** for a personal test if it's available.

</Step>

<Step>

### Record both sides

Put on headphones and play a short spoken video or podcast in another app. Click **Start Recording**, then say a few words yourself.

Look for **Recording**, the running timer, and **Hearing you** as you speak. You can leave the menu closed while recording continues.

</Step>

<Step>

### Stop and check the result

After about 30 seconds, open the menu and click **Stop**. When the saved confirmation appears, choose **View Recording**.

Once the transcript is ready, check for words from both you and the video. If either is missing, use the [audio checks below](#troubleshooting) before your next call.

</Step>

</Steps>

## Record your next call

Open the menu bar and click **Start Recording** before or during your call. Check the destination team each time you switch between personal and shared discussions.

<Callout type="info">
System audio can include other sounds playing on your Mac. Pause unrelated audio before recording.
</Callout>

| Control | What it does |
|---------|--------------|
| **Pause** / **Resume** | Take a break without starting a separate recording. |
| **Stop** | Finish the recording and keep what you captured. |
| **View live** | Open the discussion while recording continues, once it's available online. |
| **Discard recording…** | Cancel a recording you don't want to keep. |

### Let SageOx offer to record

SageOx can offer to record when it detects a meeting. To start automatically, open **Settings → Recording** and choose a team under **Auto-record into**.

In the same settings, **End when meeting ends** stops recording when the detected meeting ends, with a brief chance to undo.

You can always start and stop from the menu bar yourself. Desktop warns as a recording approaches four hours of active recording, then stops at that limit.

## Return to your workspace

Choose **Open [your team]** from the menu bar to open the full workspace. Go to **Discussions** to find recordings for that team, including ones captured on your Mac.

Open a discussion to read its transcript and, after processing, its summary, decisions, and next steps. Team discussions become part of your shared [Team Context](/docs/features/team-context), available to your human and AI coworkers.

## Troubleshooting

### The microphone meter doesn't move

Open **Microphone** in the menu bar and check the selected input, especially after connecting headphones. In **System Settings → Privacy & Security → Microphone**, check that SageOx has access.

### The transcript is missing the other side

Check SageOx's system-audio access in **System Settings → Privacy & Security**. Depending on your macOS version, the section may be called **Screen & System Audio Recording**. Follow any restart prompt, then repeat the short recording test with audio playing in another app.

### The connection drops or a recording is still saving

Desktop keeps captured audio on your Mac and retries delivery. Keep SageOx open to finish saving, and follow any recording-needs-attention message. Live viewing and processing may wait until you're back online.

### You can't find a recording

Check the team you recorded into. Open that team's workspace and look in **Discussions**; a test saved to your Private Team won't appear in another team's list.

### You need to update the app

Open the menu bar and choose **Check for Updates…**. SageOx also checks for updates automatically and waits until recording and saving have finished before installing them.

## What's next

- [Discussions](/docs/context-capture/discussions): revisit what your team said and decided.
- [Context capture overview](/docs/context-capture): choose another way to capture a conversation.
- [Audio + transcript upload](/docs/context-capture/audio-upload): bring in a recording you already have.


---

# Cap setup (https://sageox.ai/docs/context-capture/video-import-cap)

# Cap setup

[Cap](https://github.com/CapSoftware/cap) is an open-source screen recorder. We recommend it for SageOx because you get full control over export settings and recordings stay local until you're ready to share.

## Why Cap

| Feature | Cap | Loom |
|---------|--------|------|
| Export control | Full resolution/fps/quality control | Limited options |
| Local storage | Files stay on your machine | Uploads immediately |
| Cost | Free | Free tier has limits |
| Editing | Trim, cut, annotate before export | Basic trimming only |

For quick, one-off recordings, Loom works fine. For regular walkthroughs where you want consistent quality and file sizes, Cap is better.

## Recommended export settings

After recording, open Cap's export dialog and configure these settings:

<ScreenFrame
  id="docs/features/cap-export-settings"
  alt="Cap export settings showing MP4 format, 720p resolution, 15fps, Social quality"
/>

| Setting | Value | Why |
|---------|-------|-----|
| **Format** | MP4 | Universal compatibility, best compression |
| **Resolution** | 720p | Sufficient for UI walkthroughs, fast to process |
| **Frame Rate** | 15 fps | Smooth enough for demos, half the data of 30fps |
| **Quality** | Social | Best size-to-quality ratio for AI extraction |

## Expected file sizes

These settings produce predictable file sizes:

| Duration | Size | Use case |
|----------|------|----------|
| 1 min | ~8 MB | Quick bug demo |
| 5 min | ~40 MB | Feature walkthrough |
| 10 min | ~80 MB | Detailed design review |
| 30 min | ~240 MB | Full meeting recording |

<Callout type="info">
**Why smaller matters.** Every byte you save speeds up four things: upload time, transcription, keyframe extraction, and AI coworker image processing. At 720p, your AI coworker sees everything it needs. At 4K, it's just more pixels to process with no benefit.
</Callout>

## Recording tips

**Narrate as you go**
Transcript quality drives extraction quality. Silent recordings produce no searchable context. Talk through what you're doing and why.

**Keep it focused**
5-10 minutes is the sweet spot. A tight walkthrough beats an hour-long ramble. If you need more time, split into multiple recordings by topic.

**Clean your desktop**
Fewer distractions means better keyframe extraction. Close Slack, hide your bookmarks bar, and full-screen the app you're demoing.

**Use descriptive titles**
Your AI coworkers search by title. "Sprint 12 Checkout Flow Redesign" beats "Recording 47".

## Import your recording

After exporting from Cap, upload to SageOx:

1. Go to your team's **Media** section at [sageox.ai](https://sageox.ai)
2. Click **Upload**
3. Drag and drop your exported MP4 file
4. Add a descriptive title

Processing starts automatically. Transcription, keyframe extraction, and summarization run in the background.

## What's next

- [Upload via Web](/docs/context-capture/video-import-web): detailed upload guide
- [Video Import](/docs/context-capture/video-import): all import options and supported formats
- [Discussions](/docs/context-capture/discussions): where imported recordings live
- [SageOx + Figma](/docs/cookbooks/figma): record Figma walkthroughs with Cap


---

# Video import via CLI (https://sageox.ai/docs/context-capture/video-import-cli)

# Video import via CLI

Import recordings directly from your terminal with `ox import`. Paste a Loom or Cap URL, submit it for processing, and track status without leaving your editor.

## Quick start

```bash
# Import a Loom recording
ox import https://www.loom.com/share/abc123def456 --title "Sprint Planning"

# Import a Cap recording
ox import https://cap.link/abc123 --title "Bug Walkthrough"

# Import any direct video URL
ox import https://example.com/meeting.mp4 --title "Team Standup"
```

## How it works

When you run `ox import` with a URL:

1. The CLI submits the URL to SageOx for processing
2. SageOx downloads the video, transcribes it, extracts keyframes, and generates summaries
3. Artifacts commit to your Team Context
4. Your AI coworkers can reference the recording in future sessions

```mermaid
graph LR
    A[ox import URL] --> B[Cloud Processing]
    B --> C[Transcription]
    C --> D[Keyframe Extraction]
    D --> E[Summarization]
    E --> F[Team Context]
```

## Commands

### Import a video URL

```bash
ox import <url> [flags]
```

| Flag | Description |
|------|-------------|
| `--title` | Display title for the recording |
| `--team` | Team ID (auto-discovered from current repo) |
| `--json` | Output as JSON |

**Examples:**

```bash
# Loom share link
ox import https://www.loom.com/share/abc123 --title "Architecture Review"

# Cap share link
ox import https://cap.link/xyz789 --title "Design Walkthrough"

# Direct video URL
ox import https://storage.example.com/recording.mp4 --title "Customer Call"
```

### Check processing status

Track a recording's progress through the pipeline:

```bash
ox import --status <recording_id>
```

| Flag | Description |
|------|-------------|
| `--status` | Recording ID to check |
| `--watch` | Poll until processing completes or fails |
| `--json` | Output as JSON (JSONL in watch mode) |

**Examples:**

```bash
# Check status once
ox import --status rec_01HQXYZ123

# Watch until complete
ox import --status rec_01HQXYZ123 --watch

# JSON output for scripting
ox import --status rec_01HQXYZ123 --json
```

**Sample output:**

```
Recording: rec_01HQXYZ123
Title:     Sprint Planning
Status:    processing
Duration:  342s

Processing Steps
  ✓ download             complete
  ✓ transcription        complete
  ◐ keyframes            in_progress
  · summarization        pending
```

### List recordings

See all recordings for your team:

```bash
ox import --list
```

| Flag | Description |
|------|-------------|
| `--list` | Show all team recordings |
| `--team` | Team ID (auto-discovered from current repo) |
| `--json` | Output as JSON |

**Sample output:**

```
ID                                       TITLE                          STATUS       CREATED
---------------------------------------- ------------------------------ ------------ --------------------
rec_01HQXYZ123                           Sprint Planning                ready        2026-03-20 14:30
rec_01HQABC456                           Bug Repro: Cart Total          processing   2026-03-20 15:45
rec_01HQDEF789                           Architecture Overview          ready        2026-03-19 10:00
```

## Supported sources

| Source | URL format |
|--------|------------|
| **Loom** | `https://www.loom.com/share/...` |
| **Cap** | `https://cap.link/...` |
| **Direct video** | Any URL ending in `.mp4`, `.webm`, `.mov` |

## Team discovery

The CLI auto-discovers your team from the current repo. If you're outside a SageOx project or want to import to a different team:

```bash
# Specify team explicitly
ox import https://loom.com/share/abc --team team_01HQ123

# Or run from inside an initialized repo
cd ~/projects/my-app
ox import https://loom.com/share/abc
```

## Scripting

Use `--json` for machine-readable output:

```bash
# Import and capture recording ID
RECORDING_ID=$(ox import https://loom.com/share/abc --title "Demo" --json | jq -r '.recording_id')

# Wait for processing to complete
ox import --status "$RECORDING_ID" --watch --json | while read -r line; do
  STATUS=$(echo "$line" | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "ready" ]; then
    echo "Processing complete!"
    break
  fi
done
```

## What's next

- [Video Import Overview](/docs/context-capture/video-import): all import methods
- [Cap Setup](/docs/context-capture/video-import-cap): optimal recording settings
- [Using in Coding Sessions](/docs/context-capture/video-import-coding): how AI coworkers use recordings
- [ox import reference](/docs/cli/import): full CLI reference


---

# Recordings in coding sessions (https://sageox.ai/docs/context-capture/video-import-coding)

# Using recordings in coding sessions

Every recording you import becomes searchable context for your AI coworkers. Repo-based coding sessions can reference transcripts, keyframes, summaries, and decisions from your walkthroughs.

## What your AI coworker sees

Recordings are broken into layers of progressively deeper context:

| Layer | What AI sees | When it's used |
|-------|--------------|----------------|
| **Summary** | Chapters, decisions, action items | "What was discussed in the design review?" |
| **Transcript** | Timestamped speech with speaker labels | "What exactly did the designer say about the nav?" |
| **Keyframes** | Frame images + AI-generated descriptions | "Show me the mockup from the walkthrough" |
| **Metadata** | Title, participants, duration | Matching the right recording to your prompt |

Your AI coworker reads these artifacts; it doesn't watch the video.

## Example: Implement from a design walkthrough

Ask a repo-based AI coworker to implement a feature based on a recorded walkthrough:

> "Look at the UX walkthrough 'Checkout Flow Redesign' and implement the bottom action bar shown at 2:30"

The AI coworker:
- Reads the summary to find the "Action Bar Design" chapter
- Finds the keyframe at 2:31 showing the mockup
- Extracts requirements from the transcript (2:15-3:45)
- Implements based on what the designer explained

The result: implementation that matches design intent, not just a static screenshot.

## Example: Reference a design decision

Ask about decisions from past discussions:

> "What did the team decide about the notification system in the last design review?"

The AI coworker finds the relevant recording, reads the summary, and returns:
- **Chapter:** "Notification Redesign" (3:20-5:45)
- **Decision:** Toast notifications replace the modal dialog
- **Action item:** Implement toast component with auto-dismiss (5s default)

No digging through Slack threads or meeting notes.

## Example: Debug from a bug report

Ask a repo-based AI coworker to analyze a recorded bug report:

> "Watch the bug report 'Cart Total Mismatch' and find the root cause"

The AI coworker:
- Reads the transcript describing the issue (total shows $0 after removing last item)
- Examines the keyframe showing the empty cart state
- Traces the issue to `CartTotal.tsx` where `reduce()` has no initial value

Bug reports with video context lead to faster fixes.

## Best practices

**Give recordings descriptive titles**
AI coworkers search by title. "Sprint 12 Checkout Flow Redesign" beats "Recording 47".

**Narrate while recording**
Transcript quality drives extraction quality. Silent recordings produce no searchable context. Talk through what you're doing and why.

**Keep recordings 5-10 minutes**
Focused context is more actionable than hour-long meetings. Split long sessions by topic.

**Reference recordings by title in prompts**
"Look at the checkout flow walkthrough" works better than "check that recording I made".

**Use 720p resolution**
AI processes 720p images faster with zero loss in code/UI comprehension. 4K adds processing time with no benefit.

## How it connects

Your recording flows through this pipeline before your AI coworker sees it:

```mermaid
graph LR
    A[Import] --> B[Transcribe]
    B --> C[Extract Keyframes]
    C --> D[Summarize]
    D --> E[Commit to Team Context]
    E --> F[AI Coworker Access]
```

1. **Import**, uploaded via web UI
2. **Transcribe**, audio extracted, transcribed with speaker identification
3. **Keyframes**, scene changes detected, frames analyzed by vision AI
4. **Summarize**: chapters, decisions, and action items generated
5. **Commit**, artifacts committed to your Team Context
6. **Access**, AI coworkers load these via `ox agent prime` at session start

## What's next

- [Video Import](/docs/context-capture/video-import): import recordings from Loom, Figma, Cap
- [Team Context](/docs/features/team-context): where recording artifacts live
- [Claude Code Integration](/docs/developers/claude-code): how context flows into coding sessions
- [SageOx + Figma](/docs/cookbooks/figma): design walkthrough workflow


---

# Loom import (https://sageox.ai/docs/context-capture/video-import-loom)

# Loom import

Already using Loom? Import recordings directly from share URLs. No need to download and re-upload, paste the URL and SageOx handles the rest.

## Import from URL

1. Copy your Loom share URL (e.g., `https://www.loom.com/share/abc123def456`)
2. Go to your team's **Media** section at [sageox.ai](https://sageox.ai)
3. Click **Import**
4. Paste the Loom URL
5. Add a descriptive title

SageOx downloads the video server-side and processes it through the full extraction pipeline: transcription, keyframe extraction, and summarization.

## Alternative: Download and upload

If you prefer to keep a local copy:

1. In Loom, click the **...** menu on your recording
2. Select **Download** and save the MP4
3. Go to your team's **Media** section
4. Click **Upload** and drag in the file

Both methods produce the same result, the URL import is faster since you skip the download step.

## Loom settings for best results

**Resolution**
720p or 1080p both work. Loom defaults to 1080p, which is fine. If you can lower it to 720p in your Loom settings, processing is faster with no loss in extraction quality.

**Camera**
Optional. SageOx extracts value from screen content and narration, not your face. Disabling the camera bubble reduces file size.

**Audio**
Keep narration clear. Speak at a normal pace and avoid background noise. Transcript quality drives everything downstream, a clear recording produces better summaries and more searchable content.

**Duration**
5-10 minutes is the sweet spot. For longer content, consider splitting into multiple recordings by topic. Each gets its own transcript and summary.

## What gets extracted

From your Loom recording, SageOx produces:

| Artifact | What it contains |
|----------|------------------|
| **Transcript** | Timestamped text with speaker labels |
| **Keyframes** | Representative screenshots with AI descriptions |
| **Summary** | Chapters, decisions, and action items |
| **Metadata** | Title, duration, import date |

Your AI coworkers read these artifacts at session start. They can cite specific recordings when implementing features or explaining decisions.

## Bulk import

Have a backlog of Loom recordings? Import them one at a time through the web UI, or contact support for bulk import assistance.

## What's next

- [Video Import](/docs/context-capture/video-import): all import options and supported formats
- [Upload via Web](/docs/context-capture/video-import-web): detailed upload guide
- [Cap Setup](/docs/context-capture/video-import-cap): alternative recording tool with more export control
- [Discussions](/docs/context-capture/discussions): where imported recordings live


---

# Upload via web (https://sageox.ai/docs/context-capture/video-import-web)

# Upload via web

The fastest way to get recordings into SageOx. Upload local files or paste URLs from Loom, Figma, and Cap.

## Upload a file

<ScreenFrame
  id="docs/features/upload-dialog"
  alt="Upload dialog with drag-and-drop area"
/>

1. Go to your team's **Media** section at [sageox.ai](https://sageox.ai)
2. Click **Upload**
3. Drag your recording into the upload area (or click **Browse Files**)
4. Add a descriptive title, this is how coworkers and AI coworkers find your recording

Processing starts automatically.

## Import from URL

For Loom, Figma, and Cap recordings:

1. Go to your team's **Media** section
2. Click **Import**
3. Paste the share URL
4. Add a descriptive title

SageOx downloads the video server-side and processes it automatically. No need to download and re-upload.

## Supported formats

### File upload

| Type | Formats |
|------|---------|
| Video | MP4, WebM, MOV, MKV |
| Audio | MP3, WAV, M4A, OGG, FLAC, AAC, WMA |
| Transcript | VTT, SRT, TXT, MD, DOCX (skips transcription) |

### URL import

| Source | URL pattern |
|--------|-------------|
| Loom | `loom.com/share/...` |
| Figma | `figma.com/...` |
| Cap | `cap.so/...` |

## Limits

| Limit | Value |
|-------|-------|
| Max file size | 1000 MB |
| Batch upload | Up to 20 files |
| Recommended size | Under 100 MB for fastest processing |

<Callout type="info">
**Smaller files process faster.** 720p at 15fps is the sweet spot. See [Cap Setup](/docs/context-capture/video-import-cap) for optimal recording and export settings.
</Callout>

## What happens after upload

SageOx automatically:

1. **Extracts audio** and transcribes with speaker identification
2. **Detects scene changes** and extracts representative keyframes
3. **Analyzes keyframes** for UI elements, code, and visual context
4. **Generates a summary** with chapters, decisions, and action items
5. **Commits artifacts** to your Team Context

You can track progress in the pipeline view. Processing typically completes within a few minutes.

## How recordings get used

Coworkers and AI coworkers do not watch videos every time, they read the structured output:

- **Transcript text** for searchable narration
- **Keyframe descriptions** for visual context
- **Summaries** for decisions and action items

- MCP-connected tools can search the transcript, summary, and visual context.
- Repo-based AI coworkers can reference the recording while implementing features or explaining decisions.
- In **the web app**, humans can open the source recording, transcript, and keyframes directly.

## What's next

- [Video Import](/docs/context-capture/video-import): overview of all import options
- [Loom Import](/docs/context-capture/video-import-loom): Loom-specific guidance
- [Cap Setup](/docs/context-capture/video-import-cap): optimal recording settings
- [Discussions](/docs/context-capture/discussions): where imported recordings live


---

# Video import (https://sageox.ai/docs/context-capture/video-import)

# Video import

Record a walkthrough, import it, and SageOx turns it into context your team can read back from a connected tool, a coding session, or the web app. Design rationale, bug reproductions, architecture explanations, all searchable and accessible across the product.

<ScreenFrame
  id="docs/features/pipeline-complete"
  alt="A fully processed recording with pipeline stages, summary, and keyframe thumbnails"
/>

## Supported sources

Import from the tools you already use:

| Source | How to import |
|--------|---------------|
| **Loom** | Paste share URL in the web app |
| **Figma** | Paste Figma recording URL |
| **Cap** | Paste share URL or upload exported file |
| **Zoom/Meet** | Upload the downloaded recording |
| **Local files** | Drag and drop MP4, WebM, or audio files |

## How it works

You record. SageOx does the rest. Every recording goes through an extraction pipeline that turns video into structured, searchable artifacts.

```mermaid
graph LR
    A[Record] --> B[Import]
    B --> C[Transcribe]
    C --> D[Extract Keyframes]
    D --> E[Summarize]
    E --> F[Commit to Team Context]
    F --> G[AI Coworker Access]
```

The pipeline runs automatically after upload. When it finishes, extracted artifacts commit to your Team Context: the shared knowledge base your team can read back from a connected tool, a coding session, or the web app.

## What gets extracted

Each recording produces structured artifacts:

```
discussions/2026-03-20-ux-review/
├── transcript.vtt        # timestamped speech with speaker labels
├── summary.json          # chapters, decisions, action items
├── keyframes.json        # frame images + vision descriptions
└── metadata.json         # title, participants, duration
```

Coworkers and AI coworkers consume these artifacts to understand what was discussed, what decisions were made, and what the UI looked like. They do not watch the raw video every time; they read the structured output.

## Import methods

### Web app (recommended)

The fastest way to import a single recording:

1. Go to your team's **Media** section
2. Click **Import** and paste a Loom, Figma, or Cap URL
3. Or click **Upload** to drag and drop a local file

Processing starts automatically. You'll see progress in the pipeline view.

### CLI

Import directly from your terminal without leaving your editor:

```bash
ox import https://www.loom.com/share/abc123 --title "Sprint Planning"
ox import --status rec_01234567 --watch  # track progress
```

See [Video Import via CLI](/docs/context-capture/video-import-cli) for details.

### Supported formats

| Type | Formats |
|------|---------|
| Video | MP4, WebM, MOV, MKV |
| Audio | MP3, WAV, M4A, OGG, FLAC, AAC |
| Transcript | VTT, SRT, TXT, MD (skip transcription step) |
| Max size | 1000MB |

## Recording tips

<Callout type="info">
**Smaller files = faster everything.** 720p at 15fps is the sweet spot. Smaller files upload faster, transcribe faster, and extract cleaner keyframes. Target ~1 MB per minute. Your AI coworker doesn't need 4K.
</Callout>

**For best results:**

- **Narrate as you go**: Transcript quality drives extraction quality. Silent recordings produce no searchable context.
- **Keep it focused**: 5-10 minutes is ideal. Split longer sessions by topic.
- **Use descriptive titles**: Your AI coworkers search by title. "Sprint 12 Checkout Flow Redesign" beats "Recording 47".

See [Cap Setup](/docs/context-capture/video-import-cap) for optimal export settings.

## Use cases

| Record this | Your AI coworker gets |
|-------------|----------------------|
| Figma design walkthrough | Design rationale to reference when implementing UI |
| Bug reproduction | Searchable steps + screenshot keyframes |
| Architecture explanation | Context for future refactoring decisions |
| Code review walkthrough | Reasoning behind feedback and suggestions |
| Product demo | Feature intent and expected behavior |

## How recordings get used

### In a coding session

Repo-based AI coworkers can receive recording-derived context through Team Context and cite specific decisions when implementing features.

### In a connected tool

MCP-connected tools can search the transcript, summary, and related context without needing a local repo checkout.

### In the web app

Humans can open the recording, transcript, summary, and keyframes directly when they want the source material itself.

## Getting started guides

| Guide | What you'll learn |
|-------|-------------------|
| [Cap Setup](/docs/context-capture/video-import-cap) | Optimal recording and export settings |
| [Upload via Web](/docs/context-capture/video-import-web) | Drag-and-drop upload in the browser |
| [Import via CLI](/docs/context-capture/video-import-cli) | Import from your terminal |
| [Using in Coding Sessions](/docs/context-capture/video-import-coding) | How AI coworkers consume your recordings |

## What's next

- [web app recorder](/docs/context-capture/web-app-recorder): record directly from your browser
- [Discussions](/docs/context-capture/discussions): all ways to capture team knowledge
- [Team Context](/docs/features/team-context): where imported recordings live
- [Distillation](/docs/features/distill): how recordings become team memory


---

# Web app recorder (https://sageox.ai/docs/context-capture/web-app-recorder)

# Web app recorder

The SageOx web app recorder lets you capture team discussions directly from your browser. Recordings are automatically transcribed and feed into your Team Context.

## Accessing the recorder

### From the web app

1. Navigate to your team's **Media** section
2. Click **Record** to open the recorder
3. Or go directly to: `https://sageox.ai/team/{your-team-id}/media/record`

### From mobile (iPhone, Android)

The recorder works in any mobile browser. For the best experience, add it to your home screen.

## Add to home screen

Adding SageOx to your home screen gives you:
- One-tap access to the recorder
- Standalone app experience (no browser chrome)
- Faster launch times

### Safari (iPhone/iPad)

1. Open `sageox.ai` in Safari
2. Tap the **Share** button (square with arrow)
3. Scroll down and tap **Add to Home Screen**
4. Tap **Add** to confirm

The app will appear on your home screen as "Record" with the SageOx icon.

### Chrome (Android)

1. Open `sageox.ai` in Chrome
2. Tap the **three-dot menu** (⋮)
3. Tap **Add to Home screen**
4. Tap **Add** to confirm

## Recording a discussion

### Before recording

On the entry screen, you can optionally add:
- **Title** - Name your recording (auto-generated if blank)
- **Participants** - Tag who's in the discussion
- **Intent** - What type of discussion (standup, design review, etc.)
- **Context** - Notes for the AI to understand the recording

### During recording

The minimal recording interface shows:
- **Timer** - Duration of current recording
- **Waveform** - Visual audio feedback
- **Pause/Resume** - Temporarily stop audio capture
- **Stop** - End recording and begin processing

You can also:
- Edit the title
- Add or remove participants
- Add context notes
- Take photos (for whiteboard captures, diagrams)

### After recording

When you stop:
1. Recording is uploaded to SageOx
2. AI transcription begins automatically
3. Speaker identification runs on the transcript
4. You're redirected to the recording detail page

## Features

### Real-time upload

Audio chunks are uploaded as you record, not after you stop. This means:
- No waiting for upload after recording
- Audio already uploaded is not lost if your connection drops
- Works on slow connections

### AI transcription

Recordings are automatically transcribed with:
- Speaker diarization (identifies different voices)
- Timestamps for every segment
- Searchable transcript text

### Speaker assignment

After transcription, you can:
- Match detected speakers to team members
- Listen to voice samples for each speaker
- Jump to specific quotes in the audio

### Photo capture

During recording, tap the camera icon to:
- Capture whiteboard content
- Save diagrams and sketches
- Reference photos are attached to the recording

## Mobile limitations

Mobile browsers have limitations that affect recording:

### Background audio

**iOS Safari and Android Chrome stop recording when you switch apps.** This is a browser security restriction, not a SageOx limitation.

If the recording stops due to app switching:
- Audio captured before leaving is preserved
- You'll see a notification when returning
- The partial recording is still accessible

### Battery and storage

- Long recordings use significant battery
- Audio is uploaded in real-time (uses data)
- Consider WiFi for recordings over 30 minutes

## Troubleshooting

### Microphone permission denied

1. Open your browser settings
2. Find SageOx in site permissions
3. Enable microphone access
4. Reload the page

### Recording won't start

- Check that another app isn't using the microphone
- Try closing other browser tabs
- On mobile, ensure the device isn't on Do Not Disturb

### Poor audio quality

- Move closer to the microphone
- Reduce background noise
- Check if you're using the correct microphone (laptop vs headset)

## What's next

- [Discussions](/docs/context-capture/discussions) - Managing recorded content
- [Getting Started](/docs/getting-started) - Full setup guide


---

# SageOx + Cap (https://sageox.ai/docs/cookbooks/cap)

# SageOx + Cap

Cap gives you full control over recording quality and export settings, something Loom doesn't offer. This cookbook shows how to configure Cap for optimal SageOx extraction and build a recording habit that compounds into searchable team knowledge.

## Why Cap over Loom

| Feature | Cap | Loom |
|---------|--------|------|
| Export control | Full resolution/fps/quality settings | Limited options |
| Local storage | Files stay on your machine until you upload | Uploads immediately |
| Editing | Trim, cut, annotate before export | Basic trimming only |
| Cost | Free | Free tier has limits |
| Privacy | Nothing leaves your machine until you choose | Cloud-first |

For quick, one-off recordings, Loom works. For regular walkthroughs where you want consistent quality and smaller file sizes, Cap is better.

## What you need

- [Cap](https://github.com/CapSoftware/cap) installed (free)
- A SageOx account with a connected repo (`ox init`)

## The workflow

### 1. Record your screen

Open Cap and start a screen recording. Narrate as you go; the transcript quality drives extraction quality.

**Good recordings have:**
- Clear narration explaining *why*, not just *what*
- Focused scope (5-10 minutes max)
- Minimal desktop clutter

### 2. Export with optimal settings

After recording, open Cap's export dialog and configure:

| Setting | Value | Why |
|---------|-------|-----|
| **Format** | MP4 | Universal compatibility, best compression |
| **Resolution** | 720p | Sufficient for UI walkthroughs, fast to process |
| **Frame Rate** | 15 fps | Smooth enough for demos, half the data of 30fps |
| **Quality** | Social | Best size-to-quality ratio for AI extraction |

These settings produce ~8 MB per minute, fast to upload, fast to process.

### 3. Upload to SageOx

1. Go to your team's **Media** section at [sageox.ai](https://sageox.ai)
2. Click **Upload**
3. Drag in your exported MP4
4. Add a descriptive title

Processing starts automatically. Transcription, keyframe extraction, and summarization run in the background.

### 4. Your AI coworker references it

The next time Claude Code starts a session, your recording is in context. Your AI coworker can reference the decisions you explained, the UI you walked through, or the bug you reproduced.

## Recipes

### Bug reproduction recordings

When you find a bug, record the reproduction steps:

1. Show the starting state
2. Narrate the steps: "I'm clicking the submit button with an empty form..."
3. Show the unexpected behavior
4. Explain what you expected instead

Export and upload with a title like "Bug: Cart total shows $0 after removing items". Your AI coworker can analyze the recording to help find the root cause.

### Architecture walkthrough recordings

Before diving into a refactor, record a walkthrough of the current state:

1. Open the relevant code files
2. Explain how data flows through the system
3. Point out the pain points you want to address
4. Sketch the target architecture (whiteboard or drawing tool)

This gives your AI coworker the full context when you ask it to help with the refactor.

### Code review walkthrough recordings

Instead of writing long PR comments, record a 3-minute walkthrough:

1. Open the PR diff
2. Walk through the changes
3. Explain your feedback verbally
4. Highlight specific lines that need attention

The recording captures nuance that's hard to convey in text. Upload it and link in the PR.

### Onboarding recordings

Record walkthroughs for common onboarding topics:

- "How our auth system works"
- "The request lifecycle from API to database"
- "How to set up the local dev environment"

New team members get these recordings in their AI coworker context from day one.

## Tips for better recordings

**Narrate your reasoning**
"I'm checking the network tab because I suspect the preflight is failing" beats silent clicking.

**Say code names out loud**
"This is the `RecordingService` in `apps/workflow`" creates transcript anchors that link to your codebase.

**Keep it under 10 minutes**
Shorter recordings produce tighter summaries. Split longer sessions by topic.

**Clean your desktop**
Close Slack, hide bookmarks, full-screen the app you're demoing. Fewer distractions means better keyframe extraction.

**Use descriptive titles**
"Sprint 12 Checkout Flow Redesign" beats "Recording 47". AI coworkers search by title.

## Build the habit

The highest-value pattern: **record a 2-minute Cap walkthrough after every meaningful decision.**

- Chose an architecture approach? Record why.
- Fixed a tricky bug? Record the root cause.
- Designed a new component? Record the rationale.

Within a week, your Team Context has a searchable history of *why* things are the way they are.

## What's next

- [Cap Setup](/docs/context-capture/video-import-cap): detailed export settings guide
- [Video Import](/docs/context-capture/video-import): all import options and formats
- [SageOx + Loom](/docs/cookbooks/loom): alternative recording workflow
- [Using Recordings in Coding Sessions](/docs/context-capture/video-import-coding): how AI coworkers use your recordings


---

# SageOx + Figma (https://sageox.ai/docs/cookbooks/figma)

# SageOx + Figma

Design decisions happen in Figma: component rationale, spacing tradeoffs, accessibility choices, interaction patterns. But that context stays locked in someone's head or buried in comment threads. This cookbook turns Figma design walkthroughs into structured knowledge your AI coworkers can reference when implementing UI.

## What you need

**To upload design walkthroughs** (designers, stakeholders, no CLI needed):
- A SageOx team account
- Screen recordings of Figma design sessions (use Loom, Cap, or Figma's built-in recording)

**To implement with design context** (developers):
- SageOx CLI installed (`ox`) with a connected repo (`ox init`)
- A coding agent (Claude Code, Codex, etc.)

## The workflow

### 1. Record your Figma walkthrough

Open your Figma file and start a screen recording. Walk through the design while narrating your decisions:

- **Why** you chose this layout over alternatives
- **How** components relate to existing patterns
- **What** edge cases the design handles (empty states, error states, responsive breakpoints)

Keep recordings under 10 minutes. If a design review runs longer, split by feature area.

### 2. Upload the recording

1. Go to your team's **Media** section at [sageox.ai](https://sageox.ai)
2. Click **Import** and paste the recording URL (Loom, Figma, or Cap)
3. Or click **Upload** to drag in a local recording
4. Add a descriptive title like "Dashboard redesign, card layout rationale"

No CLI needed. SageOx transcribes the narration, extracts keyframes of the Figma screens, and commits structured artifacts to your Team Context. Processing takes 1–3 minutes.

<Callout type="info">
**Developers** can also import via CLI, useful for bulk imports or scripted workflows. See [CLI import](/docs/context-capture/video-import-cli).
</Callout>

### 3. Your AI coworker implements with context

When an engineer (or their AI coworker) picks up the implementation, the design walkthrough is already in context. Instead of interpreting a static Figma link, the AI coworker knows:

- The spacing rationale you narrated
- Which components you pointed at and why
- The edge cases you called out on screen
- How this design relates to existing patterns

**Before SageOx:** "Why is this card 16px padding instead of 24px?" → open Figma, search comments, ping the designer.

**After SageOx:** "Why is this card 16px padding instead of 24px?" → your AI coworker cites the walkthrough where you explained the density requirements for data-heavy dashboards.

## Recipes

### Design review recordings

Record your design review sessions, the back-and-forth is where the real decisions happen. Upload the recording to your team's **Media** section when the review wraps.

The transcript captures both the designer's rationale and the engineer's implementation questions, creating a complete decision record. Import these with titles like "Design review, onboarding flow v2".

### Component documentation walkthroughs

When you create a new component in Figma, record a 2-minute walkthrough of its variants, states, and usage guidelines.

This is especially valuable for components with complex state (loading, error, empty, partial) that are hard to convey in a static Figma frame. Title these clearly: "Alert banner, variants and usage guidelines".

### Narrate your design system decisions

Walk through your design system changes and explain the reasoning:

- "We're moving from 8px to 6px grid because..."
- "This color scale replaces the old one because..."
- "The new elevation system works like..."

These recordings become the institutional memory for your design system, when someone asks "why is our primary green and not blue?", the answer exists in context.

## Tips for better Figma recordings

**Zoom in on the details**
SageOx extracts keyframes: close-ups of spacing, color tokens, and component anatomy capture better than full-canvas shots.

**Name your layers**
When you hover or click, visible layer names in Figma give the transcript anchors that link to implementation.

**Show the before and after**
If you're redesigning, briefly show what exists today before walking through the new design.

**Call out responsive behavior**
Resize the frame on camera, "at 768px, these cards stack to a single column because..."

## Build the habit

The highest-value pattern: **record a walkthrough every time you hand off a design.**

The handoff recording replaces the sync meeting, outlives the Slack thread, and gives every future engineer (human or AI) the full context of your design intent.

Anyone on your team can upload recordings through the web: no CLI, no setup. Within a month, your Team Context has a visual history of *why* the UI looks the way it does, not just the final pixels, but the reasoning behind every tradeoff.

## What's next

- [Upload via web](/docs/context-capture/video-import-web): drag-and-drop upload from the SageOx web interface
- [Video Import](/docs/context-capture/video-import): all import options and supported formats
- [Cap Setup](/docs/context-capture/video-import-cap): optimal recording settings
- [SageOx + Loom](/docs/cookbooks/loom): the complete Loom import workflow
- [SageOx + Claude Code](/docs/developers/claude-code): how your AI coworker uses imported recordings


---

# Cookbooks (https://sageox.ai/docs/cookbooks)

# Cookbooks

Practical guides that walk through complete workflows, from setup to daily habit. Each cookbook covers a specific integration or use case with concrete examples.

## Recording integrations

Turn the tools you already use into AI-accessible team knowledge.

| Cookbook | What you'll build |
|----------|-------------------|
| [SageOx + Loom](/docs/cookbooks/loom) | Import Loom walkthroughs and make them searchable for AI coworkers |
| [SageOx + Figma](/docs/cookbooks/figma) | Turn design walkthroughs into context your AI coworkers reference when implementing UI |
| [SageOx + Cap](/docs/cookbooks/cap) | Screen recording with full export control for optimal file sizes and quality |

## AI integrations

Connect SageOx to your AI coding tools.

| Cookbook | What you'll build |
|----------|-------------------|
| [SageOx + OpenClaw](/docs/cookbooks/openclaw) | Run AI agent factories with team context, distillation, and Slack digests |

Wiring up an individual coding agent lives under **Developers**: [SageOx + Claude Code](/docs/developers/claude-code), [SageOx + Codex](/docs/developers/codex), and the full [supported-agents matrix](/docs/developers/coding-agents).

## What's next

- [Getting Started](/docs/getting-started): initial SageOx setup
- [Team Context](/docs/features/team-context): understand what's in your team's shared knowledge
- [Video Import](/docs/context-capture/video-import): import recordings from Loom, Figma, Cap


---

# SageOx + Loom (https://sageox.ai/docs/cookbooks/loom)

# SageOx + Loom

You already record Loom walkthroughs. This cookbook turns them from ephemeral Slack links into structured knowledge your AI coworkers can reference during coding sessions.

## What you need

**To upload Loom recordings** (anyone on the team, no CLI needed):
- A SageOx team account
- Loom recordings you want to preserve

**To implement with recording context** (developers):
- SageOx CLI installed (`ox`) with a connected repo (`ox init`)
- A coding agent (Claude Code, Codex, etc.)

## The workflow

### 1. Upload or import a Loom recording

1. Copy the share URL from any Loom video
2. Go to your team's **Media** section at [sageox.ai](https://sageox.ai)
3. Click **Import**
4. Paste the Loom URL and add a descriptive title

SageOx downloads the video and processes it automatically. Processing takes 1–3 minutes depending on length.

### 2. See what SageOx extracts

Once processing completes, your recording becomes a structured artifact:

| Artifact | What it contains |
|----------|------------------|
| **Transcript** | Full text with timestamps and speaker labels |
| **Summary** | Key points, decisions, and action items |
| **Keyframes** | Screenshots at visually significant moments with AI descriptions |
| **Metadata** | Title, duration, import date |

### 3. Your AI coworker references it

The next time an AI coworker starts a session, the recording's content is part of its context. It can reference the walkthrough's decisions, the architecture you drew on screen, or the bug reproduction steps you narrated.

**Before SageOx:** "Why did we redesign the upload API?" → grep through Slack, find nothing, guess.

**After SageOx:** "Why did we redesign the upload API?" → your AI coworker cites the Loom walkthrough where you explained the rate-limiting issues.

## Recipes

### Import your Loom back catalog

Got months of Loom recordings scattered across Slack? Import them one at a time through the web UI. Each import runs independently, queue up as many as you have.

For large backlogs, consider prioritizing:
1. Architecture and design decision recordings
2. Onboarding walkthroughs
3. Bug investigation recordings
4. Feature demos with design rationale

### Record with better extraction in mind

SageOx extracts more value when you record with a few habits:

**Narrate your reasoning, not your clicks**
"I'm switching to the network tab because I suspect the preflight is failing" beats silent mousing.

**Say names out loud**
"This is the `RecordingService` in `apps/workflow`" gives the transcript anchors that link to your codebase.

**Keep it under 10 minutes**
Shorter recordings produce tighter summaries. If you're going longer, the topic deserves two recordings.

### Download-then-upload workflow

If your Loom is behind SSO or you prefer local files:

1. In Loom, click **...** → **Download** → save the MP4
2. Go to your team's **Media** section
3. Click **Upload** and drag in the file
4. Add a descriptive title

Both methods produce the same result, URL import is faster when available.

## Build the habit

The highest-value pattern: **record a 2-minute Loom after every meaningful decision.**

- Architecture call? Record it.
- Bug root-caused? Record the fix.
- PR feedback session? Record the walkthrough.

Anyone on your team can upload recordings through the web: no CLI, no setup. Within a week, your Team Context has a searchable history of *why* things are the way they are, not buried in Slack threads, not lost in someone's head.

## What's next

- [Upload via web](/docs/context-capture/video-import-web): drag-and-drop upload from the SageOx web interface
- [Video Import](/docs/context-capture/video-import): all import options and supported formats
- [Loom Import](/docs/context-capture/video-import-loom): detailed Loom import guide
- [SageOx + Claude Code](/docs/developers/claude-code): how your AI coworker uses imported recordings
- [SageOx for solo players](/docs/quickstart/solo): build a personal knowledge base before your team joins


---

# SageOx + OpenClaw (https://sageox.ai/docs/cookbooks/openclaw)

# SageOx + OpenClaw

OpenClaw orchestrates automated AI coding sessions: spawning agents that work on issues, PRs, and maintenance tasks without human intervention. SageOx gives those agents the same team context a human coworker would have, and their discoveries flow back into your team's knowledge base.

## How it works

```mermaid
graph TD
    OC[OpenClaw Factory] -->|spawns| CS[Claude Code Session]
    CS -->|reads CLAUDE.md| AP[ox agent prime]
    AP -->|injects| TC[Team Context]
    CS -->|session artifacts| L[Ledger]
    L -->|distillation| M[Team Memory]
    M -->|feeds back| TC
```

Every factory-spawned session follows the same lifecycle as a human coding session, it receives team context on startup, and its discoveries flow back into the knowledge base.

## What you need

- SageOx CLI installed (`ox`)
- A connected repo (`ox init`)
- An [OpenClaw](https://openclaw.dev) account with factory access

## Setup

### 1. Connect your repo

<Terminal>
  <TerminalCommand>ox login</TerminalCommand>
  <TerminalCommand>cd ~/code/my-project</TerminalCommand>
  <TerminalCommand>ox init</TerminalCommand>
</Terminal>

`ox init` configures your `CLAUDE.md` with the `ox agent prime` hook. This is the universal integration point, any tool that starts Claude Code in your repo gets SageOx context automatically, including OpenClaw.

### 2. Verify factory agents receive context

When OpenClaw spawns a session, it starts Claude Code in your repo. Claude Code reads `CLAUDE.md` and runs `ox agent prime`. Verify with:

<Terminal>
  <TerminalCommand>ox status</TerminalCommand>
</Terminal>

Each factory agent receives the full team context payload:

| Context layer | What the agent receives |
|---------------|-------------------------|
| **Team norms** | AGENTS.md conventions, coding standards |
| **Architecture decisions** | Distilled discussions and recordings |
| **Domain terminology** | Team-specific vocabulary and concepts |
| **Recent memory** | Summaries from recent team activity |
| **Current work** | What's happening across your product |

### 3. Enable session capture

Configure factory sessions to use session capture:

```
/ox-session-start
... agent works on the issue ...
/ox-session-stop
```

Session transcripts (the agent's reasoning, decisions, and code changes) get committed to your repo's Ledger and feed into future sessions.

## The overnight factory pattern

Run OpenClaw agents on a nightly schedule against your backlog:

1. **OpenClaw picks issues** labeled `factory-ready` from your tracker
2. **For each issue**, it spawns a Claude Code session in the relevant repo
3. **`ox agent prime` injects team context** including yesterday's distilled insights
4. **The agent works on the issue**, commits code, opens a PR
5. **Session artifacts are captured** to the Ledger
6. **Distillation extracts insights** for future sessions

Your team arrives to PRs ready for review, with full context on why each change was made.

## Multi-agent awareness

When multiple agents run in parallel (each in its own git worktree working on a different issue) SageOx ensures they share context:

- An agent refactoring the auth module knows another agent is adding a new endpoint that depends on auth
- An agent updating types knows another agent changed the schema those types derive from
- Merge conflicts and duplicate work drop because agents are aware of each other's in-flight changes

This is the difference between N isolated agents and N agents that collaborate.

## Cross-platform context

Most coding agents have some form of memory or team context, but it's locked to that vendor. Claude Code's memory doesn't reach Codex. If your team uses more than one agent platform, each agent operates blind to what the others know.

SageOx sits underneath all of them. Because context flows through the repo itself via `ox agent prime`, it works with any agent that reads `CLAUDE.md` or `AGENTS.md`. A discovery made in one agent is available to every other agent in the next session.

## The compounding loop

The real power is the feedback loop between factory agents and distillation:

1. **Factory agent works on an issue**, discovers that the payment service needs a retry wrapper
2. **Session gets captured** to the Ledger
3. **Distillation extracts the insight**, "payment service calls need retry wrappers due to intermittent timeouts"
4. **Next factory session receives this** via team context
5. **That agent adds retries proactively** when touching payment code

After a month of factory runs plus distillation, your agents have absorbed hundreds of codebase-specific insights that no prompt engineering could replicate.

## Best practices

**Start with well-scoped issues**
Factory agents work best on issues with clear acceptance criteria. "Add retry logic to payment service" beats "improve reliability".

**Review PR descriptions**
Factory agents include their reasoning in PR descriptions. This becomes part of the permanent record and feeds future context.

**Capture important sessions**
Use `/ox-session-start` for sessions that produce valuable insights. Not every session needs capturing, focus on debugging breakthroughs and architecture decisions.

**Feed recordings into context**
Import Loom walkthroughs and design sessions. Factory agents implementing UI benefit from design rationale captured in recordings.

## What's next

- [SageOx + Claude Code](/docs/developers/claude-code): the full coding session lifecycle
- [SageOx + Loom](/docs/cookbooks/loom): feed design walkthroughs into the context loop
- [SageOx + Figma](/docs/cookbooks/figma): turn design decisions into agent context
- [Distillation](/docs/features/distill): how the memory pipeline works
- [Video Import](/docs/context-capture/video-import): import recordings that feed into context


---

# SageOx + Slack via OpenClaw (https://sageox.ai/docs/cookbooks/slack-openclaw)

# SageOx + Slack via OpenClaw

Your team makes decisions in Slack every day. Architecture calls in `#engineering`, deployment approvals in `#ops`, debugging breakthroughs in DMs. Within a week, those threads are buried. Within a month, they're gone.

This cookbook uses **OpenClaw** to bridge Slack and SageOx, automatically capturing meaningful conversations as searchable Team Context.

## What you need

- SageOx CLI installed and a connected repo (`ox init`)
- An [OpenClaw](https://openclaw.dev) account
- Slack workspace admin access (for the bot install)

## How it works

```mermaid
graph LR
    A[Slack thread] -->|OpenClaw bot| B[Recording created]
    B -->|SageOx pipeline| C[Transcript + summary]
    C --> D[Team Context]
    D --> E[AI coworker sessions]
```

OpenClaw watches Slack channels you configure. When a conversation matches your criteria (length, keywords, emoji reactions) it creates a SageOx recording from the thread content. SageOx processes it through the same pipeline as any recording: transcription, summarization, and indexing into Team Context.

## Setup

### 1. Install the OpenClaw Slack bot

Follow the [OpenClaw Slack integration guide](https://openclaw.dev/docs/slack) to add the bot to your workspace. Grant it access to the channels you want monitored.

### 2. Connect OpenClaw to SageOx

<Terminal>
  <TerminalComment>Link your OpenClaw account to SageOx</TerminalComment>
  <TerminalCommand>ox integrations connect openclaw</TerminalCommand>
</Terminal>

This establishes the bridge so OpenClaw can create recordings in your SageOx team.

### 3. Configure capture rules

Define which Slack conversations get captured. OpenClaw supports rules based on:

| Trigger | Example |
|---------|---------|
| **Channel** | All threads in `#architecture-decisions` |
| **Emoji reaction** | Any thread with a `:bookmark:` reaction |
| **Thread length** | Threads with 5+ messages |
| **Keyword** | Threads mentioning "decided", "agreed", "going with" |

Start narrow. A single channel or emoji trigger is better than capturing everything and drowning in noise.

### 4. Verify it works

Post a test thread in a monitored channel, trigger your capture rule, and confirm the recording appears:

<Terminal>
  <TerminalCommand>ox recordings list --limit 5</TerminalCommand>
</Terminal>

## Recipes

### The `:bookmark:` workflow

The lowest-friction approach: tell your team to react with `:bookmark:` on any Slack thread worth preserving. OpenClaw captures bookmarked threads automatically.

This works because it's opt-in and zero-effort, no workflow changes, no new tools. Someone already bookmarks important threads. Now those bookmarks become permanent team knowledge.

### The decisions channel

Create a `#decisions` channel (or `#architecture`, `#tech-decisions`, whatever fits). Configure OpenClaw to capture every thread in this channel.

The social contract: if you make a decision, post it to `#decisions`. One sentence is enough, "Going with Postgres JSONB for metadata, schema is too unstable for columns." The full context lives in the thread.

Within a month, your AI coworkers can answer "why did we choose X?" by citing the actual discussion.

### Capture debugging sessions

Long debugging threads in `#incidents` or `#bugs` are gold: they contain the symptoms, the investigation, the false leads, and the fix. Configure OpenClaw to capture threads over 10 messages in your incident channels.

Next time a similar bug surfaces, your AI coworker has the debugging playbook from last time.

## What gets captured

SageOx processes Slack threads the same way it processes any recording:

| Artifact | Source |
|----------|--------|
| **Transcript** | Thread messages, preserving author and timestamp |
| **Summary** | Key decisions, action items, and conclusions |
| **Annotations** | Links to code, PRs, and concepts mentioned in the thread |

The thread becomes a first-class knowledge artifact: searchable, referenceable, and available to every AI coworker session.

## What's next

- [SageOx + Claude Code](/docs/developers/claude-code): how your AI coworker uses captured context
- [SageOx + Loom](/docs/cookbooks/loom): capture video walkthroughs alongside Slack threads
- [SageOx for solo players](/docs/quickstart/solo): start building context before your team adopts


---

# Agent factories (https://sageox.ai/docs/developers/agent-factories)

ox works with any tool that orchestrates coding agents: OpenClaw, Factory Droid, custom orchestration. However the session is launched, the integration is identical: the agent primes on startup, Team Context flows in, and artifacts are captured back.

## The integration is the same

An orchestrator changes how a session starts, not what ox does inside it. The orchestrator spawns the agent, the agent runs `ox agent prime`, and from there the [prime-work-capture loop](/docs/developers/how-it-works) runs unchanged.

```mermaid
graph LR
    O["Orchestrator"] --> A["Agent starts"]
    A --> P["ox agent prime"]
    P --> W["Agent works"]
    W --> C["Artifacts captured to Ledger"]
```

Because priming is wired into the repo's `CLAUDE.md` (or the equivalent for other agents), it fires regardless of launch path: terminal, IDE, API, or factory. You don't configure the orchestrator to know about ox; the agent carries the integration with it.

## Many agents, one Team Context

When a factory runs several agents in parallel against the same repo, they all prime from the same [Team Context](/docs/features/team-context). Every agent sees the same conventions, decisions, and domain terms, so parallel work stays coherent instead of drifting apart.

```mermaid
graph LR
    T["Team Context"] --> A1["Agent 1"]
    T --> A2["Agent 2"]
    T --> A3["Agent 3"]
    A1 --> N["New decisions"]
    A2 --> N
    A3 --> N
    N --> T
```

As each agent's session is captured, its decisions feed back into the shared knowledge that future sessions consume. This is the multiplayer loop at scale: more agents working in parallel means the context compounds faster.

<Callout type="info">
Captured artifacts become available to other sessions once committed. Agents running concurrently see each other's work on the next prime, not mid-session, so coordinate parallel agents around natural commit boundaries.
</Callout>

## What's next

- [How it works](/docs/developers/how-it-works): the loop every orchestrated session runs
- [Session recording](/docs/developers/session-recording): how captured work becomes shared memory
- [Coding agents](/docs/developers/coding-agents): which agents orchestrators can drive


---

# SageOx + Claude Code (https://sageox.ai/docs/developers/claude-code)

# SageOx + Claude Code

Claude Code is the deepest ox integration. It gets the same prime-work-capture loop every agent gets, plus real-time hooks, slash commands, installed rules, and MCP support that no other agent has today.

For the general model (how priming injects Team Context and how sessions are captured) read [how it works](/docs/developers/how-it-works) first. This page covers what's Claude-Code-specific.

## Setup

<Terminal>
  <TerminalCommand>curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash</TerminalCommand>
  <TerminalCommand>ox login</TerminalCommand>
  <TerminalCommand>cd ~/code/my-project</TerminalCommand>
  <TerminalCommand>ox init</TerminalCommand>
</Terminal>

`ox init` configures Claude Code to run `ox agent prime` at session start. That's the entire setup, start `claude` as normal and Team Context is injected automatically.

## Real-time hooks

ox wires into Claude Code's lifecycle events, so context injection and session capture happen without you thinking about it.

| Hook | What ox does |
|---|---|
| `SessionStart` | Runs `ox agent prime` to inject Team Context |
| `Stop` | Captures the session to the Ledger and summarizes it |
| `PostToolUse` | Tracks the work as it happens for richer session capture |
| `UserPromptSubmit` | Prepends `[ox-recall]` from prior work on question-like prompts |

These fire automatically in any connected repo. No manual `start` or `stop` step is required for the common case.

## Slash commands

For explicit control, ox installs slash commands you can run inside a Claude Code session.

| Command | What it does |
|---|---|
| `/ox-session-start` | Begin recording a session manually |
| `/ox-session-stop` | End recording, commit, and upload to the Ledger |
| `/ox-session-status` | Show the current session's state |
| `/ox-prime` | Re-inject Team Context after a clear or compact |

<Terminal>
  <TerminalComment>Inside a Claude Code session</TerminalComment>
  <TerminalCommand>/ox-session-start</TerminalCommand>
  <TerminalComment>... work on your feature ...</TerminalComment>
  <TerminalCommand>/ox-session-stop</TerminalCommand>
</Terminal>

## Installed rules

ox installs a canonical rule at `.claude/rules/ox.md` plus a pointer under the `.claude/rules/sageox/` namespace. The pointer teaches Claude Code to discover your team's rules in their canonical home rather than syncing every team rule into every cloned repo.

The `sageox/` namespace reserves room for future ox-installed rules without cluttering your `.claude/rules/` directory. Uninstalling removes only ox-stamped files, your own rules are left untouched.

## MCP support

Claude Code can reach SageOx over MCP, giving the agent live access to team knowledge and tools beyond the static prime payload. This is the path that lets the agent query across team-shared content during a session.

## Anti-entropy auto-recovery

ox self-heals rather than failing loudly. If a session upload is interrupted, a hook set drifts, or a summary is missing, the background daemon detects the gap and repairs it on its next tick.

<Callout type="info">
ox leaves your hand-authored `.claude/settings.json` alone. It only rewrites the hooks shape when Claude Code would actually reject the file: so your formatting, comments, and permission rules survive.
</Callout>

## CLAUDE.md setup

When you run `ox init`, it adds this to your repo's `CLAUDE.md` so priming happens regardless of how the session was started: terminal, IDE, or orchestrator:

```markdown
## SageOx

Run `ox agent prime` at session start, after /clear, and after /compact.
```

## The compounding loop

The value isn't any single session: it's the loop that makes each one start smarter than the last.

1. **You record a decision**: a Loom walkthrough, a voice memo, a team discussion.
2. **SageOx processes it** into structured Team Context.
3. **Your AI coworker references it** in the next coding session.
4. **That session produces new insights** captured to the Ledger.
5. **Future sessions start smarter** because of steps 1–4.

After a week, Claude Code knows not just your code but *why* it's shaped the way it is. After a month, it carries context that would take a new hire weeks to absorb.

## Multiplayer, shared context across coworkers

When several people work the same repo, they all receive the same Team Context, and decisions made in one session become available to every future session, human or AI.

```mermaid
graph TD
    TC["Team Context"] --> S1["Session: Person A"]
    TC --> S2["Session: Person B"]
    TC --> S3["Session: Agent factory"]
    S1 -->|new insights| TC
    S2 -->|new insights| TC
    S3 -->|new insights| TC
```

The integration point is always `ox agent prime` via `CLAUDE.md`. Any tool that starts Claude Code in your repo (terminal, IDE, or orchestrator) gets SageOx context with no extra configuration. For running Claude Code at scale, see [Agent factories](/docs/developers/agent-factories).

## Best practices

**Record decisions, not just code**
The highest-value context is *why* things are the way they are. Record a 2-minute Loom after architecture calls, bug fixes, and design decisions.

**Use descriptive session names**
When you run `/ox-session-start`, the session gets a name. "Auth refactor investigation" is more findable than "Session 47".

**Review your Team Context**
Periodically browse `.sageox/teams/primary/` to see what your AI coworkers are reading. Edit `AGENTS.md` to add conventions they should follow.

**Capture onboarding sessions**
When a new teammate explores the codebase with Claude Code, capture that session. Their questions and the AI's explanations become documentation for the next person.

## What's next

- [How it works](/docs/developers/how-it-works): the general prime-work-capture model
- [Supported coding agents](/docs/developers/coding-agents): every agent and its tier
- [Session recording](/docs/developers/session-recording): how captured sessions become team memory
- [Agent factories](/docs/developers/agent-factories): orchestrating Claude Code at scale
- [Team Context](/docs/features/team-context): what's in it and how to edit it


---

# CodeDB: smarter code navigation (https://sageox.ai/docs/developers/codedb)

CodeDB is a semantic index of your codebase that your AI coworker can query during a session: search by meaning, trace git history, and navigate cross-references, instead of falling back on grep and a stack of file reads.

## What CodeDB indexes

CodeDB builds a local database from your repository: code symbols, git history, and (optionally) GitHub activity. Your AI coworker queries it during sessions to navigate with precision rather than guessing at file names.

| Source | Content |
|--------|---------|
| Code symbols | Functions, types, classes |
| Git history | Commits, diffs, file changes |
| GitHub PRs and issues | Titles, descriptions, comments, review threads |

The index lives in your repository's `.sageox/cache/codedb/` directory and never leaves your machine. SageOx servers never see your source code.

## Index your repo

Run the index once. It updates incrementally after that, only new commits since the last run are processed.

<Terminal>
  <TerminalComment>Build or update the code index (run once, updates automatically)</TerminalComment>
  <TerminalCommand>ox code index</TerminalCommand>
</Terminal>

Force a full rebuild after a major refactor or when results look stale:

<Terminal>
  <TerminalCommand>ox code index --full</TerminalCommand>
</Terminal>

Check what's indexed and when it last ran:

<Terminal>
  <TerminalCommand>ox code status</TerminalCommand>
</Terminal>

## Search by meaning

Once indexed, query CodeDB with natural language. Search matches on what code does, not on a text pattern alone.

<Terminal>
  <TerminalComment>Find code by intent, not by name</TerminalComment>
  <TerminalCommand>ox code search "authentication middleware"</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Limit results and get JSON for scripting</TerminalComment>
  <TerminalCommand>ox code search "database migration" --limit 10 --full-json</TerminalCommand>
</Terminal>

## What your AI coworker gains

When a session starts, your AI coworker gains access to CodeDB queries. That turns a few common questions from slow file-spelunking into direct lookups:

- **Semantic search**: find functions and types by what they do, not by guessing the name
- **History queries**: "when did this behavior change?" answered from git history instantly
- **Cross-reference navigation**: understand how modules connect across the codebase
- **PR and issue context**: reference decisions from code review threads

Without CodeDB, your AI coworker relies on grep and file reads. With it, the agent has a map of your codebase, and spends its turns reasoning instead of searching.

<Callout type="info">
CodeDB is local-only by design. Your code and git history stay on your machine; the index is rebuilt from your repo, never uploaded.
</Callout>

## What's next

- [Supported coding agents](/docs/developers/coding-agents): which agents can query CodeDB
- [SageOx + Claude Code](/docs/developers/claude-code): CodeDB in a live coding session
- [ox index](/docs/cli/index-cmd): full indexing reference, flags, and GitHub activity


---

# SageOx + Codex (https://sageox.ai/docs/developers/codex)

# SageOx + Codex

OpenAI Codex is a bundled, **Silver-tier** ox integration. `ox init` wires it up:
Codex primes your Team Context at session start, its hooks fire, and its sessions
are captured to the Ledger in real time, the same prime-work-capture loop every
agent gets, with a touch less depth than [Claude Code](/docs/developers/claude-code).

For the general model, how priming injects Team Context and how sessions are
captured, read [how it works](/docs/developers/how-it-works) first. This page
covers what's Codex-specific.

## Setup

<Terminal>
  <TerminalCommand>curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash</TerminalCommand>
  <TerminalCommand>ox login</TerminalCommand>
  <TerminalCommand>cd ~/code/my-project</TerminalCommand>
  <TerminalCommand>ox init</TerminalCommand>
</Terminal>

`ox init` configures Codex to run `ox agent prime` at session start. Codex's
adapter ships inside ox, no separate install.

### Install hooks

Codex hooks are stable and enabled by default. `ox init` installs the project
hooks so session capture and lifecycle events fire automatically.

<Terminal>
  <TerminalCommand>ox integrate install --codex</TerminalCommand>
</Terminal>

Verify the wiring:

<Terminal>
  <TerminalCommand>ox doctor</TerminalCommand>
</Terminal>

## What's Codex-specific

| Aspect | Codex behavior |
|---|---|
| Tier | Silver, core parity with Claude Code's Gold |
| Source | Bundled (ships inside ox) |
| Session capture | Real-time, tailing append-only JSONL session files |
| Hooks | `SessionStart`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SessionEnd` |
| Context injection | `ox agent prime` at session start |

`SessionEnd` finalizes the recording when the Codex conversation ends. After
the hooks are installed, capture and priming run without you thinking about
them. See the [support matrix](/docs/developers/coding-agents) for how the tiers
compare.

## Recipe 1: Context-aware Codex sessions

Start Codex as normal. ox primes your Team Context first, so Codex follows your
team's patterns instead of generic best practices from its training data, it
knows your conventions, architecture decisions, domain terms, and current work
before it writes a line.

## Recipe 2: Feed recordings into Codex context

Import your Loom walkthroughs, Figma design sessions, and team recordings. Codex
references them during implementation, citing the designer's explanation from a
walkthrough, not just interpreting a static mockup.

Import via the [web UI](https://sageox.ai); recordings are transcribed and added
to Team Context, which flows to Codex via `ox agent prime`. See
[Video import](/docs/context-capture/video-import).

## Recipe 3: Multi-agent workflows

Run Codex alongside other agents, they all share one Team Context. A decision
discovered in one session becomes available to every future session, regardless
of which agent surfaced it.

```mermaid
graph TD
    TC["Team Context"] --> C1["Codex session"]
    TC --> C2["Claude Code session"]
    TC --> C3["Cursor session"]
    C1 -->|new insights| TC
    C2 -->|new insights| TC
```

## Recipe 4: Codex in CI/CD pipelines

Running Codex in automated pipelines (code review, test generation, docs)?
Authenticate with a [Personal Access Token](/docs/cli/pats) instead of
`ox login`:

```bash
export SAGEOX_TOKEN="${{ secrets.SAGEOX_TOKEN }}"
ox agent prime
```

ox auto-detects the CI environment and skips the daemon, local Ledger, and
CodeDB setup, no flag required. See
[Running ox in constrained environments](/docs/cli/ephemeral-mode) for the full
reference, including Claude Code Cloud, Devin, and GitHub Actions recipes.

## Best practices

**Keep project hooks installed**
Run `ox doctor` if priming or session capture stops firing. It detects missing
Codex hooks and shows the repair command.

**Record decisions that affect code patterns**
The more context in your Team Context, the better Codex performs. Record
architecture calls, design decisions, and convention changes.

**Review what Codex receives**
Browse `.sageox/teams/primary/` to see your Team Context. Edit `AGENTS.md` to add
conventions Codex should follow.

## What's next

- [How it works](/docs/developers/how-it-works): the general prime-work-capture model
- [SageOx + Claude Code](/docs/developers/claude-code): the deepest, Gold-tier integration
- [Supported coding agents](/docs/developers/coding-agents): every agent and its tier
- [Team Context](/docs/features/team-context): what's in the context Codex receives


---

# Supported coding agents (https://sageox.ai/docs/developers/coding-agents)

ox connects your AI coworkers to Team Context and records what they do: regardless of which coding agent you run. This page is the canonical list of supported agents, what each one can do, and how to install adapters for the rest.

## How support works

Every agent is bridged by an **adapter**: a small binary (`ox-adapter-<name>`) that knows where the agent writes session files, how to install hooks, and how to detect it on your machine. Some adapters ship inside ox (bundled); others install on demand from a GitHub release.

Support depth is graded into three tiers. The tier reflects how deeply ox integrates with the agent, not how good the agent is.

| Tier | What it means |
|------|---------------|
| **Gold** | Full parity. Real-time session recording, hooks, whispers, anti-entropy recovery. Tested in CI. |
| **Silver** | Core features. Hooks fire, context primes correctly, incremental session recording. |
| **Bronze** | Context injection via AGENTS.md plus session capture. Limited or no native hooks. |

## Tier and capability matrix

Bundled adapters ship with ox, no install step. Community adapters install from `sageox/ox-adapters`.

| Agent | Tier | Source | Session capture | Hooks | Notes |
|-------|------|--------|:-:|:-:|-------|
| Claude Code | Gold | Bundled | Real-time | Yes | Reference implementation. [Dedicated guide](/docs/developers/claude-code). |
| Gemini CLI | Silver | Bundled | Real-time | Yes | Rewrites its session file every turn; full re-read per turn. |
| OpenAI Codex CLI | Silver | Bundled | Real-time | Yes | JSONL sessions, append-only. |
| Aider | Silver | Bundled | Incremental | Yes | Reads markdown chat history. |
| Amp | Bronze | Bundled | Manual | — | Cloud-first sessions; AGENTS.md marker only. |
| Pi | Bronze | Bundled | Incremental | — | Reads AGENTS.md / CLAUDE.md natively; MCP server support. |
| OpenCode | Bronze | Bundled | Incremental | — | SQLite session storage. |
| Cursor | — | Community | Incremental | — | Install from `sageox/ox-adapters`. |
| Windsurf | — | Community | Incremental | — | Install from `sageox/ox-adapters`. |
| GitHub Copilot | — | Community | Read-only | — | Install from `sageox/ox-adapters`. |
| Cline | — | Community | Read-only | — | Install from `sageox/ox-adapters`. |

<Callout type="info">
The highest-feature agents get their own page. Claude Code is the reference integration: see [SageOx + Claude Code](/docs/developers/claude-code) for hooks, whispers, and session capture in depth.
</Callout>

## Bundled agents

These ship inside ox. After `ox init`, use `ox doctor` if you want to verify hooks and context injection or diagnose something that feels off.

### Claude Code (Gold)

The reference implementation. Real-time recording via fsnotify, lifecycle hooks, push whispers, and anti-entropy recovery all work out of the box. `ox init` wires everything; no extra setup. Full details on the [Claude Code page](/docs/developers/claude-code).

### Gemini CLI (Silver)

Sessions, hooks, and context priming work. Gemini rewrites its session file every turn, so the adapter re-reads the whole file and tracks an entry-count offset instead of a byte offset. Three hook events fire (`PreToolUse`, `PostToolUse`, `Stop`).

### OpenAI Codex CLI (Silver)

JSONL sessions are tailed in real time, the same as Claude Code. Six hook events fire (`SessionStart`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SessionEnd`). `SessionEnd` finalizes the recording when the Codex conversation ends.

Codex hooks are stable and enabled by default; `ox init` installs them for the project.

### Aider (Silver)

Aider records from its markdown chat history, supports incremental recording, and detects automatically.

### Amp, Pi, OpenCode (Bronze)

These get context injection plus session capture, with limited native hooks. Amp is cloud-first (sessions live on ampcode.com), so recording is export-based and context flows through an AGENTS.md marker. Pi reads AGENTS.md and CLAUDE.md natively and exposes an MCP server. OpenCode stores sessions in SQLite rather than files.

## List, install, and inspect adapters

See what's installed and what's available:

<Terminal>
  <TerminalComment>List bundled, installed, and available adapters</TerminalComment>
  <TerminalCommand>ox adapter list</TerminalCommand>
</Terminal>

Install a community adapter by name from the registry:

<Terminal>
  <TerminalComment>Install the Cursor adapter</TerminalComment>
  <TerminalCommand>ox adapter install cursor</TerminalCommand>
</Terminal>

Install an unlisted adapter straight from a GitHub repo:

<Terminal>
  <TerminalCommand>ox adapter install github.com/yourname/ox-adapter-myagent</TerminalCommand>
</Terminal>

Inspect a single adapter's capabilities and binary path:

<Terminal>
  <TerminalCommand>ox adapter info gemini</TerminalCommand>
</Terminal>

Installed adapters land in `~/.local/share/ox/adapters/`. Bundled adapters live alongside the ox binary and can't be removed.

## What's next

- [SageOx + Claude Code](/docs/developers/claude-code): the Gold-tier reference integration
- [Build a custom adapter](/docs/developers/custom-adapter): support an agent ox doesn't bundle yet
- [CodeDB: smarter code navigation](/docs/developers/codedb): give any agent a semantic map of your codebase


---

# Connect a repository (https://sageox.ai/docs/developers/connect-repository)

# Connect a repository

Connecting a repository links your codebase to SageOx, enabling AI context injection and team knowledge sharing. After connecting, every AI coworker session in that repo starts with your team's conventions, decisions, and domain knowledge.

## Connect in 30 seconds

<Terminal>
  <TerminalCommand>cd ~/code/my-project</TerminalCommand>
  <TerminalCommand>ox init</TerminalCommand>
</Terminal>

That's it. Your repo is now connected.

<Callout type="info">
**First time using SageOx?** Run `ox login` first to authenticate. See [Getting Started](/docs/getting-started) for the full setup.
</Callout>

## What happens when you connect

When you run `ox init`:

1. **Team Context syncs**, Your team's shared knowledge syncs locally
2. **Ledger activates**, Code work history and session artifacts can be tracked
3. **AI context enabled**, Claude Code and other AI coworkers can receive team context via `ox agent prime`
4. **Hooks configured**, Claude Code automatically runs context injection on startup

## Prerequisites

- A git repository with at least one commit
- A SageOx account ([sign up free](https://sageox.ai))
- The ox CLI installed (`curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash`)

## Team vs personal scope

When connecting, you choose who can access the repo's knowledge:

| Scope | Who can access | Use case |
|-------|----------------|----------|
| **Team** | All team members | Shared projects, production codebases |
| **Personal** | Only you | Side projects, experiments, learning |

To connect to a specific team:

<Terminal>
  <TerminalCommand>ox init --team my-team</TerminalCommand>
</Terminal>

If you don't specify a team, `ox init` prompts you to choose or create one.

## Verify your connection

<Terminal>
  <TerminalCommand>ox doctor</TerminalCommand>
</Terminal>

You should see green checkmarks:

<Terminal>
  <TerminalOutput>Authentication</TerminalOutput>
  <TerminalOutput>  ✓ Logged in as you@example.com</TerminalOutput>
  <TerminalOutput></TerminalOutput>
  <TerminalOutput>Repository</TerminalOutput>
  <TerminalOutput>  ✓ Connected to team: my-team</TerminalOutput>
  <TerminalOutput>  ✓ Team Context synced</TerminalOutput>
  <TerminalOutput></TerminalOutput>
  <TerminalOutput>Claude Code</TerminalOutput>
  <TerminalOutput>  ✓ Hooks configured</TerminalOutput>
</Terminal>

## How AI coworkers use the connection

Once connected, Claude Code automatically receives your team's context:

1. You start Claude Code with `claude`
2. Claude Code runs `ox agent prime` on startup (configured automatically)
3. Your AI coworker receives Team Context: conventions, decisions, domain terms, current work
4. Every session starts informed, not from scratch

No manual priming needed. The connection handles it.

## Connect multiple repositories

Each repository is connected independently. Run `ox init` in each repo you want to connect:

<Terminal>
  <TerminalCommand>cd ~/code/frontend && ox init</TerminalCommand>
  <TerminalCommand>cd ~/code/backend && ox init</TerminalCommand>
  <TerminalCommand>cd ~/code/mobile && ox init</TerminalCommand>
</Terminal>

All repos can share the same team, giving your AI coworkers consistent context across your stack.

## Disconnect a repository

To disconnect:

<Terminal>
  <TerminalCommand>rm -rf .sageox</TerminalCommand>
</Terminal>

This removes local configuration. The repository record stays on SageOx but becomes inactive.

## Troubleshooting

### "Not a git repository"

Initialize git first:

<Terminal>
  <TerminalCommand>git init && git commit --allow-empty -m "Initial commit"</TerminalCommand>
</Terminal>

### "Already initialized"

Remove the existing configuration and reinitialize:

<Terminal>
  <TerminalCommand>rm -rf .sageox && ox init</TerminalCommand>
</Terminal>

### "Authentication required"

Run login first:

<Terminal>
  <TerminalCommand>ox login</TerminalCommand>
</Terminal>

## What's next

- [Team Context](/docs/features/team-context): what's in the context your AI coworkers receive
- [ox init reference](/docs/cli/init): all flags and options
- [ox doctor](/docs/cli/doctor): diagnose configuration issues
- [Claude Code integration](/docs/developers/claude-code): how context flows into coding sessions


---

# Build a custom adapter (https://sageox.ai/docs/developers/custom-adapter)

If ox doesn't bundle your coding agent, write an adapter for it. An adapter is a standalone binary that bridges ox and one agent, once it exists, `ox adapter install <name>` makes recording work without any change to ox itself.

## The adapter model

An adapter is an external binary named `ox-adapter-<name>` that speaks the **ox adapter protocol** over stdin/stdout as newline-delimited JSON (NDJSON). ox never touches agent session files directly: every agent-specific detail (where sessions live, the transcript format, how to install hooks) lives in the adapter.

Because the contract is a wire protocol, any language works: Go, Rust, Python, TypeScript, C++. The adapter knows four things about its agent:

- Where the agent writes session files
- How to parse the agent's transcript into ox's `RawEntry` shape
- How to install and remove ox hooks in the agent's config
- Whether the agent is installed on the current machine

## Two operational modes

An adapter runs in one of two modes depending on what ox asks for.

| Mode | Used for | Process lifetime |
|------|----------|------------------|
| **One-shot** | Low-frequency calls: `info`, `detect`, `install-hooks`, `check-hooks`, `diagnose` | Spawned, responds with one JSON line, exits |
| **Serve** | High-frequency calls during a live session: `find-session`, `read-from-offset` | Spawned at session start, lives until the session ends |

One-shot subcommands are invoked as `ox-adapter-<name> <subcommand> [flags]`. They read flags and environment, write exactly one compact JSON object to stdout, and exit. Here's a one-shot `info` response, the call that declares the adapter's identity and capabilities:

```json
{
  "protocol_version": 1,
  "name": "myagent",
  "display_name": "My Agent",
  "version": "1.0.0",
  "type": "session",
  "capabilities": ["session_reader", "hook_installer", "incremental_reader", "serve_mode"],
  "hook_env_values": ["myagent"],
  "serve_mode": true
}
```

Serve mode keeps one process alive across many hook calls. The daemon spawns a single `ox-adapter-<name> --serve` and routes every active session of that agent type through it, so each request carries an `agent_id` you use to look up per-session state.

```json
{"id": 1, "method": "find-session", "params": {"agent_id": "r7f3a2-OxA1b2", "repo_root": "/tmp/repo", "since": "2026-01-01T00:00:00Z"}}
{"id": 1, "result": {"session_file": "/path/session.jsonl", "offset": 512}}
```

Unknown methods must return a `method_not_found` error rather than crashing, ox treats that as "capability absent" and degrades gracefully.

## Declare your capabilities

The `capabilities` array in your `info` response tells ox exactly what your adapter implements. Declare only what you build; ox asserts required capabilities at session registration, so a missing one fails fast with a clear error instead of breaking mid-recording.

| Capability | What it grants |
|------------|----------------|
| `session_reader` | `find-session`, `read`, `read-metadata`, the baseline for any session adapter |
| `hook_installer` | `install-hooks`, `check-hooks`, `uninstall-hooks` |
| `incremental_reader` | `read-from-offset`, required for serve-mode recording |
| `file_watcher` | Push entry events automatically after `find-session`, no polling |
| `serve_mode` | Support the `--serve` flag |
| `rules_installer` | Install and remove ox rules in the agent's config |
| `session_importer` | Import a prior session by ID after the fact |

## The Go SDK

Go authors should use the SDK rather than implementing the wire protocol by hand. Two public, versioned packages do the heavy lifting:

- `pkg/adapterruntime`: the serve loop, subcommand dispatch, JSON framing, and graceful shutdown. You register typed handler functions; the SDK makes the protocol invisible.
- `pkg/adapterprotocol`: the shared request, response, and `RawEntry` types, plus the capability constants.

A minimal Go adapter is a `main` that hands a `Config` of handlers to the runtime:

```go
func main() {
    adapterruntime.Run(adapterruntime.Config{
        Info:           handleInfo,
        Detect:         handleDetect,
        InstallHooks:   handleInstallHooks,
        CheckHooks:     handleCheckHooks,
        UninstallHooks: handleUninstallHooks,
        Read:           handleRead,
        ReadMetadata:   handleReadMetadata,
        Diagnose:       handleDiagnose,
        FindSession:    handleFindSession,
        Serve:          handleServe,
    })
}
```

Non-Go adapters implement the protocol spec directly. The package `pkg/ndjson` provides the framing utilities Go gets for free.

## Verify against the compliance suite

The compliance test suite validates any adapter binary against the protocol, regardless of language. Run it during development to catch contract violations before users hit them:

<Terminal>
  <TerminalComment>Run compliance against your binary, from the ox repo</TerminalComment>
  <TerminalCommand>go test ./pkg/adapterprotocol/compliance/... -adapter ./ox-adapter-myagent</TerminalCommand>
</Terminal>

Once installed, ox can run the same suite for you:

<Terminal>
  <TerminalCommand>ox adapter verify myagent</TerminalCommand>
</Terminal>

During development, symlink a locally-built binary instead of installing a release:

<Terminal>
  <TerminalCommand>go build -o ./bin/ox-adapter-myagent ./cmd/ox-adapter-myagent</TerminalCommand>
  <TerminalCommand>ox adapter link ./bin/ox-adapter-myagent</TerminalCommand>
</Terminal>

## Key contracts to get right

A few behaviors are load-bearing regardless of language. Get these wrong and recordings silently truncate or stall.

- **Compact JSON only.** One object per line, no pretty-printing, no literal newlines inside values. NDJSON uses newlines as delimiters.
- **Line buffer ≥ 1MB.** Default line readers (64KB in Go's `bufio.Scanner`) truncate large tool outputs. Raise the buffer and check for read errors after the scan loop finishes.
- **Respect the timeouts.** `read-from-offset` is the hot path, every tool call waits on it. Keep the file handle open from `find-session` and never re-open from zero.

<Callout type="warn">
The `fast` timeout for `read-from-offset` defaults to 100ms. Exceeding it on three consecutive calls downgrades the session to one-shot mode: recording continues, only slower. Key all per-session state by `agent_id`, never by `repo_root` (git worktrees produce different paths for the same repo).
</Callout>

This page is the orientation, not the full reference. The in-repo authoring guide walks through every subcommand with examples, and the protocol spec is the complete contract, read both before shipping an adapter for others to install.

## What's next

- [Supported coding agents](/docs/developers/coding-agents): the agents ox already bundles
- [SageOx + Claude Code](/docs/developers/claude-code): the reference adapter in action
- [CodeDB: smarter code navigation](/docs/developers/codedb): what your agent gains once recording works


---

# How it works (https://sageox.ai/docs/developers/how-it-works)

ox gives any supported AI coding agent your team's institutional knowledge at session start, then records what the agent does so the next session inherits it. This page covers the general model, it applies to every agent ox supports.

## The prime, work, capture loop

Every session follows the same three beats, regardless of which agent you run.

```mermaid
graph LR
    A["Team Context"] --> B["ox agent prime"]
    B --> C["Agent works"]
    C --> D["Session captured to Ledger"]
    D --> A
```

1. **Prime**, the agent runs `ox agent prime` and receives Team Context.
2. **Work**: the agent codes with your conventions, decisions, and domain terms in hand.
3. **Capture**, the session is committed to the per-repo Ledger and summarized, feeding future primes.

This is the multiplayer loop: every session enriches the context the next one consumes.

## Prime injects Team Context

When an agent starts in a connected repo, `ox agent prime` injects your [Team Context](/docs/features/team-context), your team's shared knowledge. The agent reads it before touching code.

<Terminal>
  <TerminalComment>The agent runs this at session start (configured automatically by ox init)</TerminalComment>
  <TerminalCommand>ox agent prime</TerminalCommand>
</Terminal>

Re-run it after clearing or compacting the agent's context, priming is cheap and keeps the agent grounded.

## What your agent receives

Prime delivers your team's accumulated knowledge as structured context. The categories below generalize across agents, the source is the same, the format adapts per agent.

| Context type | Source | Example |
|---|---|---|
| Team norms | `AGENTS.md` in Team Context | "We use snake_case for all API fields" |
| Architectural decisions | Recorded discussions | "We chose Postgres JSONB for metadata because the schema isn't stable yet" |
| Domain terminology | Team Context definitions | "A 'parcel' is a geographic land unit, not a shipping package" |
| Recent decisions | Transcribed walkthroughs | "The upload flow was redesigned last week, here's what changed and why" |
| Prior sessions | The repo's Ledger | "Auth was refactored to device-flow tokens three sessions ago" |
| Code patterns | [CodeDB](/docs/developers/codedb) index | Symbol search, git history, cross-references across your codebase |

## Works across every supported agent

The prime, work, capture loop is agent-agnostic. Claude Code, Codex, Gemini, Aider, and others all run `ox agent prime` and capture sessions the same way.

What differs is **depth**, some agents support real-time hooks and slash commands, others get priming and capture with fewer touchpoints. The [coding agents](/docs/developers/coding-agents) page has the per-agent support matrix.

## Local recall on question-like prompts

When you type a question ("how did we handle pagination on the activity feed?"), ox checks your locally-cached Ledger for prior sessions or decisions that look relevant. If it finds a match, it prepends a short `[ox-recall]` preamble above your prompt so the agent sees it.

<Callout type="info">
Recall runs entirely on your machine by default, your prompt never leaves your laptop. It fires only on question-like prompts of a reasonable length, and silently skips if the lookup is slow or finds nothing. No configuration needed.
</Callout>

The preamble is a few lines at most:

```text
[ox-recall]
2026-04-12-activity-feed · "we cursor-paginate by created_at desc with a tiebreak on id"
2026-03-30-feed-perf · "switched off offset pagination after the N+1 regression on page 30+"
```

The agent reads it as additional context. If you want recall to also reach team-shared SageOx content beyond your local cache, opt into cloud mode, prompts pass through the same redactor used by session uploads before any byte transits the network.

<Terminal>
  <TerminalComment>Opt recall into team-shared cloud content (off by default)</TerminalComment>
  <TerminalCommand>ox config set hooks.userpromptsubmit.cloud_query true</TerminalCommand>
</Terminal>

## What's next

- [Coding agents](/docs/developers/coding-agents): which agents are supported and at what depth
- [SageOx + Claude Code](/docs/developers/claude-code): the deepest integration, with hooks and slash commands
- [Session recording](/docs/developers/session-recording): how captured sessions become team memory


---

# Developers (https://sageox.ai/docs/developers)

If you run an AI coding agent (Claude Code, Codex, Gemini, Aider, and more), the ox CLI gives it your team's full context at startup and captures what it does back to your Ledger.

Your agent stops starting from zero. It starts from where your team left off, then leaves a record the next session can build on.

## The CLI plus adapter model

ox is a single CLI that connects your repo to SageOx. Each supported agent gets a thin **adapter** that knows how to inject context into that agent and capture its sessions: so the same workflow works whether you drive Claude Code, Codex, or anything else.

The loop is the same across every agent:

1. The agent runs `ox agent prime` at session start.
2. Team Context flows in: conventions, decisions, domain terms, prior work.
3. The agent works.
4. The session is captured to the per-repo Ledger and summarized.

Depth varies by agent. Claude Code is the deepest integration; others get the same priming and capture with fewer real-time touchpoints. See [coding agents](/docs/developers/coding-agents) for the support matrix.

## Start here

| Page | What it covers |
|------|----------------|
| [How it works](/docs/developers/how-it-works) | The prime-work-capture loop, and what any agent receives |
| [Supported coding agents](/docs/developers/coding-agents) | Supported agents and per-agent depth |
| [SageOx + Claude Code](/docs/developers/claude-code) | The deepest, Gold-tier integration |
| [Session recording](/docs/developers/session-recording) | Why and how coding sessions become team memory |
| [CodeDB](/docs/developers/codedb) | Semantic code navigation your agent can query |
| [Build a custom adapter](/docs/developers/custom-adapter) | Wire up an agent ox doesn't support yet |
| [Agent factories](/docs/developers/agent-factories) | Orchestrators and parallel agents |

## What's next

- [How it works](/docs/developers/how-it-works): start with the general model
- [ox CLI reference](/docs/cli): every command and flag


---

# Session recording (https://sageox.ai/docs/developers/session-recording)

A coding session is a conversation between a coworker and an AI coworker: the questions, the reasoning, the decisions, the code that came out of it. ox captures that as institutional memory so the next person, human or AI, doesn't re-solve a solved problem.

## Why record sessions

The hardest part of a problem is rarely the final diff: it's the path that got you there. Which approaches were tried and abandoned, why one design won, what constraint forced the awkward workaround.

That reasoning usually evaporates the moment the session ends. Recording sessions keeps it. Teammates learn how a problem was actually solved, and future agents prime on it instead of starting cold.

## How it works

When a session ends, ox commits it to the **Ledger**, the per-repo history of code work. Each session is summarized automatically, so you get a readable account without writing one by hand.

The Ledger is per-repo and distinct from [Team Context](/docs/features/team-context), which is team-wide. Sessions are code work; discussions and conventions live in Team Context.

## How your team gains value

Recorded sessions turn one person's debugging run into a resource the whole team draws on.

- **Search prior work.** Ask `ox query` a question and get back relevant past sessions instead of re-deriving the answer.
- **See recent activity.** Browse what teammates and their agents have been working on across the repo.
- **Avoid re-solving solved problems.** When local recall finds a matching session, it surfaces it before your agent starts, so you reuse the answer rather than rediscover it.

<Terminal>
  <TerminalComment>Ask a question across past sessions and team knowledge</TerminalComment>
  <TerminalCommand>ox query "how did we handle pagination on the activity feed?"</TerminalCommand>
</Terminal>

## View and use recordings

List recent sessions and open the one you want straight from the CLI.

<Terminal>
  <TerminalComment>List recent sessions in the Ledger</TerminalComment>
  <TerminalCommand>ox session list --limit 5</TerminalCommand>
  <TerminalComment>Open a session by name</TerminalComment>
  <TerminalCommand>ox session view 2026-04-13-auth-refactor</TerminalCommand>
</Terminal>

Beyond manual viewing, recorded sessions feed back into [priming](/docs/developers/how-it-works). When a future agent starts in the repo, relevant prior sessions are part of the context it receives, so the value compounds without anyone reading a single transcript.

## What's next

- [How it works](/docs/developers/how-it-works): where session capture fits in the loop
- [ox session reference](/docs/cli/session): every session subcommand
- [Team Context](/docs/features/team-context): team-wide knowledge, versus the per-repo Ledger


---

# Distillation (https://sageox.ai/docs/features/distill)

Distillation turns raw team knowledge (discussions, coding sessions, and GitHub activity) into structured memory that AI coworkers can use. It's the process that makes [Team Context](/docs/features/team-context) get smarter over time.

## The problem distillation solves

Teams generate knowledge constantly: in recorded discussions, coding sessions, PR reviews, issue threads. Without distillation, AI coworkers only see the raw artifacts: long transcripts, individual commits, scattered PR comments.

Distillation extracts the signal: decisions made, patterns discovered, constraints learned. The result is layered memory that compounds over time, not a pile of unprocessed notes.

## How it works

Three knowledge sources feed through fact extraction and temporal synthesis into Team Context memory.

```mermaid
graph LR
    D[Discussions] --> E[Fact extraction]
    S[Sessions] --> E
    G[GitHub activity] --> E
    E --> Daily[Daily synthesis]
    Daily --> Weekly[Weekly synthesis]
    Weekly --> Monthly[Monthly synthesis]
    Monthly --> TC[Team Context memory]
    TC --> AI[AI coworker sessions]
```

Each source contributes different kinds of signal. The extraction stage pulls structured facts, then temporal synthesis layers compress and connect them over time.

## Three knowledge sources

### Discussions

Recorded team conversations. The LLM reads VTT transcripts and extracts decisions, action items, and observations. When server-generated summaries already exist, those are used directly, no redundant extraction.

### Coding sessions

Session summaries from the [Ledger](/docs/features/team-context). No LLM needed here: structured data (decisions, action items, open questions, aha moments) is mapped directly from `summary.json`. This is the cheapest and fastest source.

### GitHub activity

PRs, issues, and commits assembled from CodeDB. The LLM extracts what shipped, what's blocked, collaboration patterns, and review decisions. This captures knowledge that lives in code review threads and commit messages.

## Temporal layers

Distillation organizes memory into time-based layers. Each layer synthesizes the one below it, creating progressively higher-level insight.

| Layer | Contains | Example |
|-------|----------|---------|
| **Daily** | Raw signal from today's work | "Team decided to use pgroll for all schema migrations" |
| **Weekly** | Patterns and themes from the week | "Authentication refactor dominated the week, three PRs, two design pivots" |
| **Monthly** | Strategic direction and compounding insights | "Team is converging on event-driven architecture for all async workflows" |

The daily layer captures facts. The weekly layer spots patterns. The monthly layer reveals direction.

## The compounding loop

Distillation creates a virtuous cycle where team knowledge feeds forward into future work:

1. AI coworker works on code, discovers an insight
2. Session is captured to the Ledger
3. Distillation extracts the insight into memory
4. Next AI coworker session receives it via Team Context
5. That coworker applies the insight proactively

This means knowledge discovered in one session automatically benefits every future session, across your entire team.

## Local-first architecture

Distillation runs on your machine using your AI coworker's CLI. This gives you:

- **Richer context**: local repo state, codebase knowledge, recent work
- **No SageOx inference cost**: uses your own LLM
- **Git-native output**: results committed directly to your Team Context repo

The server runs anti-entropy fallback workflows for missed distillations. If the CLI skips a run, the backend detects the gap and regenerates with whatever context it has.

## Customize distillation

Teams can customize how facts are extracted and synthesized using two guidance files in `memory/guidance/`:

| File | Controls |
|------|----------|
| `EXTRACT.md` | How facts are extracted from sources: what to emphasize, what terminology to use, what patterns to watch for |
| `DISTILL.md` | How facts are synthesized into summaries: what level of detail, what structure, what to highlight |

Run `ox doctor --fix` to create these files with sensible defaults. Edit them as your team develops preferences for what gets captured.

## Run distillation

<Terminal>
  <TerminalComment>Sync sources and run distillation</TerminalComment>
  <TerminalCommand>ox distill --sync</TerminalCommand>
</Terminal>

This fetches the latest discussions, sessions, and GitHub activity, then runs extraction and synthesis for any new or updated sources.

## What's next

- [`ox distill` CLI reference](/docs/cli/distill): all flags and options
- [Team Context](/docs/features/team-context): the repo that distillation writes to
- [SageOx + OpenClaw](/docs/cookbooks/openclaw): factory automation pattern using distillation
- [SageOx + Claude Code](/docs/developers/claude-code): how distilled memory flows into coding sessions


---

# Features (https://sageox.ai/docs/features)

SageOx turns what your team says into what your team (and its AI coworkers) can use. A recording becomes a transcript, the transcript is distilled into decisions and memory, and the result lands in your Team Context for every coworker to read back from an MCP-connected tool, a coding session with the ox CLI, or the web app.

```mermaid
graph LR
    A["Capture"] --> B["Distill"]
    B --> C["Team Context"]
    C --> D["Connected tools, coding sessions, web app"]
```

## The core features

| Feature | What it does | Read |
|---------|--------------|------|
| Team Context | Your team's shared knowledge (conventions, decisions, terminology) that coworkers and AI coworkers read back across different work modes | [Team Context](/docs/features/team-context) |
| Plans | The plan of record for work your team executes: mockups, GTM, rollouts, engineering. Authored by your AI coworker, reviewed by you | [Plans](/docs/features/plans) |
| Murals | A picture of what your team has been working on. Click a scene to see the discussions, murmurs, and sessions it was drawn from | [Murals](/docs/features/murals) |
| Distillation | Turns raw transcripts into structured, layered memory worth keeping | [Distillation](/docs/features/distill) |
| Your data | Where your recordings and context are stored, who can see them, and how to take them with you | [Your data](/docs/features/your-data) |

## How it fits together

You [capture](/docs/context-capture) a discussion. SageOx transcribes it and [distills](/docs/features/distill) the transcript into decisions, action items, and memory. That distilled knowledge commits to your [Team Context](/docs/features/team-context): a real git repo scoped to your team. From there, coworkers can read it back over MCP in a connected tool, through the ox CLI in a coding session, or on the web when they need the source material directly.

<Callout type="info">
A recording's audience is its team. Team Context is scoped per team, so what one workspace records stays within that workspace.
</Callout>

## What's next

- [Team Context](/docs/features/team-context): the shared knowledge base at the center of it all.
- [Plans](/docs/features/plans): visual plans for the work your team executes, authored by your AI coworker and reviewed by you.
- [Murals](/docs/features/murals): explore the scenes of your team's mural and the sources behind each one.
- [Distillation](/docs/features/distill): how raw recordings become structured memory.
- [Your data](/docs/features/your-data): storage, visibility, and export.


---

# Murals (https://sageox.ai/docs/features/murals)

# Murals

A mural is a picture of what your team has been working on. Click a scene in it and SageOx shows where it came from: the discussions, murmurs, and sessions behind it, in the words of the coworkers who said or wrote them.

<ScreenFrame caption="The team murals page in dark mode. A mural with Explore scenes on, so every scene is outlined, and the Where this came from panel open below it with one scene marked." />

Scene exploration is on for every team. There is nothing to turn on.

## Find your team's murals

Your team home shows the latest mural as a poster. Click it to open your team's murals page at `sageox.ai/team/{team_id}/murals`.

Flip between murals with the chevrons beside the mural, the left and right arrow keys, or the grid below it. A busy day can produce several murals, and the next one arrives after your team's next active window.

<Callout type="info">
Scene exploration lives on this page. The mural for a single discussion, in that discussion's Visuals tab, is a plain picture.
</Callout>

## Explore a scene

A scene is a labeled area of the mural: the main idea or one of its sections. Hover a scene to see its name and how many sources it links to, such as "3 linked sources". A scene with no linked sources has nothing to open, so it isn't clickable.

Select a scene to open **Where this came from** below the mural. The panel marks that scene and scrolls to it.

| To do this | Use |
|------------|-----|
| Select a scene | Click it, press `Enter` or `Space` on a focused scene, or click its name in the panel |
| Move between scenes | The arrow keys, while focus is on the mural |
| Clear the selection | `Esc`. Press it again to return to the team page |
| Flip to a newer or older mural | `←` or `→`, while no scene is selected |

The address bar updates to end in `#scene=<id>` when you select a scene. Copy the link to send a coworker straight to it.

## Read the sources behind a scene

**Where this came from** lists every scene with the sources it was drawn from. It starts closed. Click its header to expand it.

<ScreenFrame caption="The Where this came from panel, cropped tight. One person's avatar and name once, then their own sentences word for word, with a discussion shown as a titled link and a small type label." />

Sources are grouped by person. Each person's avatar and name appear once, followed by their own sentences, word for word. Nothing is shortened or rewritten.

| Source | What you see |
|--------|--------------|
| Murmur | The words themselves |
| Discussion, session, plan, or chat | Its title as a link, with a small type label |

Every row shows a time of day. Sources with no author are listed in their own group, never under someone's name.

If a source's content hasn't been collected yet, its row reads **Not harvested yet** in place of its words. When chat is on, the selected scene also offers **Ask about this scene**, which opens chat with your question already typed.

<Callout type="info">
The panel contains nothing written by a model. It shows what your coworkers said and wrote, so you can check a scene against the people behind it.
</Callout>

## See every scene at once

The **Explore scenes** toggle (the compass icon) sits in the row below the mural, under the date. Next to it, a count reads like "4 scenes · 9 linked sources".

Turn it on to outline every scene without hovering. It is the way in for keyboard and touch, where there is no hover to reveal a scene.

The toggle isn't saved, so it starts off on each visit. The row only appears when the mural has at least one clickable scene.

## Older murals

Murals drawn before their scenes were mapped, and murals where mapping didn't complete, show as a plain picture. They have no **Explore scenes** toggle and no **Where this came from** panel.

## What's next

- [Team Context](/docs/features/team-context): the shared knowledge your team's discussions feed into
- [Slack integration](/docs/integrations/slack): post team and discussion murals to a channel
- [Discussions](/docs/context-capture/discussions): capture the conversations that become a scene's sources
- [Plans](/docs/features/plans): the plans that can appear as sources


---

# Plans (https://sageox.ai/docs/features/plans)

# Plans

A plan in SageOx is the plan of record for work your team executes: a design mockup, a go-to-market strategy, a rollout sequence, an engineering change. It is a rich, visual page, not a wall of text. Your AI coworker authors it, you review it, and your coworkers act on it.

<ScreenFrame
  id="docs/features/plans-hero-rendered-plan"
  alt="A rendered SageOx plan page: a ten-minute summary, cited badges, and the reasoning that shaped the change."
  maxWidth="44rem"
  caption="A rendered plan in SageOx: a decide-in-ten-minutes summary, badges cited to real artifacts, and the reasoning that shaped the change, enriched from your Team Context."
/>

Every plan is stored in a repository's Ledger, enriched from your [Team Context](/docs/features/team-context), and built to be decided on in ten minutes. When the plan shapes code, it stays linked to the pull request it produced, so the reasoning behind a change is never lost.

<Callout type="info">
A plan's subject is anything your team must execute. Where it is authored is narrower: today you write plans inside an AI coworker session (Claude Code or Codex) in a repository set up with SageOx (`ox init`), with the `ox` CLI installed. The repository is where the plan is stored, not what the plan has to be about.
</Callout>

## You prompt, your coworker authors

You ask your AI coworker for a plan, and it picks the right visuals, writes the page, and saves and renders it for you, running the `ox` CLI on your behalf.

| You say | Your coworker does |
|---------|--------------------|
| "Plan the retry migration. Make it a visual plan and render it." | Authors a page, saves it to your repository's Ledger, opens it for review |
| "Ground it in real data and flag conflicts with our ADRs." | Reads live SageOx Team Context, adds cited badges, surfaces collisions |
| "Tighten the risks section." | Revises the same page |

## Prompts that produce great plans

A bare "make a plan" gets a bare plan. Give your coworker three things: the decision, the audience, and real grounding:

**Minimum**

<AgentPrompt badge="Claude Code">Plan the speaker-rematch work. Make it a SageOx enriched visual plan, save it, render it for review.</AgentPrompt>

**Good**, names the decision and the reader

<AgentPrompt badge="Claude Code">Design X as a visual plan for a principal engineer with 10 minutes who must decide go / no-go. Lead with the conclusion and the biggest risk.</AgentPrompt>

**Best**, grounds it in real data and SageOx Team Context

<AgentPrompt badge="Claude Code">Design the speaker-rematch work as a visual plan for a principal engineer deciding go / no-go: run it against a real recording from our data, enrich it against our SageOx Team Context, and add cited badges for any collisions or conflicting ADRs.</AgentPrompt>

**Not only code.** The same three things make a non-engineering plan land:

<AgentPrompt badge="Claude Code">Plan the launch of the new pricing page as a visual plan for the team executing it: the sequence week by week, who owns each step, what we announce where, and the two decisions we need before we start.</AgentPrompt>

<Callout type="info">
Every cited badge points at a real artifact: an ADR, a decision, a teammate's live edit. A plan never puts words in a coworker's mouth; when the evidence is thin, it degrades to a nudge to consult the right person.
</Callout>

## Review and iterate

Read the rendered plan, then tell your coworker what to change: it revises the same page, so nothing forks. When the work becomes a pull request, the plan is linked from it, and the review conversation happens there alongside the diff.

<Callout type="info">
**Coming soon:** clicking an element on a shared plan to leave an anchored comment your coworker acts on. Today, review happens on the rendered page and in the linked PR.
</Callout>

## Find plans in the web app

In the SageOx web app, open your team and choose **Plans** in the left nav. Every plan saved for the team shows up there, newest first. Open any plan to read the full page and share it with a coworker.

## Solo? Plans still pay off

You don't need a human team. A coworker is any team member: human or AI. As a team of one, your coworker authors a plan you review in ten minutes instead of a text wall, several coworkers can co-author the same page, and your Ledger accrues durable, searchable plans so a later reader inherits the *why*.

## Every PR links its plan and session

When work lands, the pull request carries a credit line linking the session and the plan that produced it. Open a PR months later and jump straight to the plan that shaped it, the reasoning travels with the code.

## See real examples

Two public plans from the SageOx team, open them to see different visual forms doing real work.

**[A sequencing plan](https://sageox.ai/plan/pln_019feec8-9abf-738a-b72e-1449eb23390e)**, a phase-by-phase timeline, with live collision and conflict badges cited to a real file and a tracked issue.

<ScreenFrame caption="A sequencing plan, phase-by-phase timeline with collision and conflict badges cited to a real file and a tracked issue. Sign in to open the full page." />

**[An architecture plan](https://sageox.ai/plan/pln_01a01cdb-8f5d-7a77-b576-ecbd887d36f6)**, a dependency graph plus an ownership table with a candid "deliberately excluded" column.

<ScreenFrame caption="An architecture plan, a dependency graph plus an ownership table with a candid 'deliberately excluded' column. Sign in to open the full page." />

More curated examples are coming to the SageOx public team.

## What's next

- [Team Context](/docs/features/team-context): where a plan's cited evidence comes from
- [SageOx + Claude Code](/docs/developers/claude-code): how plans fit into a coding session
- [Distillation](/docs/features/distill): how raw team knowledge becomes structured memory


---

# Team Context (https://sageox.ai/docs/features/team-context)

# Team Context

Team Context is a git repo that holds your team's shared knowledge: conventions, decisions, domain terminology, and distilled insights from discussions. Every captured discussion feeds back into it, and coworkers read it back from their connected tools, their coding sessions, and the web app.

You can browse and edit it directly on your filesystem.

## Access your Team Context

<Terminal>
  <TerminalCommand>cd my-project/.sageox/teams/primary</TerminalCommand>
  <TerminalCommand>ls</TerminalCommand>
  <TerminalOutput>AGENTS.md    MEMORY.md    SOUL.md    TEAM.md    discussions/    docs/    memory/</TerminalOutput>
</Terminal>

This is a real git repo. You can open it in your editor, commit changes, and push. SageOx syncs it automatically.

## What's inside

### Prime-loaded files

These files are the most direct part of Team Context in a coding session. When a repo-based AI coworker starts via the ox CLI, they are read at session start. Keep them concise, every token costs context window space across every session.

| File | Purpose | Budget |
|------|---------|--------|
| `AGENTS.md` | Team norms, repo layout, conventions, coding standards | &lt; 200 lines |
| `SOUL.md` | Team identity: purpose, values, decision principles | &lt; 100 lines |
| `TEAM.md` | Team roster, roles, working patterns, current focus | &lt; 100 lines |
| `MEMORY.md` | Auto-generated index of distilled team wisdom | &lt; 200 lines |

<Callout type="info">
Prime-loaded files are auto-loaded into context. Bloat here directly degrades AI coworker performance. Prefer links and pointers over inline content.
</Callout>

### `docs/`, Team documents

Add markdown files for anything your AI coworkers should know: architecture guides, API conventions, domain knowledge, engineering principles. Each file covers one topic.

| Example doc | What it covers |
|-------------|---------------|
| `docs/architecture.md` | How your systems fit together |
| `docs/glossary.md` | Domain-specific terms and definitions |
| `docs/coding-conventions.md` | Style guides, naming rules, structural patterns |
| `docs/api-conventions.md` | REST conventions, error formats, versioning |

Files are indexed automatically. In a repo, AI coworkers see a catalog of available docs at session start and read full content on demand when the task is relevant. Over MCP, a connected tool can search and retrieve the same knowledge without a repo.

Add optional frontmatter to help coworkers find the right doc:

```yaml
---
title: API Design Guide
description: REST conventions, error formats, versioning rules
when: designing APIs, reviewing endpoints, error handling
---
```

### `docs/governance/REDACT.md`, Redaction rules

SageOx applies built-in redaction before storing observations. This file lets your team add domain-specific overrides: additional terms, patterns, or categories to redact.

### `memory/`, Layered memory

Team memory is organized in time-based layers, built automatically from recorded discussions and observations.

| Location | Contains | When to read |
|----------|----------|--------------|
| `memory/daily/` | Recent observations and daily distillations | Recent context |
| `memory/weekly/` | Weekly pattern summaries | Broader trends |
| `memory/monthly/` | Monthly themes and strategic direction | Long-term context |

You don't need to write memory files by hand, the distillation pipeline generates them from captured discussions.

### `discussions/`, Recorded conversations

Transcripts and artifacts from captured discussions land here. Each discussion gets its own directory with the transcript, summary, and extracted insights.

## Edit your Team Context

Open the files in your editor and make changes. The most impactful edits:

**`AGENTS.md`**: This is the file AI coworkers read first. Add your team's coding conventions, architectural decisions, and domain rules here.

<Terminal>
  <TerminalComment>Open in your editor</TerminalComment>
  <TerminalCommand>code my-project/.sageox/teams/primary/AGENTS.md</TerminalCommand>
</Terminal>

**`SOUL.md`**: Define your team's values and decision principles. When an AI coworker faces an ambiguous choice, this is what guides the decision.

**`docs/glossary.md`**: Add domain-specific terms. If "parcel" means a geographic land unit in your domain (not a shipping package), define it here so AI coworkers don't guess wrong.

## How coworkers use it

### In a coding session

When an AI coworker starts a repo-based session via `ox agent prime`:

1. **Prime-loaded files** (`AGENTS.md`, `SOUL.md`, `TEAM.md`, `MEMORY.md`) are read immediately
2. **Doc catalog** is scanned, titles and descriptions are loaded, full content is fetched on-demand
3. **Discussion transcripts** are available for reference when the task relates to a past conversation

The result: your AI coworker starts the coding session with your team's institutional knowledge, not a blank slate.

### In a connected tool

When a coworker uses SageOx over MCP, the tool can search Team Context, read relevant documents, and cite prior discussions without needing a checked-out repo first.

### In the web app

Humans can browse recordings, transcripts, summaries, and related artifacts directly when they want the original material rather than an answer relayed through a tool.

## What's next

- [SageOx + Claude Code](/docs/developers/claude-code): see how Team Context flows into coding sessions
- [Discussions](/docs/context-capture/discussions): capture conversations that feed into Team Context
- [web app recorder](/docs/context-capture/web-app-recorder): record from your browser or phone


---

# Team rules: share AI coding rules across repos and tools (https://sageox.ai/docs/features/team-rules)

# Team rules

Team rules are conventions you write once in your [Team Context](/docs/features/team-context) that reach every AI coworker on your team, in every repo, in every coding tool: Claude Code, Codex, Cursor, Gemini, Droid, OpenCode, Amp, and Goose. One file replaces a copy per repo per tool, and there is nothing left to drift.

## One design system, three repos

Say your team ships a desktop app, a mobile app, and a website: three repos, one visual language. The spacing scale, color tokens, typography, and component naming have to hold across all three, or the product stops looking like one product.

Today you have two options, and both leak. Paste the conventions into each repo's local rule files (`.claude/rules/`, `.cursor/rules/`, `AGENTS.md`) and watch the copies drift, or re-explain them at the start of every session. There is no clean way to sync rules between repositories, and a rule written for Claude Code never reaches the coworker on Cursor.

A team rule fixes both problems at once. Write `tokens.md` once in Team Context, and the ox CLI delivers it to every AI coworker in all three repos at session start, whichever tool that coworker runs.

```mermaid
graph LR
    R["Team Context: agents/rules/design-system/tokens.md"] --> D["desktop-app (Claude Code)"]
    R --> M["mobile-app (Cursor)"]
    R --> W["website (Codex)"]
```

## Where team rules live

Team Context is a git repo on your machine. Team rules are markdown files under `agents/rules/`, one concern per file. Subdirectories are walked, so organize them as the library grows.

<Terminal>
  <TerminalComment>ox status prints your Team Context path under Team</TerminalComment>
  <TerminalCommand>cd ~/.local/share/sageox/&lt;endpoint&gt;/teams/&lt;team-id&gt;</TerminalCommand>
  <TerminalCommand>ls agents/rules</TerminalCommand>
  <TerminalOutput>design-system/    escalation-policy.md    integration-tests-no-db-mocks.md</TerminalOutput>
  <TerminalCommand>ls agents/rules/design-system</TerminalCommand>
  <TerminalOutput>component-naming.md    tokens.md</TerminalOutput>
</Terminal>

Run `ox status` to see the exact path for your team, then open it in your editor if you prefer.

## Team rule, repo rule, or personal rule?

Every rule has a natural home. Pick it by asking who the rule applies to, not where you happen to be typing.

| Put it in | When | Who it reaches |
|---|---|---|
| Team Context: `agents/rules/<topic>.md` | It applies to your team's work in general: design tokens, testing philosophy, security policy, review conventions, language idioms | Every coworker, every repo, every coding tool |
| The repo: `.claude/rules/<topic>.md` (or your tool's equivalent) | It's specific to this one codebase: its paths, services, schemas, build steps | Anyone who clones this repo and uses that tool |
| Your home directory: `~/.claude/rules/<topic>.md` | It's a personal preference you don't want to impose on the team | You |

If you've been sharing Claude Code rules across your team by committing them to each repo's `.claude/rules/`, the test is whether the rule mentions anything only that codebase has. If it doesn't, it's a team rule. When you edit a `.claude/rules/` file that reads as generally applicable, your AI coworker should offer to publish it to the team as well.

## Write a team rule

Each rule is a markdown file with YAML frontmatter. Only `name` and `description` are required.

<Terminal>
  <TerminalComment>ox status prints your Team Context path under Team</TerminalComment>
  <TerminalCommand>cd ~/.local/share/sageox/&lt;endpoint&gt;/teams/&lt;team-id&gt;</TerminalCommand>
  <TerminalCommand>mkdir -p agents/rules/design-system</TerminalCommand>
  <TerminalCommand>$EDITOR agents/rules/design-system/component-naming.md</TerminalCommand>
</Terminal>

```markdown
---
name: ds-component-naming
description: Shared design-system components use the Ds prefix and the same name in every repo.
---

**Why:** the desktop app, mobile app, and website ship the same components. When `DsButton`
is `PrimaryButton` in one repo and `Button` in another, nobody can search across them and
the design team has no single name to reference.

**How to apply:**
- Prefix shared components with `Ds`: `DsButton`, `DsCard`, `DsDialog`.
- Use the identical name in all three repos, including tests and stories.
- A new shared component gets its name in the design-system catalog before it lands anywhere.
```

Write the body the way you'd brief a new coworker: why the rule exists, then how to apply it. The `description` is the one line your AI coworker sees in every session, so make it the line that tells it when to open the file.

### Frontmatter fields

| Field | Required | Values | What it does |
|---|---|---|---|
| `name` | yes | kebab-case identifier | Stable handle for cross-references and `superseded-by` |
| `description` | yes | one short line | Shown in the rule catalog every session |
| `repos` | no | list of `owner/repo` slugs | Omit for all team repos. Set it to limit the rule to those repos |
| `globs` | no | path patterns | Which files the rule is about. Omit for any file |
| `audience` | no | `ai`, `human`, `both` | Default `ai`. `human` rules never enter AI coworker context |
| `visibility` | no | `always`, `indexed`, `hidden` | Default `indexed`. How much of the rule loads each session |
| `status` | no | `active`, `draft`, `superseded-by:<name>` | Default `active`. `draft` and superseded rules stay out of sessions |
| `from-discussion` | no | discussion id | Links the rule to the recorded [discussion](/docs/context-capture/discussions) that decided it |

## Control how much context a rule costs

Every rule reaches your AI coworker through `ox agent prime`, and every token it loads competes with the actual work. `visibility:` decides how much of a rule loads.

| Value | What loads each session | Use it for |
|---|---|---|
| `indexed` (default) | Name, description, and path. Your AI coworker reads the full file when the task calls for it | Almost everything |
| `always` | The full body, inlined, every session | Short rules that must never be missed: security, escalation |
| `hidden` | Nothing, unless the rule is named explicitly | Drafts, archived rules, work in progress |

<Callout type="warn">
`always` costs context in every session, on every repo, for every coworker on the team. Keep it rare, and keep those rules to a paragraph or two. A substantive rule belongs in `indexed`; your AI coworker opens it when the description matches the task.
</Callout>

`ox agent list` reports the cumulative tokens delivered into AI coworker sessions, split three ways: what the ox CLI itself injects, what your team's content adds (including `always` rule bodies), and what the project's own `AGENTS.md` adds. If the team bucket is climbing into the thousands, demote some rules to `indexed`.

<Terminal>
  <TerminalComment>The context budget split appears at the bottom of the output</TerminalComment>
  <TerminalCommand>ox agent list</TerminalCommand>
</Terminal>

## Scope a rule to file types with `globs:`

Some rules are about certain files, not certain repos. The design system's token rule is one: it applies in all three repos, but only when someone is editing styles or components.

```markdown
---
name: ds-tokens
description: Use the shared spacing, color, and type tokens; never hardcode values.
globs: ["**/*.css", "**/*.tsx"]
---

**Why:** a hardcoded `#1a1a1a` or `13px` in any of the three repos drifts the moment the
palette or the scale changes.

**How to apply:**
- Spacing: the 4px scale, `--space-1` through `--space-8`. No arbitrary pixel values.
- Color: tokens only (`--color-surface`, `--color-accent`). No hex literals.
- Type: `--text-body` and `--text-heading-*`. Never set `font-size` directly.
```

Both forms parse, so use whichever you already have:

```yaml
globs: ["**/*.css", "**/*.tsx"]   # list form, same shape as repos:
globs: **/*.css,**/*.tsx          # comma form, same shape as Cursor rule files
```

<Callout type="info">
`globs:` is advisory today. Your AI coworker sees the scope next to the rule in its session context and applies the rule when the files it's working on match. Native path-triggered loading, where the coding tool itself loads the rule the moment a matching file is opened, arrives with rule sync-out. A rule you scope now gains that automatically.
</Callout>

`repos:` and `globs:` are independent axes. The combination most teams need is the one that had no expression before: applies everywhere, but only to certain files.

| | Any file | Scoped with `globs:` |
|---|---|---|
| **All team repos** (no `repos:`) | Escalation policy, review conventions | Design tokens (`**/*.css,**/*.tsx`), Go error-wrapping idioms (`**/*.go`), migration rules (`migrations/**`) |
| **Some repos** (`repos:` set) | "The billing service is PCI scope" | Schema rules in the two repos that own schemas |

## Roll out to one repo first with `repos:`

Omit `repos:` and a rule applies to every repo on the team. To pilot a rule before the whole team lives with it, name the repo you want to start in.

```yaml
---
name: ds-tokens
description: Use the shared spacing, color, and type tokens; never hardcode values.
repos: ["acme/mobile-app"]
globs: ["**/*.css", "**/*.tsx"]
---
```

Once it holds up there, delete the `repos:` line and push. The same file now reaches the desktop app and the website with no other change. While you're still drafting, `status: draft` keeps a rule out of sessions entirely.

## Publish to your team

Team Context is a git repo the ox CLI keeps in sync, so publishing a rule is a commit and a push.

<Terminal>
  <TerminalComment>ox status prints your Team Context path under Team</TerminalComment>
  <TerminalCommand>cd ~/.local/share/sageox/&lt;endpoint&gt;/teams/&lt;team-id&gt;</TerminalCommand>
  <TerminalCommand>git add agents/rules/design-system/</TerminalCommand>
  <TerminalCommand>git commit -m "Add design-system rules: tokens and component naming"</TerminalCommand>
  <TerminalCommand>git push</TerminalCommand>
</Terminal>

On their next session, every AI coworker on the team sees the new rules: the full body for `always`, a catalog entry for `indexed`. Nothing to install, nothing to copy into other repos.

Who a team rule reaches:

- **Every coworker who runs the ox CLI** in a repo connected to the team. Coworkers who don't use the ox CLI won't see it, the same way `.claude/rules/` only reaches Claude Code users.
- **Every AI coworker those coworkers use.** The rule loads through `ox agent prime`, which works the same for every [supported coding agent](/docs/developers/coding-agents).

For Claude Code, the ox CLI also [installs a pointer rule](/docs/developers/claude-code#installed-rules) so Claude Code knows to look in Team Context, instead of copying every team rule into every clone.

The same reference is available offline with `ox guide team-rules`. Team skills (reusable workflows, as opposed to conventions) are on the way; this page covers rules.

## What's next

- [Team Context](/docs/features/team-context): everything else that lives alongside your rules, and how AI coworkers read it
- [How it works](/docs/developers/how-it-works): the prime, work, capture loop that delivers rules at session start
- [Supported coding agents](/docs/developers/coding-agents): every tool team rules reach, and its integration tier
- [SageOx + Claude Code](/docs/developers/claude-code): the installed rules and hooks specific to Claude Code
- [ox guide](/docs/cli/guide): read this reference in your terminal with `ox guide team-rules`


---

# Your data (https://sageox.ai/docs/features/your-data)

# Your data

SageOx stores your team's content in git repos: Ledgers and Team Context. You can inspect the customer content we store, clone it locally, and take it with you if you leave.

## Data sovereignty

Your data belongs to you, in formats your tools can actually read. SageOx stores customer content in standard git repos, no proprietary export format and no lock-in.

- **You own it.** Clone the repo and you hold a complete copy, full history included.
- **You can see it.** Every customer-content file is readable and every change is in `git log`.
- **It's versioned.** Git tracks every change, so you can diff any two points in time and audit exactly what moved.
- **Your AI coworkers can consume it.** Git, Markdown, and standard media files work with tools beyond SageOx. Your data feeds your tools directly, not just ours.

This is a deliberate bet: the tools people keep are the ones whose data stays available to them and to the AI coworkers working on their behalf.

## It's git repos all the way down

All customer content SageOx stores for your team lives in a git repository:

| Repo | What it contains | Scope |
|------|-----------------|-------|
| **Team Context** | Conventions, decisions, discussions, discussion recordings, transcripts, distilled memory | Team-wide |
| **Ledger** | Code work history, commits, session records, project-specific decisions | Per-repo |

These are real git repos. You can browse them, diff them, and `git log` them. A `git checkout` contains all customer content, including audio recordings. Only rebuildable caches and operational state such as permissions and settings live outside these repositories.

<Terminal>
  <TerminalComment>Browse your Team Context</TerminalComment>
  <TerminalCommand>cd my-project/.sageox/teams/primary</TerminalCommand>
  <TerminalCommand>ls</TerminalCommand>
  <TerminalOutput>AGENTS.md    MEMORY.md    SOUL.md    TEAM.md    discussions/    docs/    memory/</TerminalOutput>
  <TerminalComment>See the full history of changes</TerminalComment>
  <TerminalCommand>git log --oneline</TerminalCommand>
</Terminal>

## Common questions

### Does SageOx work with private repos?

Yes. SageOx connects to your existing git hosting (GitHub, GitLab, etc.) using the access you grant during `ox init`. Your source code stays where it is. SageOx reads metadata and commit history, not your codebase.

CodeDB indexes your code locally on your machine. The index lives in your local filesystem, not on SageOx servers.

### Does SageOx send my code to Anthropic or OpenAI?

**SageOx does not send your source code to any LLM provider.**

When you use AI coworkers (like Claude Code), those sessions run through *your* AI provider account, the same way they would without SageOx. SageOx adds context to those sessions (Team Context, CodeDB results), but doesn't proxy or intercept the AI traffic.

SageOx uses LLMs for processing recordings (transcription, summarization, keyframe analysis) via **AWS Bedrock** in our own AWS account. Your code is not involved, the inputs are audio and video from discussions you record, not your source code.

### Where does the data live?

| Data type | Where it lives |
|-----------|---------------|
| **Your source code** | Your existing git host (GitHub, GitLab, etc.), unchanged |
| **Team Context** | SageOx-hosted git server (us-west-2) |
| **Ledger** | SageOx-hosted git server (us-west-2) |
| **Discussion recordings (audio/video)** | Team Context git repository on the SageOx-hosted git server (us-west-2) |
| **CodeDB index** | Your local machine only |

Team Context and Ledger repos are synced to your local filesystem via `ox init`. You always have a local copy.

### Can I export my data?

All customer content is in git repos. Your Team Context and Ledger checkouts give you a complete copy, recordings and full history included.

<Terminal>
  <TerminalComment>Back up one local Team Context checkout</TerminalComment>
  <TerminalCommand>cp -r my-project/.sageox/teams/primary ~/my-team-context-backup</TerminalCommand>
</Terminal>

Repeat that for each Ledger you want to back up. No export wizard, no CSV downloads, no waiting for a support ticket. It's git. We will keep improving the checkout and portability experience over time.

### Can SageOx employees see my data?

SageOx infrastructure operators have access to the git servers that host your Team Context and Ledger repos, the same way any hosted git provider's operators have access to the servers hosting your repos. We don't access customer data without explicit permission, and all access is audit-logged.

We can't see your source code: it stays on your existing git host. We can't see your CodeDB index: it's local to your machine. We don't proxy or inspect the live traffic between your AI coworker and your provider. Session records you capture live in your Ledger and have the same access controls as its other customer content.

## The transparency principle

Most tools that offer "AI-powered team knowledge" are black boxes. You put data in, magic happens, and you hope the output is right.

SageOx customer content lives in git repos. You can `cat` every file, `git log` every change, and `diff` any two points in time. If something looks wrong, you can see exactly what changed and when.

If you decide SageOx isn't for you, make a `git checkout` and walk away. Your data is yours.

## What's next

- [Team Context](/docs/features/team-context): what's inside your Team Context repo and how to edit it
- [Connect a repository](/docs/developers/connect-repository): how SageOx connects to your code
- [Security](/security): encryption, access control, and compliance details


---

# Integrations (https://sageox.ai/docs/integrations)

Your team's decisions get argued out in chat and on calls, not only in meetings you remember to record. Integrations connect those places to your Team Context, so the knowledge your AI coworkers capture shows up where your team already is.

## The model: one ladder, per place

A **place** is somewhere your team talks — a chat workspace, a meeting platform. Every place is scored on the same ladder, from passive to active:

```mermaid
graph LR
    P["Posts<br/>SageOx publishes"] --> L["Listens<br/>SageOx reads the room"]
    L --> J["Joins in<br/>SageOx replies"]
```

- **Posts** — SageOx publishes into the channels you pick: discussion murals, live join links, nightly team murals, and a welcome when a coworker joins.
- **Listens** — what happens in the place flows back into Team Context, so a decision made in a thread is something your coworkers can cite months later.
- **Joins in** — SageOx takes part directly: replying, raising a point, sharing what it knows.

## Where SageOx can take part today

| Place | Posts | Listens | Joins in |
|---|---|---|---|
| [**Slack**](/docs/integrations/slack) | Available | Not yet | Not built |
| **Zoom** | Not applicable | Available, per meeting | Not built |
| **Google Meet** | Not applicable | Available, per meeting | Not built |
| **Buzz** · **Google Chat** · **Microsoft Teams** | Coming soon | Coming soon | Coming soon |

A meeting platform is not a publishing destination and never will be, which is why its Posts column reads "not applicable" rather than "off". Meetings also connect differently: there's no workspace to authorize, so you invite SageOx into a specific call with its join link.

<Callout type="info">
Chat places are configured per team, in **Settings → Communication**. What one team connects and publishes stays scoped to that team. Each integration's page says **who authorizes** the grant — some are personal, some are team-wide, and one grant never implies another.
</Callout>

## What's next

- [Slack](/docs/integrations/slack): publish your team's knowledge into the channels it already watches, and what every control on the settings page does.
- [Team Context](/docs/features/team-context): where published knowledge comes from.
- [Context capture](/docs/context-capture): how conversations become knowledge in the first place.


---

# Slack (https://sageox.ai/docs/integrations/slack)

# Slack

SageOx and Slack connect in four separate ways, and the word "connect" hides the question that matters: **who is granting what, and in which direction does data move?** One grant never implies another: a workspace admin publishing to `#decisions` doesn't let SageOx read your messages, and asking Slackbot a question doesn't let anyone else see your Slack.

```mermaid
graph LR
    subgraph you["You authorize"]
        direction TB
        SB["Ask Slackbot"]
        SR["Search your Slack"]
        SI["Sign in with Slack"]
    end
    subgraph admin["An admin authorizes"]
        PB["Post to channels"]
    end
    SX["SageOx"]
    SX -->|"your context, on ask"| SB
    SR -->|"your messages, per question"| SX
    SI -->|"identity only"| SX
    SX -->|"murals, join links"| PB
```

| Grant | Who authorizes | What moves | What SageOx keeps |
|---|---|---|---|
| **Post to channels** <br/>*Available* | A workspace admin, per team | SageOx → the channels you pick | A workspace credential, and your channel choices |
| **Ask Slackbot** <br/>*Coming soon* | You, inside Slack | Your SageOx context → Slackbot, only when you ask | The same per-user grant every AI tool gets |
| **Search your Slack** <br/>*Coming soon* | You | Your Slack messages → SageOx, per question, never stored | An encrypted credential, not the messages |
| **Sign in with Slack** <br/>*Coming soon* | You | Nothing. Identity only | A verified link between your two accounts |

<Callout type="info">
Personal grants ("You authorize") benefit only you and the AI tools you connected. The team grant benefits every coworker on that team, human and AI. Manage personal grants from [Settings → Connections](/settings/connections) and [Settings → Security](/settings/security); the team grant lives in the team's **Settings → Communication**.
</Callout>

## Post to channels

Your team already lives in Slack. Architecture calls happen in `#engineering`, roadmap trade-offs in `#product`, critique in `#design`, and the reasoning behind each one scrolls away by Friday. Linking a channel closes the gap between where the work is discussed and where it's remembered.

{/* Asset is published as `docs/integrations/communication-slack-channels`
    (@sageox/assets 0.1.16). Add `id="docs/integrations/communication-slack-channels"`
    once the monorepo's @sageox/assets pin can be bumped off 0.1.10 — blocked on a
    read:packages grant for the local npm token. */}
<ScreenFrame
  alt="The Where SageOx is section of team Settings → Communication, expanded to show a connected Slack workspace and its two channels."
  caption="Settings → Communication. Each place carries its own row; expanding a workspace shows every channel SageOx is in, what publishes there, and what it can read."
/>

**This grant is one direction: publish only.** SageOx pushes knowledge *out* to Slack; it does not read your Slack conversations back *in*. Reading channels is designed but not built, and the settings page above says so on its face rather than hiding it.

### What gets published

Four kinds of post, and nothing else. Each one is something you choose per channel.

| What lands in the channel | When |
|---|---|
| **Discussion murals** | The mural from each discussion, posted when it wraps. |
| **Live discussion started** | A join-now link — posts every time a discussion starts. |
| **Team murals** | A nightly mural of what moved on the team. |
| **Coworker joined** | A welcome note when a new coworker joins the team. |

Raw transcripts, recordings, and full distillations are never posted to Slack. A mural carries the distilled takeaway as a picture, with a link back to the discussion for anyone who wants the detail.

### Set up

<Steps>

<Step>
#### Open your team's communication settings

Go to **Settings → Communication** for your team. The **Where SageOx is** section lists every place SageOx can take part in.
</Step>

<Step>
#### Connect your workspace

Click **Connect** on the Slack row and authorize SageOx. This installs the SageOx app into your workspace so it can post to the channels you choose. It does **not** read your workspace's messages.

Slack shows **"App is not approved by Slack"** on the install screen. That appears for every app not yet listed in the Slack Marketplace, ours included. Nothing is broken.
</Step>

<Step>
#### Pick the channels and what goes in each

Right after you connect, the list of your workspace's public channels opens — pick one (private channels aren't listed yet, see below). Adjust its chips to choose what posts there, and use **Add channel** on the Slack row to add more. Two channels is the shape most teams settle on: a high-signal `#discussions` for discussion murals and join links, and an ambient `#status` for nightly team murals and welcomes.
</Step>

<Step>
#### Confirm it's working

For an instant check, open a channel's **⋯** menu and choose **Send test message** — it posts a real message so you can confirm murals will land. Beyond that, the next discussion posts its join link as it starts and its mural when it wraps. No bot to babysit.
</Step>

</Steps>

## What the controls do

The page answers two questions with opposite shapes, so it is two lists, not one.

- **What SageOx posts** — short and enumerated. One row per kind of post, showing which channels receive it. Use this when you're thinking *"where do nightly murals go?"*
- **Where SageOx is** — unbounded. One row per place, with its channels collapsed underneath. Use this when you're thinking *"what is SageOx doing in `#status`?"*

Both lists edit the same underlying routing, so a change in one shows up in the other immediately.

### Passive and active

Every place is scored on one ladder, from passive to active. The columns are the same for Slack, Zoom, and anything else SageOx takes part in.

```mermaid
graph LR
    P["Posts<br/>SageOx publishes"] --> L["Listens<br/>SageOx reads the room"]
    L --> J["Joins in<br/>SageOx replies"]
```

For Slack today:

| Control | State | What it means |
|---|---|---|
| **Posts** | Available | SageOx publishes the four kinds above into channels you pick. |
| **Listens** | Coming soon | SageOx doesn't read channel messages yet. |
| **Joins in** | Coming soon | SageOx doesn't reply in channels yet. |

<Callout type="info">
A dashed control is a promise about the shape of the page, not about a date. Nothing in SageOx reads your Slack messages today, and the settings page will never let you turn on something that doesn't exist.
</Callout>

### Per-channel controls

Click the channel count on the Slack row — for example, *"2 channels · 2 posting"* — to expand the list of channels SageOx is in.

- **The chips** are what publishes here. Add one with **+ Add**; remove one with its ✕. A channel always keeps at least one chip — to stop a channel entirely, use the switch instead.
- **Posts** is a pause. Turning it off stops publishing to that channel and keeps every chip exactly as you left it, so turning it back on needs no re-setup. Pausing is not unrouting.
- Each channel's **⋯** menu has **Send test message**, which posts a real message so you can confirm murals will land, and **Stop posting here**.

The **Posts** cell on the Slack row itself is a readout of that summary, not a master switch. There is no workspace-wide kill switch by design: a master switch ANDed with per-channel switches is how a team ends up connected, apparently enabled, and silently posting nothing. To stop everything, disconnect the workspace from its **Settings** page — that forgets its channel choices, so reconnecting starts over.

### Public channels only, for now

**The Add channel list shows public channels only, and SageOx joins one on its own — there is nothing to do.**

**Private channels are not supported yet.** They do not appear in the picker, and inviting SageOx does not change that: SageOx never asks your workspace for permission to see private channels, so it cannot list them. Supporting them means requesting an additional Slack permission and every connected workspace re-authorizing, which is why it is a deliberate future step rather than a setting.

<Callout type="warn">
If a channel row ever warns that **SageOx isn't in this channel yet**, run `/invite @SageOx` there. That warning means SageOx could not confirm its own membership, and it matters more than it looks: Slack lets an app post **text** into a channel it can see, while posting an **image** requires real membership. So join links would keep arriving while murals silently dropped. If murals are the one thing missing from a channel, this is the first thing to check.
</Callout>

## Ask Slackbot

**Coming soon.** Slackbot, Slack's built-in AI assistant, will connect to SageOx and answer _"what did we decide about X?"_ or _"who should I ask about Y?"_ from your team's discussions, decisions, and sessions without leaving Slack.

It will connect the same way Claude and ChatGPT do, with a grant that's yours alone: Slackbot will see exactly what you can see in SageOx, and nothing more. Answers will come back to you, in your own Slackbot conversation; posting one into a channel will be your call, the same as pasting an answer from any AI tool.

## Search your Slack

**Coming soon.** When you connect your own Slack account, SageOx will be able to include the messages you already have access to when answering your questions, in any AI tool you've connected. Searches will run under your credential at the moment you ask; SageOx will keep the credential, never the messages.

## Sign in with Slack

**Coming soon.** You'll be able to sign in to SageOx with the Slack account you already use, with no new password. Signing in will also record a verified link between your Slack and SageOx identities, which is how AI coworkers attribute your contributions correctly, and it grants nothing else.

## What's next

- [All integrations](/docs/integrations): the other places SageOx takes part in.
- [MCP overview](/docs/mcp): how AI tools, including Slackbot, connect to SageOx and what they can do.
- [Team Context](/docs/features/team-context): where the knowledge SageOx publishes to Slack comes from.


---

# Connect ChatGPT to SageOx (https://sageox.ai/docs/mcp/chatgpt)

# Connect ChatGPT to SageOx

Most AI chats are an island. You make a decision in ChatGPT, and your team never hears about it unless you stop and tell them. Your team settles something in a Discussion, and your ChatGPT has no idea.

Connect ChatGPT to SageOx and that changes. **Your ChatGPT hears your team, and your team hears it.** Choose one team for cited company knowledge when you connect. If that team also enables the ChatGPT plugin Preview, its updates can reach ChatGPT without anyone posting them twice.

- **Your ChatGPT knows what happened.** When a coworker posts a Murmur or a team Discussion finishes, your AI coworker in ChatGPT gets it as context. It brings it up when it bears on what you are doing. It does not push a feed at you.
- **Your team keeps what you decided.** When a saved ChatGPT conversation lands a decision, SageOx keeps it for the team. The card has one action: **Undo**. A short Murmur can also carry useful work in progress to teammates; it is attributed to your AI coworker, never posted as you.
- **The work crosses tools.** Ask to continue a specific SageOx Plan in Codex. A separate **Open in Codex** card hands the verified Plan and the decisions you kept in this conversation to your own Codex session, for seven days.
- **ChatGPT can act when something happens.** Ask for an automation, such as _"when a Discussion in my team is ready, summarize the decisions"_, and ChatGPT runs it the moment the Discussion is ready.

<Callout type="info">
  The ChatGPT plugin is a **team Feature Preview**, offered to every team and off until a team owner turns it on in the team's **Settings → Feature Preview**. A team's updates reach ChatGPT only while that team has it on.
</Callout>

<Callout type="warning">
  Automatic Keep, company-knowledge citations, and Codex handoff are currently a limited rollout for test users and SageOx employees. Their general-production rollout remains at 0% while live ChatGPT and Codex validation finishes.
</Callout>

## Connect in two minutes

ChatGPT connects to SageOx as a custom app, which needs ChatGPT's Developer mode on the web. Which plans include it, and which can take actions as well as read, is set by OpenAI. See OpenAI's [Developer mode guide](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).

1. **Turn on Developer mode.** In [ChatGPT settings](https://chatgpt.com/#settings), open **Security and login → Developer mode**.

2. **Create the app.** In settings, open **Apps → Create**, then fill in:
   - **Name:** SageOx
   - **URL:** `https://sageox.ai/mcp`

3. **Authorize.** ChatGPT opens a SageOx tab. Sign in, select exactly one team for company knowledge, and approve the connection.

<Callout type="info">
  On a ChatGPT Business, Enterprise, or Edu workspace, an admin turns on Developer mode under **Workspace settings → Permissions & Roles** and can create the app under **Workspace settings → Apps**.
</Callout>

That's it. Start a new conversation and ask _"What is SageOx and how do I get started?"_ to confirm. The guided version of these steps is in [Settings → Connections](/settings/connections). If you connected ChatGPT before your team turned the plugin on, start a new conversation so it picks up the new capability.

## See how it works

| What | When | What ChatGPT gets |
|---|---|---|
| A coworker posts a Murmur | Within about a minute | The Murmur, as context for your AI coworker |
| A team Discussion is ready | When processing finishes | The title, a link, and how many decisions it holds |
| Your saved conversation decides something | When the decision is clear | A kept-decision card with **Undo**; the team record receives the decision |
| Another user's AI reads a Plan you own | On your next eligible new chat, within seven days | One neutral line with the canonical Plan link; no new thread, badge, title, or coworker name |
| You ask to continue a Plan in Codex | After SageOx verifies your Plan and active captured conversation | A separate card whose only action is **Open in Codex** |

- **What was said stays behind your access.** A notice carries an id and a link, never the transcript. ChatGPT reads the Discussion through SageOx using your own access.
- **Company knowledge stays on the connected team.** ChatGPT's citation tools search only the one team selected on this connection. A citation can open the complete authorized Discussion or verified Plan; SageOx does not fan the query out to your other teams.
- **No repeats, no noise.** A conversation murmurs again only when something new and useful has changed. Small talk never becomes a Murmur. If your AI coworker already shared a Murmur itself, SageOx does not repeat it.
- **You never hear your own Murmurs back.** Murmurs that come from your conversations go to your coworkers, not back to you.
- **Return comes from authenticated Plan reads, not Murmurs.** SageOx records identifiers and counts only after another authorized user successfully reads the full verified Plan. Raw Murmurs never trigger the line in your next chat.
- **A Codex handoff stays yours.** It has no recipient picker, assignment, or cross-person delivery. Only the same signed-in SageOx user can reopen it before it expires.

## Control what flows

- **For the whole team.** A team owner turns the ChatGPT plugin on or off in the team's **Settings → Feature Preview**. Off stops that team's updates for everyone on it.
- **On / Off.** In [Settings → Connections](/settings/connections) → ChatGPT, turn the connection's team updates off and on. Turning it back on is instant.
- **Team updates.** On the same page, pick which teams may send enabled updates to ChatGPT. Updates arrive only from selected teams that also have the plugin Preview on.
- **Company knowledge.** Select exactly one team for ChatGPT's cited `search` and `fetch` tools. Those tools never fan out to other teams you can access.
- **Off the record.** Say _"off the record"_ in ChatGPT. Nothing after that is captured or shared.
- **Disconnect.** Disconnecting ChatGPT removes its team updates and settings along with the connection.

## Explore what's next

- [Getting the most out of SageOx](/docs/mcp/getting-the-most): how to prompt your AI coworker well
- [MCP overview](/docs/mcp): what tools are available and how sign-in works


---

# Connect Claude to SageOx (https://sageox.ai/docs/mcp/claude)

# Connect Claude to SageOx

SageOx is not yet listed in the Anthropic connector directory, so you cannot find it by searching Claude's connector browser. You can still connect by adding it manually, the process takes under two minutes and works identically whether or not a connector is listed.

## Claude Code

The recommended path is the ox CLI: it gives Claude Code ledger sync, session recording, and richer team context than MCP alone.

<Terminal>curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash</Terminal>

After install, run `ox login` and follow the prompts. See [Getting started with the CLI](/docs/cli) for what to do next.

**MCP-only alternative.** If you want the MCP connection without the CLI, run:

<Terminal>claude mcp add --transport http sageox https://sageox.ai/mcp</Terminal>

Claude Code will open a browser tab to authorize your SageOx account on first use. After that, ask Claude Code _"What is SageOx and how do I get started?"_ to confirm the connection.

## Claude Desktop and Claude.ai (web)

Both surfaces share the same Connectors panel, so the steps are identical. Starting from the web is easier: there is no app to navigate.

1. **Open Connectors.** Go to [claude.ai/customize/connectors](https://claude.ai/customize/connectors) (web), or in Claude Desktop open the Customize panel from the menu.

2. **Add a custom connector.** Click the **+** icon in the top-right of the Connectors panel, then choose **Add custom connector**.

3. **Fill in the details.**
   - **Name:** SageOx
   - **URL:** `https://sageox.ai/mcp`

   Click **Add**.

4. **Connect.** SageOx appears under *Not connected*. Click **Connect** on that row, a browser tab opens to authorize your SageOx account.

   <Callout type="info">
     If the browser is signed into a different Claude account than your desktop app, you will see an **Account mismatch** screen. Sign out at claude.ai, sign back in with the same account as your Claude Desktop, then click Connect again.
   </Callout>

5. **Approve the security prompt.** Claude warns that the connector is _"not verified by Anthropic."_ This appears for every manually-added MCP server. It is not specific to SageOx. Click **Allow access**, then return to Claude.

Once connected, ask Claude _"What is SageOx and how do I get started?"_ to confirm everything is working. Claude will call the `GetStarted` tool and walk you through the rest.

## Managing your connection

Active grants are listed at [/settings/security](/settings/security). You can disconnect SageOx at any time, revocation takes effect on the next MCP call.

## What's next

- [Getting the most out of SageOx](/docs/mcp/getting-the-most): how to prompt Claude well and what the interactive cards do
- [MCP overview](/docs/mcp): what tools are available and how auth works


---

# Getting the most out of SageOx (https://sageox.ai/docs/mcp/getting-the-most)

# Getting the most out of SageOx

Connecting SageOx is step one. The difference between "it's installed" and "it's useful" is knowing how to ask. This page is the short version.

## Ask for what you actually want

AI tools decide which tool to call from how you phrase the request. A little specificity goes a long way.

| Instead of | Try |
|---|---|
| "What's our retry policy?" | "Search SageOx for what we decided about the ingestion retry policy." |
| "Save this." | "Save this conversation as a session in the **Platform** team." |
| "What am I working on?" | "List my SageOx teams, then show recent sessions in the one for this repo." |

Naming the action ("search SageOx", "save to the X team"), and naming the destination removes the guesswork. When in doubt, mention **SageOx** by name, it nudges the model toward the right tool.

## What you can do today

- **See your teams.** _"What teams am I on in SageOx?"_
- **Search team knowledge.** _"What did we decide about the cast renderer audio track?"_, pulls from discussions and prior sessions, not just open files.
- **Save a session.** _"Save this chat as a session in the Marketing team."_ Your conversation joins the team's Ledger, so the next coworker, human or AI, inherits it.
- **Read team knowledge.** _"What's in the SageOx onboarding team?"_

## The interactive cards, the best way to use SageOx

This is the difference that compounds. In **Claude, ChatGPT, VS Code, Goose, and SageOx's own chat**, answers can come back as **interactive cards** instead of paragraphs.

Without cards, you ask "what did we decide?" and read a summary, then you still have to go act on it somewhere else. With cards, the decision ledger comes back as something you scan and click. Action items arrive as a list you check off. A session is a card you name and save without leaving the conversation. What's being captured shows as a live control surface. You stop *reading about* your team's work and start *operating on it* in place.

That matters most when you're working alongside peers and other agents: their output lands as objects you can manipulate, not transcripts you have to re-read.

### Cards you'll see

| Card | What it does |
|------|-------------|
| **Session control surface** | Shows your session's scope at a glance: what it reads, where it writes, and whether it's recording. Toggle sources, switch the write target, stop or save the recording inline. |
| **Decision ledger** | Decisions and action items pulled from a recording, each marked AI- or human-sourced, with the moment they were grounded. |
| **Recording insights** | The intelligence from a recording: decisions, action items, open questions, who decided what. |
| **Chapter scrubber** | A recording's auto-extracted chapters as a timeline you can jump around by topic. |
| **Session recap** | Your team's recent recordings, with live status, one click into any of them. |
| **Attention tray** | One consolidated "what needs me": recent blockers, decisions, and recordings. |
| **Team murmurs** | A live pulse of your team's coordination signals: what's in progress, decided, or blocked. |
| **Expertise map** | Who to ask about a topic, surfaces who knows what across your team. |
| **Org memory** | The topic view of your team's knowledge: what's been discussed and decided, by subject. |
| **Bubble & team pickers** | Click to choose which Knowledge Bubble or team a conversation works against, no copy-pasting IDs. |

You don't have to do anything to get them, when a card fits, your tool renders it. A few things worth knowing:

- **Cards are live, not screenshots.** Click into them; they do the action.
- **They respect your permissions** exactly like text answers do (see below).
- **No card support? Nothing breaks.** You get the same answer as plain text, without the click.


## It sees only what you see

This is the part that matters most. When you connect, SageOx maps the grant to **your** account. Your AI tool can read your personal team plus any team or repo where you're a member, and nothing else. There's no admin override, no "service account" that sees everything.

That means you can connect with confidence, and you can disconnect just as easily at [`/settings/security`](/settings/security). Revoking takes effect on the next call.

## Where to go next

- New here? Start with the [MCP overview](/docs/mcp).
- Picking a tool? [Settings > Connections](/settings/connections) has a guided setup for each one.


---

# MCP overview (https://sageox.ai/docs/mcp)

# MCP

MCP (Model Context Protocol) lets AI tools securely read your SageOx knowledge: no scraping, no copies, just your permissions extended.

When you connect, your AI tool gets a scoped OAuth grant that maps to **your** SageOx account. It sees what you see: your personal team plus any team or repo where you're a member. Nothing more.

## Connect your tool

Connect from [Settings > Connections](/settings/connections). Pick your tool and authorize. Cursor, VS Code, Windsurf, Goose, Claude Desktop, ChatGPT, and Copilot Studio each have a guided setup there. Claude Code does not need one: it uses the ox CLI instead.

Using a different client? Point it at the [raw URL and canonical `mcpServers` JSON](/docs/mcp/manual).

## What MCP does for you

Once connected, your AI tool can:

- **See your teams.** "What teams am I on in SageOx?"
- **Search team knowledge.** "What did we decide about the ingestion retry policy?"
- **Save sessions.** "Save this conversation as a session in the Marketing team."
- **Read team knowledge.** "What's in the SageOx Marketing team?"

The scopes are presented when you authorize, you can see exactly what the tool will be able to do before you click Approve.

Once you're connected, [**Getting the most out of SageOx**](/docs/mcp/getting-the-most), shows how to prompt your tool well and what the interactive cards do.

## Managing connections

Active MCP grants are listed at [`/settings/security`](/settings/security). You can disconnect individual clients or disconnect all at once. Disconnecting forces the client to reauthorize on its next call: there's no token left behind.


---

# Connect any MCP client (https://sageox.ai/docs/mcp/manual)

# Connect any MCP client

SageOx speaks the standard MCP protocol with OAuth 2.1 + Dynamic Client Registration (RFC 7591). If your tool supports MCP, this is everything it needs.

## Server URL

```text
https://sageox.ai/mcp
```

## mcpServers config

For tools that use a JSON config file:

```json
{
  "mcpServers": {
    "sageox": {
      "url": "https://sageox.ai/mcp"
    }
  }
}
```

## How auth works

On the first call to the SageOx MCP server, your tool will:

1. Discover OAuth metadata at `/.well-known/oauth-authorization-server`
2. Register itself via DCR at `/api/auth/oauth2/register` (PKCE required)
3. Open a browser tab to the OAuth consent screen
4. Exchange the auth code for an access token at `/oauth2/token`
5. Use the bearer token for all subsequent MCP calls

This is standard MCP, no SageOx-specific extensions. Any MCP-compliant client should Just Work.

## Tools available

| Tool | What it does |
|------|-------------|
| `ListTeams` | Lists the teams the authorized user belongs to |
| `ListBubbles` | Lists Knowledge Bubbles the user can see (personal / profile / team / repo / custom) |
| `SaveSession` | Saves a chat session into a chosen bubble |
| `Search` | Searches the team knowledge index |

Tool definitions come from `tools/list`. Scopes are surfaced on the OAuth consent screen.

## Managing connections

[`/settings/security`](/settings/security) lists all active grants. Revoke per-client or all at once, revocation invalidates the access token, so the next MCP call returns 401 and the client cleans up its local state.


---

# New team member quickstart (https://sageox.ai/docs/quickstart/new-team-member)

# New team member quickstart

This guide is for people **joining an existing team** via an invite link.

<Callout>
  Setting up SageOx for your team from scratch? See the [Team Setup Quickstart](/docs/quickstart/team-setup) instead.
</Callout>

## Step 1: Accept the invite

Click the invite link your teammate shared. This takes you to SageOx where you can create an account (or sign in), and join the team.

## Step 2: Choose how you want to start

| If you are mostly | Start here |
|---|---|
| Working in a repo | Install the ox CLI, then connect each repo you work in |
| Working in a connected tool | Connect SageOx over [MCP](/docs/mcp) |
| Recording discussions | Start with [web app recorder](/docs/context-capture/web-app-recorder) |
| Importing an existing recording | [Video import](/docs/context-capture/video-import) |

## Step 3: If you are building in code, install the CLI

<Terminal>
  <TerminalCommand>curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash</TerminalCommand>
</Terminal>

## Step 4: If you are building in code, authenticate

<Terminal>
  <TerminalCommand>ox login</TerminalCommand>
</Terminal>

This opens your browser to confirm. Your session persists across terminal restarts.

## Step 5: If you are building in code, connect your repositories

In each git repo you work on:

<Terminal>
  <TerminalCommand>cd ~/code/my-project</TerminalCommand>
  <TerminalCommand>ox init</TerminalCommand>
</Terminal>

This links the repo to your team. Repeat for each repo you work on.

## Step 6: Start using SageOx

If you connected a repo, launch your AI coding tool as usual:

<Terminal>
  <TerminalCommand>claude</TerminalCommand>
</Terminal>

The agent automatically runs `ox agent prime` on startup, injecting your team's shared context: conventions, architectural decisions, and domain knowledge.

If you started with MCP instead, connect your tool through the [MCP overview](/docs/mcp), and ask it to search SageOx or read team knowledge.

If you started with capture, record a discussion or import a walkthrough and let SageOx distill it into Team Context for the rest of the team.

If the repo-connected setup seems off, run `ox doctor` to diagnose authentication, repo connection, and team membership.

## Next steps

- [CLI Commands Reference](/docs/cli/quickstart)
- [MCP overview](/docs/mcp)
- [Learn about Team Context](/docs/context-capture/discussions)
- [web app recorder](/docs/context-capture/web-app-recorder): record team discussions


---

# Solo quickstart (https://sageox.ai/docs/quickstart/solo)

# You don't need your whole team

This page is for **you**, the solo builder shaping product in a repo before the rest of the team joins.

If you are starting from a connected tool or from recordings instead, see [Getting started](/docs/getting-started).

## Setup (2 minutes)

<Terminal>
  <TerminalComment>Install the CLI</TerminalComment>
  <TerminalCommand>curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash</TerminalCommand>
  <TerminalComment>Sign in and connect your repo</TerminalComment>
  <TerminalCommand>ox login</TerminalCommand>
  <TerminalCommand>cd ~/code/my-project</TerminalCommand>
  <TerminalCommand>ox init</TerminalCommand>
</Terminal>

That's it. You now have a team (just you), and a connected repo.

---

## Immediate wins, no teammates required

### 1. Better coding sessions, instantly

When you run `ox init`, SageOx sets up context injection for your AI coworkers. Every repo-based coding session starts with your team's conventions, architectural decisions, and domain knowledge pre-loaded.

But here's the solo-player unlock: **CodeDB**.

<Terminal>
  <TerminalComment>Index your codebase for semantic search</TerminalComment>
  <TerminalCommand>ox code index</TerminalCommand>
</Terminal>

CodeDB indexes your repo's code and git history into a searchable database that repo-based coding tools can query. Instead of grep-and-hope, your AI coworker gets:

- **Semantic code search**: find functions, types, and patterns by meaning, not just text
- **Git history search**: "when did this behavior change?" and "who touched this module?"
- **Cross-reference navigation**: understand how code connects across your codebase

This alone makes coding sessions much better at navigating large codebases. No coworkers needed: it's you and a better-informed AI coworker.

### 2. Turn screen recordings into searchable knowledge

You already record Loom walkthroughs. You already use Cap to capture quick demos. Right now those recordings live in Slack threads that nobody will ever find again.

Import them into SageOx and they become structured, searchable artifacts:

<Terminal>
  <TerminalComment>Import a Loom walkthrough</TerminalComment>
  <TerminalCommand>ox import https://www.loom.com/share/abc123</TerminalCommand>
  <TerminalComment>Import a local Cap recording</TerminalComment>
  <TerminalCommand>ox import ~/Movies/cap-recording.mp4</TerminalCommand>
</Terminal>

SageOx transcribes the audio, extracts keyframes, summarizes the content, and commits it all to your Team Context repo. The next time you work in a connected tool or a coding session, the context is there waiting.

**Use cases that pay off immediately:**

| Record this | Get this |
|---|---|
| Quick UX walkthrough of a bug | Searchable reproduction steps + screenshot keyframes |
| "Here's how this feature should work" | Design intent your AI coworker can reference later |
| CLI tool error you hit | Captured error output + your verbal debugging notes |
| Architecture explanation to yourself | Transcribed decisions your future self can search |

### 3. Voice memos to yourself

Create a habit of recording 60-second voice memos when you have an idea, make a decision, or hit a wall.

Open the [web app recorder](/docs/context-capture/web-app-recorder) on your phone (add it to your home screen for one-tap access), and talk:

- *"I'm going with Postgres JSONB for the metadata column because we don't know the schema yet and I don't want to run a migration every time we add a field."*
- *"The auth flow is broken when the refresh token expires during a long-running upload. Need to add retry logic in the upload middleware."*
- *"Idea: we should expose the keyframe extraction as a public API endpoint so other tools can use it."*

These get transcribed and committed automatically. Six months from now, when someone asks "why did we use JSONB here?", the answer is in your Team Context, not lost in your head.

### 4. Import your back catalog

Got a folder of old Loom videos? A backlog of Cap recordings? Import them all at once:

<Terminal>
  <TerminalComment>Batch import from a directory</TerminalComment>
  <TerminalCommand>ox import ~/recordings/*.mp4</TerminalCommand>
</Terminal>

Every recording gets transcribed, summarized, and indexed. Instant searchable knowledge base from content you already have.

---

## Why this matters even as a solo player

The compounding effect is real. After a week of importing recordings and recording voice memos, you'll have:

- **An AI coworker that knows your decisions**: not just your code, but *why* you wrote it that way
- **Searchable walkthroughs**: no more scrubbing through 20-minute Loom videos to find the one thing you said about the API
- **A personal engineering journal**: that you barely had to write, because you just talked

And when your coworkers eventually ask "what is this thing you keep importing recordings into?", you already have the answer. Some of them may join with the ox CLI in a repo. Others may start from a connected tool, or by recording. Everything you've built is already there waiting for them.

## Running in cloud agents

If you use Claude Code Cloud, Devin, or run `ox` from CI, the `ox login` device flow doesn't work: there's no browser in those sandboxes. Use a [Personal Access Token](/docs/cli/pats) instead:

<Terminal>
  <TerminalCommand>export SAGEOX_TOKEN=oxp_...</TerminalCommand>
  <TerminalCommand>ox agent prime</TerminalCommand>
</Terminal>

See [Running ox in constrained environments](/docs/cli/ephemeral-mode) for platform-specific recipes.

## Next steps

- [Video Import](/docs/context-capture/video-import): full guide to importing recordings
- [web app recorder](/docs/context-capture/web-app-recorder): record from your browser or phone
- [Team Setup](/docs/quickstart/team-setup): ready to invite your team?


---

# Team setup quickstart (https://sageox.ai/docs/quickstart/team-setup)

# Team setup quickstart

This guide is for **team creators**, the first person setting up SageOx for their team.

<Callout>
  Already been invited to a team? See the [New Team Member Quickstart](/docs/quickstart/new-team-member) instead.
</Callout>

## Prerequisites

- A [SageOx account](https://sageox.ai)
- A git repository you want to connect

## Step 1: Install the CLI

<Terminal>
  <TerminalCommand>curl -fsSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash</TerminalCommand>
</Terminal>

## Step 2: Authenticate

<Terminal>
  <TerminalCommand>ox login</TerminalCommand>
</Terminal>

This opens your browser to sign in. Credentials are stored securely on your machine.

## Step 3: Connect your first repository

Navigate to your repo and initialize SageOx:

<Terminal>
  <TerminalCommand>cd ~/code/my-project</TerminalCommand>
  <TerminalCommand>ox init</TerminalCommand>
</Terminal>

This creates a team automatically (if you don't have one), and registers your repository.

## Step 4: Invite your team

Open your team page in the web app and copy the invite message. It includes:

- Your team invite link
- the repo-connected ox CLI path for coworkers building in code
- the docs links for coworkers who will start in connected tools or through capture flows

Share it via Slack, email, or however your team communicates.

When you share it, tell people to start with whichever matches how they actually work:

- **In a repo**: install the ox CLI, then run `ox login` and `ox init` in the repos they work in
- **In a connected tool**: connect SageOx over [MCP](/docs/mcp)
- **By recording**: start with [web app recorder](/docs/context-capture/web-app-recorder), or [Video import](/docs/context-capture/video-import)

## Step 5: Record a discussion

Capture team knowledge so it flows into your Team Context:

1. Open the [web app recorder](/docs/context-capture/web-app-recorder) from your team page
2. Click **Start Recording**
3. Transcription and insights happen automatically

## Next steps

- [CLI Commands Reference](/docs/cli/quickstart)
- [MCP overview](/docs/mcp)
- [Learn about Team Context](/docs/context-capture/discussions)
- [web app recorder](/docs/context-capture/web-app-recorder)


---

# ox adapter (https://sageox.ai/docs/cli/adapter)

# ox adapter

Discover, install, remove, and inspect the adapter binaries that connect AI coworkers to ox.

## Usage

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

## Subcommands

| Command | Description |
|---------|-------------|
| `ox adapter list` | List installed and available adapters |
| `ox adapter info <name>` | Show detailed info for an adapter |
| `ox adapter install <name\|github-url>` | Install an adapter from the registry or a GitHub repository |
| `ox adapter remove <name>` | Remove an installed adapter |
| `ox adapter link <path>` | Symlink a local adapter binary for development |
| `ox adapter unlink <name>` | Remove a symlinked adapter |
| `ox adapter verify <name>` | Run compliance tests against an adapter |
| `ox adapter reload` | Signal the daemon to re-scan adapter directories |

## Examples

List what's installed and available:

<Terminal>
  <TerminalCommand>ox adapter list</TerminalCommand>
</Terminal>

Install an adapter by name from the built-in registry, or by GitHub URL. Binaries land in `~/.local/share/ox/adapters/`:

<Terminal>
  <TerminalCommand>ox adapter install cursor</TerminalCommand>
  <TerminalCommand>ox adapter install github.com/sageox/ox-adapters</TerminalCommand>
</Terminal>

Installing from an arbitrary repository, or a curated entry without a pinned checksum, requires opting out of the SageOx-curated checksum:

<Terminal>
  <TerminalCommand>ox adapter install github.com/sageox/ox-adapters --allow-unverified</TerminalCommand>
</Terminal>

## Develop an adapter

Symlink a locally-built binary into the adapter directory, then run it against the protocol compliance suite. `link` is the recommended workflow while developing, the binary must respond to the `info` subcommand:

<Terminal>
  <TerminalCommand>go build -o ./bin/ox-adapter-myagent ./cmd/ox-adapter-myagent</TerminalCommand>
  <TerminalCommand>ox adapter link ./bin/ox-adapter-myagent</TerminalCommand>
  <TerminalCommand>ox adapter verify myagent</TerminalCommand>
</Terminal>

`verify` checks that the adapter correctly implements the `info`, `detect`, and `serve-mode` commands. Remove a symlink again with `ox adapter unlink <name>`, it only removes symlinks, never real binaries.

## What's next

- [ox agent](/docs/cli/agent) - Prime the AI coworker an adapter connects
- [ox daemon](/docs/cli/daemon) - The daemon that `ox adapter reload` signals
- [ox integrate](/docs/cli/integrate) - Wire agents into a repository


---

# 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


---

# ox login (https://sageox.ai/docs/cli/auth)

# ox login

Authenticate your CLI with the SageOx platform using device flow authorization.

## Usage

<Terminal>
  <TerminalCommand>ox login</TerminalCommand>
</Terminal>

<Callout type="info">
**For CI, cloud agents, or scripts:** use a Personal Access Token instead of interactive login. See [Personal Access Tokens](/docs/cli/pats).
</Callout>

## How It Works

The `ox login` command uses OAuth 2.0 device flow:

1. **Request device code** - CLI requests a code from SageOx
2. **Open browser** - Authorization page opens automatically
3. **Authorize** - Sign in and approve CLI access
4. **Complete** - CLI receives and stores credentials

This is secure because your password never enters the terminal.

## Credential Storage

| OS | Location |
|----|----------|
| macOS/Linux | `~/.config/sageox/credentials.json` |
| Windows | `%APPDATA%\sageox\credentials.json` |

## Commands

<Terminal>
  <TerminalComment>Check authentication status</TerminalComment>
  <TerminalCommand>ox status</TerminalCommand>
  <TerminalComment>Remove stored credentials</TerminalComment>
  <TerminalCommand>ox logout</TerminalCommand>
  <TerminalComment>Re-authenticate (switch accounts)</TerminalComment>
  <TerminalCommand>ox login --force</TerminalCommand>
</Terminal>

## Troubleshooting

**Browser does not open** - Copy the displayed URL manually.

**Authentication timeout** - Device code expires after 15 minutes. Run `ox login` again.

**Wrong account** - Run `ox logout` then `ox login`.

## Environment Variables

| Variable | Description |
|----------|-------------|
| `SAGEOX_API_URL` | Override API endpoint |
| `SAGEOX_NO_BROWSER` | Set to `1` to disable automatic browser |
| `SAGEOX_TOKEN` | Personal Access Token for headless auth, see [pats](/docs/cli/pats) |

## Related Commands

- [Personal Access Tokens](/docs/cli/pats) - Headless auth for CI and cloud agents
- [Running ox in ephemeral environments](/docs/cli/ephemeral-mode) - Claude Code Cloud, Devin, GitHub Actions
- [ox doctor](/docs/cli/doctor) - Diagnose CLI issues
- [ox init](/docs/cli/init) - Initialize a repository


---

# ox code (https://sageox.ai/docs/cli/code)

# ox code

Search this repo's git history and current code with natural-language queries. `ox code` reads CodeDB -- the local index built by [`ox index`](/docs/cli/index-cmd) -- and surfaces planning signals like hotspots, stalled PRs, and index status.

## Usage

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

Every subcommand reads the local CodeDB index. Build or refresh it first with [`ox index`](/docs/cli/index-cmd).

## Subcommands

| Command | Description |
|---------|-------------|
| `ox code search <query>` | Search indexed code using queries |
| `ox code insights` | Show planning-relevant code insights (hotspots, contention, recent activity) |
| `ox code prs` | List pull requests with triage signals |
| `ox code status` | Show code index status |
| `ox code activity` | Assemble GitHub activity clusters for the fact extractor |
| `ox code index [url]` | Index a git repository -- alias for [`ox index code`](/docs/cli/index-cmd) |

## Search code

<Terminal>
  <TerminalCommand>ox code search "authentication middleware" --limit 10</TerminalCommand>
</Terminal>

Ranks matches across commits, symbols, and diffs by relevance.

| Flag | Description |
|------|-------------|
| `--limit` | Max results to return |
| `--decisions` | Only results from this repo's decision records (ADRs/DDRs) |
| `--full-json` | Full uncompacted JSON output (~6x more context tokens) |

<Terminal>
  <TerminalComment>Search only Decision Records</TerminalComment>
  <TerminalCommand>ox code search "rate limiting" --decisions</TerminalCommand>
</Terminal>

## Planning insights

<Terminal>
  <TerminalCommand>ox code insights --days 30</TerminalCommand>
</Terminal>

Reports change hotspots, file contention, and recent activity -- the signals worth reading before planning a change.

| Flag | Description |
|------|-------------|
| `--days` | Time window in days |
| `--limit` | Max rows per section |
| `--json` | Structured JSON output for agents |

## Triage pull requests

<Terminal>
  <TerminalCommand>ox code prs --sort stalled --state open</TerminalCommand>
</Terminal>

Ranks indexed PRs by triage signal -- most-stalled open PRs first by default. Ranking is deterministic and computed from indexed GitHub data (no LLM, no external API).

| Flag | Description |
|------|-------------|
| `--sort` | Ranking: `stalled` \| `age` \| `activity` |
| `--state` | PR state: `open` \| `closed` \| `merged` \| `all` |
| `--limit` | Max number of PRs to return |
| `--pretty` | Pretty-print JSON output |

## Index status

<Terminal>
  <TerminalCommand>ox code status</TerminalCommand>
</Terminal>

Shows what CodeDB has indexed and how current it is. Add `--json` for machine-readable output.

## What's next

- [ox index](/docs/cli/index-cmd) - Build the CodeDB index that `ox code` searches
- [ox query](/docs/cli/query) - Search recorded team knowledge beyond code
- [ox decision](/docs/cli/decision) - Enrich Decision Records with team context


---

# ox config (https://sageox.ai/docs/cli/config)

# ox config

View and modify ox configuration settings. Settings can be configured at user, repo, or team level with a priority chain.

## Usage

```bash
ox config                              # Interactive TUI editor
ox config list                         # List all settings with values
ox config get <key>                    # Show setting with override chain
ox config set <key> <value>            # Set at user level
ox config set <key> <value> --repo     # Set at repo level
ox config set <key> <value> --team     # Set at team level
ox config unset <key>                  # Clear user-level override
ox config unset <key> --repo           # Clear repo-level override
```

## Interactive mode

When run in a terminal without arguments, `ox config` launches an interactive TUI for browsing and editing settings.

## Available settings

| Setting | Values | Default | Description |
|---------|--------|---------|-------------|
| `session_recording` | `disabled`, `manual`, `auto` | `manual` | When to record coding sessions |
| `github_sync` | `enabled`, `disabled` | `enabled` | Sync GitHub PRs and issues |
| `github_sync_prs` | `enabled`, `disabled` | `enabled` | Sync GitHub pull requests |
| `github_sync_issues` | `enabled`, `disabled` | `enabled` | Sync GitHub issues |
| `murmuring` | `manual`, `auto` | `auto` | AI coworker murmur publishing |
| `telemetry` | `on`, `off` | `on` | Anonymous usage telemetry |
| `tips` | `on`, `off` | `on` | Show contextual tips |
| `context_git.auto_commit` | `on`, `off` | `on` | Auto-commit context changes |
| `context_git.auto_push` | `on`, `off` | `on` | Auto-push context commits |
| `attribution.commit` | text or `""` | — | Commit attribution text |
| `attribution.pr` | text or `""` | — | PR attribution text |

## Priority chain

Settings are resolved in this order (first match wins):

1. **User** (`~/.config/sageox/config.toml`), Personal preferences
2. **Repo** (`.sageox/config.toml`), Project-specific settings
3. **Team** (Team Context config), Team-wide defaults
4. **Default**, Built-in fallback values

## Examples

### List all settings

```bash
ox config list
```

```
session_recording    manual     (user)
github_sync          enabled    (default)
murmuring            auto       (team)
telemetry            on         (default)
```

### Get a specific setting

```bash
ox config get session_recording
```

```
session_recording = manual

Override chain:
  user:    manual  ← active
  repo:    (not set)
  team:    auto
  default: manual
```

### Set at user level

```bash
ox config set telemetry off
```

### Set at repo level

```bash
ox config set session_recording auto --repo
```

This adds the setting to `.sageox/config.toml` in the current repo.

### Set at team level

```bash
ox config set murmuring auto --team
```

This updates the team context config, affecting all team members.

### Clear an override

```bash
ox config unset session_recording
ox config unset session_recording --repo
```

## Subcommands

| Command | Description |
|---------|-------------|
| `ox config list` | List all settings with current values and sources |
| `ox config get <key>` | Show a setting's value and override chain |
| `ox config set <key> <value>` | Set a configuration value |
| `ox config unset <key>` | Remove an override at a specific level |

## Flags

| Flag | Description |
|------|-------------|
| `--repo` | Apply to repo-level config (`.sageox/config.toml`) |
| `--team` | Apply to team-level config |

## Related commands

- [ox status](/docs/cli/status): View current configuration state
- [ox init](/docs/cli/init): Initialize a project with default settings


---

# ox conversation (https://sageox.ai/docs/cli/conversation)

# ox conversation

Read-only commands for browsing recorded team conversations locally: summaries, transcript slices, and distillation topics, served from the team-context checkout the daemon keeps synced. Works fully logged out, and with no subcommand behaves like `ox conversation list`.

Commands disclose progressively (`list` → `show` → `topics` → `topic` → `transcript`), and each JSON envelope names the next step in its `guidance` field while `token_estimate` reports what reading the payload costs.

Accepts three id forms anywhere an `<id>` is expected: `cnv_<uuidv7>`, `rec_<uuidv7>`, or a full `sageox://` citation URI copied from a distillation atom.

## Usage

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

## Subcommands

| Command | Description |
|---------|-------------|
| `ox conversation list` | List the active team's recorded conversations |
| `ox conversation show <id>` | Show one conversation's metadata and human summary |
| `ox conversation topics <id>` | List a conversation's distillation topics |
| `ox conversation topic <id> <tp_id>` | Show one distillation topic's atoms |
| `ox conversation transcript <id>` | Read a transcript slice by cue range or time window |

## Examples

<Terminal>
  <TerminalCommand>ox conversation list --limit 5</TerminalCommand>
</Terminal>

Browse the active team's recent conversations, newest first, with the ids, title, date, and participants needed to descend a rung.

<Terminal>
  <TerminalCommand>ox conversation show cnv_01hxyz</TerminalCommand>
</Terminal>

Read one conversation's metadata and human summary. A conversation without a summary yet reports `available=false` with a typed reason, data, not an error.

<Terminal>
  <TerminalCommand>ox conversation topics cnv_01hxyz</TerminalCommand>
</Terminal>

List the distillation topics for a conversation: one row per topic with its title, summary, atom count, and citation URIs.

<Terminal>
  <TerminalCommand>ox conversation transcript cnv_01hxyz --cues 1-100</TerminalCommand>
</Terminal>

Read a transcript slice by an inclusive 1-based cue range. Use `--from`/`--to` for a media-clock window instead, or `--full` to serve the whole transcript.

## Flags

| Flag | Description |
|------|-------------|
| `--format string` | Output format: `json` or `text` |
| `--limit int` | Cap the number of conversations returned |
| `--since string` | Only conversations recorded on or after this instant (RFC3339 or `YYYY-MM-DD`) |
| `--text` | Shorthand for `--format text` |

## What's next

- [ox query](/docs/cli/query) - Semantic search across discussions and sessions
- [Team Context](/docs/features/team-context) - The team-wide conversation store these commands read from
- [Discussions](/docs/context-capture/discussions) - How recorded human conversations are captured


---

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

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

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

<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>
  <TerminalOutput>  ▸ Load with ox coworker load &lt;name&gt;</TerminalOutput>
</Terminal>

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

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

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

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

### Optional frontmatter

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

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

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

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


---

# ox daemon (https://sageox.ai/docs/cli/daemon)

# ox daemon

Manage the background sync daemon that keeps your Ledger and Team Context automatically synchronized.

## What the daemon does

The SageOx daemon runs in the background and handles:

- **Automatic git sync** - Pushes and pulls changes to your Ledger and Team Context repos
- **Change debouncing** - Batches rapid changes to avoid excessive git operations
- **Periodic pulls** - Fetches updates from your team at regular intervals

The daemon starts automatically when you run `ox init` or `ox login`. You don't need to manage it manually unless troubleshooting.

## Usage

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

## Subcommands

| Command | Description |
|---------|-------------|
| `start` | Start the daemon |
| `stop` | Stop the daemon |
| `restart` | Restart the daemon |
| `status` | Show daemon status |
| `logs` | View daemon logs |
| `list` | List all running ox daemons |
| `kill` | Kill daemon process(es) |

## Check daemon status

<Terminal>
  <TerminalCommand>ox daemon status</TerminalCommand>
</Terminal>

<Terminal title="ox daemon status">
  <TerminalOutput>Daemon Status</TerminalOutput>
  <TerminalOutput>  PID: 12345</TerminalOutput>
  <TerminalOutput>  Running: yes</TerminalOutput>
  <TerminalOutput>  Uptime: 2h 15m</TerminalOutput>
  <TerminalOutput>  Last sync: 30s ago</TerminalOutput>
</Terminal>

### Status flags

| Flag | Description |
|------|-------------|
| `--verbose` | Show detailed status information |

## View daemon logs

<Terminal>
  <TerminalCommand>ox daemon logs</TerminalCommand>
</Terminal>

### Logs flags

| Flag | Description |
|------|-------------|
| `-n, --lines` | Number of lines to show (default: 50) |
| `-f, --follow` | Follow log output in real-time |
| `--path` | Show log file path instead of contents |
| `--all` | Show logs from all daemon instances |

Follow logs in real-time:

<Terminal>
  <TerminalCommand>ox daemon logs -f</TerminalCommand>
</Terminal>

## Start and stop

Start the daemon manually:

<Terminal>
  <TerminalCommand>ox daemon start</TerminalCommand>
</Terminal>

Run in foreground (for debugging):

<Terminal>
  <TerminalCommand>ox daemon start --foreground</TerminalCommand>
</Terminal>

Stop the daemon:

<Terminal>
  <TerminalCommand>ox daemon stop</TerminalCommand>
</Terminal>

Restart after configuration changes:

<Terminal>
  <TerminalCommand>ox daemon restart</TerminalCommand>
</Terminal>

## Managing multiple daemons

List all running ox daemons across your system:

<Terminal>
  <TerminalCommand>ox daemon list</TerminalCommand>
</Terminal>

Kill a specific daemon or all daemons:

<Terminal>
  <TerminalCommand>ox daemon kill</TerminalCommand>
  <TerminalCommand>ox daemon kill --all</TerminalCommand>
</Terminal>

## When to restart the daemon

Restart the daemon after:

- Changing SageOx configuration in `.sageox/config.toml`
- Updating the ox CLI to a new version
- Switching teams or repositories
- Resolving sync conflicts manually

## Troubleshooting

**Daemon not running** - Start it manually:

<Terminal>
  <TerminalCommand>ox daemon start</TerminalCommand>
</Terminal>

**Sync issues** - Check the logs for errors:

<Terminal>
  <TerminalCommand>ox daemon logs -n 100</TerminalCommand>
</Terminal>

**Daemon unresponsive** - Kill and restart:

<Terminal>
  <TerminalCommand>ox daemon kill && ox daemon start</TerminalCommand>
</Terminal>

**Multiple daemons running** - Clean up stale processes:

<Terminal>
  <TerminalCommand>ox daemon list</TerminalCommand>
  <TerminalCommand>ox daemon kill --all</TerminalCommand>
  <TerminalCommand>ox daemon start</TerminalCommand>
</Terminal>

## Related commands

- [ox init](/docs/cli/init) - Initialize repository (starts daemon automatically)
- [ox doctor](/docs/cli/doctor) - Diagnose configuration issues
- [ox login](/docs/cli/auth) - Authenticate with SageOx


---

# ox decision (https://sageox.ai/docs/cli/decision)

# ox decision

Work with this repo's Decision Records (DRs -- ADRs are one type). `ox decision enrich` computes deterministic team context for a DR -- related-decision candidates, corpus conventions, drift and reference checks, and ready-to-paste citations -- with zero LLM or network cost.

## Usage

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

DRs are committed markdown files (default discovery: `docs/adr`, `docs/decisions`, `adr`, `docs/architecture/decisions`; override via the committed `.sageox` config `decision.paths`). They are already full-text searchable via [`ox code search --decisions`](/docs/cli/code).

## Subcommands

| Command | Description |
|---------|-------------|
| `ox decision enrich` | Enrich a Decision Record (or DR topic) with team context (JSON by default) |

## Enrich a Decision Record

Run `enrich` before you write. `--topic` consults team context before drafting a new DR; `--file` verifies an existing DR and adds code-drift and reference checks. `ox` computes everything locally and never edits the DR -- the agent authors every word.

<Terminal>
  <TerminalComment>Consult team context before drafting a new DR</TerminalComment>
  <TerminalCommand>ox decision enrich --topic "rate limiting strategy"</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Verify an existing DR before editing it</TerminalComment>
  <TerminalCommand>ox decision enrich --file docs/adr/042-rate-limiting.md</TerminalCommand>
</Terminal>

Pipe a draft on stdin to verify it before you present it:

<Terminal>
  <TerminalCommand>cat draft-dr.md | ox decision enrich</TerminalCommand>
</Terminal>

Output is JSON by default (the agent path). Add `--text` for a human summary.

## Flags

Flags for `ox decision enrich`:

| Flag | Description |
|------|-------------|
| `--topic` | Consult mode: the DR subject, before drafting |
| `--file` | An existing DR file to enrich (adds drift + ref checks) |
| `--text` | Human summary instead of JSON |

## What's next

- [ox code](/docs/cli/code) - Full-text search DRs with `ox code search --decisions`
- [ox query](/docs/cli/query) - Search recorded team knowledge and prior Sessions
- [ox agent](/docs/cli/agent) - Prime an agent with team context before it writes


---

# ox distill (https://sageox.ai/docs/cli/distill)

# ox distill

Turn raw team activity into structured memory. `ox distill` collects observations from Discussions, coding sessions, and GitHub, then uses your AI coworker to synthesize daily, weekly, and monthly summaries stored in Team Context.

## Usage

<Terminal>
  <TerminalCommand>ox distill [flags]</TerminalCommand>
</Terminal>

Run from any initialized repository. The pipeline runs locally, using your AI coworker's CLI for LLM calls.

## What happens during distill

1. **Collects raw observations** from three sources: Discussions, coding sessions (Ledger), and GitHub activity
2. **Extracts structured facts** using your AI coworker (or direct mapping for sessions)
3. **Synthesizes summaries** at the appropriate time layer (daily, weekly, monthly)
4. **Commits results** to Team Context as Markdown files
5. **Pushes to remote** unless `--no-push` is set

Content hashing skips redundant LLM calls, so re-running is cheap.

## Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--layer` | string | all | Distill a specific layer: `daily`, `weekly`, or `monthly` |
| `--dry-run` | bool | false | Show what would be distilled without invoking the LLM |
| `--sync` | bool | false | Sync Ledger, Team Context, and code index before distilling |
| `--verbose` | bool | false | Log full prompts to stderr |
| `--model` | string | | Override the AI coworker model (e.g., `sonnet`, `opus`) |
| `--no-push` | bool | false | Skip pushing Team Context commits to remote |
| `--concurrency` | int | 1 | Max parallel LLM calls (1-8) |
| `--all` | bool | false | Process full history instead of last 7 days |

## Sources

Three extraction sources feed into the daily layer:

### Discussions

Recorded team Discussions from Team Context. The LLM extracts decisions, action items, and key observations from VTT transcripts.

Output: `memory/.discussion-facts/`

### Sessions

Coding session summaries from your Ledger. No LLM calls needed here -- structured data from `summary.json` is mapped directly into facts.

Sessions with a quality score below 0.2 are filtered out.

Output: `memory/.session-facts/{date}/`

### GitHub

PRs, issues, and commits from CodeDB. The LLM extracts what shipped, what's blocked, and review decisions.

Output: `memory/.github-facts/`

## Layers

Distillation runs in three time layers, each building on the one below it.

### Daily

Extracts facts from all three sources and synthesizes them into a daily summary.

Output: `memory/daily/YYYY-MM-DD-{uuid7}.md`

### Weekly

Synthesizes daily summaries into a weekly rollup. Runs when 7 or more days have passed since the last weekly summary.

Output: `memory/weekly/YYYY-WXX.md`

### Monthly

Synthesizes weekly summaries into a monthly overview. Runs on month change based on your team's configured timezone.

Output: `memory/monthly/YYYY-MM.md`

When you run `ox distill` without `--layer`, all applicable layers run based on timestamps in the state file.

## Environment variables

| Variable | Description |
|----------|-------------|
| `DISTILL_REPOS` | Colon-separated project roots for multi-repo distillation |
| `OX_TIMEZONE` | IANA timezone for date boundaries (also configurable via `ox config set timezone`) |

## State tracking

Distill tracks progress in `.sageox/cache/distill-state-v2.json`, which records `last_weekly` and `last_monthly` timestamps. Daily tracking uses frontmatter in the output files themselves. The default lookback window is 7 days; use `--all` for full history.

## Examples

<Terminal>
  <TerminalComment>Run a full distillation with sync</TerminalComment>
  <TerminalCommand>ox distill --sync</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Preview what would be distilled</TerminalComment>
  <TerminalCommand>ox distill --dry-run</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Distill only the weekly layer</TerminalComment>
  <TerminalCommand>ox distill --layer weekly</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Speed up extraction with parallel LLM calls</TerminalComment>
  <TerminalCommand>ox distill --concurrency 4</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Process full history across multiple repos</TerminalComment>
  <TerminalCommand>DISTILL_REPOS=~/src/api:~/src/web ox distill --all</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Distill without pushing to remote</TerminalComment>
  <TerminalCommand>ox distill --no-push</TerminalCommand>
</Terminal>

## Customization

Place guidance files in `memory/guidance/` within your Team Context repo to influence how the LLM synthesizes summaries. These files let you steer what gets emphasized, what terminology to use, and what patterns to watch for.

## Troubleshooting

**"No sources found"** -- The lookback window (7 days by default) found no new Discussions, sessions, or GitHub activity. Use `--all` to process full history, or check that your Ledger and Team Context repos are up to date with `--sync`.

**"LLM call failed"** -- Verify your AI coworker CLI is configured and authenticated. Use `--verbose` to see the full prompt sent to the model.

**Stale summaries** -- Delete `.sageox/cache/distill-state-v2.json` to reset state tracking and re-run.

**Partial failures** -- The pipeline pushes at the end even after partial failures, so completed work is preserved. Re-run to retry failed extractions.

## What's next

- [ox prime](/docs/cli/prime) -- Load Team Context into your AI coworker's session
- [ox record](/docs/cli/record) -- Capture coding sessions that feed into distillation
- [Discussions](/docs/context-capture/discussions) -- Record team conversations for extraction


---

# ox doctor (https://sageox.ai/docs/cli/doctor)

# ox doctor

Run diagnostics on your SageOx setup to identify configuration issues, verify authentication, and check repository health.

## Usage

<Terminal>
  <TerminalCommand>ox doctor [--verbose]</TerminalCommand>
</Terminal>

## What It Checks

### Authentication
- Valid session token
- Token expiration
- Correct permissions

### Repository Registration
- Repository is registered with SageOx
- Local configuration matches server
- Repository exists on platform

### Context Injection
- Context injection is configured
- CLAUDE.md and context files are set up
- Context can be retrieved from server

### Session Uploads
- Coding sessions cached locally have reached the Ledger
- Pending uploads left behind by an earlier failure are retried

This check repairs itself: when `ox doctor` finds sessions that never finished
uploading, it retries them for you rather than only reporting the backlog. If
SageOx has told you that your coding sessions stopped arriving, this is the
check that clears it.

## Output

| Symbol | Meaning |
|--------|---------|
| `[OK]` | Check passed |
| `[WARN]` | Non-critical issue |
| `[FAIL]` | Critical issue |

<Terminal title="ox doctor">
  <TerminalOutput>SageOx Doctor</TerminalOutput>
  <TerminalOutput>=============</TerminalOutput>
  <TerminalOutput> </TerminalOutput>
  <TerminalOutput>Authentication</TerminalOutput>
  <TerminalOutput>  [OK] Logged in as user@example.com</TerminalOutput>
  <TerminalOutput> </TerminalOutput>
  <TerminalOutput>Repository</TerminalOutput>
  <TerminalOutput>  [OK] Repo registered: my-project</TerminalOutput>
  <TerminalOutput> </TerminalOutput>
  <TerminalOutput>Context Injection</TerminalOutput>
  <TerminalOutput>  [OK] Context injection enabled</TerminalOutput>
  <TerminalOutput> </TerminalOutput>
  <TerminalOutput>All checks passed.</TerminalOutput>
</Terminal>

## Verbose Mode

<Terminal>
  <TerminalCommand>ox doctor --verbose</TerminalCommand>
</Terminal>

Shows config paths, API endpoints, and full server responses.

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All checks passed |
| 1 | One or more checks failed |

## Common Issues

**Not Authenticated** - Run `ox login`

**Repository Not Registered** - Run `ox init`

**Expired Token** - Run `ox login`

**Sessions Not Arriving** - Run `ox doctor --fix` in the affected repository to retry pending uploads and repair what it can. If sessions still don't arrive, share the output of `ox doctor --json` with SageOx support.

## Related Commands

- [ox login](/docs/cli/auth) - Authenticate with SageOx
- [ox init](/docs/cli/init) - Initialize repository
- [ox prime](/docs/cli/prime) - Context injection for agents


---

# ox export (https://sageox.ai/docs/cli/export)

# ox export

Show where all your SageOx data lives on disk and how to take it with you. Everything an AI coworker learns about your work is stored in ordinary git repositories you own and control: there is no proprietary format and no lock-in.

## Usage

<Terminal>
  <TerminalCommand>ox export</TerminalCommand>
</Terminal>

`ox export` prints the exact on-disk location of each repo and how to reach it:

- **Ledger**: this repo's history of work, decisions, and coding Sessions.
- **Team Context**: your team's permanent conversation store: recorded Discussions, Sessions, and shared memory.

Both are plain git repos on your machine. You can `cd` into them, run `git log`, copy them elsewhere, or push them to a remote you control.

## Examples

### Show where your data lives

<Terminal>
  <TerminalCommand>ox export</TerminalCommand>
</Terminal>

Prints the on-disk path of your Ledger and every Team Context, plus how to reach each one.

### Refresh before copying

<Terminal>
  <TerminalCommand>ox export --sync</TerminalCommand>
</Terminal>

Checks out and refreshes every Team Context and this repo's Ledger first, so a copy you make right now is complete and current.

### Machine-readable output

<Terminal>
  <TerminalCommand>ox export --json</TerminalCommand>
</Terminal>

Emits the same locations as JSON for scripting.

## Flags

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |
| `--sync` | Check out and refresh all team contexts and this repo's ledger before printing |

## What's next

- [ox sync](/docs/cli/sync) - pull the latest Ledger and Team Context updates
- [ox team](/docs/cli/team) - list the teams whose Team Context you can export
- [Team Context](/docs/features/team-context) - what lives in the team-wide store versus the per-repo Ledger


---

# ox gc (https://sageox.ai/docs/cli/gc)

# ox gc

Reclone the local repositories ox manages (your Ledger and Team Context) for the ones eligible for it, done safely. Reach for it when a managed clone needs a clean checkout.

## Usage

<Terminal>
  <TerminalCommand>ox gc</TerminalCommand>
</Terminal>

## What's next

- [ox sync](/docs/cli/sync) - Synchronize your Ledger and Team Context
- [ox doctor](/docs/cli/doctor) - Diagnose configuration and repository issues


---

# ox glance (https://sageox.ai/docs/cli/glance)

# ox glance

See what your team's AI coworkers are working on. `ox glance` shows recent AI coworker Murmurs across your team and flags potential collisions where multiple people are touching the same files. Output is JSON, designed for AI coworker consumption.

## Usage

<Terminal>
  <TerminalCommand>ox glance [flags]</TerminalCommand>
</Terminal>

With no flags, `ox glance` reports activity since your last checkpoint (or the last 4 hours).

## Examples

### Since your last checkpoint

<Terminal>
  <TerminalCommand>ox glance</TerminalCommand>
</Terminal>

Recent Murmurs and file collisions since the last checkpoint, or the last 4 hours if there isn't one.

### A fixed lookback window

<Terminal>
  <TerminalCommand>ox glance --since 3d</TerminalCommand>
</Terminal>

Activity over the last 3 days. `--since` accepts `3d`, `7d`, `24h`, `1w`, or an ISO date.

### A bounded window

<Terminal>
  <TerminalCommand>ox glance --since 7d --until 3d</TerminalCommand>
</Terminal>

Activity from 7 days ago up to 3 days ago. Pair `--since` with `--until` (both take the same formats) to inspect a fixed range, such as `--since 2026-03-18 --until 2026-03-22`.

## Flags

| Flag | Description |
|------|-------------|
| `--since` | Start of time window (`3d`, `7d`, `24h`, `1w`, ISO date) |
| `--until` | End of time window (same formats as `--since`; default: now) |

## What's next

- [ox murmur](/docs/cli/murmur) - post the Murmurs that ox glance surfaces
- [ox coworker](/docs/cli/coworker) - work with your team's AI coworkers
- [ox status](/docs/cli/status) - check this repo's sync and session state


---

# ox guide (https://sageox.ai/docs/cli/guide)

# ox guide

Render a bundled topical guide in your terminal. The guides ship inside the ox binary, so they work offline and stay in sync with the version you're running.

Run `ox guide` with no arguments to list every available topic, or pass a topic to render it.

## Usage

<Terminal>
  <TerminalCommand>ox guide [topic]</TerminalCommand>
</Terminal>

## Examples

List all topics:

<Terminal>
  <TerminalCommand>ox guide</TerminalCommand>
</Terminal>

Render a specific guide:

<Terminal>
  <TerminalCommand>ox guide team-rules</TerminalCommand>
  <TerminalCommand>ox guide getting-started</TerminalCommand>
</Terminal>

Emit plain markdown to pipe to an AI agent:

<Terminal>
  <TerminalCommand>ox guide team-rules --raw</TerminalCommand>
</Terminal>

## Flags

| Flag | Description |
|------|-------------|
| `--raw` | Output raw markdown without terminal rendering |

## What's next

- [ox agent](/docs/cli/agent) - Prime an agent with team rules and context
- [ox query](/docs/cli/query) - Search your team's discussions and sessions


---

# ox hooks (https://sageox.ai/docs/cli/hooks)

# ox hooks

Manage event hooks triggered by daemon events such as session uploads, murmurs, and sync completions. Event hooks let you run custom commands when things happen in SageOx.

## Usage

```bash
ox hooks list                    # List registered event hooks
ox hooks add <event> <command>   # Register a new event hook
ox hooks test <event>            # Fire a synthetic event to test hooks
ox hooks log                     # Show how to view hook execution logs
```

## Subcommands

### ox hooks list

List all registered event hooks.

```bash
ox hooks list
```

```
EVENT              COMMAND                           STATUS
session-upload     notify-send "Session uploaded"    enabled
murmur             ./scripts/on-murmur.sh            enabled
sync               echo "Sync complete"              enabled
```

### ox hooks add

Register a new event hook.

```bash
ox hooks add <event> <command>
```

**Events:**
- `session-upload`, Triggered when a coding session is uploaded
- `murmur`, Triggered when a murmur is received from a coworker
- `sync`, Triggered when ledger or team context sync completes

**Example:**

```bash
# Desktop notification on session upload
ox hooks add session-upload 'notify-send "Session uploaded"'

# Run a script when a murmur arrives
ox hooks add murmur './scripts/handle-murmur.sh'

# Log sync completions
ox hooks add sync 'echo "$(date): sync complete" >> ~/.sageox/sync.log'
```

### ox hooks test

Fire a synthetic event to test your hooks.

```bash
ox hooks test session-upload
ox hooks test murmur
ox hooks test sync
```

### ox hooks log

Show how to view daemon hook execution logs.

```bash
ox hooks log
```

## Git hooks

SageOx also installs git hooks for commit attribution. These are managed separately from event hooks:

| Hook | Purpose |
|------|---------|
| `prepare-commit-msg` | Adds Co-Authored-By and SageOx-Session trailers |

Git hooks are installed automatically by `ox integrate install` and `ox init`.

To check git hook status:

```bash
ox integrate list
```

## Hook execution

- Hooks run asynchronously; they don't block the daemon
- Hook output is logged to the daemon log
- Failed hooks don't affect other hooks or daemon operation
- Hooks receive event data via environment variables

## Environment variables

Hooks receive context via environment variables:

| Variable | Description |
|----------|-------------|
| `SAGEOX_EVENT` | Event type (session-upload, murmur, sync) |
| `SAGEOX_TEAM_ID` | Team ID |
| `SAGEOX_REPO_ID` | Repository ID (if applicable) |
| `SAGEOX_AGENT_ID` | Agent ID (for murmur events) |

## Related commands

- [ox integrate](/docs/cli/integrate): Install AI agent hooks
- [ox daemon](/docs/cli/daemon): Manage the background daemon


---

# ox import (https://sageox.ai/docs/cli/import)

# ox import

Import documents or video URLs into team context for onboarding and knowledge sharing. File imports are stored with LFS-backed content. URL imports submit videos for cloud processing (transcription, summarization).

## Usage

```bash
ox import <file|url> [flags]
```

## Examples

### Import a document

```bash
# Import a PDF
ox import report.pdf

# Import with pre-extracted text stored alongside the original
ox import report.pdf --text extracted.md

# Import with a specific date
ox import notes.md --date 2026-01-15

# Import to a specific team
ox import design-doc.md --team acme-design
```

### Import a video URL

```bash
# Import a Loom video
ox import https://www.loom.com/share/abc123 --title "Architecture Review"

# Import a Cap recording
ox import https://cap.link/abc123 --title "Sprint Retro"

# Import a direct video URL
ox import https://example.com/meeting.mp4 --title "Team Standup"
```

### Check import status

```bash
# List all imports
ox import --list

# Check processing status
ox import --status rec_01234567

# Watch until processing completes
ox import --status rec_01234567 --watch
```

## Flags

| Flag | Description |
|------|-------------|
| `--text <file>` | Path to pre-extracted text/markdown, stored as `extracted.md` beside the original |
| `--date <YYYY-MM-DD>` | Date for filing (default: auto-detect from metadata) |
| `--title <text>` | Display title for URL imports |
| `--team <id>` | Team ID or slug (default: auto-discovered from repo) |
| `--force` | Re-import even if content hash already exists |
| `--status <id>` | Check processing status of a URL import |
| `--watch` | Poll `--status` until processing completes or fails |
| `--list` | List imports and their processing status |

## Supported file types

| Type | Extensions |
|------|------------|
| Documents | `.pdf`, `.docx`, `.md`, `.txt`, `.html` |
| Data | `.json`, `.yaml`, `.csv` |
| Images | `.png`, `.jpg`, `.jpeg` |
| Audio | `.m4a`, `.mp3`, `.wav`, `.ogg`, `.opus`, `.flac` |
| Video | `.mp4`, `.mov`, `.mkv`, `.avi` |

## Supported video platforms

- **Loom**: `https://www.loom.com/share/...`
- **Cap**: `https://cap.link/...`
- **Direct URLs**: Any accessible `.mp4`, `.webm`, etc.

## How file imports work

1. **Upload**, Content is uploaded to LFS (Git Large File Storage)
2. **Pointer**, A small pointer file is committed to team context
3. **Metadata**: `metadata.json` tracks title, content type, date, sidecars
4. **Push**, Changes are pushed to the team context repo

Files are stored at:
```
data/docs/YYYY/MM/DD/<slug>/
├── metadata.json      # Document metadata
├── original.pdf       # LFS pointer to original
└── extracted.md       # LFS pointer to extracted text (if provided)
```

## How URL imports work

1. **Submit**, URL is sent to SageOx cloud for processing
2. **Download**, Cloud downloads the video
3. **Transcribe**, Audio is transcribed
4. **Summarize**, AI generates summary and key points
5. **Store**, Results are stored in team context

Track progress with `--status` and `--watch`.

## Deduplication

Imports are deduplicated by content hash. If you try to import a file that's already been imported, ox will skip it:

```bash
ox import report.pdf
# Already imported (id: architecture-review). Use --force to reimport.
```

Use `--force` to reimport anyway.

## Related commands

- [ox query](/docs/cli/query): Search imported documents
- [ox sync](/docs/cli/sync): Sync team context


---

# ox index (https://sageox.ai/docs/cli/index-cmd)

# ox index

Build searchable indexes from your codebase. `ox index` creates CodeDB -- a local database of commits, symbols, diffs, PRs, and issues that your AI coworker can query during sessions.

## Usage

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

Run from any initialized repository. The index lives locally on your machine.

## What gets indexed

| Source | Content | Command |
|--------|---------|---------|
| Git history | Commits, diffs, file changes | `ox index code` |
| Code symbols | Functions, types, classes | `ox index code` |
| GitHub PRs | Titles, descriptions, comments, review threads | `ox index github` |
| GitHub issues | Titles, descriptions, labels, comments | `ox index github` |

## Subcommands

### ox index code

Index git history and code symbols from your repository.

<Terminal>
  <TerminalCommand>ox index code [url] [flags]</TerminalCommand>
</Terminal>

| Flag | Description |
|------|-------------|
| `--full` | Force a complete re-index, ignoring cached state |

Without `--full`, indexing is incremental -- only new commits since the last index are processed.

<Terminal>
  <TerminalComment>Index the current repository</TerminalComment>
  <TerminalCommand>ox index code</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Index a specific repository by URL</TerminalComment>
  <TerminalCommand>ox index code git@github.com:myorg/myrepo.git</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Force a full re-index</TerminalComment>
  <TerminalCommand>ox index code --full</TerminalCommand>
</Terminal>

### ox index github

Index PRs and issues from your GitHub repository.

<Terminal>
  <TerminalCommand>ox index github [flags]</TerminalCommand>
</Terminal>

| Flag | Description |
|------|-------------|
| `--full` | Force a complete re-index |
| `--prs-only` | Index only pull requests |
| `--issues-only` | Index only issues |

<Terminal>
  <TerminalComment>Index all GitHub activity</TerminalComment>
  <TerminalCommand>ox index github</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Index only PRs</TerminalComment>
  <TerminalCommand>ox index github --prs-only</TerminalCommand>
</Terminal>

## Where the index lives

CodeDB stores indexes locally in your repository's `.sageox/codedb/` directory. The index never leaves your machine -- your AI coworker queries it locally during sessions.

```
.sageox/
└── codedb/
    ├── commits.db      # Git history and diffs
    ├── symbols.db      # Code symbols and definitions
    └── github.db       # PRs and issues
```

<Callout type="info">
CodeDB is local-only by design. Your code and git history stay on your machine. SageOx servers never see your source code.
</Callout>

## Incremental vs full re-index

By default, `ox index` runs incrementally:

- **Code**: Indexes only commits since the last run
- **GitHub**: Fetches only PRs and issues updated since the last run

Use `--full` when:

- The index seems stale or incomplete
- You've changed indexing configuration
- You want to rebuild from scratch after a major refactor

Full re-indexing takes longer but ensures the index matches your current repository state.

## Searching the index

Once indexed, use `ox code search` to query CodeDB.

<Terminal>
  <TerminalCommand>ox code search "authentication middleware" --limit 10</TerminalCommand>
</Terminal>

| Flag | Description |
|------|-------------|
| `--limit` | Maximum number of results (default: 20) |
| `--full-json` | Output full result details as JSON |

### Example searches

<Terminal>
  <TerminalComment>Find functions related to user auth</TerminalComment>
  <TerminalCommand>ox code search "user authentication"</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Search for recent changes to the API</TerminalComment>
  <TerminalCommand>ox code search "API endpoint changes"</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Get JSON output for scripting</TerminalComment>
  <TerminalCommand>ox code search "database migration" --full-json</TerminalCommand>
</Terminal>

## Related ox code commands

The `ox code` command group provides shortcuts for common indexing operations.

| Command | Equivalent | Description |
|---------|------------|-------------|
| `ox code index [url]` | `ox index code [url]` | Alias for indexing code |
| `ox code search <query>` | -- | Search the CodeDB index |
| `ox code status` | -- | Show index status and stats |

<Terminal>
  <TerminalComment>Check index status</TerminalComment>
  <TerminalCommand>ox code status</TerminalCommand>
</Terminal>

## How AI coworkers use CodeDB

When you start a coding session with `ox prime` or `ox session start`, your AI coworker gains access to CodeDB queries. This enables:

- **Semantic search** -- find code by meaning, not just text matching
- **History queries** -- "when did this behavior change?" answered from git history
- **Cross-reference navigation** -- understand how modules connect across the codebase
- **PR/issue context** -- reference decisions from code review threads

Without CodeDB, AI coworkers rely on grep and file reads. With it, they navigate your codebase with precision.

## Troubleshooting

**"Repository not initialized"** -- Run `ox init` first to connect your repository to SageOx.

**"No commits to index"** -- The repository needs at least one commit. If you're starting fresh, make an initial commit first.

**"GitHub rate limited"** -- GitHub API has rate limits. Wait and retry, or use `--prs-only` or `--issues-only` to reduce API calls.

**Stale search results** -- Run `ox index code` to pick up recent commits. Use `--full` if incremental indexing isn't catching changes.

## What's next

- [ox prime](/docs/cli/prime) -- Activate context injection for AI coworkers
- [ox distill](/docs/cli/distill) -- Process GitHub activity into Team Context
- [Claude Code integration](/docs/developers/claude-code) -- How CodeDB enhances AI coding sessions


---

# ox init (https://sageox.ai/docs/cli/init)

# ox init

Initialize a repository with SageOx, connecting it to the platform and setting up local configuration.

## Usage

<Terminal>
  <TerminalCommand>ox init [flags]</TerminalCommand>
</Terminal>

Run this command from the root of your Git repository after authenticating with `ox login`.

## What Happens During Init

When you run `ox init`, the CLI:

1. **Creates `.sageox/` directory** - Stores local configuration including `config.toml`
2. **Registers with SageOx** - Links your repository to your SageOx account
3. **Scans repository structure** - Analyzes your codebase conventions and patterns
4. **Configures defaults** - Sets up sensible defaults based on detected project type

## Flags

| Flag | Description |
|------|-------------|
| `--name` | Override the repository name |
| `--team` | Associate with a specific team |
| `-y, --yes` | Skip confirmation prompts |
| `--force` | Reinitialize even if already configured |

## The `.sageox/` Directory

```
.sageox/
├── config.toml       # Repository configuration (committed)
└── config.local.toml # Local overrides (gitignored)
```

## Prerequisites

- Git repository with at least one commit
- Authenticated with `ox login`
- Write access to the repository root

## Troubleshooting

**"Not a git repository"** - Run from within an initialized Git repository.

**"Not authenticated"** - Run `ox login` first.

**"Repository already initialized"** - Use `--force` to reinitialize.

## Related Commands

- [ox login](/docs/cli/auth) - Authenticate before initializing
- [ox doctor](/docs/cli/doctor) - Diagnose configuration issues
- [ox prime](/docs/cli/prime) - Activate context for AI agents


---

# 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


---

# ox kb (https://sageox.ai/docs/cli/kb)

# ox kb

A Knowledge Bubble is a Curator-maintained, read-only synthesis of your team's distilled conversations for one area of work (see ox ADR-028). Team Contexts and Ledgers are separate, permanent conversation stores; they are not bubbles.

Use `ox kb list` to see the bubbles you can access and `ox kb describe <slug>` for details on one.

## Usage

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

## Subcommands

| Command | Description |
|---------|-------------|
| `ox kb list` | List Knowledge Bubbles you can access |
| `ox kb describe <#slug\|kb_id>` | Describe a single Knowledge Bubble |

## Examples

<Terminal>
  <TerminalCommand>ox kb list --type=team</TerminalCommand>
</Terminal>

List the bubbles in this project's scopes, filtered to team-type bubbles. Inside an ox-initialized repo the ambient scope is the repo's team; personal-scope listing is deferred until personal-team provisioning rolls out.

<Terminal>
  <TerminalCommand>ox kb describe '#engineering'</TerminalCommand>
</Terminal>

Resolve a bubble by slug within the project's team and print its detail. The argument may be a `kb_id`, a slug, or a slug with the display `#` prefix; rename aliases are followed server-side.

<Terminal>
  <TerminalCommand>ox kb describe platform --scope team --json</TerminalCommand>
</Terminal>

Resolve `platform` in the named scope and emit scriptable JSON.

## Flags

| Flag | Description |
|------|-------------|
| `--type string` | (`ox kb list`) Filter by kb type: `personal`, `profile`, `team`, `repo`, or `custom` |
| `--scope string` | (`ox kb describe`) Scope to resolve a slug in: `team` or `personal` (personal is not yet available) |

## What's next

- [ox conversation](/docs/cli/conversation) - Browse the recorded conversations bubbles synthesize
- [ox distill](/docs/cli/distill) - The distillation that feeds a bubble's synthesis
- [Team Context](/docs/features/team-context) - The team-wide conversation store (not a bubble)


---

# ox murmur (https://sageox.ai/docs/cli/murmur)

# ox murmur

Publish short-lived coordination signals that other AI coworkers on the same repo or team hear as whispers. Murmurs enable real-time awareness between AI coworkers working in parallel.

## Usage

```bash
ox murmur [content] [flags]
```

## What are murmurs?

Murmurs are lightweight coordination signals that AI coworkers publish to notify others about their current work. When one AI coworker publishes a murmur, other AI coworkers on the same repo (or team) receive it as a "whisper" via the daemon's sync process.

Use cases:
- **Conflict prevention**: "Modifying shared auth middleware"
- **Work-in-progress updates**: "Refactoring user service, touching API types"
- **Architecture signals**: "API contract v3 rolling out"
- **Lint/build status**: "ESLint rule failing in src/auth/"

## Examples

<Terminal>
  <TerminalComment>Basic murmur with topic</TerminalComment>
  <TerminalCommand>ox murmur --topic=wip "Refactoring auth module"</TerminalCommand>
  <TerminalOutput>Murmur published: 01904e3a-...</TerminalOutput>
</Terminal>

<Terminal>
  <TerminalComment>Critical conflict warning</TerminalComment>
  <TerminalCommand>ox murmur --importance=critical --topic=conflict "Modifying shared API types"</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Team-wide announcement</TerminalComment>
  <TerminalCommand>ox murmur --scope=team --topic=architecture "Deploying schema migration"</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Include affected files</TerminalComment>
  <TerminalCommand>ox murmur --topic=wip --files=src/auth/login.ts,src/auth/types.ts "Updating login flow"</TerminalCommand>
</Terminal>

## Flags

| Flag | Description | Default |
|------|-------------|---------|
| `--topic` | Topic slug for filtering (e.g., wip, lint, conflict) | `general` |
| `--importance` | Importance level: `critical`, `normal`, `ambient` | `normal` |
| `--scope` | Scope: `ledger` (this repo), or `team` (all repos) | `ledger` |
| `--files` | Comma-separated file paths being modified | — |
| `--agent-id` | Agent ID (falls back to SAGEOX_AGENT_ID) | — |

## Subcommands

### ox murmur list

List recent murmurs from coworkers.

<Terminal>
  <TerminalCommand>ox murmur list</TerminalCommand>
  <TerminalOutput>TIME           USER         COWORKER   TOPIC              CONTENT</TerminalOutput>
  <TerminalOutput>5m ago         ryan         Oxa7b3     wip                Refactoring auth module</TerminalOutput>
  <TerminalOutput>12m ago        ajit         Oxf2c1     conflict           Modifying shared types</TerminalOutput>
</Terminal>

| Flag | Description | Default |
|------|-------------|---------|
| `--last` | Number of murmurs to show (0 for no limit) | 10 |
| `--since` | Time window: 30m, 2h, 1d | 12h |
| `--topic` | Filter by topic slug | — |
| `--scope` | Filter by scope: ledger or team | — |
| `--agent-id` | Filter by coworker ID | — |

### ox murmur status

Show murmur delivery status and rate limit state per coworker.

<Terminal>
  <TerminalCommand>ox murmur status</TerminalCommand>
  <TerminalOutput>COWORKER     USER         LAST MURMUR    STATUS           LAST TOPIC</TerminalOutput>
  <TerminalOutput>Oxa7b3 ★     ryan         5m ago         ready            wip</TerminalOutput>
  <TerminalOutput>Oxf2c1       ajit         2s ago         ready in 3s      conflict</TerminalOutput>
</Terminal>

Shows which coworkers are ready to publish and which are rate-limited.

### ox murmur pause

Pause automatic murmur nudging for this session. Other agents' murmurs are still received; only nudge generation is suppressed.

<Terminal>
  <TerminalCommand>ox murmur pause</TerminalCommand>
  <TerminalOutput>Murmuring paused for this session (Oxa7b3). Run 'ox murmur resume' to re-enable.</TerminalOutput>
</Terminal>

### ox murmur resume

Resume murmur nudging after a pause.

<Terminal>
  <TerminalCommand>ox murmur resume</TerminalCommand>
  <TerminalOutput>Murmuring resumed for this session (Oxa7b3).</TerminalOutput>
</Terminal>

## Rate limiting

Murmurs are rate-limited to prevent spam:

- **Max 1 murmur per 5 seconds** per agent
- **Max 500 bytes** of content per murmur
- Murmurs older than 24 hours are automatically filtered out

If you hit the rate limit:

<Terminal>
  <TerminalCommand>ox murmur --topic=wip "Another update"</TerminalCommand>
  <TerminalOutput>rate limited: max 1 murmur per 5s per agent (last: 2s ago)</TerminalOutput>
</Terminal>

## How murmurs flow

```
Agent A publishes murmur
        │
        ▼
    Daemon writes to ledger/team context
        │
        ▼
    Git commit + push
        │
        ▼
Agent B's daemon syncs
        │
        ▼
    Receives murmur as whisper
```

Murmurs are delivered via the daemon's sync process. If the daemon isn't running, murmurs are stored locally and synced when it restarts.

## Scopes

| Scope | Where stored | Who sees it |
|-------|--------------|-------------|
| `ledger` | This repo's Ledger | AI coworkers on this repo |
| `team` | Team Context | AI coworkers on any repo in the team |

Use `ledger` scope (default) for repo-specific coordination. Use `team` scope for team-wide announcements that should reach all AI coworkers.

## JSON input

For programmatic use, pass JSON directly:

```bash
ox murmur '{"content": "Fixing lint rule X", "topic": "lint", "importance": "normal"}'
```

## Related commands

- [ox daemon](/docs/cli/daemon): Background sync that delivers murmurs
- [ox sync](/docs/cli/sync): Manual sync if daemon is unavailable


---

# ox plan (https://sageox.ai/docs/cli/plan)

# ox plan

Work with SageOx-enriched plans: design, GTM, rollout, engineering, any plan your team executes against. Enrich, render, and review. ox computes team-context signals (collision, prior-art, expert-routing) locally, with no LLM or network call.

Lifecycle verbs (`approve`, `work`, `realize`, `abandon`, `supersede`) are thin sugar over one event-log engine. Each accepts `--json` and is idempotent: re-running an already-applied verb is a safe no-op.

## Usage

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

## Subcommands

| Command | Description |
|---------|-------------|
| `ox plan enrich` | Enrich a plan with SageOx team context (JSON by default) |
| `ox plan render` | Render a plan to a self-contained HTML page |
| `ox plan review` | Open a live review loop for a saved plan (serve, collect, auto-reload, approve) |
| `ox plan list` | Browse saved Ledger plans |
| `ox plan view` | Read a saved plan in the terminal |
| `ox plan status` | Show a saved plan's lifecycle timeline and current status |
| `ox plan approve` | Mark a saved plan approved |
| `ox plan work` | Record that a coding session worked on a saved plan |
| `ox plan realize` | Mark a saved plan realized (its intent was carried out) |
| `ox plan abandon` | Mark a saved plan abandoned |
| `ox plan supersede` | Mark a saved plan superseded by a successor plan |

## Examples

<Terminal>
  <TerminalCommand>ox plan enrich --topic "add per-team rate limits" --files api/limits.go,api/router.go</TerminalCommand>
</Terminal>

Consult team context **before** drafting a plan. Returns JSON badges (collision, prior-art, expert-routing) at zero LLM and network cost. Add `--text` for a human-readable summary.

<Terminal>
  <TerminalCommand>ox plan enrich --file plan.md</TerminalCommand>
</Terminal>

Enrich an existing plan document (or pipe one on stdin). With no input, ox auto-discovers the newest `~/.claude/plans/*.md`.

<Terminal>
  <TerminalCommand>ox plan render --open</TerminalCommand>
</Terminal>

Render a plan to a self-contained HTML page and open it in your browser. On a saved plan, `--open` launches the live review loop, pass `--static` for a read-only page instead.

<Terminal>
  <TerminalCommand>ox plan review my-plan-slug</TerminalCommand>
</Terminal>

Serve a saved plan on a short-lived localhost server and stay up across review rounds. Reviewers mark up sections, risks, and decisions; each round writes to the Ledger and prints a digest for the agent.

## What's next

- [ox pr](/docs/cli/pr) - Emit a PR header that links the plans a change produced
- [ox viz](/docs/cli/viz) - Author the visualizations a rendered plan can embed
- [ox session](/docs/cli/session) - Sessions record which plan they worked on


---

# ox pr (https://sageox.ai/docs/cli/pr)

# ox pr

Author SageOx content that goes into a pull request. Distinct from `ox code prs`, which lists indexed PRs for triage.

## Usage

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

## Subcommands

| Command | Description |
|---------|-------------|
| `ox pr header` | Emit the SageOx credit line for the top of a PR description |

## Examples

<Terminal>
  <TerminalCommand>ox pr header</TerminalCommand>
</Terminal>

Emit a thin, on-brand credit line to paste at the very top of a PR description. It auto-links the current session, names the team, and whispers a subtle enrichment stat. Keep the `SageOx-Session:` trailer at the bottom of the body.

<Terminal>
  <TerminalCommand>ox pr header --plan pln_4d8e2f --plan pln_1a6b9c --prior-art 2 --collisions 1</TerminalCommand>
</Terminal>

Link the plans a session produced and surface enrichment counts in the whisper.

<Terminal>
  <TerminalCommand>ox pr header > body.md && cat description.md >> body.md</TerminalCommand>
</Terminal>

Write the header straight into a PR body file, then append your description. Use a file, never a heredoc; a heredoc mangles the markup. Feed the result to `gh pr create --body-file body.md`.

## Flags

`ox pr header` accepts these flags:

| Flag | Description |
|------|-------------|
| `--session` | Session URL or `ses_` id to link (repeatable; defaults to the current session) |
| `--plan` | Plan URL or `pln_` id to link (repeatable) |
| `--prior-art` | Enrichment: related sessions surfaced |
| `--collisions` | Enrichment: concurrent edits flagged |
| `--style` | Whisper render: `text`, `image`, or `auto` |
| `--no-stat` | Suppress the enrichment whisper |
| `--allow-unconfirmed` | Accept links that may not be server-visible yet, without a warning (may 404) |

## What's next

- [ox plan](/docs/cli/plan) - Get the `pln_` ids to pass to `--plan`
- [ox session](/docs/cli/session) - The sessions a PR header links back to
- [ox viz](/docs/cli/viz) - Prepare a review visualization for the PR body


---

# ox agent prime (https://sageox.ai/docs/cli/prime)

# ox agent prime

`ox agent prime` injects Team Context into AI coding agents, providing them with domain-specific guidance, architectural decisions, and coding conventions.

## How It Works

When an agent runs `ox agent prime`:

1. **Fetches Team Context** - Retrieves your team's shared knowledge base from SageOx
2. **Injects Context** - Provides it to the agent in a format it can use
3. **Confirms with Agent ID** - Returns a unique identifier confirming context is active

The agent then has access to:
- Team norms and conventions
- Architectural decisions
- Distilled learnings from past work
- Domain-specific guidance

## Setup

Context injection is automatically configured when you run `ox init` in a repository. The agent needs:

1. Repository initialized with SageOx (`ox init`)
2. Valid authentication (`ox login`)
3. Shell access to run the command

Agents like Claude Code can be configured to run `ox agent prime` automatically via CLAUDE.md instructions.

## Supported agents

| Agent | Status | How it receives SageOx context |
|-------|--------|-------------------------------|
| **Claude Code** | Supported | `ox agent prime` via CLAUDE.md hook |
| **Conductor** | Supported | `ox agent prime` via orchestrated session |
| **Codex** | Supported | `ox agent prime` via AGENTS.md / setup hook |
| **Gemini CLI** | Planned | `ox agent prime` via AGENTS.md / setup hook |
| **Amp** | Planned | `ox agent prime` via AGENTS.md / setup hook |
| **Pi** | Planned | `ox agent prime` via workspace init |
| **OpenCode** | Planned | `ox agent prime` via AGENTS.md / setup hook |

Because SageOx injects context through the repo itself (not through a vendor-specific API), a discovery made by a Claude Code session is available to a Codex agent in the next session. No vendor lock-in on your team's accumulated knowledge.

## Checking if it's working

### Agent Has Context

Ask the agent: "Are you using SageOx?"

A primed agent responds with its `agent_id`:

<Terminal title="agent response">
  <TerminalOutput>Yes, I'm using SageOx. My agent ID is: agt_01JQ2X3Y4Z5ABC123DEF456</TerminalOutput>
</Terminal>

### Command Output

Successful prime returns:

<Terminal title="ox agent prime">
  <TerminalOutput>agent_id: agt_01JQ2X3Y4Z5ABC123DEF456</TerminalOutput>
  <TerminalOutput>context_version: 2024-01-15T10:30:00Z</TerminalOutput>
  <TerminalOutput>team: acme-engineering</TerminalOutput>
  <TerminalOutput>injected: true</TerminalOutput>
</Terminal>

### Doctor Check

Run `ox doctor` to verify context injection is configured:

<Terminal title="ox doctor">
  <TerminalOutput>Context Injection</TerminalOutput>
  <TerminalOutput>  [OK] Context injection enabled</TerminalOutput>
  <TerminalOutput>  [OK] CLAUDE.md configured</TerminalOutput>
</Terminal>

## When Context Is Lost

Agents lose injected context when:

| Event | Context Status |
|-------|---------------|
| Session start | Not loaded yet |
| `/clear` command | Cleared |
| `/compact` command | May be lost |
| Context overflow | Truncated |

The agent should re-run `ox agent prime` after these events.

## Troubleshooting

**No agent_id returned** - Check `ox doctor` for configuration issues

**Context not reflected in responses** - Verify the agent actually ran the command (check for agent_id)

**Stale context** - Context version shows when it was last updated; re-prime to get latest

## Related Commands

- [ox init](/docs/cli/init) - Initialize repository (required first)
- [ox doctor](/docs/cli/doctor) - Diagnose configuration issues
- [ox login](/docs/cli/auth) - Authentication


---

# ox query (https://sageox.ai/docs/cli/query)

# ox query

Search across your team's accumulated knowledge: discussions, docs, session history, and optionally local code.

## Usage

<Terminal>
  <TerminalCommand>ox query "how do we handle authentication?"</TerminalCommand>
</Terminal>

Returns the most relevant chunks from your team's indexed content, ranked by relevance.

## What gets searched

| Source | What it includes | Controlled by |
|--------|-----------------|---------------|
| **Team Context** | Discussions, team docs, distilled memory, AGENTS.md | `--source team` (default) |
| **Ledger** | Session history, commit summaries, code decisions | `--repo` flag |
| **Code** | Local repository files | `--source code` or `--source all` |

By default, `ox query` searches Team Context only. Add `--source all` to include local code in the search.

## Flags

| Flag | Description | Default |
|------|-------------|---------|
| `-k, --limit` | Max results to return | 5 |
| `--team` | Team ID to search | Current team |
| `--repo` | Repo ID to search (searches Ledger) | — |
| `--mode` | Search mode: `hybrid`, `knn`, or `bm25` | `hybrid` |
| `--source` | Search source: `team`, `code`, or `all` | `team` |

## Example output

<Terminal title="ox query">
  <TerminalCommand>ox query "error handling conventions"</TerminalCommand>
  <TerminalOutput> </TerminalOutput>
  <TerminalOutput>[1] score: 0.92  type: doc</TerminalOutput>
  <TerminalOutput>    Error Handling Guide</TerminalOutput>
  <TerminalOutput>    All API errors return a JSON body with code and message fields...</TerminalOutput>
  <TerminalOutput> </TerminalOutput>
  <TerminalOutput>[2] score: 0.87  type: discussion</TerminalOutput>
  <TerminalOutput>    Discussion: API Review (2024-01-15)</TerminalOutput>
  <TerminalOutput>    We decided to use structured error codes instead of HTTP status...</TerminalOutput>
  <TerminalOutput> </TerminalOutput>
  <TerminalOutput>[3] score: 0.81  type: memory</TerminalOutput>
  <TerminalOutput>    Weekly Summary (2024-01-12)</TerminalOutput>
  <TerminalOutput>    Team standardized on returning 4xx for client errors with...</TerminalOutput>
</Terminal>

## Search modes

| Mode | How it works | Best for |
|------|--------------|----------|
| `hybrid` | Combines semantic similarity (knn) with keyword matching (bm25) | Most queries, balances meaning and exact terms |
| `knn` | Pure vector similarity search | Conceptual questions ("how do we approach X?") |
| `bm25` | Pure keyword matching | Exact term lookup ("what is PARCEL_ID?") |

Hybrid mode is the default and works well for most queries. Use `--mode knn` when searching for concepts without specific terminology, and `--mode bm25` when you know the exact terms you're looking for.

<Terminal>
  <TerminalComment>Semantic search for concepts</TerminalComment>
  <TerminalCommand>ox query "our approach to caching" --mode knn</TerminalCommand>
  <TerminalOutput> </TerminalOutput>
  <TerminalComment>Keyword search for specific terms</TerminalComment>
  <TerminalCommand>ox query "PARCEL_BOUNDARY" --mode bm25</TerminalCommand>
</Terminal>

## Searching across teams and repos

Search a specific team's context:

<Terminal>
  <TerminalCommand>ox query "deployment process" --team team_abc123</TerminalCommand>
</Terminal>

Search a repo's Ledger (session history and code decisions):

<Terminal>
  <TerminalCommand>ox query "why did we refactor the auth module" --repo repo_xyz789</TerminalCommand>
</Terminal>

## Agent version

AI coworkers use `ox agent query` instead of `ox query`. The behavior is identical, but `ox agent query` includes agent telemetry (agent ID, agent type) for observability.

<Terminal>
  <TerminalComment>Human usage</TerminalComment>
  <TerminalCommand>ox query "error handling"</TerminalCommand>
  <TerminalOutput> </TerminalOutput>
  <TerminalComment>AI coworker usage (includes telemetry)</TerminalComment>
  <TerminalCommand>ox agent query "error handling"</TerminalCommand>
</Terminal>

When building prompts or CLAUDE.md instructions for AI coworkers, use `ox agent query` so that queries are attributed to the agent session.

## When to use query vs. prime

| Scenario | Use |
|----------|-----|
| Start of session, load team norms | `ox agent prime` |
| Mid-session, find specific knowledge | `ox agent query` |
| Human exploring team knowledge | `ox query` |

`ox prime` loads the core context files (AGENTS.md, SOUL.md, etc.) at session start. `ox query` searches the full corpus (discussions, docs, memory) for specific information during a task.

## Related commands

- [ox prime](/docs/cli/prime): Load team context at session start
- [ox doctor](/docs/cli/doctor): Diagnose configuration issues
- [ox init](/docs/cli/init): Initialize a repository (needed to search local code: `--source code` or `--source all`)


---

# ox recap (https://sageox.ai/docs/cli/recap)

# ox recap

Answer "What value am I getting from SageOx?" with receipts, not vibes. `recap` mines your Ledger for the specific Team Context knowledge that reached your coding sessions (the decisions, conventions, and prior work SageOx put in front of you so you didn't re-derive them), and points at each by name.

Called by an AI coworker, it emits a JSON evidence bundle plus guidance to narrate a personalized answer; in a bare terminal it prints an honest summary, and prescribes the next steps when value is still ramping. Scoped to the current project's Ledger, personal by default.

## Usage

<Terminal>
  <TerminalCommand>ox recap [flags]</TerminalCommand>
</Terminal>

## Examples

<Terminal>
  <TerminalCommand>ox recap --since 30d</TerminalCommand>
</Terminal>

Report on a reporting window: a duration like `7d`, `30d`, or `24h`, or an ISO date.

<Terminal>
  <TerminalCommand>ox recap --user alex</TerminalCommand>
</Terminal>

Report for a specific coworker by display name or slug, instead of yourself.

<Terminal>
  <TerminalCommand>ox recap --json</TerminalCommand>
</Terminal>

Emit the structured JSON evidence bundle for an AI coworker to narrate.

## Flags

| Flag | Description |
|------|-------------|
| `--json` | Structured JSON evidence bundle for AI coworkers |
| `--since string` | Reporting window (e.g. `7d`, `30d`, `24h`, or an ISO date) |
| `--user string` | Report for a specific coworker (display name or slug); default is you |

## What's next

- [ox session](/docs/cli/session) - The coding sessions recap mines for delivered value
- [ox query](/docs/cli/query) - Search the knowledge recap credits by name
- [Team Context](/docs/features/team-context) - The team-wide knowledge that reaches your sessions


---

# ox release-notes (https://sageox.ai/docs/cli/release-notes)

# ox release-notes

Read formatted release notes showing what's new, changed, and fixed in the version of ox you're running.

## Usage

<Terminal>
  <TerminalCommand>ox release-notes</TerminalCommand>
</Terminal>

## Examples

Show only the latest version's notes:

<Terminal>
  <TerminalCommand>ox release-notes --latest</TerminalCommand>
</Terminal>

Output raw markdown to pipe elsewhere:

<Terminal>
  <TerminalCommand>ox release-notes --raw</TerminalCommand>
</Terminal>

## Flags

| Flag | Description |
|------|-------------|
| `--latest` | Show only the latest version |
| `--raw` | Output raw markdown without formatting |

## What's next

- [ox version](/docs/cli/version) - Check which version you're running
- [ox upgrade](/docs/cli/upgrade) - Get the newest release


---

# ox session (https://sageox.ai/docs/cli/session)

# ox session

Manage AI coworker sessions: view, commit, and upload conversations between humans and AI coworkers to the Ledger.

## What are sessions?

Sessions are conversations between a human and an AI coworker in a specific repository. They capture:

- The code changes made during the session
- Decisions and rationale
- Prompts and responses
- Files touched and commits created

Sessions are stored in the **Ledger** (the per-repo work history). They are NOT audio recordings, those are [Discussions](/docs/context-capture/discussions), which go to Team Context.

## Session lifecycle

```
ox agent session start  →  work with AI coworker  →  ox agent session stop
                                                            │
                                                            ▼
                                                     (auto-commits,
                                                      uploads to Ledger)
```

Most session management is automatic. The `ox session` subcommands exist for manual recovery and advanced workflows.

## Usage

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

## Subcommands

| Command | Description |
|---------|-------------|
| `ox session list` | List sessions in the Ledger |
| `ox session view <name>` | View a session's content |
| `ox session commit` | Commit session to Ledger |
| `ox session hydrate` | Hydrate session with metadata |
| `ox session upload` | Upload session to cloud |
| `ox session push-summary` | Push session summary |
| `ox session regenerate` | Regenerate session summary |
| `ox session score` | Report SageOx contribution score |

## List sessions

<Terminal>
  <TerminalCommand>ox session list --limit 5</TerminalCommand>
</Terminal>

Shows recent sessions from the Ledger with their status, timestamps, and summaries.

## View a session

<Terminal>
  <TerminalCommand>ox session view 2026-04-13-auth-refactor</TerminalCommand>
</Terminal>

Opens the session in your configured viewer format (HTML, text, or JSON). Set the format with:

<Terminal>
  <TerminalCommand>ox config set view_format html</TerminalCommand>
</Terminal>

If the session shows status "stub", the full content hasn't been synced yet. Run `ox sync` to fetch the complete session data.

## Manual session commands

These commands handle steps that normally happen automatically during `ox agent session stop`.

### Commit

Commit a session to the local Ledger. Use when the auto-commit failed or you need to commit manually.

<Terminal>
  <TerminalCommand>ox session commit</TerminalCommand>
</Terminal>

### Upload

Upload a committed session to the cloud Ledger. Use when the upload was interrupted.

<Terminal>
  <TerminalCommand>ox session upload</TerminalCommand>
</Terminal>

### Hydrate

Add metadata (model info, timestamps, summaries) to a session. Use when metadata generation was skipped.

<Terminal>
  <TerminalCommand>ox session hydrate</TerminalCommand>
</Terminal>

### Regenerate summary

Re-run summary generation for a session. Useful when the initial summary was poor or truncated.

<Terminal>
  <TerminalCommand>ox session regenerate</TerminalCommand>
</Terminal>

### Push summary

Push a regenerated summary to the cloud. Separate from upload because summaries can be updated after the session is uploaded.

<Terminal>
  <TerminalCommand>ox session push-summary</TerminalCommand>
</Terminal>

### Contribution score

Report the SageOx contribution score for the current or specified session. Shows how much the AI coworker contributed.

<Terminal>
  <TerminalCommand>ox session score</TerminalCommand>
</Terminal>

## Relationship to agent commands

The `ox agent session` commands handle the active session lifecycle:

| Command | Purpose |
|---------|---------|
| `ox agent session start` | Begin recording a new session |
| `ox agent session stop` | End recording and auto-commit/upload |

The `ox session` commands (without `agent`) manage already-recorded sessions in the Ledger.

## Where sessions are stored

Sessions live in the Ledger at `sessions/<session-name>/`:

```
sessions/
└── 2026-04-13-auth-refactor/
    ├── meta.json        # Session metadata
    ├── session.html     # HTML viewer (LFS)
    ├── transcript.md    # Full transcript (LFS)
    └── plan.md          # Session plan (LFS)
```

Large files (transcript, HTML viewer) are stored in Git LFS to keep the Ledger lightweight.

## Troubleshooting

**Session stuck in "uploading"** - Run `ox session upload` to retry the upload.

**Missing summary** - Run `ox session regenerate` then `ox session push-summary`.

**Can't view session** - If status shows "stub", run `ox sync` to fetch the full session data.

**Session not appearing** - Check `ox session list` to verify it was committed. If not, run `ox session commit`.

## What's next

- [ox prime](/docs/cli/prime) - Context injection for agents
- [ox init](/docs/cli/init) - Initialize repository
- [Team Context](/docs/features/team-context) - Team-wide knowledge (vs per-repo Ledger)


---

# ox status (https://sageox.ai/docs/cli/status)

# ox status

Display current authentication status, project initialization, ledger and team context sync status, daemon health, and AI coworker activity.

## Usage

```bash
ox status [flags]
```

## What status shows

Status provides a comprehensive view of your SageOx setup:

- **Authentication**: Login state, user identity, token expiration, git PAT validity
- **Configuration**: User config directory location
- **Project**: Whether the current repo is initialized, code index status
- **Ledger**: Sync status, visibility, access level
- **Team Context**: Connected teams, sync state, staleness warnings
- **Daemon**: Running state, uptime, sync statistics, summarizer agent
- **AI Coworkers**: Active coworker count and status

## Example output

```
Authentication Status
─────────────────────
Endpoint            sageox.ai (✓ logged in)
User                Ryan Chen <ryan@acme.com>
Token expires       2026-04-20 10:30:00 PST
Git PAT             ✓ valid

Configuration
─────────────
User config dir     ✓ ~/.config/sageox

Project Status
──────────────
Repo directory      /Users/ryan/src/acme-app
  SageOx state      ├── .sageox/ dir ✓
  Code indexed      └── 2m ago  (git history, symbols)

Ledger              repo_abc123
  Visibility        private (✓ member)
  Path              .sageox/ledger
  Status            ✓ synced (2m ago)

Team                acme-eng
  Visibility        private (✓ member)
  Path              .sageox/teams/primary
  Status            ✓ synced (5m ago)

Daemon Sync
───────────
Status              ✓ running 2h (pid 12345)
Summarizer          claude (auto)
Total syncs         142 (12 last hour)
Activity (4h)       ▁▂▃▅▇▅▃▂▁▁▂▃▄▅▆▇▅▃▂
                    -4h        -2h        now

AI Coworkers        2 active  (ox agent list)
```

## Flags

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON for scripting |

## JSON output

```bash
ox status --json
```

Returns structured data including:

```json
{
  "auth": {
    "authenticated": true,
    "endpoint": "sageox.ai",
    "user": "Ryan Chen",
    "email": "ryan@acme.com"
  },
  "project": {
    "initialized": true,
    "directory": "/Users/ryan/src/acme-app",
    "code_index": {
      "indexed": true,
      "commits": 1234,
      "symbols": 5678
    }
  },
  "ledger": {
    "configured": true,
    "status": "synced",
    "visibility": "private"
  },
  "daemon": {
    "running": true,
    "pid": 12345,
    "total_syncs": 142
  },
  "version": {
    "current": "0.1.42",
    "update_available": false
  }
}
```

## Common status indicators

| Indicator | Meaning |
|-----------|---------|
| `✓ synced` | Up to date with remote |
| `⚠ stale` | Last sync was too long ago |
| `✗ not cloned` | Repo exists remotely but not locally |
| `⟳ setting up...` | Initial clone in progress |
| `not accessible` | Logged in but no access to this resource |

## Troubleshooting with status

**Not logged in?**
```bash
ox login
```

**Project not initialized?**
```bash
ox init
```

**Ledger not cloned?**
```bash
ox doctor --fix
```

**Daemon not running?**
```bash
ox daemon start
```

## Related commands

- [ox doctor](/docs/cli/doctor): Diagnose and fix common issues
- [ox daemon](/docs/cli/daemon): Manage the background sync daemon
- [ox agent list](/docs/cli/agent): List active AI coworkers


---

# ox sync (https://sageox.ai/docs/cli/sync)

# ox sync

Manually synchronize your Ledger and Team Context repositories with the server. The ox daemon handles this automatically in most cases, you rarely need this command.

## Usage

<Terminal>
  <TerminalCommand>ox sync [flags]</TerminalCommand>
</Terminal>

## Flags

| Flag | Description |
|------|-------------|
| `--team <id>` | Sync a specific Team Context by ID |
| `--all-teams` | Sync all configured Team Contexts |
| `--remove-team <id>` | Remove a Team Context from local sync |

## What gets synced

The sync command pulls the latest changes from two git repositories:

| Repository | Contains | Location |
|------------|----------|----------|
| **Ledger** | Commit history, code observations, project decisions | `.sageox/ledger/` |
| **Team Context** | Conventions, distilled discussions, team knowledge | `.sageox/teams/<team>/` |

Both repositories use `git pull --rebase` to incorporate server changes while preserving any local commits (like uncommitted observations).

## When you need manual sync

The daemon syncs automatically every 5 minutes. Manual sync is useful when:

- **Network was down**: Force a sync after reconnecting
- **Need latest context immediately**: Before starting a session that needs recent team decisions
- **Debugging sync issues**: Verify that sync works before running `ox doctor`
- **After changing team membership**: Pull new Team Context access

## Examples

<Terminal>
  <TerminalComment>Sync everything (Ledger + all Team Contexts)</TerminalComment>
  <TerminalCommand>ox sync</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Sync only a specific team</TerminalComment>
  <TerminalCommand>ox sync --team team_01JQ2X3Y4Z</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Sync all Team Contexts (but not Ledger)</TerminalComment>
  <TerminalCommand>ox sync --all-teams</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Remove a team you no longer need locally</TerminalComment>
  <TerminalCommand>ox sync --remove-team team_01JQ2X3Y4Z</TerminalCommand>
</Terminal>

## Automatic sync (daemon)

The ox daemon (`oxd`) runs in the background and syncs automatically. The sync interval is controlled by your team's manifest (default: 5 minutes).

Check daemon status:

<Terminal>
  <TerminalCommand>ox daemon status</TerminalCommand>
</Terminal>

If the daemon isn't running, start it:

<Terminal>
  <TerminalCommand>ox daemon start</TerminalCommand>
</Terminal>

<Callout type="info">
Most users never need `ox sync`, the daemon handles everything. If you find yourself running it often, check that your daemon is running with `ox daemon status`.
</Callout>

## Troubleshooting

**"Not authenticated"**: Run `ox login` first.

**"Repository not initialized"**: Run `ox init` in your project directory.

**"Sync failed: network error"**: Check your internet connection and try again.

**"Merge conflict"**: This shouldn't happen (files use UUIDv7 names to avoid conflicts). If it does, the command will log an error and flag it for manual resolution.

## What's next

- [Team Context](/docs/features/team-context): Understand what's in your Team Context
- [ox doctor](/docs/cli/doctor): Diagnose sync and configuration issues
- [ox init](/docs/cli/init): Initialize a repository with SageOx


---

# ox team (https://sageox.ai/docs/cli/team)

# ox team

Work with your teams and coworkers. A bare `ox team` lists the teams you belong to (the same as `ox team list`), and each team owns a Team Context: its permanent conversation store of recordings, Discussions, Sessions, and shared memory (distinct from a Knowledge Bubble, those are listed by `ox kb list`).

## Usage

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

Most subcommands act on the team associated with the current repository (set during `ox init` and resolved from `.sageox/config.yaml`). Pass `--team <id-or-slug>` to target a different team.

## Subcommands

| Command | Description |
|---------|-------------|
| `ox team list` | List the teams you belong to |
| `ox team members` | List a team's coworkers (humans and AI coworkers) |
| `ox team show` | Show one team's details |
| `ox team open` | Open a team's dashboard in the browser |
| `ox team invite` | Invite people to a team by email |

## Examples

### List your teams

<Terminal>
  <TerminalCommand>ox team</TerminalCommand>
</Terminal>

Lists every team you belong to and its Team Context. Equivalent to `ox team list`.

### List a team's coworkers

<Terminal>
  <TerminalCommand>ox team members</TerminalCommand>
</Terminal>

Shows each coworker on the team (human and AI) with their display name, type, role, and known handles (such as a GitHub login). Add `--team <id-or-slug>` to inspect a team other than this repo's. This roster is gated by a server-side flag; when the flag is off or the server is older, the command reports the capability as unavailable rather than failing.

### Show one team's details

<Terminal>
  <TerminalCommand>ox team show acme</TerminalCommand>
</Terminal>

Prints a team's identity, where its Team Context lives on disk, how recently it synced, and its coworker count. With no argument, shows this repo's team.

### Invite people by email

<Terminal>
  <TerminalCommand>ox team invite alex@test.sageox.ai,sam@test.sageox.ai --role member</TerminalCommand>
</Terminal>

Invites one or more people (comma-, semicolon-, or space-separated), and emails each a join link. Use `--role member|admin|owner` to set the grant, `--list` to see outstanding invitations, and `--cancel <id>` to revoke one. Invitations expire after 7 days, and delivery is best-effort, a reported invitation is not proof the email arrived.

### Open a team's dashboard

<Terminal>
  <TerminalCommand>ox team open</TerminalCommand>
</Terminal>

Opens the SageOx web dashboard for this repo's team in your browser.

## Flags

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |

## What's next

- [ox init](/docs/cli/init) - initialize a repo and associate it with a team
- [ox export](/docs/cli/export) - find where your Team Context lives on disk
- [Team Context](/docs/features/team-context) - team-wide shared knowledge, versus the per-repo Ledger


---

# ox uninstall (https://sageox.ai/docs/cli/uninstall)

# ox uninstall

Completely remove SageOx from the current repository: the `.sageox` directory, git hooks, and agent integration files.

<Callout type="warn">
  This is a destructive operation and cannot be undone.
</Callout>

## Usage

<Terminal>
  <TerminalCommand>ox uninstall</TerminalCommand>
</Terminal>

## What it removes

1. The `.sageox/` directory and all its contents
2. Git hooks (`prepare-commit-msg` and others)
3. Agent integration files (`.claude/settings.json` and similar)
4. The `ox agent prime` entry from `AGENTS.md` / `CLAUDE.md`
5. User-level integration hooks, when `--user-integrations` is set

Files tracked in git are unstaged but left in the working tree unless you explicitly request their removal.

If several endpoints are configured, you can pick which one to uninstall from, or pass `--all` to remove them all.

## Examples

Preview the changes without touching anything:

<Terminal>
  <TerminalCommand>ox uninstall --dry-run</TerminalCommand>
</Terminal>

Remove from every configured endpoint without a prompt:

<Terminal>
  <TerminalCommand>ox uninstall --all --force</TerminalCommand>
</Terminal>

## Flags

| Flag | Description |
|------|-------------|
| `--all` | Uninstall from all configured endpoints |
| `--dry-run` | Preview what would be removed without making changes |
| `--force` | Skip the confirmation prompt for non-interactive use |
| `--local-only` | Skip the cloud notification (doesn't require login, but cloud resources won't be cleaned up) |
| `--user-integrations` | Also remove user-level integration hooks |

## What's next

- [ox init](/docs/cli/init) - Set SageOx back up in a repository
- [ox doctor](/docs/cli/doctor) - Verify the repository's SageOx state


---

# ox upgrade (https://sageox.ai/docs/cli/upgrade)

# ox upgrade

Detect how ox was installed and upgrade using the matching method: Homebrew, `go install`, or an in-place download that verifies and replaces the binary.

## Usage

<Terminal>
  <TerminalCommand>ox upgrade</TerminalCommand>
</Terminal>

## Examples

Pin the upgrade to a specific release tag instead of the latest:

<Terminal>
  <TerminalCommand>ox upgrade --target v0.18.0</TerminalCommand>
</Terminal>

Report the result as JSON:

<Terminal>
  <TerminalCommand>ox upgrade --json</TerminalCommand>
</Terminal>

## Flags

| Flag | Description |
|------|-------------|
| `--target <tag>` | Pin the upgrade to a specific version tag (e.g. `v0.18.0`); empty means the latest release from the GitHub releases API |
| `--json` | Output the result as JSON |

## What's next

- [ox version](/docs/cli/version) - Confirm the version after upgrading
- [ox release-notes](/docs/cli/release-notes) - See what changed in the new version


---

# ox version (https://sageox.ai/docs/cli/version)

# ox version

Display the version, build date, git commit, and Go version of the ox CLI you're running.

## Usage

<Terminal>
  <TerminalCommand>ox version</TerminalCommand>
</Terminal>

<Terminal title="ox version">
  <TerminalOutput>ox 0.14.0</TerminalOutput>
  <TerminalOutput>Built: 2026-08-21 20:49 UTC</TerminalOutput>
  <TerminalOutput>Commit: 0e41c923</TerminalOutput>
  <TerminalOutput>Go: go1.26.5</TerminalOutput>
</Terminal>

## Examples

Emit the version details as JSON for scripts and tooling:

<Terminal>
  <TerminalCommand>ox version --json</TerminalCommand>
</Terminal>

## Flags

| Flag | Description |
|------|-------------|
| `--json` | Output version information as JSON |

## What's next

- [ox upgrade](/docs/cli/upgrade) - Move to the latest version
- [ox release-notes](/docs/cli/release-notes) - See what changed in the version you're running


---

# ox view (https://sageox.ai/docs/cli/view)

# ox view

Open the SageOx web dashboard for your team or repository directly from the terminal.

## Usage

<Terminal>
  <TerminalCommand>ox view [team|repo]</TerminalCommand>
</Terminal>

## Subcommands

### ox view team

Opens your team dashboard at `sageox.ai/team/{team_id}`.

<Terminal>
  <TerminalCommand>ox view team</TerminalCommand>
</Terminal>

The team dashboard shows:
- Recent discussions and recordings
- Team members and AI coworkers
- Team Context overview

### ox view repo (coming soon)

Opens the repository dashboard for the current repo. This feature is under development.

<Terminal>
  <TerminalCommand>ox view repo</TerminalCommand>
</Terminal>

The repo dashboard will show:
- Repository activity and commits
- Ledger entries
- AI coworker sessions

## When to Use

Use `ox view` when you want quick access to dashboards without leaving the terminal. For frequently visited pages, bookmark the URL directly.

## Related Commands

- [ox init](/docs/cli/init) - Initialize repository
- [ox doctor](/docs/cli/doctor) - Diagnose configuration issues


---

# ox viz (https://sageox.ai/docs/cli/viz)

# ox viz

Use a shared visualization vocabulary in plans, documentation, pull requests, reports, and design notes. All selection is deterministic and local.

Run `ox viz` with no argument to browse the catalog; pass an id to get its cognitive payoff, authoring recipe, and (where mature) its executable visual contract (evidence slots, canvas, composition, hierarchy, typography, routing, variants, and finishing pass).

## Usage

<Terminal>
  <TerminalCommand>ox viz [id] [command]</TerminalCommand>
</Terminal>

## Subcommands

| Command | Description |
|---------|-------------|
| `ox viz suggest <intent>` | Suggest visual patterns for what you need to explain |
| `ox viz render <id>` | Render a parameterized visualization from JSON data |
| `ox viz lint <file>` | Check a visual fragment for accessibility, portability, and editorial quality |
| `ox viz pr` | Prepare a GitHub-compatible visualization for a pull request |

## Examples

<Terminal>
  <TerminalCommand>ox viz</TerminalCommand>
</Terminal>

Browse the catalog of patterns. Pass an id (`ox viz <id>`) to inspect one pattern's payoff, recipe, and required data shape.

<Terminal>
  <TerminalCommand>ox viz suggest "how a request flows through the auth middleware"</TerminalCommand>
</Terminal>

Rank patterns for an intent. Add `--limit` to cap the number of suggestions.

<Terminal>
  <TerminalCommand>ox viz render decision-matrix --data matrix.json</TerminalCommand>
</Terminal>

Render a parameterized pattern from JSON into an HTML/SVG fragment, ox computes the geometry, you supply only the data. Use `--data -` to read the JSON from stdin.

<Terminal>
  <TerminalCommand>ox viz lint fragment.svg</TerminalCommand>
</Terminal>

Check a visual fragment for accessibility, portability, and editorial quality. Add `--strict` to promote editorial warnings to a non-zero exit.

<Terminal>
  <TerminalCommand>ox viz pr --intent "why the queue depth spiked"</TerminalCommand>
</Terminal>

Choose and ship a review visualization without adding review-only binary files to the PR branch. ox never posts or edits a PR, GitHub's authenticated editor creates the final attachment URL when the PNG is pasted into the description or a comment.

## What's next

- [ox plan](/docs/cli/plan) - Plans auto-embed visualizations when rendered
- [ox pr](/docs/cli/pr) - Pair a review visualization with a PR header


---

# Ox Dot firmware and recovery (https://sageox.ai/docs/context-capture/ox-dot/firmware)

# Ox Dot firmware and recovery

Your Ox Dot updates its own firmware over the air. There's nothing to install and no cable to plug in. This page is for the rare case where a device gets stuck on an old version or can't finish an update.

<Callout type="info">
Most people never need this page. The Ox Dot checks for firmware in the background and updates itself: if your device records normally, it's already current. Use these steps only if SageOx support pointed you here, or your device is clearly stuck.
</Callout>

## How updates normally work

While it's powered and online, the Ox Dot checks SageOx for new firmware about once a minute. When an update is ready for your device, it downloads in the background, verifies the signature, and installs on the next restart. The status ring shows activity, and your recordings are never interrupted.

Updates roll out gradually, so two devices on the same team can sit on different versions for a short while. That's expected, yours catches up on its own.

Every build is verified before it's applied, and the Ox Dot keeps the previous version in reserve. If a new build doesn't boot cleanly, the device rolls back to the last working version automatically, so a failed update won't leave it unusable.

## When to use this page

Work through the recovery steps below if your Ox Dot:

- Stays on an old firmware version for days while plugged in and online.
- Begins an update but never finishes it.
- Won't come back after a restart, or loops on the startup screen.

## Recover a stuck device

<Callout type="warn">
Keep the Ox Dot powered and on Wi-Fi for the whole process. Updates need a network connection, and cutting power during a restart interrupts recovery.
</Callout>

### 1. Confirm power and Wi-Fi

Plug the Ox Dot into USB-C (or flip the side switch on the battery variant), and confirm it's on a working Wi-Fi network: an offline device can't fetch firmware. If the network looks wrong, open **Settings → Wi-Fi**, forget the network, and rejoin.

### 2. Give it a few minutes online

Once it's powered and connected, leave it alone for a few minutes. The Ox Dot re-checks for firmware on its own and pulls any pending update with no action from you.

### 3. Restart the device

Power-cycle the Ox Dot: unplug it, wait about ten seconds, and plug it back in (or toggle the side switch). A clean restart lets a downloaded update finish installing, and triggers the automatic rollback if the current version didn't boot cleanly.

### 4. Factory reset and re-pair

If it's still stuck, reset it: **Settings → Factory Reset**, confirm through the countdown, then pair the device again at [sageox.ai/device](https://sageox.ai/device). Pairing re-checks firmware from scratch. Full setup steps are in the [Ox Dot guide](/docs/context-capture/ox-dot).

## Reinstall over the web (last resort)

If the steps above don't recover the device, you can reinstall the firmware directly from your computer over USB. It runs **entirely in your web browser**: there's nothing to download or install on your computer, and it works the same on Mac and Windows.

This does a **full wipe and clean install**: it erases everything on the device (Wi-Fi networks, pairing, and settings) then writes a fresh copy of the latest firmware. You'll set it up again afterward, like a brand-new device.

<Callout type="warn">
A reinstall **erases the device completely.** Your team's recordings are safe (they live in SageOx, not on the device), but the Ox Dot's Wi-Fi and pairing are cleared, and you'll pair it again from scratch. Only do this if the recovery steps above didn't work.
</Callout>

**You'll need**

- The Ox Dot and a **USB-C cable that carries data** (some charge-only cables won't work).
- **Google Chrome or Microsoft Edge**, on Mac or Windows. Safari and Firefox can't talk to the device, the installer needs Chrome or Edge.

### 1. Open the installer

In Chrome or Edge, go to **[flash.sageox.ai](https://flash.sageox.ai)**.

### 2. Connect the Ox Dot

Plug the Ox Dot into your computer with the USB-C cable, and leave it connected for the whole process.

### 3. Install

Click **Connect**, then choose the Ox Dot from the list of devices your browser shows:

- **On Mac**, it appears as something like *"USB JTAG/serial debug unit"*, no driver or setup needed.
- **On Windows**, it appears as a **COM** port (for example *COM5*). Windows 10 and 11 add the driver automatically; give it a few seconds the first time.

{/* VERIFY(port-name): confirm how the boxed Ox Dot enumerates on Mac/Windows, and whether a BOOT button is user-reachable on the shipping enclosure (affects the fallback below). */}

Click **Install**, then confirm when it asks to **erase and install**. The whole thing takes a minute or two, leave the cable connected until it reports that it's finished.

<Callout type="info">
**If the installer can't find the device:** unplug the cable, wait a few seconds, plug it back in, and click **Connect** again. Double-check you're using a data USB-C cable, not a charge-only one. If it still won't appear, contact support, don't force it.
</Callout>

### 4. Set it up again

When the install finishes, the Ox Dot restarts to its **Starting up** screen and walks you through Wi-Fi and pairing just like a new device. Follow the [Ox Dot setup guide](/docs/context-capture/ox-dot) to get it back on your team.

## Still stuck? Contact support

If a reinstall doesn't clear it either, the fix is on our side: we can target a specific firmware version to your device or arrange a replacement. Reach out with your device's name, the firmware version shown on your device list at [sageox.ai/device](https://sageox.ai/device), and a short note on what the device is doing.

## What's next

- [Ox Dot](/docs/context-capture/ox-dot): full setup, recording, and settings guide.
- [Release notes](/docs/context-capture/ox-dot/release-notes): what each firmware version changed.
- [Context capture overview](/docs/context-capture): every way to feed your Team Context.


---

# Ox Dot (https://sageox.ai/docs/context-capture/ox-dot)

# Ox Dot

The Ox Dot is a dedicated hardware recorder for in-room discussions, a small device with a round touch display that captures audio and feeds it straight into your Team Context. Pair it once and every recording lands in your team, transcribed and ready for your AI coworkers.

<Callout type="info">
A short overview video (how to use the Ox Dot, when to reach for it, and a walk-through of features like Rewind) is coming to the top of this page.
{/* TODO(video): embed the 2-min Ox Dot overview here (record + how-we-use-it + Rewind demo). */}
</Callout>

## What you get

The Ox Dot is a round-display touch device built around an ESP32-S3. At a glance:

- **Round 1.85" touch display (360×360)**: everything happens on-screen; there's no app required to record.
- **USB-C powered (5V).** Plugged into USB-C, the Ox Dot is **always on**: there's no power button. The boxed battery variant adds a **side power switch** for cordless use.
- **One side button** for recording, plus on-screen touch controls.
- **Status ring** around the display edge that changes color to show what the device is doing.

## First-time setup

### 1. Power on and join Wi-Fi

Plug the Ox Dot into USB-C (or flip the side switch on the battery variant). It boots to a **Starting up** screen, then walks you through choosing a Wi-Fi network and entering the password with the on-screen keyboard. It remembers up to several networks and reconnects on its own next time. Ox Dot uses **2.4 GHz Wi-Fi**; see [Connect Ox Dot to Wi-Fi](/docs/context-capture/ox-dot/wifi) if your network does not appear.

### 2. Pair it to your team

Once it's online, the Ox Dot shows a **pairing screen**: an 8-character code and a QR code, with the prompt *"Scan QR or visit sageox.ai/device."*

1. On your phone or laptop, scan the QR code or go to [sageox.ai/device](https://sageox.ai/device).
2. Sign in, enter the 8-character code, and pick the team this device should join.
3. Approve it. The browser shows **Device Authorized**, and the Ox Dot finishes pairing on its own.

<Callout type="warn">
The pairing code expires after about 5 minutes, the ring around the code drains as a countdown. If it runs out, the Ox Dot shows a fresh code; use the new one.
</Callout>

## Recording a discussion

Press the side button (or use the on-screen control) to start recording. While recording, the screen shows a running timer and controls to **pause/resume** and **stop**, and the status ring glows so the room can tell at a glance that capture is live.

Audio is captured locally and uploaded in the background. A **"Syncing"** indicator shows how many pieces are still uploading; if the network drops, the Ox Dot keeps the audio on the device and shows **"Saving locally"** until it can finish, your recording is never lost.

The Ox Dot also stops on its own when it should: it can auto-stop after a stretch of silence (with a confirmation countdown), and has a hard time cap so a forgotten recording doesn't run forever.

## Rewind: capture what was said *before* you hit record

The best moments often happen right before someone remembers to record. Rewind solves that, and it's built to respect privacy.

**You turn it on in Settings.** Ambient listening is **off by default**. When you enable it, the Ox Dot keeps a rolling **short-term memory** of recent room audio in memory only: it is **never written to disk and never uploaded anywhere**. Nothing from that buffer leaves the device unless *you* pull it into a recording with Rewind.

When you start a recording, Rewind lets you reach back into that buffer:

- **Tap Rewind** to pull in the last few minutes (the default, adjustable in Settings).
- **Press and hold** to scrub further back and pick exactly where to begin.

Only the slice you Rewind into a recording is ever saved, the rest of the short-term memory is continuously discarded.

<Callout type="warn">
Because Rewind reaches back to audio from *before* you pressed record, the Ox Dot shows a one-time consent screen, *"You are responsible for complying with all local recording-consent laws."* Rewind is turned off automatically in Shared Space mode.
</Callout>

## The status ring at a glance

The ring around the display is the Ox Dot's main signal:

- **Boot**: a bouncing three-dot animation under "Starting up."
- **Pairing**: the ring drains as the pairing code counts down.
- **Recording**: a breathing teal ring for public team recording.
- **Factory reset**: a dark-red wash to signal a destructive action.

{/* VERIFY(ring-colors): firmware confirms boot animation, pairing drain, teal recording, red reset. Colors for "connecting" / "error" / "low battery" are not yet mapped in firmware, confirm before documenting. */}

## Settings and factory reset

Open **Settings** from the device to manage Wi-Fi networks, turn **ambient listening** on or off and set the Rewind default, adjust auto-stop timing, and change display brightness.

To wipe the device (before handing it to someone else, or to start pairing over) go to **Settings → Factory Reset**. A confirmation screen warns that all settings will be erased; a 3-second countdown guards the button, then **Reset** restarts the Ox Dot with everything cleared.

## Troubleshooting

- **Pairing code won't take**: it expires after ~5 minutes. Read the current code off the screen and try again at [sageox.ai/device](https://sageox.ai/device).
- **Stuck on Wi-Fi**: see [Connect Ox Dot to Wi-Fi](/docs/context-capture/ox-dot/wifi) for 2.4 GHz requirements, scan guidance, and reset steps.
- **Recordings show "Saving locally"**: the device is offline; audio is safe on the Ox Dot and uploads when Wi-Fi returns.
- **Rewind has nothing to pull in**: ambient listening is off by default; turn it on in Settings first.
- **Need a clean slate**: factory reset (above), then pair again.

## What's next

- [web app recorder](/docs/context-capture/web-app-recorder): capture a discussion from your browser or phone.
- [Audio upload](/docs/context-capture/audio-upload): bring in audio you already have.
- [Context capture overview](/docs/context-capture): every way to feed your Team Context.


---

# Ox Dot release notes (https://sageox.ai/docs/context-capture/ox-dot/release-notes)

# Ox Dot release notes

What's new in each Ox Dot firmware version, newest first. Your device installs these on its own, see [firmware and recovery](/docs/context-capture/ox-dot/firmware) for how updates work.

<Callout type="info">
There's nothing to act on here. The Ox Dot updates over the air; this page is a record of what each version changed.
</Callout>

{/*
  MAINTAINERS: this page is hand-maintained: there is no live feed from the
  firmware catalog. Add a new entry at the TOP, newest first, in this shape:

  ## <version>, <Month D, YYYY>

  - **<Area>:** what changed, in customer-facing terms.
  - **Fixed:** the symptom a customer would have noticed, now resolved.

  Keep it to what a customer can perceive. Internal/build-only changes don't belong here.
*/}

Release notes will appear here as Ox Dot firmware ships.

## What's next

- [Ox Dot](/docs/context-capture/ox-dot): setup, recording, and settings.
- [Firmware and recovery](/docs/context-capture/ox-dot/firmware): how updates install and how to recover a stuck device.


---

# Connect Ox Dot to Wi-Fi (https://sageox.ai/docs/context-capture/ox-dot/wifi)

# Connect Ox Dot to Wi-Fi

Ox Dot connects to **2.4 GHz Wi-Fi**. A network that is available only on **5 GHz** will not appear in its network picker.

## Connect

1. On Ox Dot, open **Settings → Wi-Fi → Change**.
2. Choose your network from the list and enter its password.
3. Wait for the screen to show **Connected**. Ox Dot remembers saved networks and reconnects to them when they are available.

<Callout type="info">
If your router uses one Wi-Fi name for both 2.4 GHz and 5 GHz, choose that name. Ox Dot joins its 2.4 GHz band automatically when the router offers one.
</Callout>

## Your network is not listed

The picker keeps scanning while it is open, so leave it open for a moment and look again. If the network still does not appear:

- Check that the router's **2.4 GHz** band is enabled and broadcasting its network name.
- If your router gives the bands different names, choose the 2.4 GHz name (often ending in `-2G`, `-2.4`, or similar), not the 5 GHz name.
- Move Ox Dot closer to the router, then reopen **Settings → Wi-Fi → Change**.
- Confirm the network is not hidden. Hidden networks cannot be selected from the picker because Ox Dot needs to see the network name first.

## It will not connect

Double-check the password, including capitalization. If you recently changed the router password, open the saved network's options on Ox Dot, choose **Forget**, then select it again and enter the new password.

If the screen says it is saving a recording locally, the recording is safe on the device. Ox Dot uploads it automatically after Wi-Fi returns.

## Need more help?

Open [Device Support](/device/support), and include the device name shown in its Wi-Fi settings screen, along with the network name you are trying to join.