> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oobo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Settings, config files, and environment variables

## Settings CLI

Most configuration is declarative via `oobo settings`:

```bash theme={null}
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)*               | `~`                   |

<Info>
  **`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).
</Info>

### 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:

```bash theme={null}
# 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:

```toml theme={null}
[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`

```toml theme={null}
[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)

```toml theme={null}
[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](https://oobo.ai), grab an API key, and:

```bash theme={null}
oobo settings set key <your_key>
```

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

```bash theme={null}
oobo settings set api_url https://oobo.mycompany.com
```

Or per-project (useful for staging):

```bash theme={null}
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](https://github.com/gitleaks/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:

```bash theme={null}
oobo --json
oobo anchor show <sha> --json
oobo recall "query" --json
```

Use `--agent` for compact plain-text:

```bash theme={null}
oobo --agent
oobo recall "query" --agent
```

### Trace Mode

Set `OOBO_TRACE=1` to enable internal pipeline trace spans:

```bash theme={null}
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):

```bash theme={null}
OOBO_DEBUG=1 git commit -m "test"
```

`OOBO_DEBUG=2` adds stderr output alongside the file log:

```bash theme={null}
OOBO_DEBUG=2 oobo --json
```

Fine-tune log filtering with `OOBO_LOG`:

```bash theme={null}
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:

```bash theme={null}
oobo setup --repair
```

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