Persistent memory, compact recovery, multi-agent orchestration, agent hierarchy, and safety enforcement for Claude Code sessions.

Claude Code sessions hit a hard limit: the context window. When a conversation grows too large, Claude triggers compaction -- compressing the conversation history to free space. Without external help, this means:

• Active tasks vanish. Agents lose track of what they were building, which files they modified, and what decisions they made.
• Agents work in silos. A backend agent finishes an API endpoint, but the frontend agent has no idea it exists.
• No visibility. There is no way to see what is happening across a multi-agent session -- which agents are running, what tools they are calling, or whether things are going well.
• Manual recovery. After each compact, users must re-explain the entire project state from memory.
• No safety net. Subagents can execute destructive operations (rm -rf, DROP DATABASE, .env access) without any preventive gate.

DCM sits alongside Claude Code as a persistent memory layer. It hooks into Claude's lifecycle events -- every tool call, every agent launch, every compaction -- and maintains a complete picture of what is happening. When compaction occurs, DCM automatically saves the session state beforehand and restores it afterward, so Claude picks up exactly where it left off.

The system consists of four components working together: a REST API that tracks and stores everything in PostgreSQL, a WebSocket server that streams events in real time, a Next.js dashboard that puts it all on screen, and a safety gate that blocks dangerous operations before they execute.

DCM includes a safety gate that intercepts dangerous operations before they execute. The gate runs as a PreToolUse hook on Bash and Write tools:

When a blocked operation is detected:

1. The hook returns {"decision": "block", "reason": "..."} to Claude Code, preventing execution
2. The blocked operation is logged to the DCM API (tool_type: "blocked") for centralized tracking
3. The dashboard displays blocked operations in the Safety Gate section of the Agents page

# Customize blocking rules in: context-manager/hooks/safety-gate.sh

DCM protects against context loss with four layers of defense, each catching what the previous one might miss:

When Claude's context window fills up:

1. PreCompact -- DCM collects active tasks (running + pending + blocked), modified files, agent states, key decisions (pattern-extracted from transcript), wave state, and a 3000-character summary (last 15 assistant messages), then saves them as a snapshot in PostgreSQL.
2. Compaction -- Claude compresses the conversation. Without DCM, everything before this point is gone.
3. SessionStart (compact) -- DCM uses a snapshot-first restore strategy:
   • First, looks for the saved snapshot in the database
   • If found, generates a structured Markdown brief directly from the snapshot data (tasks by status, decisions, wave progress, modified files, agent states)
   • Enriches with any live subtasks created after the snapshot
   • If no snapshot exists, falls back to generateContextBrief() with a session-scoped fallback (queries by session_id when agent_id returns no results)
   • The brief is injected via additionalContext, so Claude resumes with full awareness of prior work.

DCM tracks the full lifecycle of every subagent through centralized database tracking, with parent/child hierarchy:

Agent hierarchy: When a subagent spawns another subagent, the CLAUDE_AGENT_ID environment variable is detected by track-agent-start.sh and stored as parent_agent_id. This enables:

• Filtering by ?is_subagent=true|false on the subtasks API
• Dashboard split into Main Agents and Subagents sections with parent link indicators
• Per-level success rate statistics

All tracking data flows to PostgreSQL via the DCM API, providing a single centralized source of truth accessible from both the web dashboard and the CLI dashboard.

To create subagents with built-in DCM tracking, use the provided template:

cp context-manager/agents/monitored-agent-template.md my-agent.md

The template includes frontmatter hooks for PreToolUse (safety gate) and PostToolUse (action tracking), ensuring every tool call inside the subagent is tracked and dangerous operations are blocked.

Agents coordinate through a built-in pub/sub messaging system:

• Messages -- Agents publish to topics (e.g., api_endpoint_created, schema_updated). Other agents receive these through the context API or WebSocket subscriptions.
• Subscriptions -- Agents subscribe to topics they care about and receive targeted notifications.
• Blocking -- An agent can declare a dependency on another, preventing premature execution until the upstream work is done.
• Broadcast -- When a subagent finishes, save-agent-result.sh automatically broadcasts its result so other agents can consume it.

