double-o 0.8.0

Context-efficient command runner for AI coding agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# Configuration Reference

## Directories

oo uses the per-OS base directories from the `dirs` crate: `dirs::config_dir()` for configuration and `dirs::data_dir()` for indexed data. The table lists the default values on macOS and Linux. On Linux the values follow the XDG base directory rules as implemented by the `dirs` crate:

| Purpose | Linux | macOS |
|---------|-------|-------|
| Configuration | `$XDG_CONFIG_HOME/oo/` (default `~/.config/oo/`) | `~/Library/Application Support/oo/` |
| Data (SQLite index) | `$XDG_DATA_HOME/.oo/oo.db` (default `~/.local/share/.oo/oo.db`) | `~/Library/Application Support/.oo/oo.db` |
| Patterns (user-defined) | `<config dir>/patterns/` (default `~/.config/oo/patterns/`) | `~/Library/Application Support/oo/patterns/` |

On Linux, `XDG_CONFIG_HOME` and `XDG_DATA_HOME` are honoured only when they are absolute paths; otherwise the defaults above apply. On macOS the XDG variables are ignored. Windows is untested.

If the `dirs` crate cannot determine a base directory, the config directory falls back to `/tmp/oo` and the data directory falls back to `$HOME/.oo` (then `/tmp/.oo`).

Override the config directory with the `OO_CONFIG_DIR` environment variable. The value is used as-is (no `oo/` is appended), so `config.toml` and `patterns/` live directly inside it. A relative value is resolved against the current working directory, and an empty value (`OO_CONFIG_DIR=`) means the current working directory itself:

```bash
export OO_CONFIG_DIR=/custom/path
```

Override the data directory with the `OO_DATA_DIR` environment variable (used primarily for test isolation):

```bash
export OO_DATA_DIR=/custom/data/path
```

The SQLite database is always named `oo.db`. Its directory (`<data dir>`) is `OO_DATA_DIR` when set, used as-is (`OO_DATA_DIR=/x` gives `/x/oo.db`). A relative value is resolved against the current working directory (`OO_DATA_DIR=rel` gives `./rel/oo.db`), and an empty value gives `./oo.db`. Otherwise it is the platform data directory plus `.oo/` (the Data row above).

## Config File

Location: `config.toml` in the configuration directory (`~/.config/oo/config.toml` on Linux, `~/Library/Application Support/oo/config.toml` on macOS; see [Directories](#directories)).

The config file is optional. If it doesn't exist, oo uses defaults.

### `[learn]` section

Configuration for the `oo learn` LLM integration. This is the single source of truth for the model name — the default model is `claude-haiku-4-5` (only Anthropic is supported). An annotated example lives in [config.example.toml](../config.example.toml).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `provider` | string | `"anthropic"` | LLM provider (only `"anthropic"` is supported) |
| `model` | string | `"claude-haiku-4-5"` | Model identifier for the provider |
| `api_key_env` | string | `"ANTHROPIC_API_KEY"` | Environment variable containing the API key |

### Default behavior

If the `[learn]` section is absent or `config.toml` doesn't exist, oo defaults to `provider = "anthropic"`, `model = "claude-haiku-4-5"`, and `api_key_env = "ANTHROPIC_API_KEY"`.

### `[store]` section

Retention for indexed command output (the entries `oo` stores for `oo recall`). An annotated example lives in [config.example.toml](../config.example.toml).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `retention` | integer (seconds) | `604800` (7 days) | Indexed entries older than this are purged. `0` disables purging. Must be `>= 0`. |

- **When purging happens:** lazily and per project. A purge runs when a project next indexes output, and removes only that project's entries older than `retention`. Other projects, and a project that never indexes again, keep their entries until then.
- **Vipune store backend:** with `--features vipune-store`, the purge is bounded for projects over 10,000 entries and may leave some behind (#182).
- **Invalid config:** an absent `[store]` section or `retention` key uses the default. A negative, non-integer, or out-of-range (above 2^63-1) value, an unknown key in `[store]` (for example a typo such as `retension`), or a `config.toml` that cannot be parsed prints a warning on stderr and uses the default. The warning appears when indexing runs (not on `oo recall` or `oo forget`). Indexing is never blocked by config. Unknown top-level sections such as `[learn]` do not affect retention.
- `oo forget` clears a project's indexed entries immediately, regardless of retention.

## Environment Variables

### `OO_CONFIG_DIR`

Overrides the configuration directory.

- **Default**: the platform configuration directory plus `oo/` (see the [Directories](#directories) table)
- **Purpose**: Specify a custom location for `config.toml` and `patterns/`

```bash
export OO_CONFIG_DIR="/some/custom/dir"
```

### `OO_DATA_DIR`

Overrides the data directory that holds the SQLite index.

- **Default**: platform base data dir joined with `.oo/` (see the [Directories](#directories) table)
- **Purpose**: Relocate `oo.db`; primarily used to isolate tests from the real store

```bash
export OO_DATA_DIR="/some/custom/data/dir"
```

### `ANTHROPIC_API_KEY`

Required for `oo learn`.

- **Required**: Only when using `oo learn`
- **Default**: None

Set this to enable LLM-assisted pattern learning:

```bash
export ANTHROPIC_API_KEY="your-api-key"
```

### `ANTHROPIC_API_URL`

Optional custom endpoint for Anthropic API.

- **Default**: `https://api.anthropic.com/v1/messages`
- **Purpose**: Use a custom Anthropic-compatible endpoint

```bash
export ANTHROPIC_API_URL="https://your-proxy.example.com/v1/messages"
```

> **Security warning:** HTTP URLs only allowed for `localhost` or `127.0.0.1`. All other hosts must use HTTPS.

## Runtime Thresholds

These constants are built into the binary and cannot be configured.

| Constant | Value | Description |
|----------|-------|-------------|
| `SMALL_THRESHOLD` | 4096 bytes | Successful (exit 0) output of at most this many bytes (4 KiB) passes through unchanged; failed output is always filtered |
| `TRUNCATION_THRESHOLD` | 80 lines | Failure output truncation starts after this many lines |
| `MAX_LINES` | 120 lines | Hard cap on lines shown after smart truncation |

## Feature Flags

| Flag | Description |
|------|-------------|
| `vipune-store` | Enables Vipune backend for indexed output with semantic search. When enabled, outputs are stored using Vipune instead of SQLite. Build with `cargo build --features vipune-store`. |

To build with Vipune support:

```bash
cargo build --release --features vipune-store
```

The `vipune-store` feature changes only the storage backend for `oo recall`. All other oo behavior remains identical.

## Files in Configuration Directory

The configuration directory (see the [Directories](#directories) table) contains:

- `config.toml` - Optional user configuration
- `patterns/` - User-defined pattern files (`.toml`) — see [Custom Patterns](patterns.md)
- `learn-status.log` - Transient status from background learn processes (auto-cleaned)

Project patterns (`<git-root>/.oo/patterns/`) and user patterns in the config directory's `patterns/` directory are checked before the built-in patterns; the order is project, then user, then built-in, and the first match wins. The foreground display in `oo learn` uses built-ins only (#151). See `oo patterns` for the full list.