Litus

A web-based orchestrator for Claude Code agents.
Welcome to vibe code hell.

Submit a feature spec, watch a Claude Code agent work through it step-by-step in your browser, answer its questions when it gets stuck, and end up with a merged PR. Litus handles the entire lifecycle — from specification to CI green to merge — so you can focus on the parts that actually need a human brain.

• Fully automated pipeline — Describe a feature, hit start. Litus takes it from spec to merged PR without manual intervention — specification, planning, implementation, code review, PR creation, CI monitoring, and merge all happen automatically.
• Epic decomposition — Got a feature too big for a single pass? Submit it as an epic. Litus breaks it into individual specs with dependency tracking and runs them in the right order, parallelizing where possible.
• Human-in-the-loop when needed — When the agent hits ambiguity, Litus detects the question and surfaces it in the UI. You answer, it resumes. Everything else runs hands-off.
• CI-aware — Litus monitors GitHub Actions after PR creation. If CI fails, the agent reads the failure logs and fixes the issue — no copy-pasting error output into a chat window.
• Git worktree isolation — Every workflow runs in its own worktree. Your main branch stays clean, and multiple workflows can run in parallel without conflicts.
• Observable and configurable — Real-time agent output streaming, periodic progress summaries, and per-step configuration for models, effort levels, prompts, and retry limits.
• Max plan justifier — Finally a reason to upgrade to the Claude Max plan. Your unlimited-feeling usage won't feel so unlimited after a few epics.

Litus runs Claude Code agents against a target repository — the repo where you want code changes to happen. Before starting your first workflow, make sure the target repo is set up:

1. Authenticate gh — Run gh auth login and make sure the CLI has access to the target repo. Litus uses gh for PR creation, CI polling, and merge.
2. Authenticate Claude Code — Run claude once in the target repo to ensure the CLI is authenticated and working.
3. Verify git access — Litus creates worktrees inside the target repo. Make sure you have push access and the repo is cloned (not a shallow clone).

# Clone
git clone https://github.com/s-gehring/litus.git
cd litus

# Install dependencies
bun install

# Build client + start server with hot reload
bun run dev

Open http://localhost:3000. Override with the PORT env var.

For production (client must be pre-built):

bun run start

A pre-built image is published to GitHub Container Registry on every release.

docker run -d \
  -p 3000:3000 \
  -e ANTHROPIC_API_KEY \
  -e GH_TOKEN \
  -v litus-data:/home/litus/.litus \
  -v /path/to/your/repo:/home/litus/repos/my-project \
  ghcr.io/s-gehring/litus:latest

Litus runs Claude Code agents against a target repository — the repo where code changes happen. You must bind-mount each target repo into the container so the agent can access it:

-v /path/to/your/repo:/home/litus/repos/my-project

The container path you choose (e.g. /home/litus/repos/my-project) is what you'll select in the Litus UI when starting a workflow. You can mount multiple repositories:

-v ~/projects/frontend:/home/litus/repos/frontend \
-v ~/projects/backend:/home/litus/repos/backend

The container ships with Claude Code CLI installed globally. It needs valid credentials to call the Anthropic API.

Option A — API key (recommended for containers)

Pass your key as an environment variable:

docker run -d \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e GH_TOKEN="ghp_..." \
  -p 3000:3000 \
  -v litus-data:/home/litus/.litus \
  -v /path/to/your/repo:/home/litus/repos/my-project \
  ghcr.io/s-gehring/litus:latest

Option B — Mount an existing Claude session

If you have already authenticated with claude on the host, bind-mount the credentials directory instead of setting ANTHROPIC_API_KEY:

docker run -d \
  -e GH_TOKEN="ghp_..." \
  -v ~/.claude:/home/litus/.claude \
  -p 3000:3000 \
  -v litus-data:/home/litus/.litus \
  -v /path/to/your/repo:/home/litus/repos/my-project \
  ghcr.io/s-gehring/litus:latest

The entrypoint automatically creates the required subdirectories (workflows/, audit/) and fixes ownership on bind mounts.

mkdir -p ./litus-data

docker run -d \
  -e ANTHROPIC_API_KEY \
  -e GH_TOKEN \
  -p 3000:3000 \
  -v ./litus-data:/home/litus/.litus \
  -v ~/projects/my-app:/home/litus/repos/my-app \
  ghcr.io/s-gehring/litus:latest

1. You enter a feature spec in the browser and hit Start
2. Litus creates a git worktree and spawns claude -p <spec> --output-format stream-json
3. The agent works through the pipeline: specify → clarify → plan → implement → review → PR → CI → merge
4. When the agent asks a question, it's surfaced in the UI — you answer, the session resumes
5. When CI fails, the agent reads the logs and tries to fix it (up to your configured limit)
6. When everything's green, Litus squash-merges the PR and cleans up

