Skip to main content
Glama
opencode-chronicler

opencode-chronicler

by abdullah1116

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.

Related MCP server: agent-activity

Install and run

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:

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

Example output (abridged):

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

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:

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

{
  "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:

{
  "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:

# ~/.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
systemctl --user enable --now opencode-chronicler

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

@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

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

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A read-only MCP server that exposes local coding-agent session logs as three tools for introspection of recent work, debugging tool failures, and tracking token usage and estimated cost without parsing log files.
      3
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for unified full-text search across chat histories from Claude Code, Codex, Cursor CLI, and Antigravity CLI, using SQLite FTS5. Provides read-only tools to search sessions, list conversations, and retrieve session details.
      MIT