Skip to main content
Glama
opencode-chronicler

opencode-chronicler

by abdullah1116
README.md
# opencode-chronicler

A **read-only** Model Context Protocol server that exposes opencode session
history as well-formed Markdown over streamable HTTP. Point an MCP client at it,
ask for a session, and you get back the metadata block, every message in
authoritative `seq` order, and the tool calls with their results, rendered as
clean Markdown. Model reasoning/thinking blocks are omitted by design.

The database is opened with `{ readonly: true }` and is never written to,
migrated, or locked for writing.

## Requirements

- **Bun ≥ 1.2** — runtime, test runner, and package manager. The project uses
  `bun:sqlite`, `Bun.serve`, and `bun test`.

## Install and run

```bash
bun install
bun run start          # boots src/index.ts
```

The server listens on port `31701`: MCP is served at `/mcp` and a liveness probe
at `/health`.

## Configuration

All variables are optional; the defaults are shown below. Invalid values fail
fast at boot with an error naming the offending variable.

| Variable | Default | Description |
|---|---|---|
| `OPENCODE_DB_PATH` | `~/.local/share/opencode/opencode.db` | opencode session database (a leading `~` is expanded). |
| `HOST` | `0.0.0.0` | HTTP bind address. |
| `PORT` | `31701` | HTTP port serving `/mcp` and `/health`. |
| `LOG_LEVEL` | `info` | One of `debug`, `info`, `warn`, `error`. |
| `CHRONICLER_DIR` | `.` | Output directory. |
| `CHRONICLER_LOG_PATH` | `./chronicler.log` | Log file. |
| `OPENCODE_E2E_SESSION` | *(unset)* | Session id used by the live-database end-to-end test; unset means the test skips. |

If the database file does not exist, the server refuses to start rather than
silently creating an empty one.

## MCP tools

### `read_session`

Render one opencode session as Markdown: a metadata block (id, directory,
timestamps, project, parent, version, message count), a horizontal rule, then one
`## <role> — <time>` section per message in `seq` order.

| Parameter | Type | Default | Notes |
|---|---|---|---|
| `session_id` | string (min 1) | — | opencode session id, e.g. `ses_...`. |
| `include_tool_output` | boolean | `true` | Include tool-result output in the Markdown. |
| `max_part_chars` | int, 100–50000 | `2000` | Per-part truncation budget. |

Model reasoning/thinking blocks are omitted from the output.

Example call:

```json
{
  "name": "read_session",
  "arguments": {
    "session_id": "ses_11111111111111111111111111",
    "max_part_chars": 4000
  }
}
```

Example output (abridged):

```markdown
# Alpha Session

- **ID**: `ses_11111111111111111111111111`
- **Directory**: /home/you/projects/alpha
- **Created**: 2026-01-01T00:00:00.000Z
- **Updated**: 2026-01-01T00:00:05.000Z
- **Project**: 0123456789abcdef0123456789abcdef01234567
- **Parent**: ses_11111111111111111111111112 — subagent session
- **Version**: 1.0.0
- **Messages**: 2

---

## user — 2026-01-01T00:00:00.000Z

Summarize the release notes.

## assistant — 2026-01-01T00:00:05.000Z

**Tool: bash** (`call_abc123`)

```json
{ "command": "git branch --show-current" }
```

**Output:**

```text
main
```
```

An unknown session id returns an error result with the text
`Session not found: <id>`.

### `list_sessions`

List recent sessions newest-first as a Markdown table.

| Parameter | Type | Default | Notes |
|---|---|---|---|
| `query` | string | — | Case-insensitive filter on title or directory. |
| `limit` | int, 1–200 | `20` | Maximum rows to return. |

Example call:

```json
{ "name": "list_sessions", "arguments": { "limit": 5 } }
```

Example output:

```markdown
| ID | Title | Msgs | Updated | Directory | Preview |
|---|---|---|---|---|---|
| ses_11111111111111111111111111 | Alpha Session | 2 | 2026-01-01T00:00:05.000Z | /home/you/projects/alpha | Summarize the release notes. |
```

When no sessions match, the tool returns the single line `No sessions found.`

## Connecting an MCP client

Register the chronicler as a **remote** MCP server in your opencode config
(`opencode.json`, or `opencode.jsonc` on installs that use the JSONC extension —
strict JSON content either way):

```json
{
  "mcp": {
    "chronicler": {
      "type": "remote",
      "url": "http://localhost:31701/mcp"
    }
  }
}
```

