Claude Project History Server

Invisible project intelligence for Claude Code. Tracks workflows, tasks, blockers, and decisions locally. Zero Docker. Zero cloud. Just works.

Data lives in PGlite (Postgres WASM) at ~/.cph/db.

---

Install

git clone https://github.com/the-occom/occom-claude-project-history.git
cd occom-claude-project-history
npm install
npm run build
npm run install-hooks   # wires hooks + daemon + .mcp.json + CLAUDE.md

Register with Claude Code

Daemon mode (recommended)

The install script starts a background daemon and writes .mcp.json automatically:

{
  "mcpServers": {
    "cph": {
      "url": "http://localhost:3741/sse"
    }
  }
}

All Claude Code instances share one daemon process with atomic writes.

Stdio mode (single-session fallback)

{
  "mcpServers": {
    "cph": {
      "command": "node",
      "args": ["/absolute/path/to/occom-claude-project-history/dist/index.js"]
    }
  }
}

Or via npx:

{
  "mcpServers": {
    "cph": {
      "command": "npx",
      "args": ["github:the-occom/occom-claude-project-history"]
    }
  }
}

---

Daemon

A long-lived background process that owns the PGlite database. All MCP clients connect via HTTP/SSE.

npm run daemon:start     # spawn detached, write PID+port
npm run daemon:stop      # kill by PID, clean up state files
npm run daemon:status    # print running/stopped + port
npm run daemon:restart   # stop + start
node scripts/daemon.js ensure   # start only if not running (used by hooks)

State files live at ~/.cph/:

• daemon.pid — PID of running daemon
• daemon.port — port (default 3741, scans to 3751 if busy)
• daemon.log — stdout/stderr

The first Claude Code hook invocation of the day auto-starts the daemon.

---

How it works

You do nothing. Claude Code does everything.

At session start, Claude Code calls cph_session_init automatically (via CLAUDE.md). It gets back a minimal context — active tasks, open blockers, relevant decisions — under 600 tokens. Then it works. Tasks, blockers, and decisions are recorded silently as side effects.

The hook system enforces this:

• PreToolUse on Write/Edit/MultiEdit — blocks file writes if no active task
• Stop — surfaces incomplete tasks and open blockers at session end
• post-commit git hook — silently links commits to recent decisions

Atomic writes

State-changing tools (task_start, task_complete, task_cancel, blocker_resolve, blocker_escalate) use SELECT ... FOR UPDATE row locks inside transactions. Safe for concurrent access from multiple Claude Code sessions.

---

Tools

Session (call these)

Tool	When
cph_session_init	Start of every session — auto via CLAUDE.md
cph_detect_workflow	When on a new branch with no workflow yet
cph_set_depth	Once, to set your preferred context depth
cph_status	To verify the plugin is working

Workflows

Tool	Description
cph_workflow_create	Create workflow — do this once per project/branch
cph_workflow_list	List all workflows
cph_workflow_summary	Task counts, blocker count, estimation accuracy
cph_workflow_update	Update name, status, branch pattern

Tasks

Tool	When
cph_task_create	Before starting any discrete piece of work
cph_task_start	Immediately after create — sets status + start time
cph_task_complete	When done — provide actual_minutes
cph_task_get	Full details including subtasks + blockers
cph_task_list	List tasks (paginated, summaries only)
cph_task_update	Update title/description/priority

Blockers

Tool	When
cph_blocker_create	Immediately when blocked — before asking for help
cph_blocker_resolve	When unblocked — always provide resolution text
cph_blocker_escalate	When blocker needs urgent human attention
cph_blocker_list	List open/resolved blockers

Decisions

Tool	When
cph_decision_record	When choosing between approaches
cph_decision_search	Before any architectural choice
cph_decision_get	Full details on a specific decision
cph_decision_list	List decisions (summaries only)
cph_decision_attach_commit	Called by git hook automatically

---

Context depth

Set once per engineer, remembered forever:

minimal  = active tasks + open blockers (~300 tokens)
standard = + relevant decisions (~600 tokens) ← default
deep     = + teammate activity (~1200 tokens)

# In Claude Code:
cph_set_depth with depth="minimal"

---

Retrieval design

Lists return IDs + titles only. Full content requires a specific ID lookup. This is intentional — prevents context flood on large projects.

Pattern for using decisions:

1. cph_decision_search with keyword — get IDs
2. cph_decision_get with specific ID — get full record

Never load all decisions. Pull what you need.

---

Data

~/.cph/db/           ← PGlite database
~/.cph/daemon.pid    ← daemon process ID
~/.cph/daemon.port   ← daemon port
~/.cph/daemon.log    ← daemon logs
.cph-workflow        ← current project's workflow ID (gitignored)

Compression runs automatically at session end:

• Decisions > 30 days: rationale/alternatives discarded, title+decision kept
• Completed tasks > 7 days: description discarded, timing data kept
• Resolved blockers > 7 days: description discarded, title+resolution kept

---

Contributing

After editing TypeScript files in src/, always rebuild before testing:

npm run build

The daemon runs from dist/, not src/. If you skip the build step, your changes won't take effect and you may get confusing version-mismatch restarts.

---

What's deliberately NOT here

• No GraphQL — direct PGlite queries until multi-user sync is needed
• No cloud sync — single-user local only; team sync is the paid tier
• No ML inference — estimation intelligence is server-side (paid tier)
• No semantic search — structural matching only; local LLM is enterprise tier
• No auth — local tool, no auth needed