🧠 claude-project

Project brain for Claude Code

Drop a .claude-project file in any directory to give Claude persistent memory, an event log, agent dispatch, automations, session hooks, and auto-generated CLAUDE.md.

Docs · npm · GitHub Packages · VS Code Marketplace · Discussions

---

What it does

Capability	What you get
Persistent memory	Structured .md files Claude reads at session start
Event log	Append-only JSONL log of every session, dispatch, and automation
Automation engine	Trigger actions on events, cron, file changes, or service health
Agent dispatch	Queue tasks for Claude agents — full tool loop, sandboxed to your project
Auto CLAUDE.md	Generated and refreshed automatically from your live project brain
Session hooks	Fire on SessionStart/Stop — sync Obsidian, log events, run automations
MCP server	Memory, journal, events, dispatch, registry, and Protocol Document tools
Project registry	Global ~/.claude/registry.json — instant lookup, no filesystem scans
Background daemon	macOS launchd — refreshes registry + fires scheduled automations every 5 min
VS Code extension	Status bar, syntax highlighting, schema validation, command palette
Research instrumentation	Every API call recorded to SQLite — tokens, latency, cache hit rate, task type
Protocol Documents	Content-addressed reusable instruction blocks with deduplication
Typed dispatch	Input encoded to typed_pseudocode, dsl, toon, or codeact by task type
Clarity Layer	Local Ollama pre-processor cleans and completes input — passthrough when unavailable
Prompt cache	Deterministic stable prefix with cache_control: ephemeral — 90% prefix cost reduction
Semantic memory	LanceDB vector store (384-dim embeddings) for find_related_files queries
Federated telemetry	Opt-in anonymous metrics → Cloudflare Worker → community threshold learning
Codespaces	Zero-setup dev environment: Claude Code + live API bridge + ablation runner

---

Install

# npm (recommended)
npm install -g claude-project

# GitHub Packages
npm install -g claude-project --registry https://npm.pkg.github.com

# VS Code extension — search "claudelab.claude-project"

Open in Codespaces — zero setup dev environment:

Codespaces automatically:

• Unlocks secrets via GIT_CRYPT_KEY_B64
• Installs Claude Code CLI + cloudflared
• Starts a live API bridge on port 3000 with a public trycloudflare.com URL
• Wires ~/.bashrc with cc, bridge-start/stop/url, ablate-* shortcuts
• Exposes VS Code tasks for ablation runner, bridge control, and build

Add ANTHROPIC_API_KEY and GIT_CRYPT_KEY_B64 in your Codespaces secrets to unlock the full environment.

---

Quick Start

# 1. Initialise a project
claude-project init "My Project" -d "What it does" -s "Planning"

# 2. Add MCP server to Claude Code (~/.mcp.json)
claude-project inject

# 3. Install session hooks
claude-project hooks install --global

# 4. Start the background daemon (macOS)
claude-project daemon install

# 5. Check status
claude-project status

---

CLI Reference

Core

claude-project init <name>                 # create .claude-project
claude-project status                      # show full project brain
claude-project list [--scan]              # list all known projects
claude-project sync                        # show sync status (Obsidian optional via CLAUDE_OBSIDIAN_VAULT)
claude-project generate-claude-md         # regenerate CLAUDE.md
claude-project log-event <type> [summary] # append event to log

Automation Engine

claude-project automation list            # list automations + last-fired time
claude-project automation run <id>        # manually trigger an automation

Trigger types: event · schedule (cron) · manual · file_change · service_up · service_down

Action types: run_command · dispatch_agent · write_event · send_notification · call_webhook

// .claude-project
"automations": [
  {
    "id": "daily-standup",
    "trigger": { "type": "schedule", "cron": "0 9 * * 1-5" },
    "action":  { "type": "dispatch_agent", "agent": "summariser",
                 "prompt": "Summarise yesterday's events and flag blockers." }
  },
  {
    "id": "alert-on-api-down",
    "trigger": { "type": "service_down", "service": "api" },
    "action":  { "type": "send_notification", "message": "API is down!" }
  }
]

Agent Dispatch

# Create
claude-project dispatch create "Review PR #42" --agent reviewer \
  --body "Check for security issues."

# List
claude-project dispatch list
claude-project dispatch list --status pending --agent reviewer

