chronicle

cc-plugins

A local Claude Code, Codex, and OpenCode plugin marketplace for a personal coding workflow. It ships five plugins: monitor turns local traces into useful dashboards — the usage-dashboard skill is the rear-view mirror for usage history, and the cockpit skill is the windshield for the session currently in flight; dispatch is interview-driven planning you can then execute — spec the work, write a blueprint to disk, and fly it with a quality loop, or map a whole project into milestone legs and plan each one just-in-time; relay delegates a task out to another harness's CLI (codex, opencode, or claude) — delegate work, request a review, or generate an image — then captures the result and reports back; chronicle authors your git history — commits (auto simple/atomic), reviewer-legible PRs/MRs, and config-first releases that bump versions, write the changelog, and cut the tag; herdr is reference plus a typed wrapper for driving agents across panes in the Herdr terminal workspace manager.

Development Workflow

This repository uses GitHub Flow. Create feature and fix branches from main, then open pull requests back into main. The existing develop branch is historical and does not indicate that this repository uses git-flow. Chronicle records this machine-readable PR policy in .chronicle/pr.json.

Plugins

monitor bundles three skills:

Skill	Description
usage-dashboard	Local usage dashboard for Claude Code, Codex, and OpenCode: sessions, tokens, cost, model mix, and project activity, plus live sessions for Claude Code and Codex
cockpit	Per-project work cockpit for Claude Code, Codex, and OpenCode: goal capture, decision log, live transcript, needs-your-call bridge, and a send box for live sessions
install	One-stop prerequisite check and permission wiring for the whole plugin, command-triggered

dispatch bundles five skills:

Skill	Description
preflight	Short interview that captures what you want as docs/<slug>/INTENT.md, before anyone decides how to build it — writes one file and stops, never executes
hop	Lightweight interviewer that gathers requirements into a single in-conversation plan to approve and execute
flightplan	Heavyweight interviewer that writes a multi-file blueprint to disk — PLAN.md + a tasks/ tree of self-contained task files for sub-agents
autopilot	Executes a flightplan tree in parallel waves — a dev→verify→judge→score loop gated on each task's Eval rubric, an atomic commit between waves, then the closing final-review gate, leaving an audit trail
waypoints	Rolling-wave milestone-roadmap tier above flightplan — writes only docs/<proj>/WAYPOINTS.md plus a waypoints.ts CLI (active / leg-scaffold / advance) so each leg's flightplan is planned just-in-time after the previous leg lands

relay is a single portable skill:

Skill	Description
relay	Delegate a task to another harness's CLI (codex / opencode / claude): delegate (do work), review (analysis only), or image (codex only) — capture the result, smart-apply when safe, and report back

chronicle bundles four skills:

Skill	Description
commit	Craft git commit(s) for the current changes — auto-decides between one simple commit and an atomic split
pr	Open a reviewer-legible PR/MR for the current branch, enriched by the cockpit decision trail when present
release	Cut a release — bump version files, write the CHANGELOG entry, then commit, merge, tag, and push; local stops before the push, prepare after the entry
install	Set up chronicle's prerequisites — the named agent roles on Codex (Claude Code needs none)

herdr is a single skill:

Skill	Description
herdr	Reference for the Herdr terminal workspace manager (config, CLI, plugin dev) plus a typed herd wrapper to spawn and drive agents in sibling panes when running inside herdr

Claude Code Installation

CLI

claude plugins marketplace add FunnyQ/cc-plugins
claude plugins install monitor@q-lab-marketplace
# Any of these plugin ids works: monitor, dispatch, relay, chronicle, herdr

TUI

1. Open Claude Code
2. Type /plugins to open the plugin manager
3. Select Add Marketplace → enter FunnyQ/cc-plugins
4. Select Install Plugin → choose the plugin you want

The usage-dashboard skill runs a prerequisite check automatically before launching the dashboard, so there's no manual setup step. If something is missing, the hint is surfaced in the terminal. The most common case is stats-cache.json not existing yet; run /stats once in Claude Code to seed it.

