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)│     │            │
└────────────┘     └────────────┘

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

Or via the web UI: type a message → agent works in the project directory → stream results back in real-time.

Data Model

Workspace
  └─ Project (RC-P1)                    ← product / game / campaign
       │  directory: /path/to/project   ← agents run here
       ├─ Epic (RC-E10: Phase 1)        ← milestone (depends_on other epics)
       │    ├─ Issue (RC-I26: task)      ← individual task
       │    └─ Issue (RC-I27: task)      ← depends_on RC-I26
       └─ Conversation                  ← persistent chat with agent
            └─ Messages (user/assistant, DB-stored)

Plus: Wiki pages, Ontology, Comments, Dependencies, Work sessions, Context snapshots, Human input requests, Agent directives.

CLI

rc project create "MyApp" --directory /path/to/myapp --priority high
rc project list / show / update / delete

rc epic list / show / create / update / delete
rc issue list / create / start / done / delete

rc context                          # full work context
rc context save RC-P1 "progress..." # save snapshot
rc session start / end / list

rc wiki list / search
rc search "keyword"
rc ontology show / rebuild

MCP Tools (40+)

API

All endpoints under /api/v1, authenticated via Authorization: Bearer <api-key>.

Full endpoint list: Dependencies, Locks, Ontology, Search, Comments, Agents, Directives, SSE streaming.

Testing

cd packages/web && pnpm test:e2e   # 14 Playwright E2E tests

Documentation

• docs/SETUP.md — Installation and configuration
• docs/SESSION_GUIDE.md — Agent session workflow

License

Apache 2.0