Claude Code Orchestration Framework

Production-ready orchestration with Vector RAG Memory

Version: 1.4.0 | 📖 Quick Start → | ⚡ 5-Minute Setup

---

🎯 The Killer Feature: Vector RAG Memory

Claude remembers everything across sessions. Your agents build institutional knowledge.

You: "Add authentication to the API"
Agent: Searches past work → Finds "We use JWT with refresh tokens (users.service.ts)"
       ↓
Agent: Implements auth matching your existing patterns (no reinventing the wheel)

How it works:

1. 📝 Subagents return structured DIGEST blocks (decisions, files changed, contracts)
2. 💾 DIGEST auto-stored in pgvector/Supabase/Pinecone (your choice)
3. 🔍 New tasks → RAG search suggests relevant past work
4. ✨ Agents build on what you already have (coherent codebase, no drift)

Supported Backends (drop-in):

• ✅ pgvector (PostgreSQL + pgvector extension) - Self-hosted, free
• ✅ Supabase (Managed pgvector) - Just add SUPABASE_URL + SUPABASE_KEY
• ✅ Pinecone (Managed vector DB) - Just add PINECONE_API_KEY

Zero vector DB knowledge required. Just paste an API key and go.

---

🚀 New in v1.4.0 - Zero Configuration!

• Automatic Per-Project Setup: First use auto-creates .claude/logs/, updates .gitignore, creates NOTES.md
• Zero Manual Work: Just install globally once, then use Claude Code in any project
• Smart Detection: Auto-detects projects (git repos, package.json, pyproject.toml, etc.)
• Runs Once: Creates .claude/.setup_complete marker to skip future setup
• Vector RAG Ready: Auto-configures memory ingestion and retrieval hooks

What's Included

🎯 Vector RAG Memory System (The Star Feature)

• Auto-Ingestion: Every DIGEST block automatically stored in vector DB
• Smart Retrieval: RAG search suggests relevant past work on every new task
• Multi-Backend: Drop-in support for Supabase, Pinecone, or self-hosted pgvector
• Zero Config: Just set environment variables - framework handles the rest
• Cross-Project Memory: Search across all your projects (global knowledge base)
• Privacy First: Self-hosted option (pgvector) keeps your data on your infrastructure

Core Components

• 40+ Specialized Agents: Implementation planner, requirements clarifier, code navigator, implementation engineer, test author, security auditor, and more
• DIGEST-Based Context: Structured JSON summaries (not giant transcript dumps)
• 12+ Automation Hooks: Pre/Post tool use hooks for validation, cost tracking, DIGEST capture, and quality gates
• Pivot Tracking System: Detect direction changes, validate FEATURE_MAP updates, auto-audit obsolete code
• Multi-Model Brainstorming: Claude + GPT-5 dialogue for strategic planning
• Cost Tracking: Automatic cost display for OpenAI and Perplexity API calls
• Pre-Merge Quality Gate: Bash script for comprehensive pre-merge validation
• MD Spam Prevention: Enforces documentation policy to prevent file sprawl

Hook Scripts (hooks/)

• pretooluse_validate.py - Validate permissions, check budgets
• posttooluse_validate.py - Lint/typecheck after edits
• checkpoint_manager.py - Auto-checkpoint before risky operations
• pivot_detector.py - Detect direction changes
• feature_map_validator.py - Validate FEATURE_MAP updates
• log_analyzer.py - Suggest specialized agents
• task_digest_capture.py - Capture subagent DIGEST blocks
• precompact_summary.py - Generate compaction summaries
• gpt5_cost_tracker.py - Track OpenAI API costs
• perplexity_tracker.py - Track Perplexity API costs
• md_spam_preventer.py - Prevent documentation sprawl
• ready-to-merge.sh - Pre-merge quality gate script

Agent Definitions (agents/)

All 40+ specialized agent definitions for routing and delegation.

Configuration

• CLAUDE.md - Global orchestration instructions
• settings.json - Hook registrations
• FEATURE_MAP.template.md - Project template

MCP Servers (Optional)

• openai-bridge - Multi-model brainstorming with GPT-5
• postgres-bridge - Read-only database queries with AI-generated SQL
• vector-bridge - Vector RAG memory (pgvector/Supabase/Pinecone backends)

---

5-Minute Setup with Vector RAG

Option 1: Supabase (Easiest - Managed, Free Tier)

# 1. Install framework
npm install -g claude-orchestration-framework
bash ~/.npm-global/lib/node_modules/claude-orchestration-framework/install.sh