# Agent publishes a message curl -X POST http://127.0.0.1:3847/api/messages \ -H "Content-Type: application/json" \ -d '{  "from_agent_id": "backend-laravel",  "topic": "api_endpoint_created",  "payload": {"endpoint": "/api/users", "methods": ["GET", "POST"]}  }' # Another agent checks messages curl "http://127.0.0.1:3847/api/messages/frontend-react?session_id=abc123"

Complex work is decomposed into waves -- sequential execution phases where subtasks within each wave run in parallel:

Wave 0: Exploration --> Wave 1: Implementation --> Wave 2: Validation --> Wave 3: Documentation [analyze codebase] [backend] [frontend] [tests] [review] [docs] [changelog] [read requirements] [database] [api] [security audit] [api spec update] 

The orchestration API supports:

• Task decomposition -- Break a high-level request into typed subtasks (POST /api/orchestration/decompose)
• Batch submission -- Submit a wave of subtasks at once (POST /api/orchestration/batch-submit)
• Conflict detection -- Identify agents modifying the same files (GET /api/orchestration/conflicts/:id)
• Result synthesis -- Aggregate results from a completed batch (POST /api/orchestration/batch/:id/complete)

DCM integrates through Claude Code's hooks system. Lightweight bash scripts fire on lifecycle events, each calling the DCM API with relevant data:

All hooks are fire-and-forget -- they never block Claude Code execution.

The monitoring dashboard runs at http://localhost:3848 and provides live visibility into multi-agent sessions:

Built with Next.js 16, React 19, shadcn/ui, Recharts, TanStack Query, and Tailwind CSS. Full light/dark mode support with glassmorphism cards.

For quick terminal-based monitoring without opening a browser:

# Snapshot view bash context-manager/hooks/dashboard.sh # Auto-refresh every 2 seconds bash context-manager/hooks/dashboard.sh --watch # Raw JSON output (for scripting) bash context-manager/hooks/dashboard.sh --json # Clean old data (>7 days) bash context-manager/hooks/dashboard.sh --clean

The terminal dashboard queries the DCM API and displays:

• Service health status (API + Database)
• KPI summary (sessions, agents, actions, success rate)
• Currently active agents with type, status, and description
• Recent tool actions (last 10)
• Blocked operations from Safety Gate (highlighted in red)

DCM learns which tools work best for which tasks through a feedback-driven keyword scoring system:

# Get tool suggestions for a keyword curl "http://127.0.0.1:3847/api/routing/suggest?keyword=database&limit=5" # Provide feedback after a successful tool use curl -X POST http://127.0.0.1:3847/api/routing/feedback \ -H "Content-Type: application/json" \ -d '{"keyword": "database", "tool_name": "Bash", "successful": true}'

Scores adjust dynamically based on success rates, guiding future tool selection.

• Bun >= 1.x
• PostgreSQL >= 16
• Node.js >= 22 (dashboard only)
• jq and curl (standard on most Linux/macOS systems)

git clone https://github.com/ronylicha/Claude-DCM.git cd Claude-DCM/context-manager bun install ./dcm install

The dcm install command runs a 5-step setup:

1. Checks prerequisites (bun, psql, jq, curl)
2. Installs dependencies
3. Creates .env from template
4. Sets up the PostgreSQL database (10 tables, 4 views, indexes)
5. Injects hooks into Claude Code's settings.json

./dcm start

This launches three processes:

• API Server on port 3847
• WebSocket Server on port 3849
• Dashboard on port 3848

# Check all components ./dcm status # Direct health check curl http://127.0.0.1:3847/health | jq .

Expected output from dcm status:

DCM Status API (port 3847): healthy (v3.1.0) WebSocket (port 3849): running Dashboard (port 3848): running PostgreSQL: connected Claude Code hooks: installed 

DCM can also run as a Claude Code plugin that auto-starts when a session begins:

ln -s /path/to/Claude-DCM/context-manager ~/.claude/plugins/dcm

The ensure-services.sh hook detects when DCM is not running, starts services, and waits for health confirmation -- all within the SessionStart hook timeout.

