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.
--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, and a local task_list.json pre-wired as the task source. The list-tasks and main host workflows are configured end-to-end out of the box.

Open .cloche/task_list.json to see the task format and add your own work items.

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 result lands on a cloche/<run-id> branch ready to inspect and merge.

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

Next Steps