# 2. Create Supabase project at https://supabase.com (free tier)
#    Enable pgvector extension in Database → Extensions

# 3. Add to ~/.zshrc or ~/.bashrc (or use .envrc with direnv)
export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_SERVICE_KEY="your-service-role-key"
export ENABLE_VECTOR_RAG=true

# 4. Reload shell
source ~/.zshrc

# 5. Done! Open Claude Code in any project - RAG memory is active

Get your keys:

• SUPABASE_URL: Project Settings → API → Project URL
• SUPABASE_SERVICE_KEY: Project Settings → API → service_role key (keep secret!)

Option 2: Pinecone (Serverless, Simple API)

# 1. Install framework (same as above)
npm install -g claude-orchestration-framework
bash ~/.npm-global/lib/node_modules/claude-orchestration-framework/install.sh

# 2. Create Pinecone index at https://www.pinecone.io (free tier)
#    Index name: "claude-memory"
#    Dimensions: 1536 (OpenAI embeddings)
#    Metric: cosine

# 3. Add to ~/.zshrc or ~/.bashrc
export PINECONE_API_KEY="your-api-key"
export PINECONE_INDEX="claude-memory"
export ENABLE_VECTOR_RAG=true

# 4. Reload and go
source ~/.zshrc

Get your API key:

• Pinecone Dashboard → API Keys → Create Key

Option 3: Self-Hosted pgvector (Full Control)

# 1. Install framework (same as above)

# 2. Set up PostgreSQL with pgvector
docker run -d \
  -e POSTGRES_PASSWORD=yourpassword \
  -e POSTGRES_DB=claude_memory \
  -p 5432:5432 \
  ankane/pgvector

# 3. Add to ~/.zshrc or ~/.bashrc
export DATABASE_URL_MEMORY="postgresql://postgres:yourpassword@localhost:5432/claude_memory"
export ENABLE_VECTOR_RAG=true

# 4. Reload
source ~/.zshrc

Verify RAG is Working

# In any project, run a task with subagent
# Example: Ask Claude to "implement user authentication"
# After task completes, check NOTES.md - you'll see DIGEST blocks
cat NOTES.md

# Future sessions will reference past work automatically!

---

Installation

NPM Installation (Recommended)

Linux/macOS:

npm install -g claude-orchestration-framework
bash ~/.npm-global/lib/node_modules/claude-orchestration-framework/install.sh

Windows (PowerShell):

npm install -g claude-orchestration-framework
powershell -ExecutionPolicy Bypass -File "$env:APPDATA\npm\node_modules\claude-orchestration-framework\install.ps1"

What the Installer Does

1. Backs up existing installation (if any)
2. Installs hooks to ~/.claude/hooks/ (version-controlled)
3. Installs agents to ~/.claude/agents/
4. Configures settings.json (with merge option)
5. Sets up environment variables
6. Optionally installs MCP servers (postgres-bridge, vector-bridge, openai-bridge)

Manual Installation

If you prefer manual installation:

Linux/macOS:

1. Clone or download the package
2. Run: bash install.sh

Windows:

1. Clone or download the package
2. Run: powershell -ExecutionPolicy Bypass -File install.ps1

Post-Installation

1. Validate Installation

Quick automated check:

bash smoke-test.sh

Comprehensive validation: See MCP test notes in MCP_TEST_REPORT.md and try the sample tool flows.

---

Operational Toggles (Hooks)

Stop Hook Performance

• STOP_TAIL_WINDOW_BYTES (default 524288): Tail bytes for fast DIGEST scan
• STOP_HOOK_MAX_TRANSCRIPT_BYTES (default 524288): Skip full parse when huge (with STOP_TAIL_FAST_ONLY=true)
• STOP_TAIL_FAST_ONLY (default false): Only tail-scan; do not full-parse if not found
• STOP_TIME_BUDGET_MS (default 0): Soft cutoff; exit early if exceeded with no DIGEST
• STOP_DEBUG (default true): Gate debug log writes

Project Status Updater (CLAUDE.md)

• PROJECT_STATUS_COMPACT (default false): compact header + Next Steps; hides decisions/risks
• PROJECT_STATUS_SHOW_DECISIONS (default true)
• PROJECT_STATUS_SHOW_ACTIVITY (default true)

Vector Ingestion (Queue)

• ENABLE_VECTOR_RAG (default false)
• INGEST_MCP_TIMEOUT_SEC (default 60): memory_ingest timeout for MCP stdio
• INGEST_NONFATAL_ERRORS_PATTERN (regex): treat transient errors as retryable (e.g., timed out|ECONN|ETIMEDOUT)