# Run (requires ANTHROPIC_API_KEY)
export ANTHROPIC_API_KEY=sk-ant-...
claude-project dispatch run --all           # all pending
claude-project dispatch run dispatch-abc12  # specific
claude-project dispatch run --dry-run       # preview

# Inspect
claude-project dispatch show dispatch-abc12

Built-in agent tools: read_file · list_files · write_file · bash · log_event

All file ops are sandboxed to the project directory.

"agents": {
  "reviewer": {
    "role": "Code reviewer",
    "model": "claude-sonnet-4-6",
    "instructions": "You are a thorough code reviewer.",
    "tools": ["read_file", "list_files", "bash", "log_event"],
    "max_tokens": 4096
  }
}

Session Hooks

claude-project hooks install           # local settings
claude-project hooks install --global  # global (~/.claude/settings.json)
claude-project hooks uninstall
claude-project hooks status

Daemon

claude-project daemon install    # install + start launchd (macOS)
claude-project daemon uninstall
claude-project daemon status
claude-project daemon run        # one manual scan cycle

MCP Server

claude-project mcp               # stdio (for Claude Code)
claude-project mcp --http        # HTTP/SSE on port 8765
claude-project inject            # add to ~/.mcp.json
claude-project eject
claude-project mcp-status

Add to ~/.mcp.json:

{
  "mcpServers": {
    "claude-project": {
      "command": "claude-project",
      "args": ["mcp"]
    }
  }
}

MCP Tools — Full Reference (39 tools)

Memory & Context

Tool	Description
store_memory	Store a memory entry (category: decision, discovery, context, task)
query_memory	Semantic search over stored memories via LanceDB
get_context	Return typed project context: stage, session summary, recent decisions
set_context	Update project stage and session summary at session end
set_file_summary	Cache a structured summary for a file path
get_file_summary	Retrieve cached file summary — call before reading any file
find_related_files	Semantic search for files related to a query

Protocol Documents (PD)

Tool	Description
register_pd	Register a reusable instruction block; deduplicates by SHA-256
get_pd	Retrieve a PD by ID
search_pd	Search PDs by task_type and/or interaction_pair
log_pd_usage	Record a PD use and tokens saved
check_negotiation_threshold	Returns true if interaction pair ≥ 3 (triggers negotiation)

Dispatch

Tool	Description
dispatch_task	Full pipeline: clarity → classify → compress → create dispatch file

Legacy tools (project events, registry, journal, automations, daemon) remain available unchanged.

---

.claude-project Schema

{
  "version": "4",
  "project_id": "auto-generated",
  "name": "My Project",
  "description": "What this project does",
  "stage": "Planning",
  "diary_path": "~/.claude/projects/my-project/memory",
  "obsidian_vault": "~/Documents/Obsidian",
  "obsidian_folder": "Projects/MyProject",

  "agents": {
    "reviewer": {
      "role": "Code reviewer",
      "model": "claude-sonnet-4-6",
      "instructions": "...",
      "tools": ["read_file", "list_files", "bash"],
      "max_tokens": 4096
    }
  },

  "automations": [
    {
      "id": "my-automation",
      "enabled": true,
      "trigger": { "type": "event", "event_type": "session_end" },
      "action":  { "type": "sync_obsidian" }
    }
  ],

  "services": {
    "api": {
      "type": "http",
      "url": "http://localhost:3000",
      "healthcheck": "http://localhost:3000/health"
    }
  },

  "monitoring": {
    "enabled": true,
    "notify": {
      "macos_notifications": true,
      "webhook_url": "https://hooks.slack.com/..."
    }
  }
}

---

Environment Variables

Variable	Default	Purpose
ANTHROPIC_API_KEY	(required for dispatch)	Claude API key
CLAUDE_OBSIDIAN_VAULT	~/.claude/obsidian	Obsidian vault path
CLAUDE_PROJECT_DIR	~/.claude/memory	Default diary directory
CLAUDE_DIARY_BASE	~/.claude/projects	Base dir for per-project diaries
CLAUDE_PROJECTS_ROOT	(none)	Extra root for daemon + list
CLAUDE_MCP_JSON	~/.mcp.json	Override MCP config path
OLLAMA_HOST	http://localhost:11434	Ollama endpoint for Clarity Layer
CLARITY_MODEL	qwen2.5:7b	Local model for input pre-processing

---

Integrations & Registries