┌─────────────────────────────────────────────────────────────────────────────┐ │ CLAUDE CODE SESSION │ │ │ │ PreToolUse ─── safety-gate.sh ──── BLOCK dangerous ops ──► DCM API │ │ PreToolUse ─── track-agent-start.sh ─── Log agent spawn ──► DCM API │ │ PostToolUse ── track-action.sh ──────── Log all tools ────► DCM API │ │ PostToolUse ── track-agent-end.sh ───── Mark completed ───► DCM API │ │ PostToolUse ── context-guardian.sh ──── Monitor context ─── (local) │ │ PreCompact ─── pre-compact-save.sh ──── Save snapshot ────► DCM API │ │ SubagentStop ─ save-agent-result.sh ─── Broadcast result ─► DCM API │ │ SessionStart ─ post-compact-restore.sh ─ Restore context ◄─ DCM API │ │ │ └──────────────────────────────┬──────────────────────────────────────────────┘ │ HTTP / curl (fire-and-forget) ▼ ┌──────────────────────────────────────────────────────────────────────────────┐ │ DCM API (Bun + Hono) │ │ Port 3847 │ │ │ │ 50+ REST endpoints: actions, subtasks, messages, compact, routing, │ │ orchestration, waves, registry, tokens, dashboard KPIs │ │ │ │ PostgreSQL 16: 10 tables, 4 views, JSONB metadata, GIN indexes │ └──────────────┬────────────────────────────────┬──────────────────────────────┘ │ LISTEN/NOTIFY │ HTTP ▼ ▼ ┌──────────────────────────┐ ┌──────────────────────────────────────────────┐ │ WebSocket Server │ │ Next.js Dashboard │ │ Port 3849 │ │ Port 3848 │ │ │ │ │ │ Real-time events │ │ 14 pages: Dashboard, Agents, Sessions, │ │ HMAC auth │────►│ Live, Waves, Flows, Messages, Routing, │ │ Channel subscriptions │ │ Registry, Compact, Performance, Tools, │ │ │ │ Context, Projects │ └──────────────────────────┘ └──────────────────────────────────────────────┘ 

The schema tracks the full hierarchy: Projects contain Requests, which spawn Waves (task lists) of Subtasks assigned to agents. Every tool invocation is recorded as an Action (including blocked operations with tool_type: "blocked"). Inter-agent coordination uses Messages, Subscriptions, and Blocking relations. Agent Contexts store recovery snapshots for compact operations.

Real-time events flow through PostgreSQL LISTEN/NOTIFY, bridged to WebSocket clients:

agents/{agent_id} -- Agent-specific events sessions/{session_id} -- Session-specific events global -- Broadcast to all clients metrics -- System metrics snapshots topics/{topic_name} -- Topic-based routing 

DCM exposes 50+ REST endpoints organized into functional groups. Full interactive documentation is available through the Swagger UI and OpenAPI spec.

Check service health:

curl http://127.0.0.1:3847/health | jq .

{ "status": "healthy", "version": "3.1.0", "timestamp": "2026-02-28T10:30:00.000Z", "database": "connected", "features": ["compact", "messaging", "orchestration", "registry", "safety-gate"] }

Save a context snapshot:

curl -X POST http://127.0.0.1:3847/api/compact/save \ -H "Content-Type: application/json" \ -d '{  "session_id": "session-abc123",  "trigger": "manual",  "context_summary": "Working on authentication feature",  "active_tasks": [{"description": "Create User model", "status": "running"}]  }'

Restore context after compact:

curl -X POST http://127.0.0.1:3847/api/compact/restore \ -H "Content-Type: application/json" \ -d '{  "session_id": "session-abc123",  "agent_id": "orchestrator",  "agent_type": "orchestrator",  "max_tokens": 2000  }'

Submit a batch of subtasks:

curl -X POST http://127.0.0.1:3847/api/orchestration/batch-submit \ -H "Content-Type: application/json" \ -d '{  "session_id": "session-abc123",  "tasks": [  {"agent_type": "backend-laravel", "description": "Create User model and migration"},  {"agent_type": "frontend-react", "description": "Build login form component"}  ]  }'

Query blocked operations:

curl "http://127.0.0.1:3847/api/actions?tool_type=blocked&limit=10" | jq .

Hooks are the integration layer between Claude Code and DCM. Each hook is a bash script that receives JSON on stdin, processes the event, and optionally returns JSON output.

