Project Layout

After running cloche init --new, a project has the following structure:

my-project/
+-- .cloche/
|   +-- develop.cloche        # Container workflow
|   +-- host.cloche           # Host orchestration workflows (list-tasks, main, release-task)
|   +-- Dockerfile            # Container image definition
|   +-- config.toml           # Project configuration
|   +-- version               # Schema version marker (used for upgrade checks)
|   +-- prompts/              # Prompt templates
|   |   +-- implement.md
|   |   +-- fix-tests.md
|   |   +-- fix-merge.md
|   +-- scripts/              # Host-side scripts
|   +-- overrides/            # Files copied on top of /workspace/ in the container
|   |   +-- CLAUDE.md         # Container-specific CLAUDE.md (optional)
|   +-- task_list.json        # Sample task file for local development and testing
|   +-- runs/                 # Runtime state (gitignored)
|   |   +-- <task-id>/
|   |       +-- prompt.txt    # User prompt
|   +-- activity.log          # Append-only JSONL activity log (attempt/step events)
|   +-- logs/
|       +-- <task-id>/        # Grouped by task
|           +-- <attempt-id>/ # One directory per attempt
|               +-- full.log                  # Unified log (all steps)
|               +-- <workflow>-<step>.log     # Per-step script output
|               +-- <workflow>-llm-<step>.log # Per-step LLM conversation
+-- cloche_init_test/
|   +-- cloche/
|       +-- test_cloche.py    # Validation tests for the Cloche setup
+-- .clocheignore             # Workspace file exclusions (patterns to omit from container)
+-- src/                      # Your project source (untouched by Cloche)
+-- .git/

Key Files

Workflow files (*.cloche)

Define the step graph, wiring, and configuration for each workflow. See the DSL Reference for syntax.

Dockerfile

Builds the container image used for container workflows. Must include the cloche-agent and clo binaries, git, an agent user, and your project’s build dependencies. See Dockerfile Requirements.

config.toml

Per-project configuration controlling orchestration behavior, evolution, and per-agent settings. See the Configuration Reference.

prompts/

Markdown prompt templates referenced by file() in workflow steps. By convention, one file per prompt step.

scripts/

Host-side shell scripts used by script steps in host workflows (e.g. get-tasks.py, claim-task.py, prepare-prompt.sh).

overrides/

Files placed here are copied on top of /workspace/ in every container at start time. Useful for container-specific configuration like a CLAUDE.md file. This directory is checked into version control — do not put secrets here.

runs/

Runtime state directory, automatically gitignored. The daemon creates a subdirectory per task for prompt files and temporary data. Cleaned up automatically when runs complete.

activity.log

An append-only JSONL file recording attempt and step lifecycle events with timestamps and outcomes. Readable with cloche activity.

logs/

Step output logs grouped by task and attempt. Each attempt directory contains a unified full.log and per-step logs split by type (script output vs LLM conversation).

.clocheignore

Works like .gitignore — patterns listed here are excluded from the project copy sent to containers. Useful for large directories (build artifacts, datasets) that the agent doesn’t need.