Settings CLI
Most configuration is declarative via oobo settings:
oobo settings set key sk_... # API key (global)
oobo settings project set key sk_... # API key (project-only, e.g. staging)
oobo settings set api_url https://api.staging.co # custom API server
oobo settings project set remote oobo # anchor Git remote override
oobo settings set transparency on # store redacted transcripts
oobo settings project set transparency off # per-project override
Settings Keys
| Key | Default Scope | Project Scope | Default |
|---|
key | API key for recall & delta | Per-project API key | (empty) |
api_url | API server URL | Per-project API server | https://api.oobo.ai |
remote | Default Git remote for anchor branch | Per-project Git remote override | origin |
transparency | on or off - controls transcript storage | Per-project override | on |
tools.experimental | Enable experimental tool integrations | (not available) | off |
setup.scan_roots | Comma-separated paths for project scanning | (not available) | ~ |
key and api_url can both be set globally or per-project. Project settings take precedence. This is useful for staging environments where only one project should use a different API endpoint and key.remote controls which Git remote receives anchor pushes. Available at both global and per-project scope (project overrides global).
Scopes
default (implicit): Global settings in ~/.oobo/configproject: Per-project overrides in .oobo/config within the repo
Project settings override defaults for that repository.
Anchor Remote (Project-Level remote)
By default, anchor metadata is pushed to origin - the same Git remote as your code. You can redirect it to a separate repository:
# Push anchors to a different named remote
oobo settings project set remote oobo
# Push anchors to a completely separate repo URL
oobo settings project set remote git@github.com:org/repo-anchors.git
# Check current value
oobo settings project remote
# Reset to default (origin)
oobo settings project unset remote
.oobo/config in the repo:
[anchors]
remote = "git@github.com:org/repo-anchors.git"
- Privacy-sensitive teams who want anchor data in a private repo
- Keeping audit data separate from application code
- Enterprise setups with dedicated metadata repositories
Data safety: Anchor data is always written to the local orphan branch first. If the push to the remote fails (permissions, network, wrong URL), the data is safe locally and the user sees a warning on stderr. The CLI retries on contention (non-fast-forward) but does not retry permission errors - the user must fix the config.
Config Files
Global config: ~/.oobo/config
[server]
url = "https://api.oobo.ai" # api_url setting
api_key = "sk_..." # key setting
[privacy]
transparency = "off" # off | on
[cursor]
enabled = true
[claude]
enabled = false
Per-project config: .oobo/config (in the repo root)
[project]
id = "r:github.com/org/repo"
enabled = true
[server]
api_key = "sk_staging_..." # overrides global key for this project
url = "https://api.staging.example.com" # overrides global url
[anchors]
remote = "oobo" # push anchors to this Git remote instead of origin
[toolname] section with enabled = true|false:
cursor, claude, gemini, windsurf, aider, copilot, zed, trae, codex, opencode, kiro, continue, droid, junie, amp
Environment Variables
| Variable | Description |
|---|
OOBO_SECRET_KEY | Override the persisted API key for the current process only |
OOBO_HOME | Override the oobo data directory (default: ~/.oobo) |
OOBO_INSTALL_DIR | Override install directory during installation |
OOBO_VERSION | Install a specific version during installation |
OOBO_NO_MODIFY_PATH | Set to 1 to skip PATH modification during install |
OOBO_INTERCEPTED | Set internally to prevent recursive hook calls |
OOBO_DEBUG | 1 = file log to ~/.oobo/logs/oobo.log, 2 = file + stderr |
OOBO_LOG | Filter for structured logging (e.g. oobo::git=debug) |
OOBO_TRACE | 1 = enable internal pipeline trace spans (logged via OOBO_DEBUG) |
Agent Detection Variables
When any of these are set and non-empty, oobo auto-activates --agent mode:
CURSOR_AGENTCLAUDECODEAIDERCONTINUE_SESSIONCONTINUE_IDEAICOMMITS
Remote & Self-Hosting
By default, oobo points at api.oobo.ai. Create a free account at oobo.ai, grab an API key, and:
oobo settings set key <your_key>
oobo settings set api_url https://oobo.mycompany.com
oobo settings project set api_url https://api.staging.example.com
oobo settings project set key sk_staging_...
| Endpoint | Method | Auth | Required | Purpose |
|---|
/anchors/search | POST | Bearer token | Yes | Search anchors/sessions (with memory + answer synthesis) |
/anchors/delta | POST | Bearer token | Yes | Compare two anchors |
/anchors/health | GET | None | No | Health check (recommended convention, not called by CLI) |
Privacy & Security
- Read-only data access - never modifies AI tool conversation history; only writes hook configs during setup
- Local by default - anchors live on a git orphan branch, config in
~/.oobo/
- Secret redaction - sessions are scrubbed with gitleaks patterns before sharing
- No telemetry - does not phone home
- Config protection - API keys in config get
chmod 0600
Agent Configuration
Agents should operate with transparency on:
| Setting | Value | Why |
|---|
transparency | on | Metadata + redacted transcripts sync |
--agent flag | Always use | Compact output, low token cost |
--json flag | When needed | Full structured data for parsing |
key | (optional) | For recall, delta, and memory |
api_url | (optional) | Only needed for self-hosted or staging |
Skill File
oobo setup installs a skill file at ~/.oobo/skills/oobo/SKILL.md with symlinks in:
~/.agents/skills/oobo/~/.claude/skills/oobo/~/.codex/skills/oobo/~/.cursor/skills/oobo/~/.gemini/skills/oobo/
AI coding tools discover the skill automatically and know how to install and use oobo.
Debugging
Output Modes
Use --json for complete structured state:
oobo --json
oobo anchor show <sha> --json
oobo recall "query" --json
--agent for compact plain-text:
oobo --agent
oobo recall "query" --agent
Trace Mode
Set OOBO_TRACE=1 to enable internal pipeline trace spans:
OOBO_TRACE=1 OOBO_DEBUG=2 git commit -m "fix auth middleware"
oobo hooks post-commit). Trace output requires OOBO_DEBUG to be set.
Debug Logging
OOBO_DEBUG=1 enables file logging to ~/.oobo/logs/oobo.log (daily rolling):
OOBO_DEBUG=1 git commit -m "test"
OOBO_DEBUG=2 adds stderr output alongside the file log:
Fine-tune log filtering with OOBO_LOG:
OOBO_LOG=oobo::git=debug OOBO_DEBUG=1 git commit -m "test"
Self-Repair
There is no oobo doctor command. The normal path is self-repair:
- Hook installation is idempotent
- Stale hook-buffer files from interrupted sessions are cleaned up automatically
- Orphan branch state is rebuilt from git history if corrupted
- Setup is safe to re-run at any time
Manual escape hatch:
Re-installs hooks, re-detects tools, and rebuilds the orphan branch if needed.
