ravenclaw

Ravenclaw

Work context management system for AI coding agents.

Ravenclaw gives AI agents persistent memory across sessions. Instead of re-explaining your project every time, agents start with full awareness — what's been built, what's in progress, and what to do next.

Web UI where you instruct agents, monitor their work in real-time, and manage project context — all in one place.

Why Ravenclaw?

AI coding agents (Claude Code, Gemini CLI, Codex) are powerful — but they forget everything between sessions. Managing multiple projects with multiple agents gets chaotic fast:

• "Where did I leave off?" repeated every session
• Context lost when switching between projects
• No visibility into what agents are doing
• No structured way to break down and track work

Ravenclaw solves this with a project management system that agents can read and write — via MCP tools, CLI, or REST API.

Screenshots

Projects + Epics	Chat with Agent
Graph View	Detail Panel

Key Features

Agent Orchestration

• Web-based chat — Send instructions to agents directly from the browser
• Real-time streaming — Watch agent responses as they type (SSE)
• Conversation continuity — Sessions persist across messages via claude --resume
• Multi-agent support — Claude Code, Gemini CLI, Codex
• Permission control — Auto-approve, bypass, accept-edits, or interactive mode
• Tool activity indicator — See "Running: Bash", "Running: Edit" in real-time

Project Management

• Three-level hierarchy — Project > Epic > Issue with dependency tracking
• Interactive graph view — Visual project structure with clickable nodes
• Detail panel — Click any item to view/edit description, status, metadata inline
• Progress tracking — Epic progress auto-calculated from issue completion
• Wiki & Ontology — Versioned knowledge base with auto-extracted concept graph

Context & Sessions

• Context handoff — Agents save snapshots; new sessions load where the last left off
• Completion notes — Agents record what was done and why when closing issues; future sessions carry this rationale forward automatically
• Human-in-the-loop — Agents ask questions, users answer via web UI
• Session locking — Epic-level locks prevent concurrent agent conflicts
• Persistent chat history — Conversations stored in DB, survive server restarts

Architecture

┌──────────────┐
│ Web Dashboard │  React + Tailwind + ReactFlow
└──────┬────────┘
       │
┌──────┴────────┐     ┌────────────┐     ┌────────────┐
│  API Server   │─────│ PostgreSQL │     │  AI Agent   │
│  (Hono)       │     └────────────┘     │(Claude/etc.)│
└──┬────┬───┬───┘                        └──────┬──────┘
   │    │   │                                   │
   │    │   └── Process Manager ────────────────┘
   │    │       (spawn, stream, resume)
   │    └── REST API + SSE Streaming
   │
   └── Conversations (DB-persisted, session continuity)

┌────────────┐     ┌────────────┐
│ MCP Server │     │  CLI (rc)  │
│ (40+ tools)│     │            │
└────────────┘     └────────────┘

Package	Description
@ravenclaw/core	DB schema (Drizzle ORM), services, types
@ravenclaw/api	Hono REST API + Process Manager + SSE + Conversations
@ravenclaw/cli	Terminal interface (rc command)
@ravenclaw/mcp	MCP server for AI agent integration (40+ tools)
@ravenclaw/web	React dashboard with graph view and interactive chat

Quick Start

git clone https://github.com/chainofdive/ravenclaw.git
cd ravenclaw
pnpm install && pnpm build

# Start PostgreSQL + run migrations
docker-compose up -d
pnpm db:push

# Start API server
source .env && DATABASE_URL="$DATABASE_URL" node packages/api/dist/index.js

# Start web dashboard
pnpm --filter @ravenclaw/web dev

See docs/SETUP.md for detailed setup instructions.

How It Works

Agent starts a session
  │
  ├─ get_latest_context(RC-P1)      ← load previous handoff
  ├─ start_work_session(...)        ← record session
  ├─ get_project(RC-P1)             ← see full project tree
  │
  ├─ start_issue(RC-I26)            ← pick up a task
  ├─ ... coding ...
  ├─ complete_issue(RC-I26,         ← mark done + record what was done and why
  │    summary: "Used ECS pattern     (completion note persisted for future sessions)
  │    for O(1) shuffle...")
  ├─ save_context(RC-P1, "...")     ← save progress for next session
  │
  ├─ request_human_input(...)       ← ask user if needed
  └─ end_work_session(...)          ← close session