Implementation Validator (IV)

• ENABLE_IV (default false): spawn IV after Stop (non-blocking)
• IV_FAST_ONLY (default true): local checks only
• IV_WRITE_NOTES (default true): append compact IV note to NOTES.md

---

Implementation Validator (IE → IV → TA)

Fast, local validation that closes gaps before tests:

• Reads last DIGEST from .claude/logs/NOTES.md and recent files from .claude/logs/wsi.json
• Flags files listed in DIGEST that weren’t touched recently
• Surfaces pending “Next Steps” to resolve before handing off to TA

Enable: export ENABLE_IV=true

Output:

• WARNINGS.md entry if gaps exist
• Compact IV note in NOTES.md with summary and actionable gaps

---

Solution Memory (Fixpacks)

Reusable, vector-searchable remediations for known errors.

MCP tools (via vector-bridge):

• mcp__vector-bridge__solution_search — find fixpacks by error message
• mcp__vector-bridge__solution_preview — DRY‑RUN preview (no changes)
• mcp__vector-bridge__solution_apply — record success/failure to track effectiveness

Hook integration:

• hooks/error_recovery.py auto‑suggests top fixpacks on hook failure and DRY‑RUN previews the first one

Env toggles:

• ENABLE_FIXPACK_SUGGEST=true (default)
• FIXPACK_MAX_SUGGESTIONS=2
• FIXPACK_SUGGEST_TIMEOUT_SEC=6
• FIXPACK_AUTO_PREVIEW=true

---

Project Status Updater (CLAUDE.md)

Maintains a <project_status> block with:

• Header: project, timestamp, data freshness (and reasons)
• Summary: phase and optional focus component
• Last Digest: agent, task, decisions/files counts
• Next Steps: top items from recent work
• Activity Snapshot: recent components

Compact mode: export PROJECT_STATUS_COMPACT=true

---

MCP Configuration

Claude Code looks for MCP configs by scope:

• User (all projects): ~/.claude.json
• Project (committable): <repo>/.mcp.json
• Local (per project, private): still ~/.claude.json, scoped to the active project

Best practices:

• Use an absolute Node path in .mcp.json (e.g., /Users/you/.nvm/versions/node/v22/bin/node)
• Provide real env values (don’t rely on ${VAR} expansion) or set OS env via launchctl setenv
• To bootstrap per‑project: the auto-setup hook creates .mcp.json from ~/.claude/mcp-template.json if missing

Quick health check (stdio):

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"readme","version":"1.0"}}}' '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| OPENAI_API_KEY="$OPENAI_API_KEY" DATABASE_URL_MEMORY="$DATABASE_URL_MEMORY" REDIS_URL="$REDIS_URL" \
  /Users/you/.nvm/versions/node/v22.15.0/bin/node ~/.claude/mcp-servers/vector-bridge/dist/index.js

---

Stop Hook Performance (large transcripts)

To keep Stop fast on large transcripts:

• Tail scan recent bytes first (STOP_TAIL_WINDOW_BYTES, default 512KB)
• Optional fast‑only mode + size cap (STOP_TAIL_FAST_ONLY=true, STOP_HOOK_MAX_TRANSCRIPT_BYTES)
• Early exit by time budget (STOP_TIME_BUDGET_MS)
• Gate heavy debug I/O (STOP_DEBUG=false)

2. Set Up API Keys (Optional)

For multi-model brainstorming and live data searches:

export OPENAI_API_KEY='sk-...'
export PERPLEXITY_API_KEY='pplx-...'

2. Enable RAG Loop (Optional)

For vector memory and DIGEST ingestion:

Linux/macOS:

export ENABLE_VECTOR_RAG=true
export DATABASE_URL_MEMORY='postgresql://user:pass@host:port/database'
export REDIS_URL='redis://host:port'

Windows:

$env:ENABLE_VECTOR_RAG = 'true'
$env:DATABASE_URL_MEMORY = 'postgresql://user:pass@host:port/database'
$env:REDIS_URL = 'redis://host:port'

3. Create FEATURE_MAP.md in Your Project

Linux/macOS:

cd ~/your-project
cp ~/.claude/FEATURE_MAP.template.md FEATURE_MAP.md

Windows:

cd C:\your-project
Copy-Item "$env:USERPROFILE\.claude\FEATURE_MAP.template.md" ".\FEATURE_MAP.md"

Edit FEATURE_MAP.md to track your project's features and pivots.

