ContextLedger

Capture session context. Resume with intent.

ContextLedger is a local-first CLI for tracking AI-assisted work across coding agents and carrying useful context into the next session.

Quickstart

Install globally from npm:

npm install -g context-ledger

Then run:

# One-command onboarding (recommended)
ctx-ledger onboard

onboard defaults:

• turns prompt capture on
• enables Claude + Codex integrations
• runs initial sync
• launches dashboard in the background (default port 4173, auto-fallback if busy)

You can handoff sesssions across different agents as well

# Analyze and generate memory handoff
ctx-ledger handoff --agent claude --from latest --no-launch --out ./handoff.md

Works from the web dashboard too!

Stack

• TypeScript + Node.js
• SQLite (better-sqlite3)
• Commander CLI

Integrations

Claude

ctx-ledger enable claude installs async command hooks into Claude settings.

It also performs a one-time backfill from local Claude session logs so existing sessions are available immediately after setup.

• User scope (default): ~/.claude/settings.json
• Project scope: .claude/settings.local.json
• Backfill source: ~/.claude/projects/**/*.jsonl (customizable via --projects-path)

Captured events:

• SessionStart
• UserPromptSubmit
• PreToolUse
• PostToolUse
• Stop
• SessionEnd

Codex

ctx-ledger enable codex enables incremental ingestion from Codex session rollouts.

• Primary source (rich events): ~/.codex/sessions/**/rollout-*.jsonl
• Fallback source: ~/.codex/history.jsonl when rollout files are unavailable
• Custom sources:
  • ctx-ledger enable codex --sessions-path /path/to/.codex/sessions
  • ctx-ledger enable codex --history-path /path/to/history.jsonl

Gemini

ctx-ledger enable gemini enables incremental ingestion from Gemini history JSONL.

• Default source: ~/.gemini/history.jsonl
• Custom source: ctx-ledger enable gemini --history-path /path/to/history.jsonl

Sync

ctx-ledger sync all
ctx-ledger sync claude
ctx-ledger sync codex
ctx-ledger sync gemini
# Optional for codex:
ctx-ledger sync codex --sessions-path /path/to/.codex/sessions
# Optional for claude:
ctx-ledger sync claude --projects-path /path/to/.claude/projects --force

stats, summarize, resume, handoff, and dashboard automatically run sync for enabled integrations.
For Claude, this automatic sync runs the one-time backfill (if pending) and then ongoing capture continues via hooks.

Privacy & Redaction

Configure privacy settings:

ctx-ledger configure privacy \
  --capture-prompts on \
  --redact-secrets on \
  --redact-emails on \
  --allow-remote-prompt-transfer off

Defaults:

• capturePrompts: off
• redactSecrets: on
• redactEmails: off
• allowRemotePromptTransfer: off

Custom regex redaction patterns:

ctx-ledger configure privacy --add-redaction-pattern "my-secret-pattern"

Summarizer Configuration

Ollama (local)

ctx-ledger configure summarizer --provider ollama --model llama3.1

OpenAI

ctx-ledger configure summarizer --provider openai --model gpt-4.1-mini
export OPENAI_API_KEY=...

Anthropic

ctx-ledger configure summarizer --provider anthropic --model claude-3-7-sonnet-latest
export ANTHROPIC_API_KEY=...

If remote prompt transfer is disabled, captured prompt samples are excluded from remote summarizer requests.

Stats

ctx-ledger stats --range 7d
ctx-ledger stats --range 30d --group-by tool
ctx-ledger stats --range all --format json
ctx-ledger stats --range all --group-by agent --agent claude
ctx-ledger stats --range all --group-by phase
ctx-ledger stats --range all --group-by project

Supported groups:

• intent
• tool
• agent
• day
• phase (planning vs execution)
• project (working directory / repo path)
• all

summary now includes planningMinutes and executionMinutes alongside totalMinutes.

Agent filter values:

• claude
• codex
• gemini

Summaries

ctx-ledger summarize --session latest
ctx-ledger summarize --pending --limit 20

This stores:

• capsules (session summary, outcomes, files/commands/errors/todos, activity timeline, handoff notes, session facts)
• intent_labels (primary intent + confidence)
• task_breakdowns (estimated time split)

Intent labels support granular paths. Examples:

• coding
• coding/frontend
• coding/frontend/design
• research
• research/tech-qna
• sql, deploy, incident, docs, other

Automatic behavior:

• Claude sessions auto-summarize on Stop (turn-level) and SessionEnd hook events.
• Codex sessions auto-summarize after Codex turn completion (task_complete) is imported.
• Gemini sessions auto-summarize after sync imports new events.
• summarize remains available as a manual/force command.

Resume Packs

ctx-ledger resume --from latest --budget 2000
ctx-ledger resume --from session-a --from session-b --format json
ctx-ledger resume --from latest --out ./resume.md

resume builds a handoff document for your next session by combining saved capsule data (summary/outcomes/todos/files/commands/errors/activity/handoff-notes/session-facts), task breakdowns, and captured prompt samples when available.

Stored in resume_packs.
List saved packs:

ctx-ledger resume-packs

Agent Handoff

Start a coding agent with verify-first context injected from stored session data:

ctx-ledger handoff --agent claude --from latest
ctx-ledger handoff --agent codex --from latest --from session-a

Generate only (without launching an agent):

ctx-ledger handoff --agent claude --from latest --no-launch --format markdown --out ./handoff.md
ctx-ledger handoff --agent codex --from latest --no-launch --format json

Dashboard

ctx-ledger dashboard --port 4173

Open:

• http://127.0.0.1:4173/
• API: /api/stats, /api/sessions, /api/resume-packs, /healthz
• Optional API filter: ?agent=claude|codex on /api/stats and /api/sessions
• UI includes planning vs execution and project-time breakdowns, plus project path in recent sessions
• Dashboard auto-refreshes every 3s and keeps syncing enabled integrations in the background

End-to-End Tests

Real Claude capture test (requires authenticated Claude CLI):

npm run test:e2e:claude-capture

Full workflow test (stats + summarize + resume + dashboard + codex/gemini sync with fixtures):

npm run test:e2e:full

Keep temporary artifacts for inspection:

npm run test:e2e:full -- --keep-artifacts

Commands

• ctx-ledger enable <claude|codex|gemini>
• ctx-ledger sync <claude|codex|gemini|all>
• ctx-ledger configure summarizer
• ctx-ledger configure privacy
• ctx-ledger configure show
• ctx-ledger summarize
• ctx-ledger resume
• ctx-ledger handoff
• ctx-ledger resume-packs
• ctx-ledger stats
• ctx-ledger dashboard
• ctx-ledger doctor

Data Path

Default data directory:

~/.context-ledger

Default database:

~/.context-ledger/context-ledger.db

Override with:

--data-dir <path>