Task Lifecycle

Every testy-claw run goes through a predictable sequence of phases. Understanding the lifecycle helps you debug failures and write better tasks.

Phases

• 1. Load — read claw.config.ts and resolve all tools
• 2. Context — load any contextFiles specified in config or via --context
• 3. Plan — send task + tool descriptions to the model, receive a step list
• 4. Execute — run each step; feed output back to the model after each one
• 5. Complete — task is marked done when the model signals completion
• 6. Log — write the full run record to .claw/runs/<timestamp>.json
• 7. Report — print the summary to stdout and exit 0 (or non-zero on failure)

Exit codes

0   — task completed successfully
1   — task failed (model error, tool error, or unhandled exception)
2   — maxSteps reached before task completed
3   — timeout exceeded on a tool call
4   — config error (invalid claw.config.ts)

Run log format

Each run produces a JSON file in .claw/runs/. The file contains the full conversation, every tool call and its result, timing data, and the final status.

{
  "id": "run_abc123",
  "task": "add a README.md",
  "status": "completed",
  "startedAt": "2024-01-15T10:32:11Z",
  "completedAt": "2024-01-15T10:32:13Z",
  "steps": [
    {
      "index": 1,
      "tool": "fs.read",
      "input": { "path": "package.json" },
      "output": "{ "name": "my-project" }",
      "durationMs": 12
    },
    {
      "index": 2,
      "tool": "fs.write",
      "input": { "path": "README.md", "content": "..." },
      "output": "42 lines written",
      "durationMs": 8
    }
  ]
}

Error handling

If a tool call throws, the error message is fed back to the model. The model can choose to retry with different arguments, skip the step, or abort the task. You can control retry behaviour with the maxRetries config option.