If you want to run the precheck yourself:

bun $CLAUDE_PLUGIN_ROOT/skills/install/scripts/install.ts

Codex Installation

Codex reads this marketplace from .agents/plugins/marketplace.json. The registry lists all five plugins, and each is installed by id.

codex plugin marketplace add FunnyQ/cc-plugins
codex plugin add monitor@q-lab-marketplace
# Any of these plugin ids works: monitor, dispatch, relay, chronicle, herdr

Check the install:

codex plugin list | rg 'q-lab-marketplace|monitor'

After installing a Codex plugin, start a new Codex session so the skill list is refreshed.

OpenCode Installation

There is no plugin registry step. The repo is the single source of truth: opencode/install.ts symlinks skills, agents, commands, and the plugin module straight into ~/.config/opencode/, so an update to the checkout is live immediately — no reinstall, no rebuild.

Requires OpenCode 1.x. The plugin module targets OpenCode's V1 plugin API. OpenCode 2.x replaced that API, so on 2.x the module fails to load and none of its hooks run. The cockpit send and relay's opencode backend also support 1.x only.

bun opencode/install.ts --check     # report what is and is not wired
bun opencode/install.ts --apply     # symlink everything, raise subagent_depth
bun opencode/install.ts --unlink    # remove only what --apply created

--dry-run also exists — it prints the same plan as --apply without writing anything.

--apply installs:

Installs	Count	Target
Skills	15	~/.config/opencode/skills/<name>/
Plugin module	1	~/.config/opencode/plugin/q-lab.ts
Chronicle agents	6	~/.config/opencode/agents/<name>.md
Commands	2	~/.config/opencode/commands/<name>.md
subagent_depth	1 edit	~/.config/opencode/opencode.json

The subagent_depth prerequisite. --apply raises subagent_depth to at least 2 in ~/.config/opencode/opencode.json, the one config file it touches outside symlinks. The edit is raise-only — every other key in that file is preserved, and a value already ≥ 2 is left alone. OpenCode ships defaulting subagent_depth to 1, which blocks nesting outright, so this isn't a hypothetical edge case — it's the shipped default. Chronicle no longer needs it — none of its agents spawns a child — but dispatch's autopilot does: below the required depth its driver simply stops mid-run with no error naming the config, and the failure reads exactly like a plugin bug. Anyone hand-editing opencode.json instead of running --apply needs to set this key to 2 themselves.

Which config file gets the edit. OpenCode merges three global config names in order — config.json, then opencode.json, then opencode.jsonc — so the last one present wins. The installer patches whichever of those already exists, highest precedence first, and creates opencode.json only when none does. Two consequences: an existing opencode.jsonc is the file that gets raised, and a config carrying comments is read but never rewritten, because re-serializing it would delete them — --check and --apply report manual and print the line to add by hand.

Works under OpenCode:

• All 15 skills, discovered from ~/.config/opencode/skills/.
• usage-dashboard reads OpenCode data natively — the shared reader already handles ~/.local/share/opencode/opencode.db.
• cockpit reads and sends for OpenCode sessions. Precondition: the OpenCode TUI must have been started with a port (opencode --port <n>), or OPENCODE_TUI_SERVER_URL must be set before cockpit starts.
• relay delegate and review.
• The five ported hook behaviors: decision-log start, the scribe nudge, the chronicle branch guard, the dispatch flightplan lint, and the guard comment check.
• Both monitor commands.
• Chronicle's subagents, spawned through the task tool.

Does not work under OpenCode:

• The statusline. It is a Claude-only concept with no OpenCode equivalent, and there is no plan for one.
• relay image — codex-only, and it fails at the capability gate before any CLI runs.
• Workflow-driven autopilot. There is no Workflow tool, so autopilot runs as a manual task-tool wave loop instead: behaviorally close, but with no automatic parallel-wave scheduling.
• monitor's setup.ts --session-check. It is deliberately not ported because it is inert outside Claude Code — it returns immediately without CLAUDE_PLUGIN_DATA, and its actual work is statusline-path migration and reaping orphaned Claude processes.

