ccmonitor: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

ccmonitor — A standalone Bun TUI app that monitors Claude Code session activity in real time. It watches ~/.claude/ data files (JSONL transcripts, subagent metadata, team configs, task files) and renders a terminal dashboard showing tool usage, skills, subagents, teams, tasks, token consumption, and file activity.

Build & Run Commands

bun run start          # Run the monitor (bun run src/index.ts)
bun run dev            # Run with --watch for auto-reload
bun run build          # Compile to standalone binary: dist/ccmonitor
bun run install:global # Build + copy binary to ~/.bun/bin/ccmonitor

Run with a specific session: bun run src/index.ts <sessionId>

Testing

bun test               # synthetic + fixture tests (src/*.test.ts, fixtures/*.jsonl)
bun run typecheck      # tsc --noEmit, strict + noUncheckedIndexedAccess
bun run src/index.ts --fixture fixtures/recap-basic.jsonl   # render a fixture, no registry

Fixtures are scrubbed cuts of real transcripts (scripts/make-fixture.ts, re-cut with scripts/cut-fixtures.sh). Each has a measured .expect.json sidecar. Before a release also run bun run build and the width sweep in src/ui.test.ts (80/100/140 columns). Golden renders live in fixtures/golden/; after a deliberate visual change run bun run scripts/update-golden.ts and read the diff.

Upgrade

When the user says upgrade:

• Bump the minor version in package.json
• Verify with bun run build (rebuild dist/ccmonitor)
• Add an entry to CHANGELOG.md (Keep a Changelog format)
• Update README.md (version line + any user-facing changes)
• Save, commit, push

Architecture

No external UI framework — raw ANSI escape codes to stdout. Parsing is split into a pure layer and disk loaders:

• index.ts — Entry point. CLI args ([sessionId], --fixture), keyboard (q/r/n/s/c/b/i/d/1-9/0/Enter/Esc/j/k; ↑/↓ on the dashboard change the refresh interval), view state (dashboard | recap | background | info | sessions), collapsed-section prefs (src/uiPrefs.ts → ~/.claude/ccmonitor-ui.json), refresh loop (2 s default, 2–60 s, src/refresh.ts). Holds one TranscriptReader per transcript file.
• parser.ts — Orchestration. parseTranscriptLines(lines, ctx) (pure), enrichSessionState(state) (runs the loaders on a copy), TranscriptReader (incremental tail reads; full reparse when the file shrinks or its first 64 bytes change), locate*Session helpers, computeDerived.
• entry.ts — The pure per-entry state machine (processEntry + handleSystem / handleAttachment / handleAssistant / handleUser …). Groups assistant lines by message.id, opens/closes turns, tracks background tasks, recap text, hooks, permissions, cost, links, queue, attribution, errors. Reports unknown type / system.subtype / attachment.type values through ctx.onUnknown.
• state.ts — createSessionState, ParseMemo (parser working memory), ParseSession.
• recap.ts — Pure text helpers: extractKoreanRecap, mdToPlain, parseTaskNotification, cleanNativeRecap.
• loaders/ — One file per disk source (subagents, teams, tasks, skillHook, git, gitStatus, fileHistory, sessions, memory, effort, rateLimit, process, scratchpad, globalConfig, modelCatalog, plans, feedback, history, update).
• views/sessions.ts — pure row builder for the session picker. paths.ts holds CLAUDE_DIR (override with CCMONITOR_CLAUDE_DIR).
• types.ts — All TypeScript interfaces. SessionState is the central data structure; TranscriptEntry models the JSONL schema.
• ui.ts — Pure rendering. The dashboard is header + SECTIONS (each a Section {id, key, title, render}) + footer; renderDashboardLines / renderRecapViewLines / renderBackgroundViewLines / renderInfoViewLines / renderSessionsViewLines return string[]; render() writes to stdout. Adding a panel = appending to SECTIONS. Handles CJK fullwidth and emoji widths. No state mutation.
• keys.ts — splitKeys: splits a stdin chunk into single keys (escape sequences whole). CCMONITOR_KEYLOG=<file> logs raw chunks.
• unknownFields.ts — Appends unknown kinds to ~/.claude/ccmonitor-unknown-fields.log.