Skip to main content
tiny-brain doesn’t ask the agent (or you) to report progress. A task’s phase is derived from its commit history — git is the database, and the hooks are the only writers.

​
How a phase is derived

Each task in a plan has a stable identity (a UUID stamped into the plan markdown). As commits land with that task’s Task: header, the hooks record which commit played which role:
  • a test: commit → the task’s RED commit
  • a feat: / fix: commit → the task’s GREEN commit
  • a refactor: commit during an active review → the review-refactor commit
The current phase falls out of what’s recorded: no commits yet → red (a failing test is the next step); test commit only → still red until the implementation lands; green commit present → the review pipeline takes over. Ask the CLI directly:

​
Starting a task

Work on a task begins by declaring it — before reading code, designing, or writing tests:
This flips the task to in_progress and starts its RED clock. Without it, the hooks can’t attribute commits to the task and the dashboard timeline can’t follow the work. For tasks with nothing to test (docs, config, templates), --phase green records that RED was deliberately skipped.

​
Who writes what

Everything else is projection. On current versions, progress state lives per-clone under .git/tiny-brain/ and can be rebuilt from the commit history in any clone — see the tracking model. The practical rule that keeps the model sound: never hand-edit tracking state. If the state looks wrong, the fix is finding the hook that should have written it.