usage-dashboard

A single-page dashboard that reads local ~/.claude/ and ~/.codex/ data and visualizes usage in a browser. No telemetry, no cloud; everything stays on your machine.

Features

• Live now (Claude + Codex) — a panel of your currently-active Claude and Codex sessions with live status; click one to open it in cockpit's live transcript view (token-atlas links out rather than rendering transcripts itself). When cockpit's daemon isn't running the panel says so and the rows stay inert, so a click never opens a dead tab
• Cost + usage overview — sessions, interactions, tokens, estimated spend, daily burn, and monthly budget projection
• Persistent history — Claude usage is rolled into a local SQLite store (~/.local/share/q-lab/token-atlas/), so your token/cost/model history survives Claude Code's automatic transcript cleanup (cleanupPeriodDays) instead of disappearing as old sessions age out
• Model analysis — daily trend, model distribution, and per-model token/cost breakdown
• Project insights — project rankings with drilldown details for model mix and cost
• Session ledger — recent Claude and Codex sessions side by side
• Anomaly detection — flags days that break from your recent baseline
• Token composition — input, output, cache-read, cache-write, and reasoning token shares
• Activity timeline — hourly and daily activity patterns from local session data
• Data health diagnostics — non-fatal source-read failures and record counts
• Filters + export — provider/range filters, persisted preferences, and JSON/CSV export

Prerequisites

• At least one Claude Code session (the cockpit shim fetches its release binary on first run)
• For Claude usage totals, run /stats once to seed stats-cache.json

Quick Start

packages/monitor/skills/cockpit/bin/cockpit atlas serve   # [--port N] [--no-open]

As JSON instead: cockpit atlas stats (dashboard data), cockpit atlas live (active sessions), cockpit atlas rollup-update [--rebuild] (rollup DB).

Opens http://localhost:5938 in your default browser.

Options

--port <n>    Use a different port (default: 5938)
--no-open     Don't auto-open browser

Pricing

Token costs are estimated using bundled defaults (references/pricing-defaults.json). On startup, live prices are fetched from OpenRouter (3s timeout, silent fail). You can override with a custom file:

~/.config/cc-dashboard/pricing.json

{
  "models": {
    "claude-opus-4-7": { "input": 5.00, "output": 25.00, "cacheRead": 0.50, "cacheWrite": 6.25 }
  }
}

cockpit

Cockpit is a per-project dashboard and skill for active work. Start with a session goal, keep a distilled decision log, stream the current Claude Code or Codex transcript, and park on needs_your_call so a button click in the dashboard wakes the session.

Quick Start

In Claude Code or Codex, invoke the cockpit skill and confirm the proposed goals. From a development checkout, the dashboard can also be started directly:

packages/monitor/skills/cockpit/bin/cockpit server

Opens http://localhost:5858 in your default browser.

Provider Support

• Claude Code transcripts resolve from ~/.claude/projects/**/<session>.jsonl.
• Codex transcripts resolve from ~/.codex/state_5.sqlite thread rows and rollout files under ~/.codex/sessions.
• OpenCode transcripts resolve via the opencode provider in packages/monitor/cockpit-rs/src/server/transcript.rs, reading the same ~/.local/share/opencode/opencode.db the usage-dashboard uses.
• Decision logs live per-project under .cockpit/; the registry and wait/send bridge are shared through ~/.local/share/q-lab/cockpit/.

Send box

The send box at the bottom of the Decision Log column can send text into a running session.

• Claude Code uses the monitor mod's inbox poll, described below. The agent's answer comes back through the live transcript.
• Codex uses the managed Codex remote-control daemon. Cockpit connects to the local app-server control socket, resumes the selected thread, and submits or steers a turn. Direct app-server is only a fallback when remote-control is unavailable.
• OpenCode uses the TUI HTTP bridge, not the mod: it discovers the running TUI from OPENCODE_TUI_SERVER_URL (or a ps scan for opencode --port <n>) and delivers through /tui/append-prompt + /tui/submit-prompt. Same port precondition as the OpenCode Installation section above — the TUI must have been started with --port; a serve process is not discovered, and a successful send is not a delivery receipt.

