Runmark — Centralize every AI coding conversation — from Codex on one machine, Claude Code on another — into a single place for analysis, search, and cost insight.
- 📡 Unified collection & review — Aggregates sessions from Cursor, OpenCode, Codex, Claude Code, CodeBuddy, WorkBuddy, Grok Build and other AI coding clients into one place. Review usage, cost, and full conversation content across all your machines.
- 📝 AI-powered summaries — Automatically summarizes your AI conversations, so you can quickly see what was done and keep handoff notes up to date.
- 🔗 Open API & SDK — Standard ingest and query APIs let you plug Runmark into any agent or automation workflow.
- 📊 Usage & cost insight — Aggregates tokens, cost, model, and client distribution over today / this week / this month windows, so you always know where the money goes.
- 📋 Matter archive — Persists work outcomes and handoff-able items across sessions. Focus on "what was done" instead of scrolling through sessions.
- 🧠 Layered memory — Keep preferences and decisions per global / project scope, shared across machines, with optional named-Agent memories. A short index for discovery, details read on demand; see Memory.
- 🔍 Call-chain tracing — A dense trace view that walks back through the messages, reasoning turns, and tool calls of a single conversation.
- 💰 Cursor billing sync — Integrates the Cursor Usage API and reconciles it against local telemetry for an official billing perspective.
- 🤖 Configurable agents — Custom triggers (throttle on new conversations, scheduled CRON) run background jobs like summary and archiving automatically.
- 🚀 One-command deploy —
setup.shhandles service install, auth, and client configuration; the Dashboard ships a built-in help center.
Overview |
Session list |
Session summary |
Matter archive |
[Cursor Hook] ─┐
[OpenCode Plugin] ─┤
[Codex Hook Plugin] ─┤
[Claude Code Plugin] ─┼─ POST /v1/ingest ─▶ [Runmark Server] ─▶ [Dashboard]
[CodeBuddy Plugin] ─┤
[WorkBuddy Plugin] ─┤
[Grok Build Hooks] ─┘
[magpie / OTLP tool] ── POST /v1/traces ─▶ [Runmark Server]
Two steps: deploy the server first, then install the client plugins on each machine, or point an OTLP tool such as magpie at the server. Per-product instructions and troubleshooting live in the Dashboard help center: http://<server-address>:3456/#/help.
| Path | Where to start |
|---|---|
| Cursor / OpenCode / Codex / Claude Code / CodeBuddy / WorkBuddy / Grok Build | Install clients |
| magpie / OTLP tools | Configure magpie and other OTLP tools — no Runmark plugin needed |
Paste the prompt below into Cursor / OpenCode / Codex (or any agent), filling in your SSH command or local path:
Please deploy Runmark for me.
Target environment:
- This machine / remote server (if remote, give the SSH connection command)
Strictly follow skills/agent-tracker-setup/SKILL.md in this repo:
1. If remote, SSH into the target machine first
2. Run ./setup.sh --server per the "Server deployment" section
3. Verify /health with curl
4. Report back the Dashboard URL, API Key, and help center URL
Do not install client plugins on this machine; after deployment point me to the Dashboard help center or the README "Install clients" section.
Skill: skills/agent-tracker-setup/SKILL.md
Docker deployment is also supported. Image build, volumes, env vars, and upgrade flow: see Docker deployment guide.
Manual server deployment (expand)
On the target machine:
git clone https://github.com/yee94/runmark.git /opt/agent-tracker
cd /opt/agent-tracker
./setup.sh --server--server performs: preflight checks → install dependencies → init SQLite → generate .env → register systemd → start the service.
The terminal prints the Dashboard URL and API Key (which also acts as the login password). Verify:
curl http://<server-address>:3456/healthA {"status":"ok",...} response means it works.
git clone https://github.com/yee94/runmark.git
cd runmark
./setup.shOr manually:
bun install
cd packages/server
bun devDashboard: http://localhost:3456/. The script is idempotent — rerunning never overwrites existing config.
After updating the server code or package, restart the service to migrate the existing database automatically; no manual SQL is required. Startup adds missing columns and indexes with CREATE INDEX IF NOT EXISTS, including the four composite indexes used by session lists and details. Repeated startup is safe. The performance upgrade does not change historical records, costs, or usage. Building indexes on a large database may extend the first startup; wait for the health check to recover.
Monthly large-payload storage requires the updated external updater for automatic migration; replacing only the server package does not update that script. Direct deployments can migrate explicitly. Back up the main database and its monthly files together, and inline all payloads before downgrading to an older server. See the storage and rollback guide.
Once the server is up, install the plugins on each machine: Cursor / OpenCode / Codex / Claude Code / CodeBuddy / WorkBuddy / Grok Build. The unified entry point is the @runmarks/runmark package.
Paste this prompt into your local agent (Cursor / OpenCode / Codex etc.), filling in your Dashboard address and API Key:
Please install the Runmark client plugins on this machine.
Server:
- Dashboard / endpoint: http://<server-address>:3456
- API Key: <server API key>
Strictly follow skills/agent-tracker-clients/SKILL.md in this repo:
1. List the available clients (Cursor / OpenCode / Codex / Claude Code / CodeBuddy / WorkBuddy / Grok Build) and let me pick; do not default to all
2. Write or verify ~/.config/runmark/env (RUNMARK_ENDPOINT + RUNMARK_API_KEY)
3. Install via the unified entry: npx @runmarks/runmark --clients <my selection>
4. Tell me which clients need a restart and how to verify on the Dashboard
Skill: skills/agent-tracker-clients/SKILL.md
- Write the unified config (required for new installs; if the file exists, verify — don't blindly overwrite):
mkdir -p ~/.config/runmark
cat > ~/.config/runmark/env << 'EOF'
export RUNMARK_ENDPOINT="http://<server-address>:3456"
export RUNMARK_API_KEY="<server API key>"
EOF- Install with the brand package:
# Interactive install (recommended): auto-detects; rerunning preselects and updates installed clients
npx @runmarks/runmark
# Update only installed Runmark clients (non-interactive)
npx @runmarks/runmark --clients installed
# or: npx @runmarks/runmark --yes
# Install everything / on demand
npx @runmarks/runmark --clients all
npx @runmarks/runmark --clients cursor,codex,workbuddy
# Uninstall example
npx @runmarks/runmark --clients codebuddy --uninstallIf npx @runmarks/runmark reports command not found, use:
npx -p @runmarks/runmark runmark
# or: bunx @runmarks/runmark-
Restart the installed clients (Claude / CodeBuddy / WorkBuddy support
/reload-plugins; Grok Build just needs a new session). If Codex / Claude-family prompts for trust, review and trust the Runmark plugin hooks in the app. -
Open the Dashboard sessions page and confirm
agent=cursor|opencode|codex|claude|codebuddy|workbuddy|grok.
Available clients: cursor · opencode · codex · claude · codebuddy · workbuddy · grok · all · installed · detected. With no arguments it auto-detects and prompts interactively (preselecting and updating what's already installed).
Open Dashboard → Help center → OTLP ingestion (magpie and others): http://<server-address>:3456/#/help/otlp. The page fills in the current server address and API key for you.
In magpie, open Settings → Observability and configure:
| Field | Value |
|---|---|
| Collector | OTLP |
| OTLP endpoint | Runmark root address, e.g. http://<server-address>:3456 |
| OTLP headers | X-API-Key=<your API key> |
| OTLP export | On |
| Trace agent conversations | Recommended: On |
| Request and response content | On if you want prompts and replies |
| Export metrics | Off (metrics are not shown yet) |
Other tools that need a full Traces URL use http://<server-address>:3456/v1/traces, pick the OTLP/HTTP JSON encoding, and send the X-API-Key header. The default Langfuse SDK setup (protobuf / Basic auth) is not supported.
After one new call, open the Dashboard sessions page and filter by the agent name reported by the tool. What you see depends on what the tool actually reports. See the user guide and the protocol notes.
bun install
bun testKey packages:
packages/runmark— unified install entry point@runmarks/runmarkpackages/server— Bun + Hono + SQLite server and Dashboardpackages/plugin-opencode— OpenCode pluginpackages/plugin-codex— Codex hook pluginpackages/plugin-claude-compat— Plugin Marketplace package for Claude Code / CodeBuddy / WorkBuddy (product selected via--runtime; idempotentnpxupgrades)packages/plugin-grok— Grok Build user-level hooks plugin (~/.grok/hooks, reads local sessions on Stop)packages/hook-cursor— Cursor hookshared— shared types, pricing, and utilitiesskills/agent-tracker-setup/skills/agent-tracker-clients— server deploy / client install skills