Claude Code Event --> Bash Hook Script --> curl POST to DCM API --> PostgreSQL <-- JSON response (if needed) 

Every hook receives JSON on stdin:

{ "tool_name": "Read", "tool_input": {"file_path": "/src/server.ts"}, "tool_output": {"content": "..."}, "session_id": "session-abc123", "cwd": "/home/user/project", "timestamp": "2026-02-09T10:30:00.000Z", "exit_code": 0 }

When the safety gate blocks an operation, it returns:

{ "decision": "block", "reason": "SAFETY GATE: DROP DATABASE detected. This operation has been blocked to prevent data loss." }

SessionStart hooks can inject context into Claude by outputting:

{ "hookSpecificOutput": { "additionalContext": "# Restored Context\n\nYou were working on..." } }

This is how DCM restores context after compaction -- the brief appears as if Claude always knew the information.

The dcm command is the single entry point for all operations.

dcm install # Full setup: dependencies, database, hooks dcm start # Start API + WebSocket + Dashboard dcm stop # Stop all services dcm restart # Stop then start dcm status # Health check for all components dcm health # Quick API health check (JSON) dcm logs api # Tail API logs dcm logs ws # Tail WebSocket logs dcm logs dashboard # Tail Dashboard logs

dcm hooks # Install/update Claude Code hooks dcm unhook # Remove all DCM hooks (with backup)

dcm db:setup # Initialize database schema dcm db:reset # Drop and recreate database (destructive, requires confirmation)

dcm snapshot <session_id> # Trigger a manual context snapshot dcm context <agent_id> [session_id] # Get context brief for an agent

bash hooks/dashboard.sh # Snapshot view with KPIs and active agents bash hooks/dashboard.sh --watch # Auto-refresh every 2 seconds bash hooks/dashboard.sh --json # Raw JSON output for scripting bash hooks/dashboard.sh --clean # Clean data older than 7 days

dcm version # Show version (3.1.0) dcm help # Show usage information

Both modes include ensure-services.sh, which auto-starts services if they are not running when a Claude Code session begins. PostgreSQL must be running first -- using systemd is recommended:

sudo systemctl enable postgresql sudo systemctl start postgresql

Copy .env.example to .env in the context-manager directory:

cp .env.example .env

package.json is the single source of truth for versioning. The API server reads it dynamically (import pkg from "../package.json"), the dashboard sidebar fetches it from /health, and plugin.json + openapi.yaml are kept in sync. No more hardcoded version strings.

Sessions are considered "active" if ended_at IS NULL or ended_at is within the last 30 minutes. When DCM restarts and a session resumes, track-session.sh reactivates it by setting ended_at = NULL. This fixes the Flows/Live pages showing 0 active sessions after a DCM restart.

DCM is designed for zero-impact integration. Hooks must never slow down Claude Code.

• Safety gate: PreToolUse hook blocks destructive operations (rm -rf, DROP DATABASE, .env access, fork bombs)
• Input validation: Zod schemas on all API endpoints
• Rate limiting: Auth endpoint limited to 10 requests per 15 minutes
• HMAC authentication: WebSocket connections require signed tokens in production
• Parameterized queries: All SQL uses parameterized queries (no injection risk)
• CORS protection: Configurable allowed origins
• Circuit breaker: Hooks gracefully degrade if the API is unreachable
• No secrets in logs: Configuration via environment variables only
• Centralized audit trail: All blocked operations logged in PostgreSQL for review

cd context-manager bun test

Test suites cover API endpoints, message handling, cleanup logic, orchestration planning, and WebSocket functionality.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Install dependencies (cd context-manager && bun install)
4. Set up the database (./dcm db:setup)
5. Make changes and add tests
6. Run the test suite (bun test)
7. Commit with conventional format (git commit -m "feat: add my feature")
8. Push and open a Pull Request

Key extension points:

• Add agent types in src/data/catalog.ts
• Create prompt templates in src/templates/
• Add custom hooks in hooks/
• Customize safety gate rules in hooks/safety-gate.sh
• Create monitored agents from agents/monitored-agent-template.md
• Extend the schema via migrations in src/db/migrations/

See the full Contributing Guide for development setup, code style, and PR process.

MIT