--- name: sageox-setup description: Install the ox CLI, connect this repository to SageOx, and verify the first primed session. --- # Set up SageOx with Claude Code or Codex (https://sageox.ai/docs/quickstart/ai-setup) > 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. | You are | `--agents` value | |---|---| | Claude Code | `claude-code` | | Codex CLI | `codex` | | Gemini CLI | `gemini` | | Amp | `amp` | | OpenCode | `opencode` | | Goose | `goose` | | Factory Droid | `droid` | **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: ```bash ox --version ``` If the command is not found, ask the person before running the installer: ```bash 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 ```bash 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: ```bash 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: ```bash 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. ```bash 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: ```bash git diff --cached --stat git diff --cached ``` ## 6. Verify ```bash 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: ```bash 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 ```bash 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: | Step | Status | Evidence | |---|---|---| | Install | done / skipped / failed | `ox --version` output | | Sign in | | email from `ox status --json` | | Connect repository | | team name, or "already connected" | | Staged changes | | files from `git diff --cached --stat`, staged and not committed | | `ox doctor` | | failures and unexpected warnings | | `agent_id` | | the ID | | First query | | one result, or "empty" | List every step you could not verify, and why. ## What's next - [Getting started](https://sageox.ai/docs/getting-started): the same setup by hand, plus capturing discussions - [ox init](https://sageox.ai/docs/cli/init): every flag `ox init` accepts - [Supported coding agents](https://sageox.ai/docs/developers/coding-agents): what each tool gets from SageOx