Epic decomposition with dependencies	Creating a new specification
Pipeline in progress with live output	Agent asking a question

Litus orchestrates a 13-step pipeline. Each step is either handled by Litus itself or delegated to a Claude Code agent.

In Manual automation mode, Litus pauses before merging so you can review the PR. At that pause, you can:

• Resume — merge the PR as-is.
• Provide Feedback — type free-form feedback. Litus spins up a dedicated feedback-implementer agent that reads your feedback, makes the requested changes, commits with Conventional Commit messages, and pushes. When the change is materially relevant to the PR outcome, the agent also losslessly augments the PR description on GitHub.
• Abort — stop the workflow entirely.

After a feedback iteration lands commits, CI re-runs, and you return to the same merge-pause with the same choices — iterate as many times as you need.

The Provide Feedback button only appears in Manual mode. In Normal or Full Auto modes the workflow merges automatically and the button is never shown.

How feedback is applied to later agents. Every submitted feedback entry is persisted alongside the workflow and injected as an authoritative "USER FEEDBACK (overrides spec/plan on any conflict)" block into every subsequent agent prompt (including fix-ci and review iterations). If a later agent could otherwise undo your change to match the original spec, the feedback block tells it to preserve your preference.

Semantics.

• Empty or whitespace-only feedback acts as Resume — no entry is created, the iteration counter does not advance.
• Only one feedback iteration can run at a time per workflow.
• Pausing then aborting during a feedback run records the iteration as cancelled and terminates the workflow.
• Restarting the server during a feedback run records the iteration as cancelled and rewinds to the merge-PR pause, so you can retry with the same or different feedback.

Iteration history — text, timestamp, outcome badge, and any non-fatal warnings (e.g., PR description update failed) — is always visible on the workflow detail view.

For features too large for a single workflow, Litus supports epics:

1. Click New Epic and describe the feature at a high level
2. Litus decomposes it into individual specs with dependency tracking
3. Specs execute in dependency order and as parallel as possible — downstream workflows wait for their blockers to complete
4. The epic tree view shows the full dependency graph and per-spec status

Click the gear icon in the header to open the config panel. Everything is configurable per-step:

• Models — Choose which Claude model to use for each pipeline step
• Effort levels — low, medium, high, or max per step
• Prompts — Customize question detection and review classification prompts
• Limits — Max review iterations, CI fix attempts, merge retries
• Timing — Poll intervals, idle timeouts, summary frequency
• Auto Mode — Skip optional checks and auto-answer questions (for the brave)

Config is persisted to ~/.litus/config.json.

All data lives under ~/.litus/:

~/.litus/
  config.json                  # App configuration
  workflows/
    index.json                 # Workflow index
    {id}.json                  # Individual workflow state
    epics.json                 # Epic definitions
  audit/
    events.jsonl               # Audit log

Litus orchestrates a few external tools. Here's what they do and where to find them:

Anthropic's CLI for Claude. This is the actual agent that reads your code, writes implementations, and creates PRs. Litus spawns it as a child process and communicates via --output-format stream-json. All AI interactions go through the CLI — Litus has zero direct API calls, so there's no extra API cost beyond your normal Claude Code usage. Think of Litus as the control tower and Claude Code as the plane.

GitHub's official CLI. Litus uses it for PR creation, CI status polling, failure log retrieval, and squash-merge operations. You'll need it installed and authenticated (gh auth login).

A set of Claude Code skills that power the specify → implement pipeline. These live in your target repository's .claude/skills/ directory and give the agent structured prompts for each pipeline step. If speckit skills are missing from a target repo, Litus auto-installs them via uvx during the setup step.

bun run dev    # Build client + start server with --watch

bun test                       # Run tests
bun run tsc --noEmit           # Type check
bunx biome ci .                # Lint & format (CI mode)
bunx biome check --write .     # Auto-fix lint & format
bun audit                      # Dependency vulnerability scan

1. Fork the repo
2. Create a feature branch (feat/your-thing)
3. Make your changes — keep commits atomic and small
4. Follow Conventional Commits for all commit messages (CI enforces this on PRs)
5. Run bunx biome ci . and bun test before pushing
6. Open a PR against master

Linting is enforced by Biome. CI will reject anything that doesn't pass biome ci, type checking, tests, or conventional commit checks. Don't fight it.

This project is licensed under the GNU Affero General Public License v3.0.

This project utilizes AI products to generate code. The outputs of these tools are not covered by the AGPL license. The authors of this software do not claim any ownership rights over the code or other artifacts generated by the software.