Ravel is a task orchestrator for interactive AI coding sessions. It keeps
plans as version-controlled Markdown, lets you choose work with fzf, and
hands each task to an AI agent with a task-specific review and integration
prompt.
Ravel owns task files, dependency checks, task selection, and prompt generation. workmux owns the agent command, Git branches and worktrees, shared files, multiplexer windows, merge behavior, and cl A628 eanup. There is no Ravel server, database, runtime state, or configuration file.
Ravel v2 supports macOS and Linux and requires Node.js. Install it from npm:
npm install --global @initrc/ravelfzf is the only mandatory external
command. Bare ravel cannot open its task picker without it.
Git, tmux, and workmux are recommended for the complete parallel workflow. If Git, tmux, or workmux is unavailable, Ravel falls back to a manual prompt instead of preventing you from working on the task.
Run the prerequisite checks at any time:
ravel doctorravel doctor checks fzf as mandatory and Git, tmux, and workmux as
recommended. A missing recommended tool is reported but does not make the
command fail.
Initialize Ravel in the root of a repository:
cd your-project
ravel initThis creates ravel/docs/ and ravel/tasks/, installs
ravel/docs/ravel-conventions.md if it does not exist, and creates or updates
only the ## Ravel Conventions section of AGENTS.md. Re-running the command
is safe: it preserves an existing conventions file and all unrelated
AGENTS.md content.
When upgrading an existing Ravel project, replace
ravel/docs/ravel-conventions.md with the current
bin/templates/ravel-conventions.md from the installed Ravel package. Ravel
preserves the project copy during ravel init, and current versions rely on it
for the implementation, review, and integration workflows.
Create tasks by asking your AI agent, for example:
Create a Ravel task for each of the following:
- Add dark mode to settings
- Fix pagination's off-by-one errorThe generated AGENTS.md instructions require the agent to read the Ravel
conventions before creating or implementing tasks. Tasks are Markdown files
with YAML frontmatter:
---
id: T0001
title: Add dark mode
status: new
dependencies: []
---
# Scope
- Add a dark mode setting.
# Acceptance
- The setting persists between launches.
# Implementation Notes
- Start with the settings module.Then launch the picker:
ravelRavel delegates the full worktree lifecycle to workmux. Follow the workmux documentation for installation and configuration details. This is the minimal configuration for direct prompt delivery to Codex:
agent: codex
base_branch: auto
panes:
- command: <agent>
focus: trueChoose any agent supported by workmux. The agent value controls what
<agent> launches, base_branch: auto starts each task from workmux's
effective main branch, and the agent pane receives Ravel's generated prompt
directly.
Keep workmux-specific choices in its global or project configuration. Workmux owns agent commands, base and merge branch behavior, worktree paths, copied or symlinked files, setup hooks, pane and window layouts, merging, and cleanup. Ravel neither reads nor writes workmux configuration.
Ravel does not emit a system notification when a task becomes ready for review. The agent reports readiness and ends its turn, so any turn-completion notification belongs to the configured agent. Ravel does not install or require workmux agent-status hooks or tmux status icons.
After approval and a successful merge, the retained
workmux merge --rebase --notification command lets workmux send its native
merge notification. That notification is independent of the agent's
turn-completion behavior.
Bare ravel searches upward from the current directory for ravel/tasks/.
When Git is available, it reads git worktree list --porcelain -z, loads the
primary worktree's tasks as the authoritative collection, and finds each
task's live state from the registered worktree whose branch exactly matches
the task filename. This works with custom worktree locations because Ravel
uses Git's registered absolute paths rather than guessing a directory.
The fzf picker shows every task that is not yet done in the primary
worktree, grouped in this order:
merge-ready T0001 Approved but not integrated
review-ready T0002 Waiting for human review
in-progress T0003 Agent is implementing
new T0004 Ready to start
blocked T0005 Waiting for dependenciesThe preview displays the complete live task file. Enter selects a task and
Escape cancels without launching anything. blocked is derived from
incomplete dependencies and cannot be selected for implementation.
The two readiness states are also derived rather than stored:
review-readymeans the matching worktree's task is inreviewwhile the primary task remains open.merge-readymeans the matching worktree's task isdonebut that approved commit has not reached the primary worktree. It also keeps interrupted rebase, verification, or merge work visible.
Selecting a new, in-progress, or review-ready task with Git, tmux, and
workmux available runs the equivalent of:
workmux add <task-branch> --open-if-exists --prompt <generated-prompt>Workmux creates or reopens the worktree and injects the prompt directly into
the configured agent pane. Ravel does not also copy the prompt on this
successful path. Selecting merge-ready reopens the registered worktree
without generating a duplicate implementation prompt.
ravel/docs/ravel-conventions.md is the source of the task lifecycle. The
generated prompt supplies only the selected task file and whether the launch
uses the workmux or manual workflow. Before approval, the conventions tell
the agent to:
- Moves a new task to
in-progressbefore implementation. - Implements only that task and runs its required verification.
- Moves the task to
reviewwhen it is ready for a human. - Reports that the task is ready for review and stops without committing.
- Waits for the user to say
LGTMexplicitly.
After explicit LGTM, the workmux conventions tell the agent to:
- Set the task to
doneand create exactly one task commit. - Run
workmux rebase, resolve any conflicts, and verify the rebased result. - Only after verification succeeds, run
workmux merge --rebase --notification. - If a newer merge-time conflict occurs, resolve it, verify again, and retry the same workmux merge command.
The separate rebase prevents a conflict-free merge from integrating and
cleaning up the worktree before the rebased result has been tested. Workmux
resolves the saved base and merge target, performs the merge, sends its native
successful-merge notification, and cleans up its resources. The conventions
explicitly mark these two post-LGTM workmux commands as narrow exceptions to
the general Ravel prohibitions on agent-owned merge and deletion. Direct Git
push, merge, rebase, worktree removal, and branch deletion remain prohibited.
If Git, tmux, or workmux is unavailable—or workmux launch fails—Ravel switches to the manual prompt variant. It reports the unavailable tools, copies the full prompt to the clipboard, and also prints it so clipboard failure cannot lose the instructions. Clipboard writing is used only for this manual/error fallback.
Open an AI agent in the checkout where you want to work and paste the prompt.
Ravel does not create a branch, change directories, update task status, or
start an agent in manual mode. The same review gate applies, but after LGTM
the manual workflow in the conventions stops after the single approved commit
and leaves rebase, merge, and cleanup to you.
For a merge-ready task without workmux, Ravel prints its registered branch
and worktree path so you can resume integration manually; it does not copy a
new prompt.
| Command | What it does |
|---|---|
ravel |
Check fzf, discover live task states, and open the picker |
ravel init |
Install or refresh the repository-local Ravel structure |
ravel doctor |
Check mandatory and recommended prerequisites |
ravel --help |
Show command help |
ravel --version |
Show the installed package version |
- Remove the
.ravel/directory. - Replace
ravel/docs/ravel-conventions.mdwith the currentbin/templates/ravel-conventions.mdfrom the installed Ravel package. - Run
ravel initto refresh the Ravel section inAGENTS.md.
Existing task and design documents under ravel/ remain valid. Ravel v2
neither reads nor recreates .ravel/.