Getting Started

Cloche runs LLM agents — like Claude Code — inside isolated Docker containers to automate coding tasks. You define a workflow, point it at a task list, and Cloche picks up work, runs the agent, and hands back results as clean git branches ready for review.

This quick-start takes you from a fresh project to a running workflow in three steps.

1. Install Cloche

If you haven’t already, follow the Installation guide to build Cloche from source and start the daemon. Confirm it’s ready:

cloche --version

2. Get oriented

Before running cloche init, skim the Basic Concepts page. It introduces the four primitives you’ll see in the generated files — workflows, steps, wires, and agents — and explains the difference between host and container environments. The rest of this page makes more sense once those four ideas click.

3. Your First Workflow

From the root of a git repository, scaffold a starter project:

cloche init --new

--new generates the workflow files, Dockerfile, prompt templates, and scripts that make up a working project. Without it, cloche init only refreshes the .cloche/ config and registers the project with the daemon — useful for existing projects, but it won’t give you anything to run.

Common flags you’ll reach for on this first run:

Flag When to use it
--workflow <name> Name the starter workflow something other than develop (creates .cloche/<name>.cloche).
--base-image <image> Use a custom base Docker image instead of cloche-agent:latest.
--agent-command <cmd> Override the LLM used during the init analysis phase (defaults to claude).
--no-llm Skip the LLM-assisted placeholder filling. Recommended for CI or offline setups.
--no-commit Skip the automatic commit of the generated scaffold.
--install-shell-helpers One-time: install bash/zsh completion scripts.

Full flag reference: cloche init.

What gets created

After cloche init --new, your project has a .cloche/ directory with a starter workflow, a Dockerfile, prompt templates, host scripts, and a bundled copy of the getting-started tutorials at .cloche/docs/init/. The list-tasks and main host workflows are configured end-to-end out of the box.

The default task tracker is beads: if the bd CLI is installed and .beads/ doesn’t exist, init runs bd init and creates two starter validation tasks. If bd is missing, init prints install instructions and still generates the scaffold — re-run cloche init --new after installing to create the starter tasks. The tracker is swappable; the bundled tutorials cover replacing it with your own.

Init finishes by committing the generated files (Add cloche scaffold), because containers are seeded from a clean git snapshot of the last commit — uncommitted files are invisible in-container. Use --no-commit to skip this.

A few files contain TODO(cloche-init) placeholders that the init LLM auto-fills by analyzing your project. To review what’s left:

grep -r 'TODO(cloche-init)' .cloche/

Start the loop

cloche loop

Cloche runs list-tasks to find the open task, spins up a Docker container, passes the task to the configured agent, and streams progress to your terminal. When the agent finishes, the daemon extracts its work onto a result branch and the scaffold’s merge step rebases it onto your branch and fast-forwards — the change lands directly on your current branch, and the task is closed in the tracker. If the merge fails, the result branch and its worktree (under .gitworktrees/cloche/) are kept for inspection.

cloche status        # see active runs
cloche logs <run-id> # tail the output of a specific run

Next Steps