convez.ai
MCP Server
MatthewDegtyar

claude-project-history

MatthewDegtyar/claude-project-history

Ver no GitHub
InicialPluginScore · de 0 a 100

Invisible project intelligence for Claude Code — local-first MCP server tracking workflows, tasks, blockers, and architectural decisions. Zero cloud, zero Docker.

Instalação

$npx convez-ai MatthewDegtyar/claude-project-history

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Claude Project History MCP 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)

ToolWhen
cph_session_initStart of every session — auto via CLAUDE.md
cph_detect_workflowWhen on a new branch with no workflow yet
cph_set_depthOnce, to set your preferred context depth
cph_statusTo verify the plugin is working

Workflows

ToolDescription
cph_workflow_createCreate workflow — do this once per project/branch
cph_workflow_listList all workflows
cph_workflow_summaryTask counts, blocker count, estimation accuracy
cph_workflow_updateUpdate name, status, branch pattern

Tasks

ToolWhen
cph_task_createBefore starting any discrete piece of work
cph_task_startImmediately after create — sets status + start time
cph_task_completeWhen done — provide actual_minutes
cph_task_getFull details including subtasks + blockers
cph_task_listList tasks (paginated, summaries only)
cph_task_updateUpdate title/description/priority

Blockers

ToolWhen
cph_blocker_createImmediately when blocked — before asking for help
cph_blocker_resolveWhen unblocked — always provide resolution text
cph_blocker_escalateWhen blocker needs urgent human attention
cph_blocker_listList open/resolved blockers

Decisions

ToolWhen
cph_decision_recordWhen choosing between approaches
cph_decision_searchBefore any architectural choice
cph_decision_getFull details on a specific decision
cph_decision_listList decisions (summaries only)
cph_decision_attach_commitCalled 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
Ver o original no GitHub

Bom para

Relacionados