Configuration

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/config
project: 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

This writes to .oobo/config in the repo:

[anchors]
remote = "git@github.com:org/repo-anchors.git"

Use cases:

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

Project-level settings override global settings. Resolution order: environment variable > project config > global config > default.

Tool Sections

Each of the 15 supported tools has an optional [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_AGENT
CLAUDECODE
AIDER
CONTINUE_SESSION
CONTINUE_IDE
AICOMMITS

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>

To self-host, point at your own API server:

oobo settings set api_url https://oobo.mycompany.com

Or per-project (useful for staging):

oobo settings project set api_url https://api.staging.example.com
oobo settings project set key sk_staging_...

Your backend implements these endpoints:

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)

Team sync is Git-first - anchors live on the orphan branch and push with your code. There is no cloud upload pipeline.

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

Use --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"

The trace fires inside the post-commit hook (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:

OOBO_DEBUG=2 oobo --json

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:

oobo setup --repair

Re-installs hooks, re-detects tools, and rebuilds the orphan branch if needed.

Get Started

Usage

Deep Dives

Configuration

Settings CLI

Settings Keys

Scopes

Anchor Remote (Project-Level `remote`)

Config Files

Global config: `~/.oobo/config`

Per-project config: `.oobo/config` (in the repo root)

Tool Sections

Environment Variables

Agent Detection Variables

Remote & Self-Hosting

Privacy & Security

Agent Configuration

Skill File

Debugging

Output Modes

Trace Mode

Debug Logging

Self-Repair

​Settings CLI

​Settings Keys

​Scopes

​Anchor Remote (Project-Level remote)

​Config Files

​Global config: ~/.oobo/config

​Per-project config: .oobo/config (in the repo root)

​Tool Sections

​Environment Variables

​Agent Detection Variables

​Remote & Self-Hosting

​Privacy & Security

​Agent Configuration

​Skill File

​Debugging

​Output Modes

​Trace Mode

​Debug Logging

​Self-Repair

Settings CLI

Settings Keys

Scopes

Anchor Remote (Project-Level `remote`)

Config Files

Global config: `~/.oobo/config`

Per-project config: `.oobo/config` (in the repo root)

Tool Sections

Environment Variables

Agent Detection Variables

Remote & Self-Hosting

Privacy & Security

Agent Configuration

Skill File

Debugging

Output Modes

Trace Mode

Debug Logging

Self-Repair