An MCP server that reads every Claude Code and Codex session from its transcript: turns, plan, diff, status, cost.
peek-mcp is its own project; smine installs it as the Peek component, runs one central instance per profile and reads sessions through it. Sessions never talk to each other directly: an agent that wants to know what another session is doing asks peek. The config server's session pages, the context report, heartbeat's subagent tree, the nightly miner and the usage page all read through it.
Three MCP tools, each taking agent (claude or codex) and a session id or title (exact match first, else substring; omitted: the most recent session).
| Tool | Returns |
|---|---|
| session_list | Every session with its plan and diff flags. |
| session_get | One session's sections, each switched by a flag: turns (last n, default 20; tools adds each turn's tool calls, thinking the thinking text), events, plan, diff (merge-base diff against the inferred base), uncommitted_diff, remember (the project's auto-memory). subagent scopes it to one subagent's transcript. Paginated: while has_more is true, call again with the returned request_id; json returns the whole typed response unpaginated. |
| session_events | A bounded status: counters, cost, wall and active time, the last activity. Cheap enough to poll: monitoring loops use it, never a full-turn read, whose payload compounds. |
In a session, /peek (alias /pk, Aliases) routes to these tools: /peek 5, /peek list, /peek plan, /peek diff, /peek status <id|title>, /peek <title>, /peek codex.
| Part | Detail |
|---|---|
| Version | Pinned in PEEK_MCP_VERSION (1.2.14 today). On Windows peek-mcp.exe ships in smine-setup.exe and lands in %LOCALAPPDATA%\smine\bin. |
| Started by | The config server, at boot (-peek-start): it spawns peek when nothing serves the port; no standalone peek-mcp start is needed. It reuses a listener only if that listener's /healthz identity matches this profile's homes; otherwise peek integration is disabled with a logged error. |
| Client | The config server is peek's MCP client over Streamable HTTP at 127.0.0.1:<peek.port>/mcp. |
| Back link | The spawn passes --back-link with the server's address, so peek's dashboard nav links back as "Hub". Older peek binaries lack the flag and fail to start; keep peek current. |
| Peek down | The config server's session column degrades and the pages still render; live lists retry every 15 s. Heartbeat marks its peek sensor degraded and retries every heartbeat.peek_retry (default 30s). |
Component peek in the install record. Set a value on the config server's Smine tab or with smine-rules settings set peek.<key> <value>; all four apply on restart.
| Setting | Default | Installer flag | Meaning |
|---|---|---|---|
| peek.port | 4242 | -peek-port | The central peek MCP server; heartbeat's peek address follows it. 0 disables peek entirely. |
| peek.control_port | 42442 | -peek-control-port | peek's control dashboard and OTLP telemetry receiver; also fills {{PEEK_CONTROL_PORT}} in the settings template. 0 disables the dashboard. |
| peek.claude_home | "" | Claude home peek reads sessions from; empty takes ~/.claude. | |
| peek.codex_home | "" | Codex home peek reads sessions from; empty takes ~/.codex. |
Profiles on one Mac share the loopback ports. A second profile's config server finds the first's peek on the shared port and refuses it, so its session column stays disabled rather than show another user's sessions. Give every install its own ports (Install § Multiple macOS profiles).
The peek settings fragment (settings/claude_code/components/peek.json) carries the OTLP export env: CLAUDE_CODE_ENABLE_TELEMETRY and the endpoint http://127.0.0.1:{{PEEK_CONTROL_PORT}}/otlp, expanded from peek.control_port. The receiver is the central peek's control server; per-session peeks run --control-port=0 in both fragments and never contend for the port. Skill and tool efficacy on the config server come from these OpenTelemetry (OTel) events.
Never run peek-mcp setup on a managed machine: bin/configserver -apply deploying the fragment is the setup step. The template is the single source of truth, byte-equal to what setup would write.
Drift, say after a peek version bump, surfaces through peek's own detector: its startup log, /stats and session_events' time.telemetry report misconfigured with the expected values.
| Reader | Uses |
|---|---|
| Config server | The live session list of every registered repo, by week and day; the session column of the pages. |
| Context report | What a session was given, its invoked skills (peek's skill_invoked events and per-skill runs), the peek tiles. |
| Heartbeat | A subscriber's spawn tree after a restart and after each subscriber turn; background agents finish on peek's task_completed event (peek 1.2.9 and later). Heartbeat never starts a peek. |
| Smining | The nightly miner reads each idle session's transcript through peek, within peek's 13-day window, one record each; SMINE_SUBAGENTS=1 adds the subagent transcripts. |
| Usage page | The hourly smine-budget routine captures each session's peek usage (root, skill runs, subagents) beside ccusage, the second cost source. |
| Skills | /peek, /watch (one status line per tick), /overlap (which recent sessions touch the plan's files), /runtime. |