That is the opencode 1.18.x V1 schema, where MCP servers live directly under the
`mcp` key. V2-style configs document them under `mcp.servers.<name>` with a
`disabled` field:

```json
{
  "mcp": {
    "servers": {
      "chronicler": {
        "type": "remote",
        "url": "http://localhost:31701/mcp",
        "disabled": false
      }
    }
  }
}
```

Replace `localhost` with the host running the chronicler when it is not on the
same machine. The chronicler never edits your opencode config or database — it
is a strictly read-only consumer of the session DB. Wiring the server into a
client is user-side setup.

## Running on boot

Any process supervisor works. On a normal machine, a systemd **user** service:

```ini
# ~/.config/systemd/user/opencode-chronicler.service
[Unit]
Description=opencode-chronicler (read-only opencode session MCP server)

[Service]
WorkingDirectory=%h/opencode-chronicler
ExecStart=/usr/bin/bun run start
Restart=on-failure

[Install]
WantedBy=default.target
```

```bash
systemctl --user enable --now opencode-chronicler
```

Cron alternative (a `@reboot` line in `crontab -e`):

```cron
@reboot cd "$HOME/opencode-chronicler" && /usr/bin/bun run start >>"$HOME/.local/share/opencode-chronicler.log" 2>&1
```

For opencode hosts without an init system, the repo ships an opencode **plugin**
at `plugin-src/chronicler-keeper/`. On opencode server boot the plugin spawns
the chronicler detached after a `/health` probe — idempotent, so a reload never
double-spawns, and spawn failures are logged and swallowed. Copy the directory
into your opencode plugin path and reference it from the config's `plugin`
array.

## How it works

| module | responsibility |
|---|---|
| `config/env.ts` | Env → `AppConfig` (db path, directory, log path). |
| `log.ts` | Level-filtered logger. |
| `domain/types.ts` | Frozen type contract shared by the data and render layers. |
| `db/rows.ts` | Schemas for raw `session_v2` / `session_message` rows. |
| `db/opencode-db.ts` | Read-only `bun:sqlite` handle plus the `ChroniclerDb` facade. |
| `db/v2parse.ts` | v2 row JSON → domain shapes (defensive, never throws). |
| `db/queries.ts` | `listSessions$`, `loadSessionDoc$` RxJS pipelines. |
| `render/session-md.ts` | `renderSession(doc, opts)`. |
| `render/sessions-table.ts` | `renderSessionsTable(summaries)`. |
| `render/parts.ts` | Per-kind part renderer registry with a never-crash fallback. |
| `mcp/server-factory.ts` | Builds a fresh `McpServer` with both tools registered. |
| `mcp/http.ts` | `Bun.serve` routing: stateless `/mcp`, `/health`. |
| `mcp/tools/*.ts` | The `read_session` and `list_sessions` handlers. |
| `index.ts` | Boot: env → logger → DB → HTTP app → graceful shutdown. |

Data flows through RxJS end to end: tool input → deferred DB read → `v2parse` →
`toArray` → `map(render)` → `Observable<string>`, with `firstValueFrom` the only
Promise-shaped edge, inside the MCP handler.

Each `/mcp` request constructs a fresh `McpServer` and a fresh single-use
transport, so there is no session state to leak between callers.

## Health check

```bash
curl http://localhost:31701/health
# {"status":"ok","service":"opencode-chronicler"}
```

`GET /health` returns HTTP 200 with that JSON body; any unknown route returns
HTTP 404 `{"error":"not found"}`.

## Read-only guarantee

The chronicler is strictly a **consumer** of `opencode.db`. The database is
opened as `new Database(path, { readonly: true, create: false })`, so SQLite
itself rejects any write attempt, and the codebase contains no `INSERT`,
`UPDATE`, `DELETE`, or migration path against it. No schema changes, no WAL
checkpoints, no config edits. The end-to-end test asserts this mechanically: it
records the database's `sha256`, mtime, and size before boot and re-asserts
byte-identical equality after a full real-client MCP run. Without a configured
database the test skips with a clear message rather than failing.

## Development and testing

```bash
bun run dev      # watch mode
bun run check    # tsc --noEmit (strict, ESM)
bun test         # unit + real-client HTTP end-to-end tests
```

The end-to-end suite runs against a live opencode database when
`OPENCODE_DB_PATH` points at one; set `OPENCODE_E2E_SESSION` to a session id to
include live session rendering, otherwise that case skips.

## License

MIT — see [LICENSE](LICENSE).