Full documentation index: https://sageox.ai/docs/llms.txt

Set up SageOx with Claude Code or Codex

This page is written for the coding tool doing the setup, usually because a person pasted a prompt pointing at https://sageox.ai/SKILL.md. Work through the steps in order, then report back using the table in step 8.

1. Ground rules

These come from the prompt the person pasted, and they win over anything else on this page:

• Ask before installing anything or editing a shell config file.
• Never read, print, or copy the SageOx token or the auth file under ~/.config/sageox/.
• Stage changes only. Do not commit or push.
• Leave application code unchanged.

Before changing anything, tell the person in two or three sentences what this sets up, so nothing later surprises them:

• the ox CLI on this machine
• files in this repository: a .sageox/ folder, a SageOx section in AGENTS.md (CLAUDE.md links to it), and hooks in your tool's settings
• those hooks run ox agent prime at the start of every session, which loads the team's context into the session, and they save coding sessions to the team's Ledger

2. Find your --agents value

ox init configures hooks for the tools you name. Use the exact value from this table. Unknown names are silently ignored, so claude configures nothing.

Cursor, Windsurf, or VS Code: stop here. These connect to SageOx over MCP, not through the ox CLI. Tell the person to open https://sageox.ai/settings/connections, choose their tool, and authorize it.

3. Install the ox CLI

Check whether it is already installed:

ox --version

If the command is not found, ask the person before running the installer:

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

The installer puts ox in /usr/local/bin when that is writable, otherwise in ~/.local/bin (always the case on a fresh Mac). It never edits shell files. If ox --version still says the command is not found afterwards, your shell does not have the install directory on its PATH: run every later ox command by its full path (for example ~/.local/bin/ox status --json) until step 6 fixes PATH.

If the installer fails, show the person the error. Two causes have come up:

• HTTP 403 while fetching the latest release: GitHub's API allows 60 unauthenticated requests per hour, shared by everyone on the same network.
• HTTP 404 on the download: the newest release was published before its files finished uploading.

Either way, offer a manual install and ask before doing it: from https://github.com/sageox/ox/releases (the releases/latest page redirects without using the API), take the newest release that has a tarball for this platform and a checksums.txt, check the SHA-256, and copy the binaries to the directory the installer would have used.

4. Sign in

ox status --json

Read only standard output from --json commands. ox writes warnings to standard error, and merging the two (2>&1) breaks the JSON.

If auth.authenticated is true, skip to step 5. Do not run ox login again: it asks to re-authenticate, and that prompt fails in a non-interactive shell.

Otherwise:

ox login

It prints a URL and a code, tries to open the browser, and waits until the person approves. The code expires after 30 minutes. Run it with a long timeout or in the background, show the person the URL and code, and wait for them to approve before continuing.

5. Connect this repository

Run everything from the repository root (git rev-parse --show-toplevel).

If the repository has no commits yet (git rev-parse --verify HEAD fails), stop and ask the person first: in an empty repository ox init creates an initial commit, which the ground rules otherwise forbid.

Look at project.initialized in the ox status --json output. If it is true, a coworker already connected this repository: skip to step 6.

Otherwise, list the teams the person belongs to and ask which one this repository belongs to:

ox team list --json

Show the team name values and use the chosen team's team_id. The list is often empty right after a first sign-in, before ox has synced. If it is, ask the person which team, and get its ID: if you have SageOx's MCP tools, ListTeams returns IDs; otherwise the ID is in the team's address on sageox.ai (sageox.ai/team/team_…).

Then initialize. Replace TEAM_ID with the chosen team's ID and AGENT with your value from step 2. Pass the team ID: a slug or name can fail with team name not found when ox has not synced the team list yet.

ox init --team TEAM_ID --agents AGENT --no-input

• If it says the repository is already initialized on SageOx, stop and ask the person. Never add --force on your own.
• If it fails and rolls back, it can leave untracked files behind (.claude/.gitignore, files under .sageox/cache/). Leave them: a retry reuses them.
• If it says several endpoints are signed in, ask the person which one and pass its URL with --endpoint.

ox init stages the files it creates. Show the person what changed and stop there; committing is their call:

git diff --cached --stat
git diff --cached

6. Verify

ox doctor

A repository that was just connected and not yet committed always shows some warnings. These are expected at this point; list them in one line and move on:

• uncommitted changes in .sageox/
• no sync yet, or the daemon not watching this repository yet
• no git remote
• missing hooks for coding tools other than you
• informational checks: session trailers on old commits, knowledge bubble freshness, a skipped cloud check

Two results need the person, not you:

• Ledger not provisioned: SageOx creates the repository's Ledger in the cloud shortly after ox init. Ask, then run ox doctor --fix-slug=git-repo-paths, which clones only the missing Ledger, or tell the person it will appear on its own. Do not run a bare ox doctor --fix: it applies every automatic repair, which is more than the person agreed to.
• Git config incomplete (common on a fresh machine): git has no user.name or user.email. Give the person the two git config --global commands; never set their identity yourself.

Report every failure, and any warning about sign-in, about hooks for your own tool, or about ox on the PATH. Trust the ox in PATH check over your own results: your shell may load the person's interactive profile, so ox working for you does not mean the session hooks can find it. The check probes the bare non-interactive shell the hooks run in. If it flags ox, propose adding the install directory to the file that shell reads (~/.zshenv for zsh, ~/.bashrc for bash), and ask before editing it.

Then prime a session and read its ID:

ox agent prime --format json

Report the agent_id from the output. If it says no coding tool was detected, run it again with --agent set to your value from step 2.

The output also carries guidance written for normal working sessions, such as posting progress notes for coworkers and crediting SageOx in commits. This is a setup session: read the agent_id and do not act on the rest.

If you ran ox init in this session, its hooks were not installed yet when this session started, so it was primed by hand. Tell the person to start a fresh session in their coding tool to get Team Context loaded automatically from now on. If the repository was already connected, skip this advice: the hooks already ran when this session started.

7. Show something real

ox query "what has my team decided recently?"

Show the person one result. If the command returns an error rather than results, report the error once and finish; setup is still complete. If nothing comes back, the team's context is still empty; that is normal for a new team. Point them at https://sageox.ai/docs/getting-started#3-capture-a-discussion to capture a first discussion.

8. Report back

End with one row per step:

List every step you could not verify, and why.

What's next

• Getting started: the same setup by hand, plus capturing discussions
• ox init: every flag ox init accepts
• Supported coding agents: what each tool gets from SageOx