# Bring your own keys Source: https://docs.twill.ai/agent-config/byok Run tasks on your own provider API keys at provider rates — Twill bills nothing for the AI usage. With BYOK, model requests go directly from the sandbox to the provider using your API key. You pay the provider at their rates; Twill tracks the spend for visibility but doesn't bill it. Sandbox compute stays covered by your plan. BYOK is available on the **Max** plan. See [Pricing](/pricing). ## Supported providers Configure keys in **Settings → Bring Your Own Keys**. Each provider takes an API key and an optional base URL (for proxies or compatible gateways): | Provider | Env vars set in the sandbox | Used by | | ---------- | ------------------------------------------------- | --------------------- | | Anthropic | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL` | Claude Code, OpenCode | | OpenAI | `OPENAI_API_KEY`, `OPENAI_BASE_URL` | Codex, OpenCode | | Google AI | `GOOGLE_GENERATIVE_AI_API_KEY`, `GOOGLE_BASE_URL` | OpenCode | | OpenRouter | `OPENROUTER_API_KEY`, `OPENROUTER_BASE_URL` | OpenCode | ## Behavior * Keys are stored encrypted and injected only into your workspace's sandboxes. * If a task's model has no key configured for its provider, the task falls back to platform credits. * Base URLs are scoped per provider, so you can route one provider through a gateway while others go direct. # MCP servers Source: https://docs.twill.ai/agent-config/mcp Built-in MCP tools from your integrations, plus custom servers via a .mcp.json in your repo. Agents reach external systems through [MCP](https://modelcontextprotocol.io/) tools and CLIs available in the sandbox. ## Built in * **Context7** — up-to-date library documentation, available on every task * **Linear** and **Notion** — MCP tools appear automatically when the [integration](/integrations/overview) is connected * **GitHub** — via the authenticated `gh` CLI (not MCP) * **Browser automation** — via the `agent-browser` CLI, which powers UI verification ## Custom servers Add a `.mcp.json` at your repo's root and the coding agents pick it up: ```json .mcp.json theme={"theme":"github-dark"} { "mcpServers": { "my-tool": { "type": "stdio", "command": "npx", "args": ["-y", "my-mcp-server@latest"] }, "database": { "type": "stdio", "command": "uvx", "args": ["postgres-mcp", "--access-mode=readonly"], "env": { "DATABASE_URI": "${DATABASE_URL}" } }, "internal-api": { "type": "http", "url": "https://mcp.myservice.com", "headers": { "Authorization": "Bearer ${MY_API_TOKEN}" } } } } ``` * `stdio` servers run as a command inside the sandbox (`npx`, `uvx`, …). * `http` servers are remote endpoints. * `${VAR_NAME}` references resolve from your workspace [environment variables](/environment#environment-variables--secrets), so secrets stay out of the repo. # Agents & models Source: https://docs.twill.ai/agent-config/overview Choose which coding agent and model runs each task — Claude Code, Codex, or OpenCode. Twill orchestrates the CLI coding agents you'd use in your own terminal, rather than reinventing one. Pick per task in the composer, set workspace defaults with [routing configs](/agent-config/routing), or run the same task with several agents in parallel and keep the best PR. ## Available agents | Agent | By | Models | | --------------- | ----------- | ------------------------------------------------------------------------- | | **Claude Code** | Anthropic | Claude Fable, Opus, Sonnet, Haiku | | **Codex** | OpenAI | GPT 5.6 Sol, GPT 5.6 Terra, GPT 5.6 Luna, GPT 5.5, GPT 5.4, GPT 5.3 Codex | | **OpenCode** | Open source | Multi-provider — see below | OpenCode runs frontier and open-weight models side by side: Kimi K3, DeepSeek V4 Pro, GLM 5.3 Flash, Qwen3.8 Max, GPT 5.6 Sol / Terra / Luna, GPT 5.5 / 5.4 / 5.3 Codex, Gemini 3.1 Pro, Gemini 3.6 Flash, Claude Opus 5, Claude Sonnet 5 — plus any OpenRouter model via the **OpenRouter…** picker. A pragmatic split: frontier models for hard tasks, open-weight models for routine ones. With [BYOK](/agent-config/byok) you pay provider rates for both. ## Reasoning effort Every model runs at an effort level: `low`, `medium`, `high`, or `xhigh` — higher effort means deeper reasoning and longer runs. Claude Code adds `ultracode`, which combines maximum effort with multi-agent workflows for the hardest tasks. ## Defaults Set what runs when you don't choose explicitly in **Settings → Routing**: the `default` routing config defines the workspace's standard agent, model, and effort, and `/trigger` keywords let a single message opt into something else. See [Routing](/agent-config/routing). ## Memory Agents persist non-obvious learnings — setup quirks, conventions, gotchas — to `CLAUDE.md` or `AGENTS.md` in the relevant repo, and read those files at the start of every task. Memory is plain Markdown in your repo: reviewable in PRs, portable across all three agents, and yours to edit. # Repository skills Source: https://docs.twill.ai/agent-config/repository-skills Teach Twill your team's procedures with SKILL.md files that live in your repos. A skill is a procedure the agent can follow — "how we deploy", "how to add an API endpoint", "how to write a migration" — written as Markdown in your repo. Twill discovers skills across all connected repos and uses them when tasks call for them. ## Writing a skill A skill is a directory containing a `SKILL.md`: ```markdown .claude/skills/deploy/SKILL.md theme={"theme":"github-dark"} --- name: deploy description: Deploy a service to staging and verify it's healthy --- 1. Run `make build SERVICE=`. 2. Push the image: `make push SERVICE=`. 3. Apply with `kubectl apply -f k8s//staging/`. 4. Verify: `curl https://staging.example.com//health` returns 200. ``` * `name` is optional (falls back to the directory name); `description` is recommended — it's how the agent decides when the skill applies. * The body is free-form Markdown. Add a `scripts/` directory alongside for helper scripts. ## Where skills live | Location | Notes | | -------------------------------- | -------------------------- | | `.claude/skills//SKILL.md` | Canonical, preferred | | `.agents/skills//SKILL.md` | Vendor-neutral alternative | If both define the same name in one repo, `.claude/skills` wins. The same name in different repos yields two entries, labeled by repo. Skills are read live from GitHub at task time — nothing to sync. ## Using skills Type `/` in the task composer to browse and insert a skill reference: The composer's slash menu listing repository skills Agents also find and follow skills on their own when a task matches a skill's description. Repository skills teach Twill's agents procedures in *your* codebase. The [Twill agent skill](/local-agents) is the inverse — it teaches your local agent to delegate to Twill. # Routing Source: https://docs.twill.ai/agent-config/routing Map trigger keywords to a mode, agent, and effort — so `/plan` or `/ultra` means the same thing everywhere. Routing configs decide how a new task runs when it arrives — from any surface. Each config is a row in **Settings → Routing**: | Field | Meaning | | ----------- | -------------------------------------------------------------------------------------------------------- | | **Trigger** | The keyword that selects this config, written as `/keyword` (e.g. `ultra`) | | **Mode** | `agent` (implement), `plan` (plan first), `ask` (read-only Q\&A), or `goal` (iterate until a goal holds) | | **Agent** | Which harness + model runs the task (e.g. Codex GPT 5.5) | | **Effort** | `low`, `medium`, `high`, `xhigh` — plus `ultracode` on Claude Code | Every workspace has an undeletable **`default`** config — the fallback when no trigger matches. New workspaces default to agent mode, Codex GPT 5.5, medium effort. Configs can also carry custom instructions appended to the task. ## Using triggers Start a task message with the trigger: ```text theme={"theme":"github-dark"} @twill /ultra fix the race condition in the export worker ``` The trigger is stripped before the agent sees the message. How a trigger fires depends on the surface: | Surface | How to fire a config | | -------------------- | ------------------------------------------------------------------ | | Web app | Pick mode/agent directly in the composer | | Slack, Notion, Asana | `/trigger` at the start of the message | | GitHub | `/trigger` in the text, **or** an issue label matching the trigger | | Linear | An issue label matching the trigger | Routing applies to a task's first message only. Follow-ups keep the task's existing agent and mode. # API Source: https://docs.twill.ai/api Create and manage tasks programmatically with the Twill REST API. The REST API covers the full task loop: create tasks, poll status, stream history, approve plans, send follow-ups, and cancel runs. Anything you can do from the web app's composer, you can script. ## Authentication Create a key in workspace **Settings → API Keys** (it's shown once — store it safely; you can set an expiration). Keys are workspace-scoped and start with `twill_`. ```bash theme={"theme":"github-dark"} curl https://twill.ai/api/v1/tasks \ -H "Authorization: Bearer $TWILL_API_KEY" ``` ## Basics * **Base URL**: `https://twill.ai/api/v1` * **Rate limits**: 100 requests/minute, 1000/hour per key * **Errors**: JSON envelope `{ "error": { "code", "message", "details?" } }` * **Pagination**: list endpoints take `limit` and `cursor`, and return `nextCursor` while older entries exist ## Quick example ```bash theme={"theme":"github-dark"} # create a task curl -X POST https://twill.ai/api/v1/tasks \ -H "Authorization: Bearer $TWILL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"command": "Fix the flaky signup test"}' # follow its history curl "https://twill.ai/api/v1/tasks/{taskIdOrSlug}/jobs?limit=20" \ -H "Authorization: Bearer $TWILL_API_KEY" ``` Interactive playground with request/response schemas for every endpoint. Prefer a terminal? The [CLI](/cli) wraps this API — tasks, automations, teleport, and sandbox SSH included. # Approve plan Source: https://docs.twill.ai/api-reference/approve-plan openapi.json POST /tasks/{taskIdOrSlug}/approve-plan Approve a drafted plan and start implementation. Call after a `plan` run finishes with `planOutcome: "READY"`. Implementation starts from the approved plan. # Cancel task Source: https://docs.twill.ai/api-reference/cancel-task openapi.json POST /tasks/{taskIdOrSlug}/cancel Stop a task's active runs. Marks the task `CANCELLED` and stops in-flight jobs. You can still follow up afterwards to resume work on the same thread. # Create task Source: https://docs.twill.ai/api-reference/create-task openapi.json POST /tasks Dispatch a new task and start an agent run. Create a task from a `command` prompt. No repository or branch is supplied — the agent picks the repo(s) at runtime from the workspace's connected repos. Optional fields: `userIntent` sets the initial run type; `agent` pins a harness as a full `/` id (a provider-only value is rejected); `files` attaches uploaded assets, with each file's content inlined as a `data:` URL (remote `http(s):` URLs are not fetched). Otherwise mode, model, and effort come from your [routing configs](/agent-config/routing) — include a `/trigger` in `command` to select one. The response includes the created task plus its first queued job. # Get task Source: https://docs.twill.ai/api-reference/get-task openapi.json GET /tasks/{taskIdOrSlug} Fetch one task by id or slug. Look up a task by its UUID or its human-readable slug. # List task jobs Source: https://docs.twill.ai/api-reference/list-task-jobs openapi.json GET /tasks/{taskIdOrSlug}/jobs A task's chronological run history. Returns the task's jobs — plans, implementation runs, follow-ups — oldest context first, with cursor pagination (`limit`, `cursor`, `nextCursor`). Use this to render a task's timeline or poll for progress. # List tasks Source: https://docs.twill.ai/api-reference/list-tasks openapi.json GET /tasks List the workspace's tasks, newest first. Supports cursor pagination (`limit`, `cursor`) and a `status` filter. Each task includes its latest job status and linked pull requests. # Send message Source: https://docs.twill.ai/api-reference/send-message openapi.json POST /tasks/{taskIdOrSlug}/messages Send a follow-up message to a task. Continues the task with your message — answer a clarifying question, request changes, or redirect the work. Optional `userIntent` (`"PLAN"`, `"SWE"`, `"ASK"`, `"DEV_ENVIRONMENT"`) switches the run type; `files` attaches assets, with each file's content inlined as a `data:` URL (remote `http(s):` URLs are not fetched). # Automations Source: https://docs.twill.ai/automations Recurring tasks on a schedule: issue triage, dependency updates, monitoring — set up once, reviewed as PRs. Automations are tasks that run on a schedule. Anything you'd delegate once, you can delegate every morning: triage new issues, update dependencies, watch error trackers, clean up stale PRs. Each run behaves like a normal task — same dev environment, same verification, same PR-based review. The Automations page with scheduled tasks and templates ## Creating an automation Open **Automations** in the sidebar and click **New Automation** (or start from a template): 1. Write the instructions, as you would for a regular task. 2. Pick the agent that runs it. 3. Set the schedule — a preset, a weekly picker, or a cron expression — and the timezone. You can also select **Schedule** mode in the task composer and describe the automation conversationally, or manage automations from the [CLI](/cli#automations) and [API](/api). Automations pull context from whatever [integrations](/integrations/overview) you've connected: GitHub issues and PRs, Linear sprints, Slack channels, Notion databases, Sentry errors, GCP and AWS logs. Automations require a paid plan — see [Pricing](/pricing). ## Templates The template gallery on the Automations page ships ready-made recurring tasks, maintained as a community catalog that grows over time. A sample of what's there: * **Daily issue triage** — scan open GitHub issues every morning: label, prioritize, spawn fixes * **Error monitoring triage** — fetch new unresolved Sentry errors and fix the actionable ones * **Cloud log error triage** — query GCP or AWS logs for new errors and crashes * **Weekly dependency updates** — update dependencies and verify the build still passes * **Sprint automation** — pick up ready Linear issues from the current sprint and start coding * **Flaky test detection** — mine CI history for flaky tests and verify with targeted reruns * **Stale PR cleanup** — nudge, rebase, or close stale pull requests Every template is editable before you enable it — they're just task instructions with a schedule. ## Managing automations Each automation can be **toggled** on/off, **force-triggered** to run now, **edited**, or **deleted**. Every run shows up as a task, so history and artifacts are always reviewable. Schedules use standard 5-field cron: `minute hour day-of-month month day-of-week`. | Expression | Meaning | | ------------- | ------------------------ | | `0 * * * *` | Every hour | | `0 */6 * * *` | Every 6 hours | | `0 9 * * *` | Every day at 9 AM | | `0 9 * * 1` | Mondays at 9 AM | | `0 9 * * 1-5` | Weekdays at 9 AM | | `0 9 1 * *` | First of the month, 9 AM | # CLI Source: https://docs.twill.ai/cli Create and manage Twill tasks, automations, and sandboxes from your terminal. ```bash theme={"theme":"github-dark"} npm install -g @twillai/cli ``` Requires Node.js 18+. Running `twill` with no arguments opens an interactive TUI; every capability is also available as a plain command for scripting. ## Authentication Create an API key in workspace **Settings → API Keys**, then: ```bash theme={"theme":"github-dark"} twill login --api-key twill_xxx twill whoami # verify twill logout ``` Credentials are stored in `~/.twill/credentials.json`. For CI or scripts, set the `TWILL_API_KEY` environment variable instead. Use `TWILL_BASE_URL` to target a self-hosted instance. Keys are workspace-scoped. Use named profiles to switch between workspaces: ```bash theme={"theme":"github-dark"} twill login --api-key twill_xxx --profile work twill tasks --profile work ``` ## Tasks ```bash theme={"theme":"github-dark"} # create twill task create --command "Fix the flaky signup test" \ [--mode code|plan|ask|dev_env] \ [--agent claude-code/opus] \ [--effort low|medium|high|xhigh] \ [--title "..."] # inspect & iterate twill tasks # list twill task # details twill task continue --message "also update the docs" twill task logs # stream live logs twill task archive twill resume # open the task in the TUI ``` In the TUI, use `/tasks`, `/resume `, `/agent`, `/forks`, and `/exit`. ## Automations ```bash theme={"theme":"github-dark"} twill automation create --title "Issue triage" \ --message "Triage new GitHub issues: label, prioritize, summarize" \ --cron "0 9 * * 1-5" [--timezone Europe/Paris] twill automations # list twill automation # details twill automation edit --cron "0 10 * * 1" twill automation pause|resume|delete ``` ## Teleport Pull a task's full context down to your machine and continue it in your local agent: ```bash theme={"theme":"github-dark"} twill teleport # writes a local Claude Code session claude -r # resume it ``` By default the session attaches to a matching project in `~/.claude/projects/`; use `--project ` to pick one explicitly. ## Sandbox access ```bash theme={"theme":"github-dark"} twill ssh # SSH into the workspace VM twill fork scratch # fork the VM under a name, then SSH in twill ssh scratch # reconnect to that fork ``` Forks are recorded in `~/.twill/forks.json`. Lifecycle: idle forks stop after 30 minutes, archive after 24 hours, and are deleted 7 days after last use. Fork names allow letters, digits, `-`, and `_`. # Desktop & mobile Source: https://docs.twill.ai/desktop-app Twill as a native desktop app with notifications and auto-updates, and as a mobile PWA for following your factory from your phone. ## Desktop app The desktop app wraps your Twill workspace in a native window with system notifications — so you see plans awaiting approval and finished tasks without keeping a browser tab open. Download from [twill.ai/download](https://twill.ai/download): | Platform | Package | Requirements | | -------- | ------------------------------- | ------------------- | | macOS | `.dmg` (Apple Silicon or Intel) | macOS 10.15+ | | Windows | x64 installer | Windows 10+ | | Linux | `.deb` or `.AppImage` | Ubuntu 22.04+ (x64) | **Sign-in** happens in your system browser and hands back to the app via a `twill://` link — no separate credentials. **Updates** are checked on start and every few hours, then installed automatically. On Linux, auto-update works for the `.AppImage` build only; `.deb` installs update through your package manager. ## Mobile Twill ships as a PWA at [twill.ai/m](https://twill.ai/m) — create tasks, answer questions, approve plans, and follow runs from your phone. Add it to your home screen for an app-like experience, and enable push notifications to hear about plans and finished tasks the moment they land. # Your dev environment Source: https://docs.twill.ai/environment A long-lived workspace sandbox that runs your whole stack — forked per task, verified against, and yours to inspect over SSH. Every workspace gets one long-lived cloud sandbox — the **workspace VM** — with all your connected repos cloned, dependencies installed, and dev servers running. Each task runs in a disposable **fork** of that VM, so tasks start from a warm, working state and can't interfere with each other. This is what makes [verification](/verification) real: the agent doesn't just compile your code, it runs your app. The Environment page: workspace VM sizing and environment variables ## Automatic setup On your first task (or whenever the environment breaks), Twill's dev environment agent bootstraps the sandbox by reading your repos: * Detects package managers from lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `poetry.lock`, …) and frameworks (Next.js, Django, Rails, FastAPI, …) * Brings up services from `docker-compose.yml` and waits for them to be healthy * Runs database migrations and seeds * Starts dev servers in the background, with logs captured * Uses `.env.example` and your CI config as hints for what the app needs Fixes made during setup run on the workspace VM itself, so they persist for every future task. You can trigger this any time: create a task with **Dev Env** mode — "set up the dev environment", or "the API server won't start, fix it". Changes made in Dev Env mode persist to the workspace VM. ## Environment variables & secrets Configure variables on the **Environment** page: * **Global** variables are injected into every task fork. * **Per-repository** variables are written to a `.env` file inside that repo on the VM. Values are encrypted at rest (AES-256-GCM). You can also just ask in a task — "I've added `STRIPE_SECRET_KEY` to the environment, wire it up" — and the agent picks it up. ## Live previews Each task exposes its running app as a live preview: a browser tab streamed from the task's sandbox, pre-opened on your dev server's port. Open it from the task header to try the change yourself before the PR lands — no tunnel or proxy configuration needed. Service logs are captured per task under `$TWILL_ENTRYPOINT_LOG_DIR` and surfaced in the task view (`dev-server.log`, `api.log`, `entrypoint.log`). ## SSH access Click **Open in** on the Environment page (or **SSH & Preview** in a task header) to get a token-scoped SSH command, valid for 60 minutes. Connect from: * Your terminal (`ssh://` link) * VS Code or Cursor via Remote-SSH — full editor access to the sandbox This works for both the workspace VM and any task fork. It's the escape hatch: inspect state, fix something by hand, or take over a task midway. The [CLI](/cli) offers the same via `twill ssh` and `twill fork`. ## What's in the sandbox Repos are cloned to `/root/workspace/{owner}/{repo}` on an Ubuntu 22.04 base image. * **Runtimes**: Node.js LTS (via nvm), Python 3 - **Package managers**: pnpm, npm, uv, pip - **Containers**: Docker Engine with the Compose plugin (`docker compose up -d`) - **CLI tools**: git, gh, jq, make, curl, wget, openssl - **Cloud CLIs**: AWS CLI v2, Google Cloud CLI (authenticated via workspace env vars) - **Browser**: headless Chromium — Puppeteer and Playwright are auto-detected - **Display**: Xvfb virtual display, which powers computer-use UI verification Choose the workspace VM size on the Environment page. Larger sizes and custom snapshots (preinstalled dependencies, GPUs, bigger resources) are available on paid plans — see [Pricing](/pricing). For custom snapshots, contact [dan@twill.ai](mailto:dan@twill.ai). # What to delegate Source: https://docs.twill.ai/first-tasks The tasks Twill handles best, and how to phrase them for a fast, reviewable PR. Twill works like a teammate you brief asynchronously: the clearer the request and the more mechanically verifiable the outcome, the better the result. This page is a menu of what to hand off. ## Good first tasks Start with changes that have a clear before/after, so you can judge the PR in one glance: * **Bug fixes** — "Clicking Save on the profile page throws a 500 when the avatar is missing. Fix it." * **UI polish** — "The mobile nav overflows on screens under 380px. Make it wrap or truncate." * **Small features** — "Add a 'Copy link' button to the share dialog, with a toast on success." * **Test coverage** — "Add tests for the date-range parser, including timezone edge cases." * **Docs & chores** — "Update the README setup steps to match the current docker-compose file." ## What Twill is well-suited for * **Changes that need the running app.** Twill starts your dev servers, clicks through UI flows in a browser, and calls your API endpoints — so it catches problems a diff review can't. Web apps get screenshots and recordings; Tauri, Electron, and React Native apps get computer-use smoke checks when they run in the sandbox. * **Multi-repo changes.** One task can touch several connected repos (frontend + backend + shared packages) and open a PR in each. * **Recurring maintenance.** Dependency updates, issue triage, stale-PR cleanup — set them up once as [automations](/automations). * **Codebase questions.** Use [Ask mode](/planning#ask-mode) to get answers with file references, no code changes. ## Writing a good task A good prompt states the outcome, not the implementation: ```text theme={"theme":"github-dark"} When a user deletes their account, cancel any active Stripe subscription before removing the user row. Cover it with a test. ``` * **Say how to verify it** if it's not obvious: "You can reproduce it on the /pricing page with an expired coupon." * **Point at context** when you have it: an issue link, a failing CI run, a Slack thread — or trigger the task directly from that thread so the context comes along. * **Ask for a plan first** on larger or riskier work. Twill researches the codebase and posts an implementation plan you approve before any code is written. See [Plans & questions](/planning). ## What to keep for yourself Twill delivers PRs — it doesn't merge, deploy, or run one-off commands against production. Deep architectural rewrites with fuzzy success criteria work better broken into steps, each with its own verifiable outcome. # How Twill works Source: https://docs.twill.ai/how-it-works The architecture: real CLI agents, specialized sub-agents, and self-verification against a running app. ## Built on the agents you already use Twill orchestrates existing CLI coding agents — Claude Code, Codex, OpenCode — rather than shipping its own harness. That's deliberate: model providers train and tune their models against their own toolchains, so delegating to those CLIs inherits that optimization, and the code they produce follows the same patterns your team writes locally. ## Sub-agents keep context focused A long task rots when one context window has to hold everything. Twill splits work across specialized sub-agents, each starting fresh with only what its phase needs: The planning agent explores the repo, asks clarifying questions, and produces a plan for approval. See [Plans & questions](/planning). The main coding agent implements the change, adapting when the codebase doesn't match assumptions. If the dev environment is missing or unhealthy, a dedicated agent repairs the bootstrap on the long-lived workspace VM — so the fix persists for every future task. See [Your dev environment](/environment). Mechanical checks (tests, lint, types, build) plus a focused pass by a code-reviewer agent for logic issues and missed requirements. See [Verification](/verification). A commit agent produces clean, reviewable commits and the PR. ## Self-verification against a real environment What makes the loop work is that tasks run inside a fork of your workspace's dev environment — the whole stack, live. The agent doesn't stop at writing code; it starts your dev server, runs your tests, drives the UI in a browser, calls your API endpoints, and reads service logs until it has observed the change working. The artifacts of that observation are what land on the PR as [proof](/verification#proof-on-the-pr). # Asana Source: https://docs.twill.ai/integrations/asana Comment on any Asana task to hand it to Twill. Connect Asana in **Settings → Integrations** and authorize via OAuth. Twill listens across all projects in your Asana workspace, including ones created later. ## Start a task Comment on an Asana task, starting with `twill`: ```text theme={"theme":"github-dark"} twill Add dark mode support to the settings screen ``` Twill reacts to the comment, posts an acknowledgment with a link to the Twill task, and keeps questions, plans, and the PR link in the same task's comments. Route mode and model with a `/trigger` after the keyword — for example `twill /plan …` — per your [routing configs](/agent-config/routing). ## What the agent can do in Asana While working, the agent can read the task's details and comments, post progress updates, update fields (like marking the task complete), and upload files. # Amazon Web Services Source: https://docs.twill.ai/integrations/aws Read-only AWS access through a cross-account IAM role — no long-lived keys. The AWS integration lets agents read your AWS resources, logs, and service metadata while debugging. Access is strictly read-only and uses a cross-account IAM role — Twill never stores AWS keys. ## Connect In **Settings → Integrations → Amazon Web Services**, click **Connect**. This opens a CloudFormation quick-create page in your AWS console. Click **Create stack** — it takes about 30 seconds. Copy the **Role ARN** from the stack's Outputs tab, paste it back into Twill, and click **Verify & Connect**. ## How access works * The role carries AWS's managed **ReadOnlyAccess** policy (`List*`, `Describe*`, `Get*`) — no write, modify, or delete permissions. * Its trust policy is scoped to Twill's account plus a unique **external ID**, so only your workspace can assume it. * At task time, Twill calls `sts:AssumeRole` and injects temporary credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`) into the sandbox. They expire after 1 hour. * Every assumption shows up in your CloudTrail, so access is fully auditable. ## Disconnect Disconnect in Twill's settings, then delete the CloudFormation stack in AWS to remove the role entirely. # Datadog Source: https://docs.twill.ai/integrations/datadog Read-only observability context for the agent: monitors, dashboards, and host details. The Datadog integration gives agents read-only visibility into your monitoring while they debug — it doesn't trigger tasks from Datadog events. ## Connect In **Settings → Integrations → Datadog**, enter: * **API key** and **Application key** (created in Datadog) * **Site** — e.g. `datadoghq.com`, or your full API host Keys are stored encrypted and validated on save. No OAuth flow is involved. ## What the agent can do Inside the sandbox, agents get a read-only `datadog` skill built on a [Dogshell-compatible](https://docs.datadoghq.com/extend/guide/dogshell/) wrapper. They can look up monitor states, dashboard definitions, and host details — useful for tasks like "figure out why the p95 latency monitor is flapping and fix the endpoint." Mutating commands are blocked; the integration cannot change anything in your Datadog account. Disconnect by removing the saved credentials on the same settings page. # Google Cloud Source: https://docs.twill.ai/integrations/gcp Read-only access to Cloud Run logs and service status for debugging production issues. Connect Google Cloud in **Settings → Integrations** and authorize via OAuth with read-only scopes. ## What the agent can do While working a task, the agent can read Cloud Run logs and service status — runtime errors, deployment state, request logs. That turns "users report 502s on the API since this morning" into a task the agent can actually investigate, correlating production logs with the code it's changing. Pairs well with [automations](/automations) — for example, a daily check that scans Cloud Run error logs and opens fix PRs for new crash signatures. Disconnect from the same settings page to revoke access. # GitHub Source: https://docs.twill.ai/integrations/github-issues Turn issues into PRs, iterate on review feedback, and let Twill fix CI — all from GitHub. GitHub is connected during [onboarding](/quickstart) by installing the Twill GitHub App on the repositories you choose. That installation powers everything here. ## Start tasks from issues Mention `@twill` in an issue body or comment, or add the `twill` label. Twill reacts with 👀, works the issue in your [dev environment](/environment), and links the resulting PR back. A GitHub issue where @twill was mentioned and answered Plans and clarifying questions post back as issue comments, and your replies continue the task. To force plan-first or pick a model, include a `/trigger` in the text or add a label matching one of your [routing configs](/agent-config/routing) — for example `/plan`. ## Work on any pull request Mention `@twill` in a PR conversation or a code-review thread — on any PR, not just Twill's own. Twill checks out the PR branch and pushes to it. For review feedback: leave `@twill` comments in **unresolved** review threads. Twill waits about 2 minutes to batch multiple comments, then addresses all unresolved threads in one pass. ## Automatic completion & CI fixes * When a PR linked to a task is merged, the task moves to **Completed** on its own. * When CI fails on a Twill PR, Twill reads the logs and pushes a fix — up to 3 attempts per failure. See [Verification](/verification#ci-auto-fix). # Linear Source: https://docs.twill.ai/integrations/linear-issues Delegate Linear issues to Twill with a label or an assignment. Connect Linear in **Settings → Integrations**. Twill creates a `twill` label in your Linear workspace and appears as an assignable teammate. ## Delegate an issue Two ways, both equivalent: * Add the **`twill` label** to an issue * **Assign the issue to Twill** A Linear issue delegated to Twill via label Twill reads the issue (title, description, comments), works it, and posts progress in the issue's thread. The PR is linked when ready, and clarifying questions arrive as comments — reply in-thread to answer. ## Plans and routing To require a plan or select a model, add a label matching one of your [routing config](/agent-config/routing) triggers — for example a `plan` or `ultra` label. On Linear, routing fires on labels (not `/text` triggers). Plans post to the thread with an **Approve** link. To stop a run, say so in the thread. # Notion Source: https://docs.twill.ai/integrations/notion Turn Notion comments into tasks — specs and roadmaps become PRs without leaving the page. Connect Notion in **Settings → Integrations** and grant access to the pages Twill should see. ## Start a task Comment on any accessible page and mention the bot: ```text theme={"theme":"github-dark"} @twill implement the rate-limiting spec described on this page ``` A Notion comment thread with a task delegated to Twill Twill reads the page for context, then keeps the whole loop in the comment thread: clarifying questions, the plan and its approval, progress, and the final PR link. Reply with `@twill` to follow up. Start the request with a `/trigger` (like `/plan`) to route mode and model via your [routing configs](/agent-config/routing). # Work from your tools Source: https://docs.twill.ai/integrations/overview Trigger Twill from GitHub, Slack, Linear, Notion, or Asana — and give it read access to your error trackers and cloud. Twill meets your team where work already lives. Connect a tool once in **Settings → Integrations**, and anyone on the team can hand off tasks from it. Follow-ups stay attached to the same thread — issue, ticket, or comment — so nobody re-explains context. The Integrations page with GitHub connected and other services available ## Trigger tasks | Tool | How to trigger | | ------------------------------------- | ----------------------------------------------------------------------------- | | [GitHub](/integrations/github-issues) | Mention `@twill` on an issue, PR, or review thread — or add the `twill` label | | [Slack](/integrations/slack) | Mention `@twill` in any channel or thread | | [Linear](/integrations/linear-issues) | Add the `twill` label or assign the issue to Twill | | [Notion](/integrations/notion) | Mention `@twill` in a comment | | [Asana](/integrations/asana) | Comment `twill ` on a task | | [Sentry](/integrations/sentry) | Error events flow in as fix proposals | Wherever the task starts, the result is the same: clarifying questions and plans post back to the thread, and the finished work arrives as a [pull request with proof](/verification). Start a message with a `/trigger` keyword (like `/plan` or `/ultra`) to pick the mode, model, and effort for that task — see [routing configs](/agent-config/routing). ## Give the agent context These integrations don't create tasks — they give the agent read-only eyes on your infrastructure while it works and powers your [automations](/automations): | Tool | What the agent can read | | --------------------------------- | ---------------------------------------------------------- | | [Datadog](/integrations/datadog) | Monitors, dashboards, host details | | [Google Cloud](/integrations/gcp) | Cloud Run logs and service status | | [AWS](/integrations/aws) | Resources, logs, and service metadata (read-only IAM role) | ## Other surfaces The [web app](/tasks) gives you the full picture — live agent activity, previews, artifacts. The [CLI](/cli) and [API](/api) cover terminals and scripts, and the [desktop & mobile apps](/desktop-app) keep you notified everywhere else. # Sentry Source: https://docs.twill.ai/integrations/sentry Let Twill investigate production errors with real stack traces and propose fixes. Connect Sentry in **Settings → Integrations** and authorize the Twill integration for your Sentry organization. ## What it does * **Error events can become tasks**: alerts flow to Twill, which investigates the issue and proposes a fix as a PR. * **Context during any task**: agents get read access to Sentry issues and stack traces, so "fix the crash reported in Sentry issue FRONTEND-123" resolves against real data. * **Automations**: pair with an [automation](/automations) to triage new errors on a schedule — deduplicate, prioritize, open fixes for the actionable ones. Disconnect any time from the same settings page; this revokes Twill's access in Sentry. # Slack Source: https://docs.twill.ai/integrations/slack Mention @twill in any channel to turn a conversation into a task — questions and results come back to the thread. Connect Slack in **Settings → Integrations**, then invite the Twill bot to the channels where work gets discussed. ## Start a task Mention the bot with your request: ```text theme={"theme":"github-dark"} @twill the onboarding email renders broken in Outlook — fix the template ``` A Slack thread where @twill picked up a task Twill replies in the thread with clarifying questions, plans (with an **Approve** button), progress, and the finished PR link. Reply with another `@twill` mention to follow up — the thread is the task's memory. Start the request with a `/trigger` like `/plan` or `/ultra` to pick mode and model via your [routing configs](/agent-config/routing). Twill reads only the thread where it's mentioned — not the whole channel. ## Attachments Files in the triggering message (and thread history) are passed to the agent: * **Images**: PNG, JPEG, GIF, WebP — great for screenshots of bugs or design mocks * **Text**: plain text, Markdown * **Data**: JSON, YAML Limits: 10 MB per file, 5 files per message, and up to 10 files pulled from thread history. Unsupported or oversized files are skipped silently. # Use with your local agent Source: https://docs.twill.ai/local-agents Delegate implementation to Twill from Claude Code, Cursor, or any local coding agent — and pull work back down when you want hands on keys. If you already use a coding agent locally, Twill slots in as its heavy-duty backend: brainstorm and spec locally where iteration is fast, then hand implementation to Twill for the parts local agents can't do — full environment builds, integration tests, browser-driven UI verification, live previews. ## Install the Twill skill Tell your local agent: ```text theme={"theme":"github-dark"} Install the skill from https://twill.ai/skill.md and save it to your local skills/ directory. ``` The skill teaches your agent to create Twill tasks, check on them, answer their clarifying questions, and approve plans — all without leaving your terminal. ## The workflow 1. **Spec locally.** Work out what you want with your local agent — requirements, constraints, edge cases. 2. **Delegate.** Your agent sends the spec to Twill as a task. Twill runs it in the cloud, asynchronously. 3. **Stay in your flow.** Follow-ups, questions, and plan approvals round-trip through your local session. 4. **Review the PR.** It comes back with test output, screenshots, and logs — same as any Twill task. ## Teleport: pull a task down locally Sometimes you want hands on keys. `teleport` pulls a Twill task's full context — conversation, plan, work done so far — onto your machine so you can continue it locally: ```bash theme={"theme":"github-dark"} twill teleport # then resume the session in Claude Code: claude -r ``` See the [CLI reference](/cli#teleport) for details, including SSH-ing straight into a task's sandbox instead. # What is Twill Source: https://docs.twill.ai/overview Twill turns task descriptions into pull requests — built and tested in a real dev environment, with proof attached. Twill is a software factory for your team. You describe a change — from GitHub, Slack, Linear, or the web app — and Twill builds it in a cloud dev environment that runs your whole stack, verifies it works, and opens a pull request with the evidence attached. Twill home screen with the task composer and recent tasks ## Why teams use Twill * **PRs come with proof.** Twill doesn't just produce a diff. It runs your build, tests, and lint, starts your app, clicks through UI changes in a browser, and attaches the evidence — test output, screenshots, recordings — to the pull request. * **It runs your whole stack.** Every task runs in a dev environment with your repos cloned, dependencies installed, databases seeded, and dev servers already running. Multi-repo and monorepo setups work out of the box. * **It works where your team works.** Trigger tasks from GitHub issues, Slack mentions, Linear labels, Notion comments, or Asana — and iterate in the same thread. No context re-explaining. * **You stay in control.** Nothing merges automatically. Every change arrives as a pull request for human review, built in an isolated sandbox — agents can't push to your default branch or touch your infrastructure. ## How it works 1. **You describe the change.** From any connected tool, the CLI, the API, or the web app. 2. **Twill asks or plans when needed.** Ambiguous tasks get clarifying questions; you can also require a reviewable plan before any code is written. 3. **An agent implements it** in a fork of your workspace's dev environment, using the coding agent and model you choose (Claude Code, Codex, or OpenCode). 4. **Twill verifies the change** — build, tests, lint, plus runtime checks against the running app. 5. **You review a PR** with a summary and proof-of-work artifacts. For the architecture behind this, see [How Twill works](/how-it-works). ## Start here Connect GitHub and get your first verified PR in minutes. The tasks Twill handles best, with example prompts. Trigger tasks from GitHub, Slack, Linear, Notion, and more. Delegate to Twill from Claude Code or Cursor. # Plans & questions Source: https://docs.twill.ai/planning Clarifying questions, plan-first workflows, and read-only Ask mode. By default Twill implements immediately. But it never guesses silently: ambiguous tasks get clarifying questions, and for larger work you can require a reviewable plan before any code is written. ## Clarifying questions When a request is ambiguous — unclear scope, multiple valid interpretations, missing context — Twill asks before proceeding. Questions are posted to the thread where the task started (Slack thread, GitHub issue, Linear comment, or the web app), and your reply continues the task. Twill asking clarifying questions in the web app ## Plan mode In plan mode, Twill researches your codebase first — reading relevant files, checking existing patterns, consulting library docs — and posts an implementation plan instead of code. A Twill plan with steps and file references You then **approve**, **edit**, or **reject** the plan. Implementation starts only after approval, and the approved plan is what the agent follows. Ways to get a plan: * **Web app**: select **Plan** in the composer's mode dropdown. * **GitHub / Slack / Notion / Asana**: include a plan-mode `/trigger` (for example `/plan`) in the message, per your [routing configs](/agent-config/routing). On GitHub issues, a matching label also works. * **Linear**: add a label matching a plan-mode routing trigger. Use plan mode when the change is large, risky, or when you want to align on approach before spending agent time on implementation. ## Ask mode Ask mode answers questions about your codebase without changing anything — no branch, no PR, read-only. ```text theme={"theme":"github-dark"} /ask How does session refresh work, and where are tokens stored? ``` * **Web app**: select **Ask** in the mode dropdown. * **Slack / GitHub / Notion**: start the message with an ask-mode trigger like `/ask`. * **CLI**: `twill task create --mode ask --command "..."`. Answers include file references so you can jump straight to the code. # Pricing Source: https://docs.twill.ai/pricing Simple credit-based plans. Unlimited users on every tier. Plans are priced on AI usage, not seats — invite your whole team on any tier. **1 credit = \$1 of AI compute at cost**: what the model providers charge is what's deducted, with no markup. | | Free | Pro | Max | | ----------------------------------------- | --------- | --------- | --------- | | Price | \$0/mo | \$50/mo | \$200/mo | | Monthly credits | 5 | 50 | 200 | | Users | Unlimited | Unlimited | Unlimited | | Agents (Claude Code, Codex, OpenCode) | ✓ | ✓ | ✓ | | Automations | — | ✓ | ✓ | | Larger sandboxes & custom snapshots | — | — | ✓ | | [Bring your own keys](/agent-config/byok) | — | — | ✓ | Sign up at [twill.ai](https://twill.ai) — no credit card required. ## How usage works * Credits reset monthly on your subscription anniversary; unused credits don't roll over. * **Free** stops at its cap. **Pro** and **Max** can opt into overage with a spending limit you set in **Settings → Billing**; overage is billed at cost. * Sandbox compute is included in every plan — credits only meter AI usage. * With [BYOK](/agent-config/byok) (Max), model usage goes on your provider bill and consumes no credits. ## Free for open source Maintaining an open-source project? Twill offers a free Pro-level subscription (fair use, no overage) for OSS maintainers — contact [dan@twill.ai](mailto:dan@twill.ai). ## Enterprise Private cloud deployment in your VPC, BYOK, and a codebase audit to find automation opportunities. [Book a call](https://cal.com/dan-c/20min-chat). # Quickstart Source: https://docs.twill.ai/quickstart From sign-up to your first verified pull request in a few minutes. 1. Sign in at [twill.ai/login](https://twill.ai/login) with GitHub or Google. 2. Name your workspace and pick a URL slug. From your workspace home, install the Twill GitHub App and choose which repositories it can access. Twill clones every connected repo into one shared dev environment, so connect all the repos that make up your stack — the agent decides which ones a task touches. Describe a change the way you'd hand it to a teammate. Start small, with a clear before/after, so the first PR is easy to judge: ```text theme={"theme":"github-dark"} Fix the empty state on the settings page: show a link to create the first workspace. ``` Twill reads the relevant code and asks clarifying questions if the request is ambiguous. Before the first real task, click **Set up dev environment** on the home screen. Twill installs dependencies and starts your dev servers once, and every future task starts from that working state — which is what makes runtime verification possible. You get a PR with the change plus whatever proof applies to your repo: test output, logs, screenshots, or a screen recording. Nothing merges automatically. You review Twill's work like any other PR. ## Next up Good first tasks and example prompts. Trigger Twill from GitHub, Slack, Linear, or Notion. What runs inside the sandbox and how to configure it. Get a reviewable plan before any code is written. # Release Notes Source: https://docs.twill.ai/release-notes Weekly updates on new features, improvements, and bug fixes ## Week of August 31, 2026 ### Improvements * **Refreshed Open-Weight Models on OpenCode** - The OpenCode model picker's open-weight entries now offer the latest OpenRouter releases: **DeepSeek V4 Pro** (0813 GA release), **GLM 5.3 Flash**, and **Qwen3.8 Max** join **Kimi K3**, replacing GLM 5.2 and Kimi K2.6 ## Week of August 3, 2026 ### New Features * **Claude Opus 5 & Sonnet 5 on OpenCode** - The OpenCode model picker's Anthropic entries now point at **Claude Opus 5** and **Claude Sonnet 5**, replacing Claude Opus 4.7 and Claude Sonnet 4.6 * **Gemini 3.6 Flash** - Google's new efficiency-focused coding and agentic model is now selectable in the OpenCode model picker alongside Gemini 3.1 Pro ## Week of July 6, 2026 ### New Features * **GPT-5.6 Models (Sol, Terra, Luna)** - OpenAI's new GPT-5.6 tier family is now selectable in the model picker for both the Codex and OpenCode harnesses: **GPT 5.6 Sol** (flagship coding/agentic tier), **GPT 5.6 Terra** (balanced everyday tier), and **GPT 5.6 Luna** (fast, low-cost tier) ## Week of June 22, 2026 ### New Features * **Routing Configs** - Workspaces can map triggers to a mode, harness, effort, and optional instructions so new tasks route automatically from integrations or the composer * **Mermaid Diagrams** - Markdown now renders Mermaid code fences as theme-aware diagrams with loading and fallback states * **Plan Approval Actions** - Plan approvals now support clearing context before implementation or setting an approved plan as a goal on supported harnesses ### Improvements * **Claude Code Task Lists** - Agent logs now render Claude Code TaskCreate and TaskUpdate events as structured todo lists instead of raw tool groups * **Slack Acknowledgments** - Slack task-created replies are shorter and repeated @twill mentions use a lightweight reaction instead of adding thread noise * **Routing Settings UX** - Routing rows now autofocus new triggers, show clearer keyboard focus indicators, and use the Twill logo loading state ### Bug Fixes * Fixed automation instruction editors being trapped in a fixed-height scroll box instead of expanding to fit their content ## Week of June 15, 2026 ### Improvements * **GLM 5.2 Model** - The OpenCode model picker now offers GLM 5.2, replacing the previous GLM 5.1 open-weight entry * **More Resilient Sandbox Fork Retries** - Sandbox fork capacity retries now use exponential backoff with jitter plus a UI indicator, and non-retriable failures fail fast instead of churning through doomed retries ### Bug Fixes * Fixed `pip install` crashing in sandboxes caused by a stale libexpat/pyexpat symbol mismatch ## Week of June 8, 2026 ### New Features * **Task Author & Source Filter** - The home task list now shows each task's author and original trigger source (GitHub, Slack, Linear, Notion, and more), with a new filter to view tasks by author * **Repository Agent Skills in the Composer** - Agent Skills defined in your connected repos now surface in the task composer through a `/` slash menu or natural language, and the agent reads and follows the matching skill at task time ### Improvements * **Skill Insert Names Source Repo** - Inserting a skill from the slash menu now names the repo it came from to disambiguate skills that share a name across repos, with a placeholder hint to type `/` for skills ### Bug Fixes * Fixed sandbox fork retries failing with a "Sandbox with this name already exists" error and deleting healthy idle forks during capacity incidents * Fixed tasks failing instantly when a browser `blob:` attachment URL was submitted instead of an uploaded file ## Week of June 1, 2026 ### Improvements * **Automations Require a Paid Plan** - Automations are now available on Pro and Max plans only, ensuring reliable scheduled task execution for paying workspaces ### Bug Fixes * Fixed a crash when pasting terminal logs containing NUL bytes or invalid Unicode characters into the task composer ## Week of May 25, 2026 ### New Features * **Reactive Repository Sync** - Connected repos now refresh automatically when you push to GitHub, so task forks always use up-to-date base branch code instead of waiting up to 24 hours * **OpenCode Context Compression** - OpenCode agents running on OpenRouter now use server-side middle-out context compression to handle long conversations that would previously hit model context limits * **Refreshed Landing Page** - Updated the landing page and marketing surfaces with a new cream paper-terminal aesthetic ### Improvements * **Multi-Repo Workspace Prompts** - Ask mode and plan mode prompts now align with multi-repo workspace layouts for better context when working across repositories * **Faster Repository Pre-Fork Refresh** - Reduced the stale-repo refresh delay from 24h to 1h as a fallback, complementing the new reactive push-based sync * **Theme-Aware Auth UI** - Sign-in and GitHub connect logos are now theme-aware and match light/dark mode ### Bug Fixes * Fixed sandbox fork lock holes that caused `Cannot POST /api/sandbox/{id}/fork` errors under concurrent load * Fixed GITHUB\_TOKEN being incorrectly injected into the agent daemon environment * Fixed workspace preview links not routing through the Twill proxy * Fixed sandbox HOME directory, git identity, and credential-helper not being properly handed off when attaching to a fork ## Week of May 18, 2026 ### New Features * **UI Redesign** - Launched a major visual redesign of the Twill interface ### Improvements * **Live Sub-Agent Log Nesting** - Agent log Task accordions now collapse by default and sub-agent events nest in real-time as they arrive, making long task logs much easier to scan * **OpenRouter Routing Hardening** - OpenRouter requests now route through the LiteLLM model list instead of a passthrough endpoint, improving reliability and cost tracking ### Performance * Reduced SSE replay tail from 1000 to 100 entries to shrink memory footprint on reconnect * Bounded Redis log persistence `LRANGE` to the last 1000 entries to prevent unbounded growth * Routed task-queue Redis snapshots to the read replica with TCP keepalive enabled ### Bug Fixes * Fixed cancel handler crashing with OOM errors on jobs with high log volume * Fixed log trace not persisting correctly from the in-memory assembler * Fixed OpenRouter streaming usage cost not forwarding into spend logs ## Week of May 11, 2026 ### New Features * **OpenRouter Without BYOK** - OpenRouter models are now available to all users without requiring your own API key ### Security * Updated to Next.js 16.2.6 (May 2026 security release) ### Bug Fixes * Fixed OpenRouter passthrough authentication and virtual key metadata handling ## Week of May 4, 2026 ### New Features * **Automatic API Key Rotation** - LiteLLM API keys now rotate automatically at the end of each Stripe billing period with no grace window, ensuring credits reset cleanly ### Improvements * Added Next.js client-side error boundaries with PostHog capture for better frontend error visibility ### Bug Fixes * Fixed queue and attachment action buttons not appearing on touch devices on mobile * Fixed SSE log replay saturating the Redis primary under heavy reconnect load ## Week of April 27, 2026 ### New Features * **GPT 5.5 Support** - Added OpenAI's GPT 5.5 as a new model option * **Chat in Agentbox** - Agents can now use the chat interface directly within the agentbox environment ### Improvements * **Reduced Task Latency** - Significant latency improvements to task startup and agent execution * **Agent Log UI Components** - Migrated agent-log UI components to the shared ai-elements system for consistency and performance ### Bug Fixes * Fixed the message composer queue button not correctly wiring to the enqueue handler ## Week of April 20, 2026 ### New Features * **PR Attribution Line** - Every pull request opened by Twill now includes an originator attribution line linking back to the task that created it ### Improvements * **Queue Follow-Up UX** - Queued follow-up messages now show an enqueue button instead of a stop button for clarity * **Login Error Messages** - Improved error messages on the login page for clearer guidance ## Week of April 13, 2026 ### New Features * **Claude Opus 4.7 Support** - Added Anthropic's Claude Opus 4.7 as a new model option * **Message Queue** - A Cursor-style message queue lets you stack follow-up instructions while the agent is working, drag to reorder them, and send urgent messages immediately. Queued messages drain sequentially when the current job completes and pause on failure with a Resume option ### Improvements * **Email Validation** - New signups are now validated via ZeroBounce with common forwarder domains blocked to improve deliverability * **OpenCode Error Surfacing** - Upstream provider errors from OpenCode are now surfaced directly in the UI instead of silently failing * **Email Invitation Limit** - Raised the workspace email invitation limit from the previous cap to 500 ### Bug Fixes * Fixed plan mode incorrectly failing jobs on non-fatal error events * Fixed task queue stop behavior and a race condition on Send Now ## Week of April 6, 2026 ### New Features * **Workspace Logo** - Admins can now upload a custom logo for their workspace from the settings page * **Tiered Sandbox Sizing** - Sandbox compute size is now gated by plan tier: small (default, all plans), medium (Pro+), large (Max), and custom snapshots (Pro+) * **CLI `/exit` Command** - Added `/exit` as a slash command in the Twill CLI interactive TUI mode ### Bug Fixes * Fixed GitHub connect not working on mobile devices ## Week of March 30, 2026 ### New Features * **Cross-Task Agent Memory** - Agents now automatically save non-obvious learnings (build commands, project conventions, environment gotchas) to a memory section in `CLAUDE.md` or `AGENTS.md`. These learnings persist in the repo and are loaded on every future task, so agents get smarter about your codebase over time * **Loop Mode** - Added a new loop mode for autonomous, iterative agent execution — the agent keeps running until the task is fully resolved * **Opt-In Dev Environment Setup** - Dev environment setup is now opt-in after connecting GitHub, giving you more control over when environments are provisioned ### Bug Fixes * Fixed a Slack webhook signature verification bypass vulnerability * Fixed incorrect credit definition displayed on the pricing page * Fixed free-tier credit abuse via rapid workspace creation ## Week of March 23, 2026 ### New Features * **OpenRouter as BYOK Provider** - OpenRouter is now supported as a Bring Your Own Keys provider, letting you use any OpenRouter-hosted model with your own API credentials * **Per-Run Cost Tracking** - Added real-time cost tracking per task run so you can see AI spend at a granular level ### Improvements * **Image Auto-Resize** - Screenshots and images exceeding Claude's 2000px dimension limit are now automatically resized before being sent to the model, preventing context errors on large screenshots ## Week of March 16, 2026 ### New Features * **Datadog Integration** - Added a read-only Datadog integration so agents can inspect monitors, dashboards, hosts, and other observability context during tasks * **Workspace Member Management** - Admins can now view and manage workspace members directly from workspace settings * **WebReel Video Recording** - Agents can now produce polished scripted browser demo videos using a two-phase workflow with WebReel; `.mp4` and `.webm` files now render as inline video players in task conversations and PRs ### Improvements * **Asana Integration Hardening** - Resolved critical security and reliability issues including per-project webhook secrets, enforced HMAC signature verification, async event processing, paginated project listing, and proper cleanup on disconnect * **Asana Task Reactions** - Task start and follow-up messages in Asana now include reaction confirmations ### Bug Fixes * Fixed scorecard history leaking across workspaces — past scorecards are now properly scoped to the current workspace * Fixed the Enter key submitting the message composer instead of inserting a newline on mobile * Fixed a left margin gap appearing on the main content area when the sidebar was collapsed * Fixed scorecard UI/UX issues ## Week of March 9, 2026 ### New Features * **Asana Workspace Picker** - Admins can now switch Asana workspaces from the integration card without re-authenticating * **Token Credit Billing** - Billing has migrated from per-run to a token credit system; subscriptions now grant monthly USD credits that offset actual AI usage costs * **GPT 5.4 Codex** - Added GPT 5.4 Codex as a new model option for Codex and OpenCode agent providers * **Agentic Legibility Scorecard** - Added a public scorecard page for analyzing GitHub repository agentic legibility with streamed results ### Improvements * **Codex Native Subagents** - Codex now uses native agent roles for subagents instead of a custom skill shim, with improved collaboration event rendering in agent logs * **Default Branch Pinned in Branch Selector** - The default branch is now pinned at the top of the branch dropdown under a "Default" heading for quicker selection * **OAuth Token Encryption** - All integration OAuth tokens (Linear, Notion, Sentry, GCP, Slack) are now encrypted at rest using AES-256-GCM * **Security Headers** - Added security headers including HSTS, X-Frame-Options, and X-Content-Type-Options to all responses * **Plan Content Sanitization** - Approved plans are now sanitized before agent handoff to neutralize hidden instructions that could be embedded in plan text * **Gemini 3.1 Model** - Updated Gemini model references to version 3.1 across all providers ### Bug Fixes * Fixed agent runs continuing to execute and bill tokens when a job was cancelled during sandbox provisioning ## Week of March 2, 2026 ### New Features * **Twill CLI** - Added a full command-line interface (`@twillai/cli`) for managing tasks and automations from the terminal, with an interactive TUI mode, live log streaming, and teleport to export sessions to Claude Code * **Bring Your Own Keys** - Workspaces can now configure their own API keys for AI providers (Anthropic, OpenAI, Google, xAI), which are used in place of system keys and exempt the workspace from billing credit checks * **Bulk Task Archive** - Added checkbox selection mode on the home page to select and archive multiple tasks in a single batch operation * **Conversational Automations** - Automations can now be created by chatting with Twill, describing what you want scheduled and letting the agent set it up for you ### Improvements * **Clickable Markdown Images** - Images in task chat messages are now clickable to view full-size * **Automation Integration Warnings** - The automation form now shows a warning banner when required integrations are not connected, with a link to the Integrations page ## Week of February 23, 2026 ### New Features * **Delegation Flow on Landing Page** - Redesigned the delegation flow section with a visual 3-column layout showing how tasks flow from inputs through runtime to outputs * **Twill CLI Documentation** - Added comprehensive documentation for the Twill CLI covering installation, authentication, task management, automations, and teleport ### Improvements * **Automation Save UX** - Saving an automation now shows a toast notification; editing stays on the page instead of redirecting, making it easier to iterate on settings * **Third-Party Code Review FAQ** - Added guidance on using third-party code review tools alongside Twill's built-in code review * **Landing Page Cleanup** - Removed the redundant use cases section that overlapped with the automations template gallery ### Bug Fixes * Fixed CodeMirror crashes in the code diff viewer by adding an error boundary with a plain-text fallback * Fixed collapsed sub-agent logs reopening automatically whenever new log events arrived * Fixed ASK mode jobs incorrectly triggering third-party notifications (Slack, Linear, etc.) * Fixed bot PR detection to specifically match Twill bots, avoiding false positives from other bots ## Week of February 16, 2026 ### New Features * **Ask Mode** - Added a read-only Q\&A mode to the message composer where the agent explores the codebase and answers questions without making any modifications * **AWS Integration** - Added an AWS integration with read-only access so agents can query your cloud resources (logs, infrastructure) during task execution * **Voice-to-Text Input** - Added a microphone button to the message composer for recording voice messages that are automatically transcribed to text * **Automated Dev Environment Health Checks** - Added daily automated health checks that verify development environments with configured entrypoint scripts are working correctly * **Newsletter Archive** - Added a newsletter archive page to browse past editions ### Bug Fixes * Fixed subtasks not being linked to their parent tasks when spawned from automations ## Week of February 9, 2026 ### New Features * **Cron-Based Automations** - Added scheduled automations with cron expressions and timezone support so Twill can run recurring workflows automatically * **Sentry Integration** - Added a Sentry integration so you can connect your workspace and trigger Twill tasks from Sentry issue events * **Google Cloud Integration** - Added a Google Cloud integration so you can connect your workspace and trigger Twill tasks from Google Cloud issue events * **Twill Agent Skill** - Published a canonical skill file at twill.ai/skill.md so external agents can learn how to use Twill ### Improvements * **GitHub Selector Defaults** - Automation form now remembers your last-selected repository from the home page composer ### Bug Fixes * Fixed modal links generating double subdomains ## Week of February 2, 2026 ### New Features * **Optional Planning** - Planning is now opt-in (Plan mode), so small changes go straight to implementation by default and run faster * **Agent/Model Overrides in Integrations** - You can set `agent=` and `model=` in Slack/Notion/GitHub/Linear triggers to pick the agent and model for a new task (best-effort matching) * **Computer Use (CLI)** - Added `computer-use-cli`, enabling agents to automate Linux desktop apps in an X11 session via screenshots plus mouse/keyboard CLI commands (great for Electron/Tauri smoke tests) * **Public Tasks API (v1)** - Added API endpoints to create/list/get/cancel tasks, send messages, and approve plans, with an OpenAPI spec in the docs * **Task Status Filter** - Filter tasks on the home page by status (running, completed, failed, archived) with automatic persistence of your selection across sessions * **API Keys Management UI** - Manage API keys directly from workspace settings, including creation, revocation, and editing ### Improvements * **Agent Browser** - Replaced Playwright with a dedicated agent browser for more reliable browser automation during tasks * **Standalone Dev Environment Agent** - Dev environment sub-agent is now a standalone agent for clearer task separation * **Plan ↔ Implementation Handoff** - Improved context sharing and resume behavior between planning and implementation agents * **Slack PR Notifications** - Pull request links are now shown as a "View Pull Request" button for easier interaction (especially on mobile) * **GitHub Integration UX** - Improved the GitHub integration setup and connection experience * **Environment Variables Hidden by Default** - Repository environment variables are now hidden by default for better security ### Bug Fixes * Fixed Codex sub-agent resume and handoff issues * Fixed Slack tasks being accidentally triggered by bot invitations and other system messages * Fixed task page scrolling issues on mobile and when opening tasks via direct links * Fixed low contrast text in preview logs making them hard to read ## Week of January 26, 2026 ### New Features * **Default Repository for Slack** - Configure a default repository for Slack bot interactions so you no longer need to specify a repo each time ### Improvements * **Slack Image Capabilities** - Slack integration now supports posting images via slash commands * **Slack Default Repo Documentation** - Added documentation for default repository behavior and channel-specific repo configuration * **Codex CLI in Supported Models Docs** - Documented the `codex` CLI tool for listing and filtering available models * **Agent Selector UX** - Improved the agent selector experience in the UI ### Bug Fixes * Fixed PR status badge not displaying correctly * Fixed environment variables being fully reset on each run instead of preserving existing values ## Week of January 19, 2026 ### New Features * **Codex Agent Provider** - Added Codex as a new agent provider, expanding the available AI backends for task execution ## Week of January 12, 2026 ### New Features * **GPT 5.2 Codex Agent** - Added support for OpenAI's GPT 5.2 Codex as an agent provider, now available as the default agent * **Security Updates Documentation** - New comprehensive guide on using Twill to automate dependency upgrades and security updates, with real examples and screenshots ### Improvements * **PR Mention Context** - When @Twill is mentioned on a PR, the agent now receives the user's actual comment and CI guidance, eliminating the need to repeat requests * **Improved Repository Selection** - Enhanced repository selection experience in the UI * **Better Task Status Readability** - Improved visual readability of task status indicators * **Webhook Simplification** - Refactored PR webhook handling for cleaner, more maintainable code ### Bug Fixes * Fixed browser freeze when loading tasks with very long messages (100k+ characters) by truncating previews * Fixed notifications not posting back to PRs when @Twill was mentioned (missing database mapping) * Fixed user comment context being lost when handling PR mentions ## Week of January 5, 2026 ### New Features * **Notion Integration** - Create tasks in Twill directly from Notion pages * **Repository Dropdown Search** - Added search functionality to quickly find repositories in the dropdown * **Slack Thread Context** - Twill now includes thread context when responding in Slack conversations * **Slack File Attachments** - Support for file attachments in Slack integration * **Dev Environment Test Card** - New test card in task chat for development environments * **Clarified @Twill Mentions** - Better distinction between available @Twill mentions and upcoming automations ### Improvements * **Configurable Commit Email** - Commit author email is now configurable * **Improved Chat Dialog Images** - Larger image display in chat dialog * **Better Plan Approval UX** - Improved plan approval experience when signing in from Slack or Linear * **Updated OpenCode Documentation** - Refreshed supported models documentation ### Bug Fixes * Fixed icon button display on Safari * Fixed task breadcrumb navigation on mobile devices * Fixed sandbox repo cache clearing when integration is installed * Fixed token refresh for long-running tasks * Fixed MCP Context7 tool name change * Fixed question parsing improvements * Fixed empty answer fallback behavior for third-party integrations * Fixed Slack follow-up and bot mention handling * Fixed repo snapshot image caching * Fixed plan mode visibility of sub-agents * Fixed OpenCode screenshot handling * Fixed message composer visibility with no parsed questions # Legibility scorecard Source: https://docs.twill.ai/scorecard Score how ready your repository is for coding agents — free, at twill.ai/score. The scorecard grades a GitHub repository on **agent legibility**: how easily a coding agent can bootstrap, navigate, and validate work in it. Run it at [twill.ai/score](https://twill.ai/score) — paste a public repo URL, or install the GitHub App for private repos (analyzed with a short-lived, scoped token). Analysis is static — no dependencies installed, no code executed. It's based on OpenAI's [agentic legibility](https://openai.com/index/practice-of-agentic-legibility/) work and runs in a sandboxed container. ## What it measures Seven metrics, each scored 0–3 (max 21), with letter grades A (85%+), B (70%+), C (50%+), D below: | Metric | Question it answers | | -------------------------- | ------------------------------------------------------------- | | Bootstrap self-sufficiency | Can an agent set the project up from the repo alone? | | Task entrypoints | Are build/test/dev commands discoverable (Makefile, scripts)? | | Validation harness | Can changes be verified mechanically (tests, CI)? | | Lint & format gates | Are style rules enforced, not tribal knowledge? | | Agent repo map | Is there an `AGENTS.md`/`CLAUDE.md` orienting agents? | | Structured docs | Do docs explain architecture and conventions? | | Decision records | Are past decisions written down (ADRs, design docs)? | A higher score means agents — Twill's included — waste less time rediscovering your setup and produce better-verified work. The report includes concrete fixes for each low metric. # Security Source: https://docs.twill.ai/security Isolation, least-privilege access, encryption, and human review at the core of the workflow. ## The workflow is the safeguard * **Nothing merges automatically.** Every change arrives as a pull request for human review. Twill has no deploy access. * **Agents can't push to your default branch.** Work happens on task branches; repo access uses short-lived, scoped GitHub tokens. * **Code runs in Twill's sandboxes, not your infrastructure.** Unless you explicitly connect read-only cloud integrations, agents can't see your infra at all. ## Isolation Each workspace gets its own sandboxed VM; each task runs in its own fork with CPU, memory, and disk quotas. Tasks can't see other workspaces or interfere with each other's runs. ## Data protection * Environment secrets and OAuth tokens are encrypted at rest with **AES-256-GCM**; all traffic is HTTPS/TLS. * Incoming webhooks (GitHub, Linear, Slack) are verified with **HMAC-SHA256** signatures using timing-safe comparison; Slack requests older than 5 minutes are rejected to block replays. * OAuth flows carry CSRF-protected state. * **Your code and prompts are never used to train models.** ## Access control Workspace roles — **Owner**, **Admin**, **Member** — govern who can manage integrations, billing, and the team. See [Team management](/team-management). API keys are workspace-scoped, hashed at rest, and rate-limited. ## Third parties Twill relies on a small set of processors: sandbox infrastructure (Modal, Daytona), the integrations you connect (GitHub, Linear, Slack, …), and Stripe for billing (PCI-compliant; Twill never sees card numbers). Model providers process code context per their API terms — or bring [your own keys](/agent-config/byok) and contract with them directly. Questions? See the [privacy policy](https://twill.ai/privacy) or reach out via the website. # Working with tasks Source: https://docs.twill.ai/tasks Create tasks, pick a mode, follow up, and track progress — from the web app or anywhere else. A task is one request to Twill: a bug to fix, a feature to build, a question to answer. Every task runs in its own fork of your workspace's [dev environment](/environment) and reports back where you created it. ## Creating a task Type your request into the composer on the home screen. Twill picks the repository (or repositories) at runtime from your connected repos — you don't select one up front. The composer also gives you: * **Agent & model** — which coding agent runs the task (Claude Code, Codex, or OpenCode) and at what reasoning effort. Defaults come from your [routing configs](/agent-config/routing). * **Attachments** — drop in screenshots, specs, or data files for the agent to reference. * **Voice input** — press Alt+Space to dictate a task. * **Skills** — type `/` to insert a [repository skill](/agent-config/repository-skills) from your codebase. You can also create tasks from [GitHub, Slack, Linear, Notion, or Asana](/integrations/overview), the [CLI](/cli), or the [API](/api). ## Modes | Mode | What it does | | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | | **Agent** | Implements the change and opens a PR. The default. | | **Plan** | Researches first and posts a plan for your approval before writing code. See [Plans & questions](/planning). | | **Ask** | Answers questions about your codebase. Read-only, no PR. | | **Dev Env** | Sets up or repairs the workspace dev environment. Changes persist for future tasks. See [Your dev environment](/environment). | | **Schedule** | Turns your prompt into a recurring [automation](/automations). | ## Following up Reply in the task thread — in the web app or wherever the task started — and Twill continues with full context. Follow-ups reuse the task's existing agent and environment, so iterating is fast: "also handle the empty state", "the test you added fails on CI, fix it", "revert the copy change". When a PR linked to a task gets merged, the task is marked **Completed** automatically. ## Tracking progress The task view streams the agent's activity live: what it's reading, running, and changing. From the task header you can also: * **Open the live preview** of the running app inside the task's sandbox. * **SSH in** from your terminal, VS Code, or Cursor to inspect or take over. * **Cancel** a run that's heading the wrong way — then follow up with a correction. Tasks are searchable from the sidebar (⌘+K), and you can archive the ones you're done with. # Team management Source: https://docs.twill.ai/team-management Invite your team, assign roles, and transfer ownership. Twill plans don't charge per seat — invite everyone. Manage members in **Settings → Team**. ## Roles | Role | Can do | | ---------- | ----------------------------------------------------------------------------------------------------------- | | **Owner** | Everything, including transferring ownership. One per workspace. | | **Admin** | Invite and remove members, promote/demote between Member and Admin. Can't modify the Owner or other Admins. | | **Member** | Full product use — create tasks, review work. Can view the team and leave the workspace. | ## Invites Admins and the Owner can invite by email, granting Member or Admin. Pending invites can be copied as links or revoked. ## Ownership The Owner can't be removed or demoted by anyone (including themselves). To leave, the Owner first transfers ownership to another member — which demotes them to Admin. # Verification Source: https://docs.twill.ai/verification Every PR ships with proof: build, tests, lint, runtime checks, and artifacts you can review. The difference between a diff and a done task is verification. Before opening a PR, Twill checks its own work mechanically — and attaches the evidence so you don't have to take its word for it. ## What gets verified * **Static checks** — type checking, lint, and a production build, using your repo's own tooling. * **Tests** — your existing suite runs; new behavior gets new tests when warranted. * **Runtime behavior** — because tasks run in a [real dev environment](/environment), the agent starts your app and exercises the change: clicking through UI flows with browser automation, calling API endpoints and capturing request/response, inspecting service logs. "The types pass" or "the diff looks right" doesn't count as verified — the agent is required to observe the change working. ## Proof on the PR Whatever the verification produced is attached to the pull request: A Twill pull request with test output and screenshots attached * Test and build output * Screenshots of UI changes, before/after when relevant * Screen recordings of flows (`.mp4`/`.webm`, rendered inline on GitHub) * Logs from the running services * A [live preview](/environment#live-previews) link while the task's sandbox is up ## CI auto-fix If CI fails on a Twill-created PR, Twill notices and fixes it without being asked: 1. GitHub reports a failed check on the PR branch. 2. Twill matches the branch to its task, reads the CI logs, and pushes a fix. 3. CI re-runs. The PR gets a comment tracking each attempt. Twill makes up to **3 fix attempts** per CI failure; the counter resets after 24 hours. This applies to PRs created by Twill while their task is still active. Twill commenting on a PR that it is fixing a failed CI check