Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quickstart

In this walkthrough you set up a workflow that runs on its own: whenever you add a feature file to your project, agents investigate the codebase and break the feature into tasks. You need tmux, Claude Code, and tome installed, and a git repository with some code in it.

1. Start the daemon

The daemon watches for triggers and starts runs. Start it in the background:

tome daemon start
tome daemon status

status prints whether it is running, and exits with code 3 if it isn’t. To have it start at login, run tome daemon install once. See Operating tome.

2. Add the workflow

tome looks for workflows in .tome/workflows in your project. Create a starter file:

cd my-project
tome workflow new plan-feature

That writes .tome/workflows/plan-feature.md. Replace its contents with this:

---
name: plan-feature
description: When a feature file is added, investigate the codebase and break the feature into tasks.
mode: orchestrated
triggers:
  - manual
  - file: "features/*/feature.md"
    on: [created]
    debounce: 5s
---
A feature was just written down. Work out how it fits this codebase and
break it into tasks.

New feature files (empty for a manual run):

{{trigger.paths}}

## Find features
Each path above looks like `features/<slug>/feature.md`. If there are no
paths, use every directory under `features/` that has a `feature.md` but no
`tasks.md`. Skip any feature that already has a `tasks.md`. If nothing is
left, finish the run successfully and say so.

## Investigate
Create a group named `investigate`. For each feature, spawn an agent worker
in it named `investigate-<slug>`. Tell it to read the feature file, then
find the code the feature touches: the modules and entry points, the tests
that cover them, and any similar feature that was built before. It must not
change any files. It reports as its summary the files that will change, the
patterns to follow, and any risks or open questions. Wait for the group.

## Break down
For each feature, write `features/<slug>/tasks.md` from the feature file and
its investigator's summary. Give each task a `### <N>. <title>` heading, a
`**Blocked by:**` line (task numbers, or `none`), and a short paragraph on
what changes, where, and how to tell it's done. Keep each task small enough
for one agent to implement and test as a single commit. List open questions
at the end.

## Hand off
For each feature that got a `tasks.md`, publish an event so the next
workflow can pick it up:

    tome publish feature.planned <slug>

## Finish
Finish the run with each feature and its number of tasks. If an
investigator failed, name its feature and fail the run.

Here you paste a finished workflow so you can see one work. For your own workflows, ask your coding agent to write them; see Create workflows with an agent.

The frontmatter holds the trigger: a feature.md created under features/. The body is plain English, split into steps under ## headings. tome never parses it; an orchestrator agent reads it. {{trigger.paths}} is replaced with the new files when the run starts.

Check it, and confirm the daemon has picked up the trigger:

tome validate plan-feature
tome triggers ls

3. Write down a feature

Describe a small change you actually want in this project. For example:

mkdir -p features/export-csv
cat > features/export-csv/feature.md <<'EOF'
# Export to CSV

Add a `--csv` flag to the export command. It writes the same rows as the
default output, as CSV with a header line.
EOF

That’s all you do. A few seconds later the daemon starts a run:

tome runs list

The run works like this:

  1. tome starts an orchestrator agent in a tmux session and gives it the workflow, with features/export-csv/feature.md filled in.
  2. The orchestrator reports each step, and spawns a worker agent named investigate-export-csv.
  3. The worker reads the code the feature touches and reports what it found, without changing anything.
  4. The orchestrator writes features/export-csv/tasks.md and publishes a feature.planned event.

4. Watch it

Each agent runs in its own tmux session. In another terminal:

tmux ls
tmux attach -t <session>

You can type into an agent’s session at any time, to answer a question or steer it. Detach with Ctrl-b d.

To see a run’s steps, history and logs:

tome runs show <id>
tome runs logs <id>

When the run succeeds, read features/export-csv/tasks.md. Change anything you disagree with; it’s your plan now.

5. Keep going

Every feature file you add from now on gets the same treatment. Nothing subscribes to feature.planned yet, so for now that event goes nowhere. Add the implement-feature recipe and each planned feature is built too, one agent and one branch per task. To build the feature you just planned, publish the event again yourself:

tome publish feature.planned export-csv

To try a trigger without touching files, fire it by hand:

tome triggers fire plan-feature --path features/export-csv/feature.md

You can also start any workflow yourself with tome run <name>. It stays attached and prints progress until the run ends.

Next