Skip to content

README.md

Latest commit

 

History

History
103 lines (68 loc) · 3.97 KB

README.md

File metadata and controls

103 lines (68 loc) · 3.97 KB

coven

An oven for claude. A minimal streaming display and workflow runner for Claude Code's -p mode. The native TUI is resource-heavy, blocks on permission prompts, and doesn't support custom workflows. Coven wraps claude -p --output-format stream-json for a lightweight display with follow-up messages, mid-stream steering, and looping workflows.

Install

# Homebrew
brew install Crazytieguy/tap/coven

# Shell (macOS/Linux)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Crazytieguy/coven/releases/latest/download/coven-installer.sh | sh

# Cargo
cargo install coven

Platform support: macOS and Linux only.

Quick Start

coven "explain this codebase"             # single session
coven ralph "pick one task from TODO.md, do it, check it off"
coven init && coven worker                 # multi-agent orchestration from brief.md

Pass flags to the underlying claude CLI after -- (e.g. coven "prompt" -- --resume SESSION_ID).

Commands

coven [PROMPT]

Interactive session with streaming display. Supports follow-up messages, mid-stream steering, message inspection (:N), and dropping into the native Claude TUI (Ctrl+O).

coven ralph <PROMPT>

Loop Claude: sends the same prompt in fresh sessions until the model outputs a <break> tag. The model can output <wait-for-user> to pause for human input before continuing; Ctrl+W also triggers a wait after the current turn.

Flag Description
--prompt-command CMD Shell command producing each iteration's prompt on stdout (env: COVEN_ITERATION, 1-based; non-zero exit ends loop). Replaces positional PROMPT.
--iterations N Max iterations (0 = infinite, default)
--break-tag TAG Custom break tag (default: break)
--no-break Disable break detection (requires --iterations or --prompt-command)
--no-wait Disable <wait-for-user> tag detection

Walk a list of files, fresh session per file:

coven ralph --prompt-command \
  'F=$(ls src/*.rs | sed -n "${COVEN_ITERATION}p"); [ -z "$F" ] && exit 1; echo "Improve $F and commit"'

coven worker

Orchestration worker. Creates a git worktree, runs agents that chain via <next> transitions, and sleeps until new commits appear on main.

Flag Description
--branch NAME Worktree branch name (random if omitted)
--worktree-base DIR Base directory for worktrees (default: ~/.coven/worktrees)
--no-wait Disable <wait-for-user> tag detection (same as ralph)

coven init

Set up orchestration for a project. Creates .coven/ directory with agent prompts and config, plus brief.md for tasks.

coven status / coven gc

Show active workers / clean up orphaned worktrees.

Flag Description
--force Force removal of dirty worktrees (gc only)

Shared Flags

All session commands (coven, ralph, worker) accept:

  • --show-thinking — stream thinking text inline instead of collapsing
  • --fork — let the model spawn parallel sub-sessions via <fork> tags
  • --reload — let the model reload claude via <reload> tags (preserves session)
  • -- [ARGS] — pass extra arguments to the claude CLI (e.g. -- --resume SESSION_ID)

When stdin isn't a terminal (scripts, CI, piped input), coven runs headlessly: no hints, no follow-up prompt, and <wait-for-user> is disabled. coven without a prompt errors in this mode.

Orchestration

coven init + coven worker enable multi-agent orchestration. Write tasks in brief.md, then start workers:

# Brief
Choose between two activities:
- Inspect program output across test scenarios and document issues in issues.md
- Pick up an issue from issues.md and do it

Workers run a generic agent loop: dispatch reads brief.md and picks tasks, then chains through main and review agents via <next> transitions. Run multiple workers for parallel execution. See .coven/system.md after init for details.

License

MIT