Skip to content
yee94Public

About

Centralize every AI coding conversation — Codex on one machine, Claude Code on another — into a single place for analysis, search, and cost insight.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Runmark

TypeScript MIT License npm version npm downloads CI Bun

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.

中文 · MIT License

✨ Features

  • 📡 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.sh handles service install, auth, and client configuration; the Dashboard ships a built-in help center.
Overview
Overview
Session list
Session list
Session summary
Session summary
Matter archive
Matter archive

Architecture

[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]

Quick Start

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

1. Deploy the server

Recommended: let an AI do it for you

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)

Deploy the service

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/health

A {"status":"ok",...} response means it works.

Local development

git clone https://github.com/yee94/runmark.git
cd runmark
./setup.sh

Or manually:

bun install
cd packages/server
bun dev

Dashboard: http://localhost:3456/. The script is idempotent — rerunning never overwrites existing config.

Server updates and database migrations

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.

2. Install clients

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.

Option A: let an AI read the Skill (recommended)

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

Option B: manual install

  1. 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
  1. 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 --uninstall

If npx @runmarks/runmark reports command not found, use:

npx -p @runmarks/runmark runmark
# or: bunx @runmarks/runmark
  1. 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.

  2. 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).

3. Configure magpie or any OTLP tool

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.

Development

bun install
bun test

Key packages:

  • packages/runmark — unified install entry point @runmarks/runmark
  • packages/server — Bun + Hono + SQLite server and Dashboard
  • packages/plugin-opencode — OpenCode plugin
  • packages/plugin-codex — Codex hook plugin
  • packages/plugin-claude-compat — Plugin Marketplace package for Claude Code / CodeBuddy / WorkBuddy (product selected via --runtime; idempotent npx upgrades)
  • packages/plugin-grok — Grok Build user-level hooks plugin (~/.grok/hooks, reads local sessions on Stop)
  • packages/hook-cursor — Cursor hook
  • shared — shared types, pricing, and utilities
  • skills/agent-tracker-setup / skills/agent-tracker-clients — server deploy / client install skills

License

MIT

About

Centralize every AI coding conversation — Codex on one machine, Claude Code on another — into a single place for analysis, search, and cost insight.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages