A task orchestration tool for interactive AI coding

Ravel is named after Maurice Ravel, the French composer and conductor. The tool takes on analogous roles:

• Composer: converts ideas into structured data — manages tasks and design docs as version-controlled Markdown files.
• Conductor: assigns tasks to AI coding agents in isolated git worktrees, then integrates their work back into the main branch. It also shows which tasks are blocked by dependencies and watches files for real-time status.

Ravel keeps task management scoped narrowly to what AI coding agents need — task files, dependencies, and statuses. It doesn't try to be a full project management tool. Unlike headless auto-orchestrators, Ravel runs interactive AI sessions: the human stays in the loop, reviewing and steering the agent in real time. Interactive sessions handle the complexity that one-shot automation can't.

Everything lives in the repo as plain files. Tasks and docs are Markdown with YAML frontmatter. No database, no server, no external services. AI handles the chore of keeping them organized, but the files are yours.

# Install
npm install -g @initrc/ravel

# Initialize a project
cd your-project
ravel init

This creates ravel/docs/ and ravel/tasks/ directories, a .ravel/config.json, and appends Ravel conventions to your AGENTS.md.

The TUI provides a real-time dashboard with task columns (New, In Progress, Review, Blocked), an event log, and slash commands — plus an interactive task picker for assignment. All commands also work in the CLI.

Ravel is built on a few deliberate choices:

UNIX-y design. Each command (init, assign, integrate, prompt) does one thing. They compose via the shell — ravel prompt T0003 --copy && cd .worktrees/T0003 && claude chains prompt generation, directory navigation, and agent launch into a single command.

Filesystem as the database. There is no database. Tasks and docs are Markdown files. Runtime state lives in JSON session files. The TUI watches the filesystem (chokidar) for changes — when a builder updates a task status in a worktree, the dashboard reflects it immediately. No daemon, no IPC.

Git worktrees for parallelism. ravel assign creates an isolated git worktree per task on a dedicated branch. Multiple tasks can run concurrently without stepping on each other. When a task is done, ravel integrate rebases the worktree branch onto local main, runs tests, and fast-forwards — all locally, no remote required.

Human-in-the-loop. Ravel is intentionally not a headless autonomous agent system. It launches interactive builder sessions where you review code as it's written. Integration only happens when you say "LGTM."

Tasks are plain Markdown files in ravel/tasks/. You create them by asking your AI coding agent:

Create a Ravel task for each of the following:
- Add dark mode toggle to settings
- Fix off-by-one error in pagination

The agent follows AGENTS.md (generated by ravel init), which references ravel/docs/ravel-conventions.md for the task format, naming rules, and valid statuses. New tasks appear immediately in the TUI dashboard.

.ravel/config.json:

{
  "agentCommand": "claude",
  "copyCommandByDefault": false,
  "mainBranch": "main",
  "testCommand": "npm test",
  "notifyWhenDone": true
}

Set testCommand to "" to skip tests during integration. agentCommand is whatever launches your AI coding tool.

TypeScript (ESM), Ink (terminal UI), Commander (CLI), Chokidar (file watching), native git CLI (worktree and branch operations).