Registry / Platform	Install
npm	npm install -g claude-project
GitHub Packages	npm install -g claude-project --registry https://npm.pkg.github.com
VS Code Marketplace	Search claudelab.claude-project
Claude Code MCP	claude-project inject
Obsidian	Auto-synced via sync_obsidian action
macOS launchd	claude-project daemon install
GitHub Codespaces

---

Contributing

See CONTRIBUTING.md. All contributions welcome.

git clone https://github.com/infraax/claude-project.git
cd claude-project && npm install && npm run build && npm link
npm test                          # 25 Vitest tests (TypeScript)
python scripts/test_full_pipeline.py  # 5 pipeline integration tests (Python)
npm run lint   # TypeScript type-check
bash scripts/test-infrastructure.sh  # 27-service connectivity report

---

Changelog

v5.3.0

• GitHub Codespaces — 3 use cases fully wired:
  • postCreate.sh — one-time setup: git-crypt unlock, npm ci, Python deps, Claude Code CLI, cloudflared, ~/.bashrc helpers (cc, bridge-start/stop/url, ablate-*)
  • postStart.sh — every-start: auto-restarts live API bridge + cloudflared tunnel, saves URL to data/tunnel.json
  • devcontainer.json — added ANTHROPIC_API_KEY secret, postStartCommand, port 3000 public with "Live API Bridge" label
  • .vscode/tasks.json — 10 VS Code tasks: bridge start/stop/URL, ablation runner (all conditions), log tail, Claude Code launch, tsc build
• Security hardening (CodeQL):
  • extension.ts: shellQuote() helper using POSIX single-quote wrapping replaces double-quote escaping on terminal.sendText() calls (CodeQL #2, #3)
  • automation.ts: escape backslashes before double-quotes in osascript notification string (CodeQL #4)
  • api-server.ts + orchestration/api-server.ts: log errors server-side, return generic "Internal server error" to clients (CodeQL #6, #7)

v5.2.0

• GitHub Pages — live at https://infraax.github.io/claude-project/
• Dashboard (/dashboard.html) — live pipeline metrics, TGCH status bars, 14-service health grid
• Orchestration Layer — Orchestrator class, HTTP API (port 3456): /health /api/services /api/metrics /api/all
• Workflow audit — removed 8 inapplicable workflows, fixed 5 broken ones (dashboard, orchestrator-health, osv-scanner, pyre, fortify)
• Security Guardian — 14-pattern secret scan + gitleaks, false positive suppression for rule definition files

v5.1.0

• Anonymous federated telemetry (opt-in) — token metrics → Cloudflare Worker → community thresholds
• telemetry_preview MCP tool — inspect exact payload before enabling
• Daemon: daily community threshold pull into .claude-project._community_thresholds

v5.0.0

• Schema v5: memory_path canonical (deprecates diary_path); removed obsidian_vault, obsidian_folder, devices, shared_paths; added optimizations, telemetry
• MCP server renamed — update ~/.mcp.json key
• Removed 10 legacy MCP tools (legacy session file / journal / Dexter profile)
• All machine-specific paths removed; Obsidian sync opt-in via CLAUDE_OBSIDIAN_VAULT
• Research instrumentation, Protocol Documents, typed dispatch, Clarity Layer, prompt cache, semantic memory

v4.2.0

• Research instrumentation — SQLite DispatchObservation recording every API call
• Task classifier — 8 task types via regex
• Format encoder — typed_pseudocode, dsl, toon, codeact, natural_language selected by task type
• Protocol Documents — content-addressed reusable instruction blocks, SHA-256 deduplication
• 13 new MCP tools
• Clarity Layer — Ollama/Qwen2.5-7B input pre-processor
• Prompt cache — stable prefix builder with cache_control: ephemeral
• LanceDB semantic memory — 384-dim all-MiniLM-L6-v2 embeddings

v4.1.0

• Automation engine — event, schedule, manual, file_change, service_up/down triggers; 6 action types
• Agent dispatch — Claude API tool loop (MAX 10 iterations), path traversal guard
• CLI: dispatch list/show/create/run, automation list/run
• Tests: 25 Vitest tests
• CI: tests on every push/PR; GitHub Packages publishing; production environment gate

v4.0.0

• v4 schema: agents, services, automations, monitoring
• Project registry + background daemon
• JSONL event log, dispatch queue, CLAUDE.md auto-generation
• Session hooks, VS Code extension, MCP server

v3.0.0

• Initial release — persistent memory, MCP server

---

License

MIT © infraax