# Configuration

There are three config surfaces worth caring about here: `agentic.toml` for non-secret agent/tool settings, `.thoughts/config.json` for per-repo mount intent, and `~/.config/agentic/repos.json` for URL-to-local-path mappings. They do different jobs, which is good, because mixing them would be worse.

## `agentic.toml` (global + local)

`agentic.toml` is the non-secret config layer used by `agentic-mcp`, the reasoning tool, the orchestrator, and a few other pieces. The merge order is defaults → global `~/.config/agentic/agentic.toml` → local `./agentic.toml` → environment variables.

These commands come from the `agentic` binary specifically, and today they are focused on managing this config surface:

Useful commands:

```bash
agentic config init
agentic config edit
agentic config validate
```

Minimal shape, trimmed from [`../agentic.toml.example`](../agentic.toml.example):

```toml
[subagents]
locator_model = "claude-haiku-4-5"
runtime_timeout_secs = 3600

[reasoning]
executor_model = "openai/gpt-5.2"

[cli_tools]
just_execute_timeout_secs = 1800
just_search_timeout_secs = 30

[services.linear]
request_timeout_secs = 60

[services.github]
total_timeout_secs = 120

[review]
run_timeout_secs = 1800

[thoughts]
add_reference_timeout_secs = 600

[logging]
level = "info"
```

Think of this as orientation and defaults, not secret storage. Models, base URLs, timeouts, and logging belong here; API keys do not.

Timeout fields use a simple shared rule: `0 = disabled`. That applies to `subagents.runtime_timeout_secs`, `cli_tools.just_execute_timeout_secs`, `cli_tools.just_search_timeout_secs`, `services.linear.connect_timeout_secs`, `services.linear.request_timeout_secs`, `services.github.total_timeout_secs`, `review.run_timeout_secs`, and `thoughts.add_reference_timeout_secs`.

One sync boundary matters for contributors: `agentic.schema.json` is regenerated by xtask sync, but `agentic.toml.example` is still maintained manually. Update both together when the modeled config surface changes.

### `orchestrator.commands`

`opencode-orchestrator-mcp` can filter which upstream `OpenCode` commands are shown by `list_commands` and which named commands may be executed through `run(command=...)`:

```toml
[orchestrator.commands]
allow = ["research", "implement_plan"]
deny = ["commit"]
```

Runtime semantics:

- `deny` wins over `allow`
- `allow = []` means there is no allowlist restriction
- matching is exact and case-sensitive
- configured entries are trimmed before comparison, so `" build "` matches `build`
- this policy applies to `list_commands` and `run(command=...)`, but not raw `run(message=...)`

One merge caveat matters here: TOML tables merge, but arrays replace rather than append. If a local `agentic.toml` sets `allow = []`, that clears any inherited allowlist instead of extending it.

## `.thoughts/config.json` (per repo, v2 only)

This file lives at `<repo>/.thoughts/config.json` and tells `thoughts` what the repo wants to mount. Current runtime expects `version: "2.0"`; older v1 configs are not supported anymore.

Useful commands:

```bash
thoughts config show
thoughts config edit
thoughts config validate
```

Minimal shape:

```json
{
  "version": "2.0",
  "thoughts_mount": { "remote": "git@github.com:user/thoughts.git", "sync": "auto" },
  "context_mounts": [{ "remote": "https://github.com/team/docs.git", "mount_path": "team-docs", "sync": "auto" }]
}
```

The real file can also include `mount_dirs` and `references`, but the shape above is the part most people need to orient themselves: one optional thoughts repo, zero or more context repos, then a reference list.

`thoughts config edit` is a thin wrapper around editing this file directly: it opens `<repo>/.thoughts/config.json` in `VISUAL`, then `EDITOR`, then `vi`; after you exit, it validates the file, rewrites it in normalized JSON, and updates active mounts.

## `~/.config/agentic/repos.json` (repo mappings)

This is the canonical mapping file for repo URLs to local paths. `~/.thoughts/repos.json` is only legacy input now, not the current home for the file.

This file is intentionally local and context-specific: different developers can map the same canonical repo identity to different clone paths on their own machines. By contrast, `agentic.toml` and `.thoughts/config.json` are the shareable, team-oriented layers that describe defaults and mount intent rather than one person's filesystem layout.

Minimal shape:

```json
{
  "version": "1.0",
  "mappings": {
    "github.com/org/repo": { "path": "/path/to/repo", "auto_managed": false }
  }
}
```

`auto_managed` is the part that usually matters in practice. `true` means the tooling created/owns that clone path; `false` means you pointed the system at a repo you manage yourself.

If you came here from setup, the next useful stop is usually [`./auth.md`](./auth.md) for secrets or [`./troubleshooting.md`](./troubleshooting.md) when a mapping exists but the mount still is not doing what you expected.
