ox doctor
Run diagnostics on your ox installation, project configuration, git health, agent environment, and connected services. Use --fix to auto-repair common issues, or --fix-slug to target specific checks.
Usage
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
By default, ox doctor lists the checks that need attention. Add --verbose to show every check, including passed and skipped ones.
Examples
Flags
| Flag | Description |
|---|---|
--fix | Automatically fix issues where possible |
--fix-slug | Fix specific issues by slug (repeatable, for example --fix-slug=ledger-path) |
--force-session-uploads | Force detection and upload of incomplete sessions |
--gc | Force garbage collection (reclone) of Team Contexts |
-v, --verbose | Show all checks, including passed and skipped |
-y, --yes | Answer yes to all prompts (for non-interactive use) |
Exit codes
| Code | Meaning |
|---|---|
| 0 | No check failed. Warnings and skipped checks alone exit 0. |
| 1 | A check failed or required setup is missing, including with --json |
With --json, the output is a single report. Read summary.has_failed for the result, and use the exit code for scripting.
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. To force detection and upload of incomplete sessions, run ox doctor --force-session-uploads. If sessions still don't arrive, share the output of ox doctor --json with SageOx support.

