# Connect a repository (/docs/developers/connect-repository)



Connect a 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 [#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 [#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 [#prerequisites]

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

Team vs personal scope [#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 [#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](mailto:you@example.com)
  </TerminalOutput>

  <TerminalOutput />

  <TerminalOutput>
    Repository
  </TerminalOutput>

  <TerminalOutput>
      ✓ Connected to team: my-team
  </TerminalOutput>

  <TerminalOutput>
      ✓ Team Context synced
  </TerminalOutput>

  <TerminalOutput />

  <TerminalOutput>
    Claude Code
  </TerminalOutput>

  <TerminalOutput>
      ✓ Hooks configured
  </TerminalOutput>
</Terminal>

How AI coworkers use the connection [#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 [#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 [#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 [#troubleshooting]

"Not a git repository" [#not-a-git-repository]

Initialize git first:

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

"Already initialized" [#already-initialized]

Remove the existing configuration and reinitialize:

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

"Authentication required" [#authentication-required]

Run login first:

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

What's next [#whats-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