> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/reference/config-files.md).

# Config files

Every file Observal reads or writes on the client (`~/.observal/`) and in each harness's config directory.

## Client-side: `~/.observal/`

| File                       | Purpose                                                                                       | Permissions      |
| -------------------------- | --------------------------------------------------------------------------------------------- | ---------------- |
| `config.json`              | CLI config (server URL, access token, user info, timeout)                                     | `0600`           |
| `aliases.json`             | User-defined shortcuts (`@my-mcp` → UUID)                                                     | `0600`           |
| `last_results.json`        | Latest typed list output, enabling row-number references                                      | `0600`           |
| `telemetry_buffer.db`      | Durable SQLite outbox for Python session exporters awaiting contiguous server acknowledgement | `0600`           |
| `opencode_session_outbox/` | Per-session durable OpenCode plugin batches and acknowledged line state                       | `0600` files     |
| `pi_session_outbox/`       | Durable pending Pi extension batches                                                          | `0600` files     |
| `sync_state.json`          | Acknowledged byte/line cursors for file-backed exporters                                      | owner read/write |
| `keys/`                    | Server-side JWT keys (operators only; path controlled by `JWT_KEY_DIR`)                       | `0600`           |

### `config.json` schema

```json
{
  "server_url": "https://observal.your-company.internal",
  "access_token": "ey...",
  "refresh_token": "ey...",
  "user_id": "f9f3...",
  "user_name": "Alice",
  "username": "alice",
  "timeout": 30,
  "update_check": true,
  "update_check_interval": 86400,
  "update_check_repo": ""
}
```

Authentication and identity fields are managed by `observal auth`. The `config set` command accepts only `server_url`, `timeout`, `update_check`, `update_check_interval`, and `update_check_repo`. Supported environment variables override persisted values for the current invocation; see [Environment variables](/reference/environment-variables.md).

### Durable session outbox

Python session exporters persist each observed batch in `telemetry_buffer.db` before network delivery. OpenCode and Pi use per-session files under their native outbox directories because their TypeScript runtimes cannot call the Python SQLite engine. All follow the same protocol: pending data survives process restarts and failed attempts, and the source line advances only when the server's contiguous checkpoint covers the complete batch. Observal does not silently evict unacknowledged records at capacity.

`sync_state.json` is a cache of acknowledged local positions, not the authority for delivered history. If it is missing, corrupt, or stale, recovery validates and restores positions from the authenticated server checkpoint. Finalized sessions also send a SHA-256 audit manifest; hashing is not performed on ordinary incremental uploads.

Use `observal ops telemetry status` to inspect pending batch count, disk use, oldest pending time, and last successful acknowledgement.

### `aliases.json` schema

```json
{
  "my-mcp": "498c17ac-1234-4567-89ab-cdef01234567",
  "reviewer": "alice/reviewer"
}
```

Use anywhere that accepts a compatible reference by prefixing the alias with `@`.

### `last_results.json` schema

```json
{
  "item_type": "skill",
  "ids": ["498c17ac-1234-4567-89ab-cdef01234567"],
  "names": {
    "reviewer": "498c17ac-1234-4567-89ab-cdef01234567"
  }
}
```

Each list invocation replaces this cache, including an empty result. Numeric row references are valid only for the component type that produced the latest list.

## harness-side

### Claude Code

| Path                           | Purpose                              |
| ------------------------------ | ------------------------------------ |
| `~/.claude/settings.json`      | Hooks, MCP servers, telemetry config |
| `~/.claude/agents/<name>.json` | User-scoped sub-agent definitions    |
| `.claude/agents/<name>.json`   | Project-scoped sub-agent definitions |
| `.claude/skills/<skill>/`      | Installed skills (SKILL.md + assets) |
| `AGENTS.md` / `CLAUDE.md`      | Rules loaded into context            |

### Kiro

| Path                         | Purpose                                                                        |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `.kiro/settings/mcp.json`    | Project-level MCP servers with direct commands or URLs                         |
| `~/.kiro/settings/mcp.json`  | Global MCP servers                                                             |
| `.kiro/agents/<name>.json`   | Project-level agent config with telemetry hooks                                |
| `~/.kiro/agents/<name>.json` | Global agent config                                                            |
| `.kiro/steering/<name>.md`   | Steering files (system instructions with YAML frontmatter for inclusion modes) |
| `.kiro/skills/`              | Kiro skills (SKILL.md)                                                         |
| `.kiro/hooks/`               | Standalone hook definitions                                                    |
| `AGENTS.md`                  | Rules loaded into context (compat with Claude Code)                            |

### Cursor

| Path               | Purpose                                  |
| ------------------ | ---------------------------------------- |
| `.cursor/mcp.json` | MCP servers with direct commands or URLs |
| `.cursor/rules/`   | Cursor rules                             |
| `AGENTS.md`        | Rules                                    |

### VS Code

| Path               | Purpose                                  |
| ------------------ | ---------------------------------------- |
| `.vscode/mcp.json` | MCP servers with direct commands or URLs |
| `AGENTS.md`        | Rules loaded into context                |

### Codex CLI

| Path        | Purpose                        |
| ----------- | ------------------------------ |
| `AGENTS.md` | Rules (rules-only integration) |

## Safe writes

`observal doctor patch` and `observal doctor cleanup` write each managed configuration file atomically and preserve unrelated entries. Use `--dry-run --output json` to review planned harness changes before writing. Agent Pull reports every created or merged file in its result.

## File permissions

Client-side files under `~/.observal/` are created with mode `0600` (owner read/write only). This holds your access token, so don't loosen the permissions.

## Related

* [Environment variables](/reference/environment-variables.md) - supported runtime overrides
* [`observal config`](/cli-reference/config.md), CLI surface for editing


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.observal.io/reference/config-files.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.