> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twill.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How Twill Works

> Learn about Twill's multi-agent architecture, sub-agent workflow, and self-verification against a real dev environment.

### Built on CLI Agents

Twill doesn't reinvent the wheel—it orchestrates existing CLI coding agents like Claude Code and OpenCode. This is intentional:

1. **Tools developers already use**: CLI agents are the same tools you use daily in your terminal. There's no new interface to learn, and the code they produce follows the same patterns you'd write yourself.

2. **Optimized by AI labs**: Model providers like Anthropic, OpenAI, and Google train models to use their toolchains effectively. By delegating work to these CLIs, Twill can take advantage of that optimization.

### Sub-Agent Architecture

Twill uses specialized sub-agents for different phases of a task. Not every task uses every sub-agent, but the overall workflow looks like this:

<Steps>
  <Step title="Research & Planning (optional)">
    If you request a plan (or the task is ambiguous), the Planning Agent explores
    the repo, asks clarifying questions, and produces an implementation plan for
    you to approve.

    See [Research & Planning](/agent/planning).
  </Step>

  <Step title="Implementation">
    The main coding agent implements the changes and adapts when reality doesn't
    match assumptions (for example, existing patterns or unexpected edge cases).
  </Step>

  <Step title="Dev Environment Setup (when needed)">
    If the dev environment is missing or unhealthy, Twill delegates to a Dev
    Environment Agent to create or fix the bootstrap script, ports, and required
    environment variables. The Dev Environment Agent runs on the long-lived
    workspace sandbox, so its fixes persist to every future task fork.

    See [Automatic Environment Setup](/auto-onboarding) and [Dev Environment](/sandbox-environment).
  </Step>

  <Step title="Verification + Review">
    Twill runs mechanical checks (tests, linting, type checking, builds) and
    delegates a focused review to a Code Reviewer Agent to catch logic issues and
    missed requirements.

    See [Verification](/agent/verifies).
  </Step>

  <Step title="Commit">
    Once verification passes and review feedback is addressed, Twill delegates to
    a Commit Agent to create clean, reviewable commits.
  </Step>
</Steps>

### Self-Verification in a Real Dev Environment

What makes this verification loop actually work is that Twill runs your entire project inside a real [dev environment](/sandbox-environment) — a long-lived per-workspace sandbox that hosts every connected repo, forked per task so concurrent runs stay isolated. The agent doesn't just write code — it:

* **Starts your dev server** using your entrypoint script
* **Runs your test suite** to catch regressions
* **Manually tests UI changes** using browser automation
* **Calls API endpoints** to verify backend changes
* **Inspects logs** to confirm services are healthy

This helps catch mismatches early and reduces back-and-forth during review.