4. Test the Installation

Linux/macOS:

# Check hooks are working
python3 ~/.claude/hooks/checkpoint_manager.py list

# Run pre-merge check
cd ~/your-project
bash ~/.claude/hooks/ready-to-merge.sh

Windows:

# Check hooks are working
python "$env:USERPROFILE\.claude\hooks\checkpoint_manager.py" list

# Run pre-merge check (requires Git Bash or WSL)
cd C:\your-project
bash "$env:USERPROFILE\.claude\hooks\ready-to-merge.sh"

Usage

Main Agent Routing

The Main Agent automatically routes tasks to specialized subagents:

• Complex features → Implementation Planner
• Vague requests → Requirements Clarifier
• Code changes → Code Navigator + Implementation Engineer
• Testing → Test Author
• Security → Security Auditor
• Performance → Performance Optimizer

Pivot Workflow

1. Change direction: "Actually, let's use Railway instead of Supabase"
2. Hook detects pivot, shows warning
3. Update FEATURE_MAP.md manually
4. Say: "I've updated FEATURE_MAP. Run the pivot cleanup workflow."
5. Main Agent auto-invokes Relevance Auditor → Auto-Doc Updater

Pre-Merge Quality Gate

cd ~/your-project
bash ~/claude-hooks/ready-to-merge.sh

# With auto-fix for linting
bash ~/claude-hooks/ready-to-merge.sh --auto-fix

Multi-Model Brainstorming

Say "brainstorm alternatives" or mention comparing approaches. Main Agent will invoke Multi-Model Brainstormer (Claude + GPT-5 dialogue).

Checkpoint Management

# List checkpoints
python3 ~/claude-hooks/checkpoint_manager.py list

# Restore a checkpoint
python3 ~/claude-hooks/checkpoint_manager.py restore <checkpoint-id>

Features

Automatic Hooks

• PreToolUse: Permission validation, budget checks
• PostToolUse: Lint/typecheck after edits, cost tracking, DIGEST capture
• UserPromptSubmit: Agent suggestions, pivot detection, FEATURE_MAP validation
• PreCompact: Generate summary before compaction
• Stop: Extract final DIGEST (fallback)

Pivot Tracking (4 Layers)

1. FEATURE_MAP.md - Single source of truth
2. pivot_detector.py - Auto-detect direction changes
3. Relevance Auditor - Find obsolete code
4. Auto-Doc Updater - Sync all documentation

Cost Tracking

Automatically displays costs for:

• OpenAI API calls (GPT-5, GPT-4o, etc.)
• Perplexity API calls (sonar, sonar-pro, sonar-reasoning)

Quality Gates

• Pre-merge validation (lint, typecheck, tests, build)
• Integration cohesion audits
• Production readiness verification

Documentation

• Global Config: ~/.claude/CLAUDE.md
• Agent Roster: ~/.claude/agents/*.md
• Hook Scripts: ~/.claude/hooks/*.py
• Project Template: ~/.claude/FEATURE_MAP.template.md
• Logs Migration: See LOGS_MIGRATION.md for per-project log configuration

Troubleshooting

Hooks Not Running

1. Check ~/.claude/settings.json has hook registrations
2. Verify scripts are executable: chmod +x ~/claude-hooks/*.py
3. Check Python version: python3 --version (need 3.8+)

MCP Servers Not Working

1. Rebuild: cd ~/.claude/mcp-servers/openai-bridge && npm install && npm run build
2. Check API keys are set in environment
3. Restart Claude Code

DIGEST Blocks Not Captured

1. Check NOTES.md exists in project root
2. Verify task_digest_capture.py hook is registered
3. Run subagents via Task tool (not direct work)

Updating

To update to a new version:

1. Download new package
2. Run bash install.sh (will backup existing)
3. Review changes in ~/.claude/settings.json.backup

Uninstalling

rm -rf ~/claude-hooks
rm -rf ~/.claude/agents
# Manually remove hook registrations from ~/.claude/settings.json
# Manually remove CLAUDE.md from ~/.claude/

Support

For issues or questions:

• Check documentation in ~/.claude/CLAUDE.md
• Review agent definitions in ~/.claude/agents/
• Check hook debug logs in ~/claude-hooks/logs/

Version History

1.0.0 (October 2025)

• Initial release
• 40+ agents
• 12+ hooks
• Pivot tracking system
• Multi-model brainstorming
• Cost tracking
• Pre-merge quality gates

License

[Your License Here]

---

Happy Coding! 🚀