lauren CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm run build       # tsc → dist/, then chmod +x the lauren bin
npm run watch       # tsc --watch
npm run clean       # remove dist/
npm run check       # biome check --write (lint + format + organize-imports)
npm run lint        # biome lint only
npm run format      # biome format --write
npm test            # vitest run (one-shot)
npm run test:watch  # vitest in watch mode

Tests live next to source as *.test.ts (Vitest, ESM, Node >=20). Verify changes by npm run build && npm run check && npm test. Manual smoke test: from a throwaway repo, run lauren vibe --dry-run to print the queue, and lauren --list to inspect state (plain table; omit --list for the interactive TUI).

External binaries

The runtime shells out to two CLIs that must be on $PATH:

• claude — used interactively (planning, spec) and as the default agent for the implement / fix pipeline phases, brain JSON decisions, and merger conflict resolution.
• codex — used as the default agent for the review pipeline phase (codex exec review -o <file> <prompt>).

Per-phase agent selection is configurable in .lauren/config.json under agents: each of implement, review, fix, merger, and brain independently accepts "claude" or "codex". The adapters live in src/agents/ and implement the CodingAgent port (runEdit, runReview, runJson) — see src/agents/types.ts.

If a binary is missing for any role configured to use it, lauren vibe will fail at the corresponding step.

Architecture

Lauren is a single-daemon system that drains a plan queue end-to-end without further human input.

lauren CLI (src/bin/lauren.ts) — the single public executable. lauren plan spawns interactive claude with PLAN_SYSTEM_PROMPT; that claude session writes .lauren/plans/<slug>.md and re-invokes the CLI as lauren _register <slug> --path ... --title ... (a hidden subcommand) to add a row with status enqueued to .lauren/plans.json. The default lauren (no subcommand) is an interactive Ink TUI (src/tui/TodoApp.tsx) showing the queue; --list (or non-TTY) prints a static colored table instead. Selecting a row dispatches to cancelPlan (src/cancel.ts) which routes by status (see Cancellation below). The TUI also supports two queue-level actions: t on a failed row resets it to ready via retryPlan (src/retry.ts), and r triggers a brain reorganize pass that re-thinks the whole ready queue (refused while lauren vibe is running, detected via .lauren/vibe.pid).