A monitor mod (hooks/register.ts) delivers Claude Code sends. On session start it long-polls the cockpit daemon's inbox over HTTP and submits each message as a new turn once the session is idle. The same mod relays permission dialogs to the dashboard. It needs a Claude Code build with function-hook mods, and a plain claude session gets both:

claude

If an older version left a hand-wired cockpit-channel entry in ~/.claude.json, /monitor:install removes it. See the cockpit skill for the full setup.

For Codex send support, install and enable the managed standalone Codex remote-control daemon:

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex app-server daemon enable-remote-control

Cockpit checks /api/codex-control/status before enabling the Codex send box, so stale or non-resumable threads stay disabled instead of failing only after send.

dispatch

Interview-driven planning you can execute. Four skills form one arc — capture what you want, gather the spec, commit a blueprint to disk, then fly it with a multi-agent quality loop — and a fifth, waypoints, sits above it for whole-project rolling-wave planning.

• preflight — a short interview that captures what you want as docs/<slug>/INTENT.md, before anyone decides how to build it. Writes one file and stops; never executes.
• hop — a lightweight interview that produces a single in-conversation plan and executes it. Best when you'll execute now, in one session. Formerly named preflight.
• flightplan — a thorough interview that writes docs/<slug>/PLAN.md plus a tasks/ tree of self-contained task files (each with its own ## Eval rubric). Best when the work spans sessions or hands off to sub-agents.
• autopilot — executes that tree in waves. Each wave re-scouts the ready set (next-ready) and runs those tasks in parallel; for each task it runs Dev → an independent binary gate (re-runs the task's Verification) → a rubric judge → a deterministic score gate, retrying until the task passes its rubric. Between waves it makes an atomic commit of the completed work, so the run leaves a clean per-wave history rather than one giant diff. The Final review task depends transitively on every other task, so the wave loop naturally schedules it last as the whole-tree gate — a closing multi-lens review round (cross-vendor codex + four /simplify lenses → an Opus fixer), followed by a final commit of its fixes. Every verdict lands in a self-gitignored docs/<slug>/.flightlog/ audit trail (RUNLOG.md).
• waypoints — the tier above flightplan for large builds. It writes only a milestone roadmap (docs/<proj>/WAYPOINTS.md, legs tracked with [x]/[~]/[ ]); each leg's detailed flightplan is generated just-in-time after the previous leg lands, so every plan starts from what actually shipped rather than one oversized up-front guess. A waypoints.ts CLI collapses the lifecycle into three verbs — active (rolling-wave digest), leg-scaffold (nest a leg's tree under docs/<proj>/legs/NN-slug/), and advance (land the active leg; writing requires --outcome as the confirmation gate). flightplan gains a narrow waypoint mode that plans one leg at a time. Human-in-loop by design — one leg lands before the next is planned.

Installation

# Claude Code
claude plugins install dispatch@q-lab-marketplace

# Codex
codex plugin add dispatch@q-lab-marketplace

# OpenCode
bun opencode/install.ts --apply

(Add the marketplace first if you haven't — see the monitor install steps above.)

relay

One portable skill that delegates a task out to another harness's CLI, then captures the output and reports back — a multi-backend generalization of the codex-only odin-codex skill.

/relay <codex|opencode|claude> delegate <task>
/relay <codex|opencode|claude> review [task]
/relay codex image <prompt> --out <path>

• delegate — ask a backend to do something (implement, refactor, debug); smart-applied when safe.
• review — analysis only, no edits. No task reviews uncommitted changes; a provided task is followed as written.
• image — generate an image via codex (gpt-image-2). codex-only; opencode/claude fail fast at the capability gate.

A capability gate rejects unsupported (backend, mode) pairs before any CLI runs. Every run captures full output to /tmp/relay/<ts>/last.md and prints it. Models resolve by precedence: --model flag > config file (~/.config/q-lab/cc-plugins/relay/config.json) > built-in defaults. Per-CLI invocation details, headless output handling, and the OpenCode symlink install live in the backend reference.

Live-pane mode — inside herdr (HERDR_ENV=1), delegate/review automatically run the backend's interactive TUI in a visible, take-over-able pane opened in its own new tab (so your working pane keeps its full size), via the herdr plugin's herd.ts, dynamically imported — no hard dependency. The answer is captured through a result-file contract; stdout stays the clean answer, live metadata rides stderr. --dangerous makes it a YOLO / unattended run (auto-approves permissions: codex/claude bypass flags, opencode --auto); without it, approval prompts surface in the pane for a human to answer. A run that outlives --wait-timeout (default 10 min) exits 0 with a "still running" report and leaves the pane alive. --headless opts out; outside herdr the classic headless flow is unchanged.

Installation

# Claude Code
claude plugins install relay@q-lab-marketplace

# Codex
codex plugin add relay@q-lab-marketplace

# OpenCode
bun opencode/install.ts --apply

If you previously ran the old manual symlink (ln -s .../packages/relay/skills/relay ~/.claude/skills/relay), remove it. opencode/install.ts --apply installs relay under ~/.config/opencode/skills/, and OpenCode scans ~/.claude/skills/ as well — leaving the old symlink in place surfaces two skills both named relay. --check warns about it.

chronicle

Chronicle authors your git history — what a commit says, what a pull request argues, and what a release ships. A thin SKILL.md sends the bulky reading to an agent — a diff, a branch, a range of commits — and keeps the decisions where you can see them. Diff-reading and git output stay out of your conversation.

• commit — one agent reads the changeset, cuts it into commits that each build on their own, and writes the messages; a script decides whether the split is worth keeping and does the staging. Pass simple to force one commit.
• pr — reads the branch, harvests the cockpit decision trail when one exists, and opens a GitHub PR or GitLab MR with a title, a four-section body, and an optional Mermaid overview diagram. The trail is an enrichment, not a requirement; an unrecognized remote stops the flow rather than guessing.
• release — config-first: detects whole-repo vs per-component layout, remembers it in a committed .chronicle/release.json, then bumps the version files and writes the CHANGELOG entry, commits, tags, and pushes. Pass local to stop before the push, or prepare to stop after the entry.
• install — sets up each harness's prerequisite: on Claude Code the nested-subagent spawn-depth setting described in the Plugins section above, on Codex the named agent roles the orchestrators are addressed by.

Installation

# Claude Code
claude plugins install chronicle@q-lab-marketplace

# Codex
codex plugin add chronicle@q-lab-marketplace

# OpenCode
bun opencode/install.ts --apply

herdr

Reference and in-session agent orchestration for Herdr, a terminal workspace manager with workspaces, tabs, split panes, and agent detection. Two halves:

• Reference — a knowledge skill that answers questions about Herdr's config.toml, CLI, keybindings, and plugin development. Detail lives in references/; the skill reads only the relevant file.
• herd wrapper — a typed Bun wrapper (scripts/herd.ts) over the raw herdr CLI, for when you (an agent) are running inside a herdr pane (HERDR_ENV=1) and want to spawn and drive other agents in sibling panes or their own tabs (spawn --new-tab). It collapses herdr's multi-step recipes into seven verbs and handles the sharp edges: it addresses agents by a collision-resistant generated name (pane ids renumber), its send writes the prompt and presses Enter (raw agent send only writes literal text), its keys verb sends bare key chords (submit / clear the input box), and its read defaults to the visible screen (agent TUIs leave scrollback empty).

HERD="$CLAUDE_PLUGIN_ROOT/skills/herdr/scripts/herd.ts"   # or the skill's load-time base dir

bun "$HERD" spawn reviewer --agent codex --task "review the diff in src/api/"
bun "$HERD" send reviewer-a3f9 "now check error handling"
bun "$HERD" wait reviewer-a3f9 --status idle --time