# Account linking support runbook
Source: https://docs.traycer.ai/account-linking-support-runbook



# Support runbook — account linking & email identity

Operational procedures for the cross-provider sign-in work: unlinking an
identity, un-parking a `former_email`, and the diagnostics that decide which of
the two a ticket needs.

This runbook is a **prerequisite for enabling Tier 1** — a linked identity has
no self-service removal, so support has to be able to remove one before the
platform starts creating them silently.

Related: `docs/email-normalize-dedupe-migration-runbook.md` (the dedupe pass that
produces parked `former_email` values).

***

## Background: the two tables support touches

| Table / column       | Meaning                                                                                                                                                                                                                                                                                                                      |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `users.provider_id`  | The account's **canonical** identity. Immutable after creation — token and owner binding depend on it. Never edit it to resolve a ticket.                                                                                                                                                                                    |
| `user_identities`    | The identity **registry**. One row per identity that may mint a session for an account. `is_canonical = true` mirrors `users.provider_id`; `is_canonical = false` is a *linked* identity added through the account-link flow. `provider_id` is globally unique, which is what stops one identity from spanning two accounts. |
| `users.email`        | The canonical account address. `email_source = USER` means the user set it in Settings and provider sign-ins must leave it alone.                                                                                                                                                                                            |
| `users.former_email` | Recoverability slot for a row that lost an email-dedupe tie-break. **Not** live access — see "Un-park" below.                                                                                                                                                                                                                |

A **linked** identity can sign in to the account. It can never rewrite the
account's handle, name, avatar or email — those stay owned by the canonical
identity.

***

## 1. Unlink an identity

Use when: a user reports a sign-in method on their account that they did not
add, or asks to detach one (e.g. a work GitHub account they no longer use).

### 1.1 Confirm the account holder

Do not proceed on the strength of the inbound email address alone. The
notification mail ("`<identity>` can now sign in to your Traycer account") is
sent to `users.email`, so a requester who can quote it demonstrates control of
the canonical mailbox. Otherwise use the normal account-ownership check.

### 1.2 Find the rows

```sql theme={null}
SELECT u.id            AS user_id,
       u.email,
       u.provider_type AS canonical_provider_type,
       u.provider_id   AS canonical_provider_id,
       i.id            AS identity_row_id,
       i.provider_type,
       i.provider_id,
       i.is_canonical,
       i.created_at
  FROM users u
  JOIN user_identities i ON i.user_id = u.id
 WHERE lower(u.email) = lower($1)
 ORDER BY i.is_canonical DESC, i.created_at;
```

Expect exactly one `is_canonical = true` row (it mirrors
`users.provider_id`) plus one row per linked identity.

### 1.3 Delete the linked row — never the canonical one

```sql theme={null}
DELETE FROM user_identities
 WHERE id = $1
   AND is_canonical = false;
```

The `AND is_canonical = false` is not decoration. Deleting the canonical row
leaves `users.provider_id` pointing at an identity the registry no longer
fences, which re-opens the "one identity, two accounts" hole for that id.
Always delete **by `id`**, verified against the query above.

Verify one row was removed. If the delete affected zero rows, the identity was
canonical — see 1.5.

### 1.4 Purge the user cache

Sign-in resolution reads a 24-hour Redis cache before Postgres, so the row you
just changed can keep being served stale. `removeUserFromCache`
(`packages/common/src/cache/user-cache.ts`) evicts **two** groups, and doing it
by hand means doing both. Keep this list in sync with that function.

**Group 1 — the six fixed keys** (`getUserCacheKeys`):

```text theme={null}
authenticatedUser:<user_id>
authenticatedUserV2:<user_id>
prismaUser:<user_id>
prismaUser:<canonical_provider_id>      # users.provider_id, NOT the unlinked one
userSubscription:<user_id>
collaboratorUserProfile:<user_id>
```

**Group 2 — one `creditSummary:<user_id>:<customer_id>` per customer id**, which
`removeUserFromCache` discovers by reading the cached blobs first and collecting
every `customerId` it finds in them: the user's own subscription, the v2 blob's
`teamSubscriptions`, the v1 blob's `organizationSubscriptions`, and the
`userSubscription` blob. That set is not derivable from `<user_id>` alone, so
**do not** delete group 1 and then go looking — the blobs you need are gone.
Match the keys first:

```bash theme={null}
# 1. Discover the creditSummary keys BEFORE deleting anything.
REDIS_URL='rediss://...'
redis-cli -u "$REDIS_URL" --scan --pattern "creditSummary:<user_id>:*"
```

Then delete both groups together:

```bash theme={null}
redis-cli -u "$REDIS_URL" DEL \
  "authenticatedUser:<user_id>" "authenticatedUserV2:<user_id>" \
  "prismaUser:<user_id>" "prismaUser:<canonical_provider_id>" \
  "userSubscription:<user_id>" "collaboratorUserProfile:<user_id>" \
  "creditSummary:<user_id>:<customer_id>"    # repeat per id from the scan
```

If the scan returns nothing, there is nothing to evict in group 2 — that is a
normal outcome for a user who has never had a credit summary computed. A leftover
`creditSummary` key is not a sign-in problem; it shows the user stale credit
figures until it expires.

The registry table itself is not cached, so the unlink takes effect on the next
sign-in either way; the purge is for the account row the user then sees.

Anything already issued stays valid: a Traycer token minted before the unlink is
bound to `user_id`, not to the identity. If this is a suspected-compromise
ticket, escalate for token revocation as well — unlinking alone only stops
*future* sign-ins.

### 1.5 If the identity to remove is canonical

Stop and escalate. Detaching a canonical identity is an account migration, not
an unlink: `users.provider_id` is immutable by design, and the correct
resolution is usually to link the user's preferred identity (they can do it
themselves by signing in with it and entering the emailed code) and leave the
old one in place.

***

## 2. Un-park a `former_email`

Use when: a user reports that their email address vanished from their account,
or that they have lost team access after the dedupe pass.

**Gate: run this procedure only after T7's `users_email_key` has been created
and verified valid.** Between T6 parking and T7, there is no unique constraint
on `users.email`; escalate the ticket rather than mechanically restoring an
address.

### 2.1 Understand what parking did and did not do

`former_email` preserves the **value** so it can be restored. It does **not**
preserve access: every team-membership join reads `users.email` and degrades to
no-access when it is NULL, regardless of what sits in `former_email`. A parked
user with an accepted team membership is therefore a live incident, not a
cosmetic one.

### 2.2 Find the parked row and its collision

```sql theme={null}
SELECT id, email, former_email, email_source, last_seen_at, created_at
  FROM users
 WHERE lower(former_email) = lower($1);
```

Then find who holds the address now:

```sql theme={null}
SELECT id, email, email_source, last_seen_at, created_at
  FROM users
 WHERE lower(email) = lower($1);
```

### 2.3 Decide

* **Nobody holds it** (second query returns no rows) — the winner was deleted or
  changed address. T7 is still required: the statement in 2.4 repeats this
  holder check atomically, and `users_email_key` protects against a concurrent
  writer after that check. Go to 2.4.
* **Someone holds it** — the address is one-owner. You cannot restore it to a
  second row. Either the current holder releases it (via Settings → change
  email), or the two accounts are merged. Both are decisions, not mechanical
  steps: escalate with both `user_id`s and the subscription/team state of each.

### 2.4 Restore

```sql theme={null}
UPDATE users
   SET email        = lower(btrim(former_email,
                        U&'\0009\000A\000B\000C\000D\0020\00A0\1680\2000\2001\2002\2003\2004\2005\2006\2007\2008\2009\200A\2028\2029\202F\205F\3000\FEFF')),
       former_email = NULL,
       email_source = 'USER',
       updated_at   = CURRENT_TIMESTAMP
 WHERE id = $1
   AND email IS NULL
   AND former_email IS NOT NULL
   AND btrim(former_email,
        U&'\0009\000A\000B\000C\000D\0020\00A0\1680\2000\2001\2002\2003\2004\2005\2006\2007\2008\2009\200A\2028\2029\202F\205F\3000\FEFF') <> ''
   AND NOT EXISTS (
         SELECT 1
           FROM users w
          WHERE lower(w.email) = lower(btrim(users.former_email,
                  U&'\0009\000A\000B\000C\000D\0020\00A0\1680\2000\2001\2002\2003\2004\2005\2006\2007\2008\2009\200A\2028\2029\202F\205F\3000\FEFF'))
       );
```

**Normalize on the way back in — do not copy `former_email` verbatim.** After
T7 the column carries `users_email_normalized_check`, and that CHECK validates
the whole new tuple, so restoring an address that is not already `lower` +
JS-whitespace-trimmed fails with SQLSTATE `23514` on a statement this runbook
told you to run. The dedupe pass normalizes before it parks, so in the common
case this is a no-op — but `former_email` carries no constraint of its own and
nothing guarantees it for a row parked by hand or by an older tool. The
`<> ''` guard is the matching case: a value that trims to empty would otherwise
be restored as `''`, which is outside the unique index entirely and silently
un-owns the address.

The holder check is `lower()` on **both** sides for the same reason — comparing
a normalized column against a possibly-unnormalized `former_email` is exactly
how a live holder goes unseen, and that is the case where the guard is
load-bearing rather than decorative.

`email_source = 'USER'` is deliberate: a restored address must not be
overwritten by the next provider sign-in, which is the defect that made the
address unstable in the first place. The `NOT EXISTS` predicate closes the gap
between the advisory lookup in 2.2 and the write: a holder visible to the
restore statement makes it affect zero rows. `users_email_key` protects the
remaining concurrent-write window. If the update affects zero rows or raises a
unique violation, re-run 2.2 and escalate rather than retrying it blindly.

> The trim set must be the `U&'…'` form. PostgreSQL's `E'…'` escapes recognise
> only `\b \f \n \r \t` (plus octal/hex/unicode) and take any other backslashed
> character literally, so `E'\v'` is the letter `v` — which would strip `v` from
> both ends of the address.

Then purge the user cache for that `user_id` (see 1.4) — `GET /user` serves an
`authenticatedUser` blob with the old value for 24h otherwise, and the
pending-invite auto-join keys off the email inside it.

***

## 3. Common tickets

### "I get a code entry box but no email arrives"

1. Check the send caps — the address is capped at 5 codes/hour and 10/day, and
   the cap **fails closed**, so a Redis outage also produces this. Look for
   `Link code send refused by cap` in the authn-v3 logs.
2. Check for a bounce in customer.io for the address in `users.email`.
3. Note that a **reload does not re-send**: the ticket mint is idempotent within
   its 15-minute window, so the original code stays valid and no second email is
   sent. Tell the user to look for the first one.

### "The code says it's wrong but I'm typing it correctly"

The ticket allows 5 attempts and is then destroyed. Ask the user to sign in
again to get a fresh code. Codes are single-use and ticket-bound — a code from
an earlier attempt, or from the Settings email-change flow, will not work here.

### "It says my GitHub account is already linked to a different account"

The presenting identity is registered to another `user_id`. This is a merge, not
an unlink: run the 1.2 query against **both** addresses and escalate with both
`user_id`s. Do not delete the other account's registry row to "free up" the
identity — that silently removes the other user's ability to sign in.

### "I signed in and my email reverted to an old address"

Should no longer happen. If it does, capture `users.email_source` for the row: a
`PROVIDER` value on an address the user set in Settings means the Settings write
did not land, which is an engineering escalation, not a support fix.

***

## 4. What support cannot do (yet)

* **Self-service unlink** — deferred; this runbook is the interim.
* **Listing linked identities in Settings** — deferred; use the 1.2 query.
* **Merging two accounts** — no mechanism exists. Escalate.


# Organizations and Teams
Source: https://docs.traycer.ai/account/organizations

Provides centralized billing, seat management, privacy controls, and team collaboration.

Organizations and teams are account-level features for seats, shared billing, and team access.

## Adding organizations

<Frame>
  <iframe title="Adding Organizations to Traycer" />
</Frame>

To add your GitHub organization to Traycer:

<Steps>
  <Step title="Access organization settings">
    Click on the account dropdown in the top navigation bar and select "Fetch Organizations".
  </Step>

  <Step title="Grant GitHub permissions">
    A GitHub OAuth window will open. Review and grant the necessary permissions for your organization.
  </Step>

  <Step title="Switch to your organization">
    Once permissions are granted, you can switch between your personal account and organization accounts using the account dropdown.
  </Step>
</Steps>

## Seat management

Navigate to your organization's **Seat Management** page to configure how seats are assigned to members.

### Automatic assignment mode

When **Automatic Assignment Mode** is enabled, any new member added to your organization is instantly granted a paid seat and full access to Traycer features. This ensures seamless onboarding and eliminates manual intervention for seat allocation.

### Manual assignment mode

In **Manual Assignment Mode**, admins can change the status for any user to enable or disable their seat, giving you full control over who has access to Traycer features.

<Frame>
  <img alt="Seat management interface showing user seats and roles" />
</Frame>

<Note>
  **Important**: Disabling a seat does not decrease your subscription seat count. The disabled seat can be enabled for another user, allowing you to reassign seats within your subscription limit without changing your billing.
</Note>

***

## Managing subscription seats

To add or remove seats from your subscription:

<Steps>
  <Step title="Access organization settings">
    Navigate to the **Settings** page for your organization.
  </Step>

  <Step title="Open subscription management">
    Click **"Manage Subscription"** to access your billing settings.
  </Step>

  <Step title="Modify seat count">
    Click **"Current Plan"** under your subscription. You'll see a counter where you can increase or decrease your seat count.
  </Step>
</Steps>

<Info>
  **Billing timing**: Additional seats are added instantly and billed immediately. Seat decrements take effect at the end of your current billing cycle.
</Info>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Does Traycer have SSO (Single Sign On)?">
    Yes, Traycer supports Single Sign-On through GitHub.
  </Accordion>

  <Accordion title="How does organization pricing work?">
    Organization pricing follows the same per-seat model as individual plans. Each subscription seat in your organization is billed at the same rate as individual subscribers, with no additional fees for organizations.
  </Accordion>

  <Accordion title="What is privacy mode?">
    Privacy controls are managed at the organization level. Your organization settings determine which cloud and inference features are available for sensitive work.
  </Accordion>

  <Accordion title="Can I share work with my organization?">
    Yes. Shared work can be made available to your organization so teammates can collaborate on the same specs and tickets. From the share dialog, select your organization and choose an access level (`Editor` or `Viewer`), then click `Share`.
  </Accordion>
</AccordionGroup>


# Pricing
Source: https://docs.traycer.ai/account/pricing

Understand Traycer plans, cloud sync, sharing, and monthly inference credits.

This page covers **Traycer Desktop** pricing. Using the IDE extension? See [Extension Pricing](/extension/pricing).

Traycer pricing separates product access from inference usage.

## Plans

| Plan      |            Price | Best for                    |       Monthly credits | Includes                                                                                                                           |
| --------- | ---------------: | --------------------------- | --------------------: | ---------------------------------------------------------------------------------------------------------------------------------- |
| **BYOA**  |              \$0 | Bring your own coding agent |                     — | Local-only Traycer with your own coding agents (Claude Code, Codex, OpenCode, Cursor). No cloud sync, sharing, or Traycer credits. |
| **Sync**  |  \$10/user/month | Perfect to try out Traycer  |                     — | Cloud Sync, Device switch, Team collaboration. Starts with a 7-day trial.                                                          |
| **Lite**  |  \$20/user/month | Ideal for casual users      |  \$20 credits + bonus | Everything in Sync, plus inference credits.                                                                                        |
| **Pro**   |  \$40/user/month | Perfect for developers      |  \$50 credits + bonus | Everything in Lite, with more credits.                                                                                             |
| **Ultra** | \$100/user/month | Built for power users       | \$150 credits + bonus | Everything in Pro, with the most credits.                                                                                          |

Paid tiers above Sync include monthly inference credits plus additional bonus credits on top. Higher tiers give more credit value per dollar.

## Monthly Inference Credits

Credits are used for models accessed through the **Traycer** provider. Each tier's credits renew monthly and <u>**do not roll over**</u>. The **Sync** plan covers product access (Cloud Sync, device switch, team collaboration) and does not include inference credits.

## What Costs Credits

Models available through the **Traycer** provider can consume inference credits. Credit usage is based on the upstream API pricing for the selected supported model, plus a **20% Traycer markup**.

There are no fixed per-request fees. Cost can still vary by operation, selected model, reasoning effort, and provider-side pricing.

Using other coding-agent paths, such as Claude Code, Codex, OpenCode, or Cursor, does **not** consume Traycer credits and does **not** include a Traycer markup. Those paths use their own account, API, or provider billing outside Traycer. Use [Agents & Models](/agents-and-models/coding-agents) for coding-agent setup.

## Team Billing

Organizations can centralize billing and seat management. Organization details live in [Organizations and Teams](/account/organizations).


# Agents & Models
Source: https://docs.traycer.ai/agents-and-models/coding-agents

Compare Traycer's supported coding-agent paths and where to configure them.

This page is the compatibility reference for Traycer's coding-agent paths and model selection.

For the agent surface itself, including composer controls, permissions, attachments, voice input, and per-turn behavior, see [Agents](/panels/agents).

## Supported Coding Agents

| Coding agent    | Chat interface | Terminal interface | Fast mode       | Setup                                |
| --------------- | -------------- | ------------------ | --------------- | ------------------------------------ |
| **Claude Code** | Yes            | Yes                | Model-dependent | Claude Code CLI/account              |
| **Codex**       | Yes            | Yes                | Model-dependent | Codex CLI/account                    |
| **OpenCode**    | Yes            | Yes                | Not supported   | OpenCode CLI/provider                |
| **Traycer**     | Yes            | Not supported      | Not supported   | Traycer sign-in and credits          |
| **Cursor**      | Yes            | Not supported      | Not supported   | Cursor API key                       |
| **Grok**        | Yes            | Not supported      | Not supported   | Grok CLI/account or xAI API key      |
| **Qwen Code**   | Yes            | Not supported      | Not supported   | Qwen Code CLI/provider               |
| **Kiro**        | Yes            | Not supported      | Not supported   | Kiro CLI/account or API key          |
| **Droid**       | Yes            | Not supported      | Not supported   | Factory Droid CLI/account or API key |
| **Kimi**        | Yes            | Not supported      | Not supported   | Kimi CLI/account                     |
| **Copilot**     | Yes            | Not supported      | Not supported   | GitHub Copilot CLI/account           |
| **Kilo Code**   | Yes            | Not supported      | Not supported   | Kilo Code CLI/account or API key     |
| **OpenRouter**  | Yes            | Not supported      | Not supported   | OpenRouter API key                   |
| **Amp**         | Yes            | Not supported      | Not supported   | Amp CLI/account or API key           |
| **Devin**       | Yes            | Not supported      | Not supported   | Devin CLI/account                    |
| **Pi**          | Yes            | Not supported      | Not supported   | Pi CLI/provider credentials          |

<Info>
  **Chat interface** means the coding agent can back an agent on the Chat
  interface. **Terminal interface** means it can also back one on the Terminal
  interface.
  A provider using a CLI behind its Chat integration does not automatically
  make it available on the Terminal interface.
</Info>

## Models

Traycer loads models from the selected coding agent and provider profile at runtime. The available list can vary with your installed CLI version, account, provider configuration, and model access, so Traycer does not maintain a fixed model list in these docs.

In the composer:

* Select a coding agent and provider profile first.
* The model picker shows the models currently available for that selection.
* Thinking effort appears only when the selected model exposes supported reasoning levels.
* Fast mode appears only when the selected Claude Code or Codex model exposes a fast tier.

Using the **Traycer** provider consumes Traycer credits. Other coding agents use their own account, API, or provider billing; see [Pricing](/account/pricing).

## Provider Setup

Configure provider credentials, environment variables, CLI paths, profiles, and default Terminal interface CLI arguments in [Settings > Providers](/settings/providers). Disabled or unavailable providers do not appear as runnable options until their setup is complete.


# Changelog
Source: https://docs.traycer.ai/changelog

Track the latest updates and improvements to Traycer Desktop.

<Update label="v1.1.9">
  Two tabs side by side, search across artifacts and workspaces, and the Oh My Pi coding agent.

  * **Split the window** — put any two tabs side by side: a Task next to History, or Settings next to a draft. Each side scrolls on its own, and the divider can be dragged or resized from the keyboard. Drag a tab to the edge of the window and hold, or pick one from the list.
  * **Search** — search artifacts and workspaces, jump to nested panes by path, and find past Tasks by branch, folder, or PR number.
  * **Oh My Pi** — the Oh My Pi coding agent is now available.
  * **Agent roles** — give an agent a role, from the app or the CLI.
  * **Steer a running agent** — press ⌘Enter to send a message to a coding agent mid-turn instead of waiting for it to finish; Enter still queues it for afterwards. Not every coding agent supports this, and it can be turned off in Settings.
  * **Sidebar** — chat rows show a second line of detail and a leading icon, and archiving is easier to reach.
  * **Worktrees** — clear out a Task's finished worktrees from History or the sidebar, one at a time or several at once, and choose your own branch prefix.
  * **Context usage** — compact a conversation straight from the context chip.
  * **Workspace files** — the file list keeps up as files change, and artifacts tell you once they have finished syncing.
  * **Notifications** — an agent that stops because it ran out of context, or because its request was refused, now tells you which. Clicking a notification opens the window holding that chat, and terminal agents get their own indicators.
  * **Installing and updating** — a failed install or update offers a way forward instead of leaving you stuck. On macOS, Traycer recovers from a failed background-service registration, and no longer runs slowed down in the background.
  * **Windows** — fixed the menu bar, window controls at non-default zoom levels, and theme switching. Environment variable overrides keep their original capitalization.
  * **Fixes** — drafts clear everywhere once sent; sign-in completes as soon as you approve it in the browser; updates ask once rather than twice before restarting; a terminal agent that fails to launch explains why; Worktrees keeps your selection as you move around Settings; adding an image no longer moves your cursor; a failed compaction is no longer marked as done; numbered lists keep their starting number; mentions accept spaces; the composer keeps focus when you switch panes; buttons work again after your machine wakes; and a provider being rechecked keeps its models on screen.
</Update>

<Update label="v1.1.8">
  A rebuilt notification center, the Hermes coding agent, and updates that survive being interrupted.

  * **Notification center** — rebuilt, with a clear way to dismiss anything needing attention and consistent wording wherever a notification appears.
  * **Updates** — large downloads resume where they left off, installing no longer freezes the app, and a Host that is still running is never restarted from under you.
  * **Hermes** — the Hermes coding agent from Nous Research is now available.
  * **Composer** — pick several skills at once with `$`, paste or drop files to insert their paths, and see why Send is unavailable. Images still attach as images.
  * **Sign-in** — the app and the CLI share one sign-in, so signing in once covers both.
  * **Rate limits** — Grok account usage appears alongside the other providers.
  * **Resource monitor** — stop an agent and everything it started in one action, with provider icons on each row.
  * **Terminals** — open a terminal from the start screen without choosing a folder first.
  * **Agent messages** — redesigned message cards, and control over what an agent is allowed to do.
  * **Worktrees** — the branch picker saves as you type and handles long branch lists, your filters persist, and a failed setup can be retried safely.
  * **Summon hotkey** — change it, or turn it off.
  * **Chats are now Agents** — the Chats panel is now Agents, and Settings › Agents is now Settings › Agent selection. New agents start in regular mode. Your history, saved titles, and existing references are unchanged.
  * **Agent selection** — guidance is now set once for everything, rather than per workspace.
  * **Fixes** — the Linux app icon appears correctly; provider sign-in failures stay visible instead of disappearing; history skips tabs you have closed; panels reconnect on their own; copying messages and pasting images work in installed builds; and file tabs can copy their path.
</Update>

<Update label="v1.1.7">
  Several accounts per provider, two new coding agents, artifact export, and terminals outside a Task.

  * **Several accounts per provider** — connect more than one account to the same provider and switch between them per conversation, with usage shown for each. Agents messaging each other use them too.
  * **Devin and Pi** — both coding agents are now available.
  * **Export artifacts** — save any artifact as Markdown or PDF.
  * **Terminals outside a Task** — open terminals not tied to a Task, plus a terminal panel on the start screen and a reworked Shell section in Settings.
  * **Fork an answered question** — return to a question you already answered and try a different path from there.
  * **Notifications** — tab indicators that persist, toasts you can click, alerts when a provider or workspace fails, and hooks that call a URL or run a command, filtered by severity.
  * **Rate limits** — Codex manual reset credits, a banner matching the model you actually picked, and a quicker way to switch accounts when you hit a limit.
  * **Worktrees and PRs** — worktree and PR context throughout the app, PR numbers you can search for, and status that finishes loading without scrolling and stays current.
  * **Claude sign-in** — paste an OAuth code when the browser redirect cannot complete.
  * **Artifacts** — edit the agent guide as Markdown, open links with editing behind a hover card, and pin items in a Task's history.
  * **Background work** — background tasks show elapsed time and readable results, and finished cards show what resumed the agent.
  * **Resource monitor** — counts everything an agent started, and sorts by total CPU or memory use.
  * **Analytics** — Traycer now collects product usage data. Automatic capture, session recording, page addresses, errors, and your content are all switched off; events are linked to your Traycer account.
  * **Open source** — Traycer's public repository is now MIT-licensed.
  * **Fixes** — Ctrl shortcuts on macOS no longer trigger the wrong action, terminal sizing and scrolling behave, the app recovers when the Host becomes reachable again instead of leaving chats offline, and WSL no longer fills up with crash dumps.
</Update>

<Update label="v1.1.6">
  Fork a chat while a question is still waiting on you.

  * **Fork a pending question** — branch a conversation while a question is still waiting for your answer, either to ask something else or to try a different answer alongside it.
  * **Compatibility** — a newer app keeps working with an older Host; anything unavailable falls back where it can, or asks you to update.
  * **Reliability** — requests finish before their connection closes.
</Update>

<Update label="v1.1.5">
  Traycer Desktop comes to Windows, with a resource monitor and worktree cleanup.

  * **Windows** — Traycer Desktop and the bundled CLI run on Windows, with window controls that follow your theme, on signed builds.
  * **Resource monitor** — see CPU and memory for everything Traycer runs, expand any entry to its sub-processes, and keep the section header in view while scrolling.
  * **Amp** — the Amp coding agent from Sourcegraph is now available.
  * **Worktree cleanup** — see which worktrees are stale, which have open or merged PRs, and which have landed. The list pages as it grows and links back to the Task that created each one.
  * **Queued messages** — pause and resume them.
  * **Nested agents** — Claude subagents and parallel groups appear as a tree.
  * **Terminal** — choose your cursor style and whether it blinks.
  * **Artifacts** — tabs take their name from the document's first heading, and sections can be dragged out.
  * **Start without a folder** — begin a chat before choosing a folder.
  * **Navigation** — Back and Forward follow where you have been inside a Task, including panes and tiles.
  * **Chat** — provider notices appear inline, and suggested next steps can be queued while an agent is still working.
  * **Fixes** — trackpad gestures no longer zoom the app, your window layout survives quitting, terminals stop reconnecting in a loop, and nested formatting in artifacts no longer breaks.
</Update>

<Update label="v1.1.4">
  Scheduled wake-ups get real controls, and diffs understand submodules.

  * **Scheduled wake-ups** — Claude's background work appears as a tree, with its status and a way to cancel a scheduled wake-up.
  * **Submodule diffs** — see changes made inside Git submodules, grouped by repository.
  * **Quote in the composer** — select text from an agent's reply and quote it.
  * **Long-running sessions** — chats and terminals pick up a refreshed sign-in without being reopened.
  * **Fixes** — terminal agents no longer die quietly when the connection drops, launching one no longer leaves an empty "New tab" behind, usage limits recover after a failed refresh, and deleting a chat clears the waiting indicator it left behind.
</Update>

<Update label="v1.1.3">
  Account usage moves into the header, alongside display scaling and font controls.

  * **Account usage** — check Codex, Claude Code, OpenRouter, Kilo Code, and Traycer usage from the header.
  * **Appearance** — scale the interface, and set separate fonts for the interface, code, and terminal.
  * **Canvas** — drag artifact cards, and references to specs or tickets in the same Task, onto the canvas.
  * **Mentions** — preview the highlighted result in a tighter menu, with results that no longer jump while you type.
  * **Terminals** — heavy output is faster and more reliable.
  * **Named agents** — give an agent a name when you create it. Provider lists also load correctly when the CLI and Host are on different versions.
  * **Fixes** — closing and reordering tabs works reliably, cancelling an edit restores your previous draft, actions unavailable to viewers explain why, and terminal agents no longer clutter the Terminals palette.
</Update>

<Update label="v1.1.2">
  Full access becomes the default permission mode.

  * **Permissions** — new conversations default to full access.
  * **Model picker** — Traycer models being retired carry a Deprecated badge and an explanation.
  * **Updating the Host** — restarts ask first, install and update no longer collide, progress appears in both the banner and Settings, and Traycer checks for new releases on launch and when your machine wakes.
  * **New Conversation** — the branch and worktree pickers scroll properly.
  * **Terminal agents** — worktree setup progress appears in the tile, with retry and open-terminal actions if it fails.
  * **Homebrew** — install a specific Desktop release, with x86\_64 Linux AppImage support.
  * **Fixes** — on WSL and manually installed Linux packages, Traycer now explains how to update by hand instead of quietly reopening the old version, and sign-in steps time out rather than hanging.
</Update>

<Update label="v1.1.1">
  Traycer remembers your model and reasoning effort for each coding agent.

  * **Remembered settings** — your model, reasoning effort, and speed tier are kept for each coding agent.
  * **Child chats** — create them from the same New Conversation dialog.
  * **Composer** — place image attachments where you want them in the message.
  * **Background work** — when work continues past a reply, Stop is no longer left active, restores are no longer blocked, and the duplicate "working" row is gone.
  * **Fixes** — the Mermaid editor no longer crashes, and creating a Task from the start page no longer leaves the tab loading forever.
</Update>

<Update label="v1.1.0">
  Eight new coding agents, device sign-in, and a much faster first launch.

  * **Eight new coding agents** — Grok (xAI), Qwen, Kiro, Kilo Code, Copilot, Kimi, Droid, and OpenRouter join the ones already supported.
  * **Faster first launch** — providers appear as they finish loading, so a new install no longer waits for all of them.
  * **Device sign-in** — sign in by approving Traycer on a web page.
  * **Model picker** — consistent provider order, OpenRouter models grouped by vendor, and keyboard shortcuts.
  * **Search** — ⌘F within a canvas tile.
  * **Navigation** — Back and Forward inside the app.
  * **Background Claude subagents** — progress keeps updating after the main reply ends, with clearer finished, failed, and stopped states.
  * **Context usage** — a clearer breakdown, which you can pin.
  * **History** — activity shown on each row, a right-click menu, and titles that fill in once generated.
  * **Diagnostics** — choose how much Traycer logs, in Settings → Diagnostics.
  * **Worktrees** — delete many at once with progress that persists, and preview a branch's setup scripts before creating one.
  * **Terminals** — reconnecting replays a clean screen without leftover output.
  * **Approvals** — approval cards summarize the command.
  * **Updates** — start an update yourself, move from a prerelease to the final version, and installs that were relocated or are read-only on macOS are handled.
  * **Homebrew** — install Traycer Desktop as a cask.
  * **Removing Traycer** — the Host no longer comes back after removal, and the app shows the removed state without needing a reload.
  * **Mermaid** — PNG downloads work.
</Update>

<Update label="v1.0.0">
  First public release of Traycer Desktop — the native app for delegating engineering work to coding agents in a local-first workspace. It bundles the Traycer CLI and provisions the local Host automatically, so there is nothing else to install.

  * **Tasks** — long-lived, repository-bound workspaces where you plan, chat, run terminal agents, review diffs, and keep history. Everything is stored locally.
  * **Coding agents, your choice** — connect Claude (Claude Code), OpenAI Codex, Cursor, OpenCode, or Traycer Inference and switch per conversation. Set reasoning effort and an optional Fast tier on supported models.
  * **Chats** — persistent conversations, run several in parallel, per-conversation change tracking, auto-saved drafts.
  * **Terminal agents** — terminal-based agents on a full xterm terminal; sessions persist across host restarts.
  * **Plan and review** — side-by-side git diffs, file viewing, and line-level comment threads.
  * **Worktrees** — isolated git worktrees keep your main checkout clean.
  * **Multiple machines** — choose the machine a chat or terminal runs on; each tab stays bound to its host for life.
  * **Native desktop** — system tray, native notifications, command palette, customizable keybindings, multiple windows, the `traycer://` deep-link scheme, and light/dark/system themes.
  * **Sign in once** — browser-based (PKCE) sign-in, shared with the bundled CLI.
  * **Background updates** — downloaded in the background and installed on quit, using signed release artifacts.
  * **Platforms** — macOS 12+ (Apple Silicon and Intel, signed and notarized) and 64-bit Linux.
</Update>


# CLI Changelog
Source: https://docs.traycer.ai/cli/changelog

Track the latest updates and improvements to the Traycer CLI.

<Update label="v1.1.9">
  Agent roles, the Oh My Pi coding agent, and Host installs that recover instead of leaving you stuck.

  * **Agent roles** — give an agent a role when you create it.
  * **Oh My Pi** — create agents with `--harness omp`.
  * **Command help** — command descriptions now spell out what each command actually does.
  * **Installing the Host** — a failed install or update offers a way forward instead of leaving you stuck. On macOS, the Host no longer runs slowed down in the background, and appears in Login Items as Traycer rather than `sh`.
  * **Fixes** — browser sign-in completes as soon as you approve it, rather than waiting out a longer polling delay, and environment variable overrides on Windows keep their original capitalization.
</Update>

<Update label="v1.1.8">
  One sign-in shared with the desktop app, and downloads that resume.

  * **Shared sign-in** — the CLI and Traycer Desktop use the same credentials, so signing in once really does cover both.
  * **Agent permissions** — set what an agent is allowed to do when creating or reconfiguring it.
  * **Installing the Host** — large downloads resume where they left off.
  * **Fixes** — the CLI now recognizes when the desktop app already manages the Host service, and replaces a competing registration rather than just refusing it.
</Update>

<Update label="v1.1.7">
  Account-aware agent commands, Devin and Pi, and steadier Host service registration.

  * **Choose an account per agent** — list the accounts available for a provider and their usage, pick one when creating an agent, and switch the account an existing agent uses.
  * **Devin and Pi** — both coding agents are now available.
  * **Shell configuration** — add or remove custom shells, and restore a shell's default arguments.
  * **Worktrees** — listings fetch current status every time you run them.
  * **Service registration** — the Host service stays correctly registered across installs and updates.
  * **Open source** — Traycer's public repository is now MIT-licensed.
</Update>

<Update label="v1.1.6">
  * **Compatibility** — a newer CLI keeps working with an older Host; anything unavailable asks you to update rather than breaking the connection.
  * **Reliability** — requests finish before their connection closes.
</Update>

<Update label="v1.1.5">
  Windows binaries, the Amp coding agent, and new worktree commands.

  * **Windows** — prebuilt Windows binaries alongside macOS and Linux.
  * **Amp** — the Amp coding agent from Sourcegraph is now available.
  * **Worktree commands** — `traycer worktree list` and `traycer worktree delete`, showing which worktrees are stale and paging as the list grows.
  * **Terminal agents** — Claude and OpenCode keep the correct session when it changes.
</Update>

<Update label="v1.1.4">
  * **Git diffs** — change data can include edits made inside Git submodules.
  * **Scheduled wake-ups** — remain compatible with earlier 1.1 releases.
  * Terminal agents no longer die quietly when the connection drops.
</Update>

<Update label="v1.1.3">
  * **Named agents** — give an agent a name when you create it.
  * Provider lists load correctly when the CLI and Host are on different versions.
</Update>

<Update label="v1.1.2">
  * **Homebrew** — install a specific CLI version.
  * **Sign-in** — a stalled sign-in now times out instead of hanging indefinitely.
</Update>

<Update label="v1.1.1">
  * Host updates recover instead of staying blocked, and refuse to restart while work is still running.
</Update>

<Update label="v1.1.0">
  Install from npm or Homebrew, sign in from any device, and eight new coding agents.

  * **Install from npm or Homebrew** — published to both.
  * **Device sign-in** — sign in by approving Traycer on a web page, shared with Traycer Desktop.
  * **Eight new coding agents** — Grok (xAI), Qwen, Kiro, Kilo Code, Copilot, Kimi, Droid, and OpenRouter.
  * **Windows Hosts** — support for bundled Windows Host archives.
  * **Diagnostics** — choose how much the CLI logs.
  * **Sign-in** — long-running `traycer monitor` sessions refresh credentials ahead of expiry and update open Host connections without reconnecting.
  * **Removing the Host** — `traycer host uninstall --all` removes the Host for good, instead of leaving it to restart itself part-way through.
</Update>

<Update label="v1.0.0">
  First public release of the Traycer CLI — the `traycer` command that provisions and supervises the Traycer Host, handles authentication, manages configuration, and exposes Traycer's workspace and agent automation. It ships inside Traycer Desktop, so most users do not install it separately.

  * **Single binary** — a self-contained executable with no external runtime dependency.
  * **Host lifecycle** — download, verify, install, start, update, and supervise the Host as an OS-managed service. Binaries are verified by SHA-256 checksum and minisign signature before installation.
  * **Authentication** — browser-based PKCE sign-in (`traycer login` / `whoami` / `logout`), shared with Traycer Desktop.
  * **Configuration** — shell selection and environment overrides for agent sessions.
  * **Workspaces and worktrees** — list workspaces and create isolated git worktrees.
  * **Agent automation** — list, create, and message agents, read transcripts, and stream inboxes.
  * **Scripting** — `--json` emits a structured NDJSON stream of `progress` and `result` events; honors `CI` and `TRAYCER_NONINTERACTIVE`, plus `--quiet` / `--no-progress`.
  * **Platforms** — prebuilt binaries for macOS (Apple Silicon and Intel) and Linux (x64).
</Update>


# CLI
Source: https://docs.traycer.ai/cli/commands

Use the Traycer CLI for host control, auth, workspace, worktree, and agent workflows.

The Traycer CLI binary is `traycer`. It is used for host control, authentication, workspace/worktree operations, and agent automation.

## Installation

The desktop app bundles the CLI, so you only need to install it separately for standalone, automation, or CI use.

Install with npm (requires Node.js 20.18+):

```bash theme={null}
npm install -g @traycerai/cli
```

Or with [Homebrew](https://brew.sh) on macOS and Linux:

```bash theme={null}
brew install traycerai/traycer/traycer
```

Verify the install:

```bash theme={null}
traycer --version
```

The npm package is [`@traycerai/cli`](https://www.npmjs.com/package/@traycerai/cli).

## Global Flags

| Flag             | Purpose                                        |
| ---------------- | ---------------------------------------------- |
| `--json`         | Print machine-readable output where supported. |
| `--quiet`        | Reduce normal output.                          |
| `--no-progress`  | Disable progress output.                       |
| `--no-bootstrap` | Skip automatic bootstrap behavior.             |

## Auth Commands

| Command                         | Purpose                        |
| ------------------------------- | ------------------------------ |
| `traycer login`                 | Authenticate the CLI.          |
| `traycer login --token <token>` | Authenticate with a token.     |
| `traycer login --token -`       | Read the token from stdin.     |
| `traycer logout`                | Remove stored CLI credentials. |
| `traycer whoami`                | Show the authenticated user.   |

CLI credentials are stored under `~/.traycer/cli/credentials`.

## Host Commands

| Command                        | Purpose                       |
| ------------------------------ | ----------------------------- |
| `traycer host start`           | Start the host.               |
| `traycer host status`          | Show host status.             |
| `traycer host doctor`          | Diagnose host setup.          |
| `traycer host restart`         | Restart the host.             |
| `traycer host stop`            | Stop the host.                |
| `traycer host install`         | Install the host.             |
| `traycer host ensure`          | Ensure the host is available. |
| `traycer host update`          | Update the host.              |
| `traycer host uninstall`       | Uninstall the host.           |
| `traycer host uninstall --all` | Remove all host installs.     |
| `traycer host available`       | List available host versions. |
| `traycer host logs`            | Show host logs.               |
| `traycer host logs --tail <n>` | Show the last `n` log lines.  |
| `traycer host logs --follow`   | Follow host logs.             |

Useful options:

| Command                                     | Purpose                                              |
| ------------------------------------------- | ---------------------------------------------------- |
| `traycer host start --cwd <path>`           | Start the host with a specific working directory.    |
| `traycer host install --release <version>`  | Install a specific registry release.                 |
| `traycer host install --from <path>`        | Install from a local host archive.                   |
| `traycer host ensure --force`               | Restart the host even if it reports active work.     |
| `traycer host ensure --no-service-register` | Install the host without registering the OS service. |

The CLI discovers host connection metadata under `~/.traycer/host/`. `host install` and `host ensure` accept either `--release` or `--from`, not both.

## Service Commands

| Command                                           | Purpose                                                            |
| ------------------------------------------------- | ------------------------------------------------------------------ |
| `traycer service install`                         | Install the OS service integration.                                |
| `traycer service install --no-linger`             | Linux only: skip `loginctl enable-linger`.                         |
| `traycer service install --allow-self-invocation` | Development only: register the current CLI as the service command. |
| `traycer service status`                          | Show service status.                                               |
| `traycer service uninstall`                       | Remove the service integration.                                    |

## CLI Commands

| Command                                                                    | Purpose                                                    |
| -------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `traycer cli upgrade`                                                      | Upgrade the CLI.                                           |
| `traycer cli upgrade --dry-run`                                            | Show what would upgrade.                                   |
| `traycer cli upgrade --target <version>`                                   | Upgrade to a target version.                               |
| `traycer cli re-anchor`                                                    | Re-anchor the CLI install.                                 |
| `traycer cli re-anchor --binary-path <path> --installed-version <version>` | Point upgrade tracking at a manually installed CLI binary. |

## Config Commands

| Command                                               | Purpose                                                                     |
| ----------------------------------------------------- | --------------------------------------------------------------------------- |
| `traycer config shell get`                            | Show shell config.                                                          |
| `traycer config shell list`                           | List shell config.                                                          |
| `traycer config shell set`                            | Set shell path or args.                                                     |
| `traycer config shell set --path <path>`              | Set shell executable path.                                                  |
| `traycer config shell set --path <path> -- <args...>` | Store shell startup args. Pass args after `--` when they start with dashes. |
| `traycer config shell set --clear-args`               | Clear shell startup args.                                                   |
| `traycer config shell reset`                          | Reset shell config.                                                         |
| `traycer config env list`                             | List configured environment overrides.                                      |
| `traycer config env get --key <name>`                 | Show one env override.                                                      |
| `traycer config env set --key <name> --value <value>` | Set an env override.                                                        |
| `traycer config env unset --key <name>`               | Explicitly unset an inherited environment variable.                         |
| `traycer config env delete --key <name>`              | Delete a configured override entry.                                         |

CLI config is stored under `~/.traycer/cli/config.json`.

Provider credentials are not CLI env vars. Configure provider credentials in **Settings → Providers**.

## Workspace and Worktree Commands

| Command                                            | Purpose                                             |
| -------------------------------------------------- | --------------------------------------------------- |
| `traycer workspace list`                           | List known workspaces.                              |
| `traycer workspace list --epic-id <id>`            | List workspaces for a specific Task id.             |
| `traycer worktree create`                          | Create a worktree for agent work.                   |
| `traycer worktree create --workspace <path>`       | Create from a workspace path.                       |
| `traycer worktree create --source-branch <branch>` | Choose the source branch.                           |
| `traycer worktree create --branch <branch>`        | Choose the new worktree branch.                     |
| `traycer worktree create --existing <branch>`      | Check out an existing branch into a fresh worktree. |
| `traycer worktree create --carry-uncommitted`      | Carry uncommitted changes into the worktree.        |

## Agent Commands

| Command                             | Purpose                                         |
| ----------------------------------- | ----------------------------------------------- |
| `traycer agent list`                | List reachable agents.                          |
| `traycer agent create`              | Create a child agent.                           |
| `traycer agent send`                | Send a message to another agent.                |
| `traycer agent transcript`          | Read an agent transcript.                       |
| `traycer agent inbox`               | Inspect pending agent messages.                 |
| `traycer agent selection-guide`     | Read the agent selection guide.                 |
| `traycer agent list-harness-models` | List models for a harness.                      |
| `traycer monitor`                   | Stream this agent's inter-agent inbox messages. |

Supported harness ids include `claude`, `codex`, `opencode`, `traycer`, and `cursor`. Supported surfaces are `gui` and `tui`; Cursor is GUI-only.

Common agent options:

| Option                                  | Applies To                                                                                       | Purpose                                                                            |
| --------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `--epic-id <id>`                        | Most `agent` commands, `monitor`, `workspace list`                                               | Task context. Defaults to `TRAYCER_EPIC_ID` when the command runs inside an agent. |
| `--sender-agent-id <id>`                | `agent list`, `agent create`, `agent selection-guide`, `agent list-harness-models`, `agent send` | Calling agent. Defaults to `TRAYCER_AGENT_ID`.                                     |
| `--all`                                 | `agent list`                                                                                     | List all agents in the Task, not just agents belonging to the current user.        |
| `--surface <surface>`                   | `agent create`                                                                                   | Child surface: `gui` or `tui`.                                                     |
| `--harness <id>`                        | `agent create`                                                                                   | Coding agent: `claude`, `codex`, `opencode`, `traycer`, or `cursor`.               |
| `--model <id>`                          | `agent create`                                                                                   | Model id for the child agent.                                                      |
| `--reasoning-effort <effort>`           | `agent create`                                                                                   | Reasoning effort for supported models.                                             |
| `--fast`                                | `agent create`                                                                                   | Request fast mode for supported GUI models.                                        |
| `--cwd <path>`                          | `agent create`                                                                                   | Primary working directory for the child agent.                                     |
| `--workspace-path <path>`               | `agent create`                                                                                   | Additional existing workspace path. Repeatable.                                    |
| `--workspace-entry <workspace=path>`    | `agent create`                                                                                   | Exact workspace binding. Repeatable.                                               |
| `--to <agentId>` / `--message <text>`   | `agent send`                                                                                     | Required receiver and message.                                                     |
| `--expect-reply` / `--response-id <id>` | `agent send`                                                                                     | Open a reply thread, or close one with the final reply.                            |
| `--agent-id <id>`                       | `agent transcript`, `agent inbox`, `monitor`                                                     | Target agent. `inbox` and `monitor` default to `TRAYCER_AGENT_ID`.                 |

Provider hook commands such as `agent title-from-hook`, `agent activity-from-hook`, and `agent turn-ended-from-hook` are used by Traycer-launched agents on the Terminal interface. They are not normal user workflows.

## Environment Variables

The CLI uses runtime environment variables for noninteractive behavior and agent context.

| Variable                 | Purpose                                 |
| ------------------------ | --------------------------------------- |
| `CI`                     | Signals CI/noninteractive environments. |
| `TRAYCER_NONINTERACTIVE` | Forces noninteractive behavior.         |
| `TRAYCER_CLI_VERSION`    | Build-provided CLI version.             |
| `TRAYCER_AGENT_ID`       | Current agent id in agent-run contexts. |
| `TRAYCER_EPIC_ID`        | Current Task id in agent-run contexts.  |
| `HOME` / `USERPROFILE`   | Used to resolve local Traycer paths.    |

Provider API keys and model credentials belong in provider setup, not in this CLI reference.


# Agent-to-Agent
Source: https://docs.traycer.ai/concepts/agent-to-agent

Understand how Traycer agents delegate work, create child agents, and coordinate inside a Task.

Agent-to-agent communication lets Traycer agents coordinate with each other inside the same Task.

Use it when running agents need to split work, ask another agent to investigate something, get a review, or share results without losing the larger Task context.

## What It Does

An agent can:

* create a child agent
* send another agent instructions
* ask for a reply or send a fire-and-forget message
* read another agent's transcript
* coordinate from the agent session it is running in

The result is still visible in the Task. Child agents appear in the [Agents](/panels/agents) tree under the agent that created them, so the lineage is not hidden.

```text theme={null}
Agent: plan the implementation           (Chat)
├─ Agent: review the database changes    (Chat)
├─ Agent: inspect failing tests          (Terminal)
│  └─ Agent: summarize the failure cause (Chat)
├─ Agent: update the docs plan           (Chat)
└─ Agent: verify the final changes       (Terminal)
```

The tree shows where each agent came from. It does not restrict which agents you can reference: referencing is not limited to a parent or a child.

```mermaid theme={null}
---
title: Any agent can reference any other agent; message delivery is narrower
---
flowchart TD
  A[Agent 1]
  B[Agent 3]
  C[Agent 4]
  D[Agent 2]
  E[Agent 5]
  F[Agent 6]

  A -.-> B
  A -.-> C
  B -.-> A
  C -.-> A

  D -.-> E
  D -.-> F
  E -.-> D
  F -.-> D

  B -.-> E
  C -.-> F
  E -.-> C

  linkStyle default stroke-dasharray: 4 4
```

Dashed edges are **references**, which are always available inside a Task. Whether a message can actually be *delivered* along one of those edges depends on the capability gates below.

## Lineage And Sessions

The agent that starts another agent is the **parent**. The new agent is the **child**.

The child agent has its own session, model, transcript, and run state. It does not merge into the parent agent. The parent can read the result, continue the conversation, or use the child agent's work as context for the next step.

This is why agent-to-agent work shows up as hierarchy in the Agents panel instead of as one flat transcript. Hierarchy is provenance only: any agent can reference any other agent in the Task, not just its own parent or children.

## Agent Selection

Traycer uses agent-selection instructions to choose the right coding agent, model, and reasoning effort for delegated work. Configure those defaults in [Settings > Agent selection](/settings/agents).

## Three Separate Capabilities

Referencing an agent, reading its transcript, and sending it a message are **different capabilities** with **different requirements**. An agent can be fully referenceable while its transcript is unreadable from where you are, and while it cannot receive a message at all. Those are normal states, not errors.

| Capability           | What it requires                                                                                                                                                             |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reference**        | Nothing beyond being a supported agent in the Task. Always available, either interface.                                                                                      |
| **Transcript**       | Same user. A **Chat**-interface agent's history is Task-backed, so it reads across Hosts. A **Terminal**-interface agent's transcript must be read on the Host that owns it. |
| **Receive messages** | Same user; sender **and** receiver both local to the same Host; and both runtimes support agent-to-agent messaging.                                                          |

Referencing is the broad capability. Transcript access is narrower, and delivery is narrowest.

## Agent-To-Agent Support

This table shows what each coding agent's **runtime** allows. The user and Host requirements above still apply on top of it.

| Coding agent             | Chat interface                  | Terminal interface              |
| ------------------------ | ------------------------------- | ------------------------------- |
| **Claude Code**          | Reference, transcript, messages | Reference, transcript, messages |
| **Codex**                | Reference, transcript, messages | Reference and transcript only   |
| **OpenCode**             | Reference, transcript, messages | Reference and transcript only   |
| **Cursor**               | Reference, transcript, messages | Not available                   |
| Every other coding agent | Reference, transcript, messages | Not available                   |

Read this by interface, not by product:

* On the **Chat** interface, every coding agent's runtime allows all three. Chat history is Task-backed, so a peer on another Host can still read it.
* On the **Terminal** interface, only **Claude Code** has an inbox for agent-to-agent messages. **Codex** and **OpenCode** Terminal-interface agents remain referenceable and their transcripts remain readable *from the Host that owns them* — they simply have nowhere to deliver a message.
* **Cursor** is Chat-interface only today, so it has no Terminal-interface row to support. See [Agents & Models](/agents-and-models/coding-agents) for which coding agents can back the Terminal interface at all.

<Warning>
  Runtime support is necessary but not sufficient. Traycer also requires:

  * **Transcript** — the same user. A Terminal-interface transcript additionally
    has to be read on the Host that owns that agent.
  * **Delivery** — the same user, *both* the sending and receiving agent local
    to the same Host, and an A2A-capable runtime on both ends.

  A Claude Code agent on another device is referenceable, but a message to it is
  rejected rather than queued, and its Terminal transcript cannot be read from
  here. See [Hosts](/concepts/hosts).
</Warning>

## Durability Is Not Availability

Closing a Terminal surface does **not** erase the agent's history. Traycer reads a Terminal-interface transcript from the coding agent's own session history rather than from terminal scrollback, so the record survives the terminal — and the app — closing.

That is durability, not universal readability. Reading it still requires the owning Host to be reachable and the coding agent's own session history to still be present. If either is missing, the transcript read fails rather than returning a partial or empty result.

Plain [Terminals](/panels/terminals) do not participate in any of the three. They are shell sessions, not agents.

For the broader distinction, see [Terminal Agents VS Terminals](/concepts/terminal-agents-vs-terminals).

## Related Pages

* [Agents](/panels/agents) explains where parent and child agents appear.
* [Agents & Models](/agents-and-models/coding-agents) lists supported coding-agent paths.
* [Settings > Agent selection](/settings/agents) explains global and workspace-specific agent-selection instructions.


# History
Source: https://docs.traycer.ai/concepts/history

Find, filter, open, rename, and clean up previous Tasks.

History is the place to find Tasks you have worked on before. It is a Task-level view, not an agent transcript view.

Open History when you want to return to earlier work, find a shared Task, or clean up Tasks you no longer need.

## What History Shows

Each History row represents a Task. Rows can show:

* Task title
* last updated time
* linked repositories
* linked workspace folders
* whether the Task is yours or shared with you

Opening a row opens that Task.

## Search, Filter, And Sort

History has search and filters for narrowing long lists of Tasks.

| Control          | What it changes                                           |
| ---------------- | --------------------------------------------------------- |
| **Search**       | Finds Tasks by title and linked repository.               |
| **Ownership**    | Filters between your Tasks and shared Tasks.              |
| **Repositories** | Filters by linked repo.                                   |
| **Workspaces**   | Filters by linked workspace folder.                       |
| **Sort**         | Orders Tasks by most recent, oldest, title, or relevance. |

When search text is active, relevance can be used as the sort order.

## Managing History

History supports management actions for Tasks you can edit.

| Action      | What it does                                           |
| ----------- | ------------------------------------------------------ |
| **Open**    | Opens the selected Task.                               |
| **Rename**  | Changes the Task title.                                |
| **Select**  | Enters selection mode for bulk actions.                |
| **Delete**  | Deletes selected Tasks when your permission allows it. |
| **Refresh** | Reloads the History list.                              |

Viewer-only shared Tasks may not allow rename or delete actions.

## What History Is Not

History is not the same as the **Agents** panel.

* Use **History** to find and open Tasks.
* Use [Agents](/panels/agents) to continue an agent inside an open Task.
* Use [Artifacts](/panels/artifacts) to find specs, tickets, stories, and reviews inside a Task.

History helps you get back to the right Task. The Task's panels hold the actual work surfaces and documents.


# Hosts
Source: https://docs.traycer.ai/concepts/hosts

Understand the Traycer process that owns workspace, terminal, file, and agent operations.

A **Host** is the Traycer process that connects Desktop to workspace folders, files, terminals, git state, and coding agents. A Host can run on the same machine as Desktop or on another reachable machine.

Most of the time, you do not manage Hosts directly. You notice them when Traycer is starting, offline, updating, or when a tab is tied to a different machine.

## What The Host Owns

The Host owns live work that depends on where it is running:

* workspace-folder access
* file previews
* git diffs
* terminal sessions
* agents on the Terminal interface
* provider and coding-agent setup that depends on tools available to that Host

Cloud sync can move durable Task data across machines, but live surfaces still depend on the Host that opened them.

## Multiple Hosts

A user can have more than one Host. For example, your laptop and a workstation can each run a Host, and each Host owns the work it can reach on that machine.

Cross-device Hosts are coming soon. The model is:

* each device can run its own Host
* Desktop can connect to a Host when that Host is reachable
* live surfaces still depend on the Host that started them
* cloud sync carries durable Task data across devices

## Current Host And Tab Host

Traycer can use a Host in two ways:

| Host relationship | Meaning                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Current Host**  | The Host Desktop is currently using for app-wide actions, such as opening Tasks, files, git diffs, and settings. |
| **Tab Host**      | The Host a specific tab or session started on.                                                                   |

Some tabs keep using their original Host:

| Surface                           | Behavior                                                                                                                         |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Chat interface**                | Can continue on another Host by cloning the agent. The clone is a NEW agent; the original stays bound to its Host.               |
| **Terminal / Terminal interface** | Cannot migrate because the PTY is tied to the Host that started it. The agent stays durable and reachable once its Host returns. |
| **File preview**                  | Loads from its Tab Host.                                                                                                         |
| **Git diff**                      | Loads from its Tab Host.                                                                                                         |

If a Host becomes unavailable, affected tabs show an unavailable state. Terminal sessions cannot move to another Host; start a new session on the Current Host when needed.

## Hosts And Agent-To-Agent Work

The Host boundary also gates what one agent can do to another. Referencing is unaffected — every agent in the Task can be referenced regardless of Host. The other two capabilities are not:

| Capability                               | Host requirement                                                                        |
| ---------------------------------------- | --------------------------------------------------------------------------------------- |
| **Reference an agent**                   | None. Works across Hosts.                                                               |
| **Read a Chat-interface transcript**     | None. That history is Task-backed, so it reads across Hosts (same user still required). |
| **Read a Terminal-interface transcript** | Must be read on the Host that owns that agent.                                          |
| **Send an agent-to-agent message**       | Sender and receiver must both be local to the same Host.                                |

A message to an agent on another Host is rejected rather than queued. The full matrix, including the runtime requirements that apply on top of these, is in [Agent-to-Agent](/concepts/agent-to-agent).

## Where To Manage Hosts

Use [Settings > Host](/settings/host) to check Host status, install or update the Host, restart it, and run Doctor diagnostics.

Use [Troubleshooting](/reference/troubleshooting) for unavailable states, logs, and issue-reporting steps.


# Tasks and Workspace Folders
Source: https://docs.traycer.ai/concepts/tasks-and-workspace-folders

Understand Tasks, Task tabs, and workspace folders in Traycer Desktop.

## Task

A **Task** is the top-level container for a piece of work in Traycer. It maps to an outer Task tab and keeps related agents, panels, artifacts, terminal sessions, files, and git diff together.

## Workspace Folder

A **workspace folder** is a local code folder or repo that Traycer can work against. A Task can be associated with one or more workspace folders.

When a workspace folder is a git repository, Traycer can run agent work in the folder itself or in a git worktree. See [Worktrees](/concepts/worktrees).

## How a Task Is Organized

| Part                  | Purpose                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------- |
| **Workspace folders** | The local code folders Traycer can inspect or modify.                                        |
| **Panels**            | Sidebar navigators for agents, artifacts, terminals, files, git diff, sharing, and comments. |
| **Canvas tabs**       | The work surfaces opened from panels, such as agents, artifacts, file previews, and diffs.   |
| **Artifacts**         | Durable specs, tickets, stories, and reviews that preserve intent and progress.              |

Learn the sidebar panel list in [Panels](/panels).


# Terminal Agents VS Terminals
Source: https://docs.traycer.ai/concepts/terminal-agents-vs-terminals

Understand the difference between an agent on the Terminal interface and a plain shell terminal.

Traycer has two terminal-looking surfaces with very different roles. One is an **agent** using the Terminal interface; the other is a plain shell.

Throughout this page, "Terminal Agent" is shorthand for *an agent you interact with through the Terminal interface*. It is not a separate kind of entity from the agents in the [Agents](/panels/agents) panel - it is one of the two interfaces those agents can use.

| Difference             | Terminal Agent                                                                                                                                                                                                                                       | Terminal                                                                                |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **What it is**         | A coding-agent session that runs through a terminal-style interface.                                                                                                                                                                                 | A plain shell session that you control directly.                                        |
| **Traycer context**    | Receives Task context, artifact guidance, skills, and agent-to-agent instructions. Every Terminal Agent is referenceable; its transcript is readable by the same user on its owning Host; only Claude Code can also receive agent-to-agent messages. | Does not receive agent prompts, skills, artifact instructions, or agent-to-agent tools. |
| **Setup**              | Starts with a workspace folder or worktree, coding agent, model, thinking effort, and optional CLI arguments.                                                                                                                                        | Starts with a workspace folder and shell command.                                       |
| **After launch**       | Launch choices stay fixed for that Terminal Agent.                                                                                                                                                                                                   | You control the shell directly.                                                         |
| **Session continuity** | Traycer stores the coding agent's upstream session id and uses it to resume the same agent session when reopened on its original Host.                                                                                                               | No coding-agent session id; it is just a PTY shell.                                     |
| **Listed in**          | [Agents](/panels/agents), because it is an agent.                                                                                                                                                                                                    | [Terminals](/panels/terminals), because it is a shell session.                          |

They can look similar because both use a terminal surface. The difference is that a Terminal Agent is still a Traycer agent, while a Terminal is just a shell.

## Terminal Agents

A **Terminal Agent** runs a coding agent in a PTY, but Traycer still wraps that session with Task context.

Terminal Agents can receive:

* Traycer's system prompt
* the Task id and agent identity
* artifact instructions for specs, tickets, stories, and reviews
* guidance for creating or updating artifacts as markdown files
* Traycer skills and planning/execution instructions
* agent-to-agent communication instructions, and message-receiving tools when the coding agent supports them

That means a Terminal Agent is not the same as opening the coding-agent CLI yourself. Traycer prepares the session so the agent understands the Task, the artifact model, and the multi-agent environment.

## Coding Agents That Support The Terminal Interface

The Terminal interface currently works with:

| Coding agent    | Can back the Terminal interface |
| --------------- | ------------------------------- |
| **Claude Code** | Yes                             |
| **Codex**       | Yes                             |
| **OpenCode**    | Yes                             |

This table is about which coding agents can *run* on the Terminal interface. It is a different question from which of them can receive agent-to-agent messages - see [Agent-to-Agent](/concepts/agent-to-agent).

For the full interface compatibility matrix, see [Agents & Models](/agents-and-models/coding-agents).

## Plain Terminals

A **Terminal** is a shell session.

Use it to run commands yourself: package scripts, tests, dev servers, logs, local debugging, or one-off shell work.

A plain Terminal does not receive Traycer's agent prompt, does not use Traycer skills, does not create artifacts by itself, and does not participate in agent-to-agent communication. It is still part of the Task, but it is not an agent session.

## Launch Setup

When you create an agent on the Terminal interface, you choose its launch setup:

* workspace folder or worktree
* coding agent
* model, when supported
* thinking effort, when supported
* Terminal interface CLI arguments, when supplied

Those choices stay fixed after launch. Start a new Terminal Agent when you need a different workspace folder, worktree, coding agent, model, thinking effort, or argument set.

Worktree choices are covered in [Worktrees](/concepts/worktrees).

Traycer also keeps the upstream coding-agent session id for the Terminal Agent. When the app or Host restarts and the same Terminal Agent is reopened on its original Host, Traycer resumes the underlying coding-agent session instead of starting from scratch.

Plain Terminals do not have a coding agent, model, thinking effort, or artifact behavior. They only need the shell/workspace context used to start the terminal.

## Agent-To-Agent Communication

Referencing an agent, reading its transcript, and sending it a message are separate capabilities with separate requirements.

* **Every** Terminal Agent is referenceable by `@` mention, with no further conditions.
* A Terminal Agent's **transcript** is readable by the same user, **on the Host that owns that agent**. Traycer reads it from the coding agent's own session history rather than terminal scrollback, so the record survives the terminal closing - but reading it still needs the owning Host to be reachable and that provider history to still exist.
* Only **Claude Code** Terminal Agents have an inbox for agent-to-agent **messages**. Codex and OpenCode Terminal Agents run terminal-style work and can be referenced and read, but a message has nowhere to be delivered.
* **Delivery** additionally requires the same user and that both the sending and receiving agent are local to the same Host, whatever the coding agent - see [Hosts](/concepts/hosts).

Every Terminal Agent appears in the Task's agent hierarchy either way, so you can always see where delegated terminal work came from.

The coordination model is covered in [Agent-to-Agent](/concepts/agent-to-agent). Multi-agent defaults are configured in [Settings > Agent selection](/settings/agents). Supported coding agents are listed in [Agents & Models](/agents-and-models/coding-agents).

If you are looking for a terminal-style coding agent, create an agent on the **Terminal** interface from the **Agents** panel. If you are looking for a shell you operate yourself, use **Terminals**.


# Worktrees
Source: https://docs.traycer.ai/concepts/worktrees

Understand how Traycer uses workspace folders and git worktrees for agents and diffs.

A **worktree** is a separate checkout of the same git repository. Traycer uses worktrees so agent work can run in an isolated folder without changing the main workspace folder.

Worktree choices are made per workspace folder. A Task can include more than one workspace folder, and each folder can use its own run location.

## Run Locations

When Traycer asks where an agent should run, each workspace folder can use one of these locations:

| Location              | What it does                                    | When it is available                                                       |
| --------------------- | ----------------------------------------------- | -------------------------------------------------------------------------- |
| **Local**             | Runs against the workspace folder itself.       | Always available. For non-git folders, this is the only option.            |
| **New worktree**      | Creates a new git worktree for the run.         | Available for git repositories.                                            |
| **Existing worktree** | Uses an already-created worktree for that repo. | Available when the Host finds existing worktrees for the workspace folder. |

For a **New worktree**, you can choose the branch source. If the current working tree has uncommitted changes, the branch picker can show a **Working tree** source. Choose that source when you want Traycer to carry those changes into the new worktree.

For an **Existing worktree**, the branch is fixed by that worktree. Traycer uses it as-is.

## New Worktree Branch Options

When you choose **New worktree**, the branch picker shows source branches. The source you choose controls whether Traycer creates a new branch, checks out an existing branch, or carries current changes.

| Source                 | What happens                                                                                                                                                                      |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Current branch**     | Traycer creates a new branch from the current branch and checks it out in a fresh worktree. This is the default clean path.                                                       |
| **Working tree**       | Traycer creates a new branch from the current branch and carries uncommitted changes. This appears when the working tree has changes to carry.                                    |
| **Other local branch** | If you leave the new branch name blank, Traycer checks out that branch in a fresh worktree. If you enter a new branch name, Traycer creates a new branch from that source branch. |
| **Remote branch**      | Traycer creates a local branch from the remote source. The branch name is required and is prefilled from the remote branch name.                                                  |

Branches that are already checked out in another worktree appear under **Existing worktree**, not as checkout options in the **New worktree** branch picker.

## Where You Choose A Worktree

Worktree choices appear in the places where Traycer starts agent work:

| Place                             | What you can choose                                                                                                                                |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **New Task / first agent**        | Workspace folders and the run location for each folder.                                                                                            |
| **Existing agent**                | The run location for the next agent turn.                                                                                                          |
| **New agent in an existing Task** | The starting run location for that new agent.                                                                                                      |
| **Terminal interface launch**     | Workspace folder, run location, coding agent, model, thinking effort, and Terminal interface CLI arguments. These choices stay fixed after launch. |
| **Git Diff**                      | Which worktree's changed files to inspect.                                                                                                         |

On the Chat interface, worktree changes apply to the next agent turn. If Traycer needs to create or set up a worktree first, the agent shows setup progress before continuing. The Terminal interface is different: an agent's workspace and worktree choices are fixed when it starts.

## Worktree Setup

When Traycer creates a worktree, it can run setup and teardown scripts for that workspace folder.

The setup controls let you:

* edit setup and teardown scripts for a folder
* create a new branch in a fresh worktree
* check out an existing branch in a fresh worktree
* create a worktree from the **Working tree** source when uncommitted changes should be carried over
* use an existing worktree instead of creating a new one

Setup can show states such as **Creating worktree**, **Setting up worktree**, **Worktree ready**, **Setup failed**, or **Setup cancelled**. Troubleshooting those states is covered in [Troubleshooting](/reference/troubleshooting#worktree-setup).

## Existing Worktrees

Existing worktrees are useful when you already have a checkout for a branch and want Traycer to use that folder instead of creating another one.

When you select an existing worktree:

* Traycer runs in that existing checkout
* the branch is read-only in the picker because it belongs to the selected worktree
* the worktree can appear in Git Diff and file-related views for that Task

## Managing Worktrees

[Settings > Worktrees](/settings/worktrees) is for management: reviewing worktrees on a Host, refreshing the list, and deleting worktrees when they are safe to remove.

The CLI can also create worktree paths without creating an agent. See [CLI](/cli/commands#workspace-and-worktree-commands).


# Email normalize dedupe migration runbook
Source: https://docs.traycer.ai/email-normalize-dedupe-migration-runbook



# Runbook: Email normalize + dedupe migration (T6)

Production data migration for the account-linking / email-identity plan (Rev 4, rollout step 3).

## What this does

1. **Pre-flight audit** — duplicate groups (normalized email), non-normalized row count, `email = ''` population, and the `lower()` parity precondition.
2. **Full-table normalize** — `lower()` + trim of the **enumerated JS-whitespace class** used by `normalizeEmail` (not Postgres `btrim`/`[[:space:]]` alone — those miss NBSP/BOM).
3. **Purge the normalize-touched users' caches immediately** — before the post-normalize gate can halt the run.
4. **Collision re-detect** after normalize (case-variant twins).
5. **Ranked dedupe** — keep one winner per address; park losers.
6. **Hard manual gate** — refuse mechanical park while any loser holds an ACCEPTED team membership or a non-PENDING personal subscription.
7. **Redis purge** — full user-cache key set mirroring `removeUserFromCache` / `getUserCacheKeys` for winners, losers, and normalized-only rows:
   `authenticatedUser:<id>`, `prismaUser:<id>`, `prismaUser:<providerId>`,
   `userSubscription:<id>`, `collaboratorUserProfile:<id>`,
   `authenticatedUserV2:<id>`, plus `creditSummary:<id>:<customerId>` for every
   customerId recovered from DB and/or cached blobs. (Partial prismaUser-only
   purge is wrong: auth caches embed email and are 24h read-through.)
8. **Farm-group export** — sizes `{18,24,43,48,49}` for trust/safety only (no enforcement).

## Rows this migration deliberately does not touch

`users.email = ''` is **outside** T7's partial unique index
(`WHERE email IS NOT NULL AND email <> ''`) — the product allows those rows, and
production holds **629** of them (2026-07-26).

They are therefore never grouped as a collision, never ranked, and never parked.
The predicate is evaluated on the **normalized** value, because the normalize
pass folds whitespace-only values (`" "`, NBSP, BOM…) to `''` and so creates
more of them. Normalization still applies to those rows: `lower(btrim(' '))` is
`''`, so a whitespace-only value would fail T7's CHECK if it were left unfolded.

The dry run prints the population and exports it to
`email-dedupe-empty-email-*.json`. If a park plan ever names one, the executor
refuses **before writing anything** (see Pre-write preconditions).

## Parking semantics (do not overstate)

Moving a loser's `email` → `former_email` preserves **recoverability of the address value only**.

It does **not** preserve live team access. Team-join sites read `users.email` and degrade to no-access when it is NULL, regardless of `former_email`.

## Prerequisites

| Step   | Requirement                                                   |
| ------ | ------------------------------------------------------------- |
| Schema | T2 applied: `users.former_email` (and related) present        |
| Guards | T2 + T3 deployed so sign-in cannot re-duplicate mid-flight    |
| Client | T5 (cloud-ui 409 / step-up) deployed per rollout order        |
| Env    | `DATABASE_URL` (auth/users Postgres), `REDIS_URL` for execute |

2026-07-25 baseline: **66** duplicated addresses across **392** rows (all GitHub-keyed).

One known dual live-row address is a **hard gate** requiring an explicit ack.
It is deliberately **not written down here or in the source**: the script pins
it by SHA-256 and the dry run names the actual address in
`email-dedupe-manual-gate-*.json`, alongside the exact command to copy. Below,
`<gated-address>` stands for that value.

## Commands

Dry-run is default. **Nothing writes without `--execute`.**

```bash theme={null}
# Pre-flight counts only
DATABASE_URL=... bun scripts/email-normalize-dedupe-migration.ts --audit-only

# Full plan + JSON exports (read-only)
DATABASE_URL=... bun scripts/email-normalize-dedupe-migration.ts

# Apply (refuses if manual-gate queue non-empty, including unacked manual-decision email).
# GATED_ADDRESS is named in the dry run's email-dedupe-manual-gate-*.json;
# it is pinned by digest in the script and never stored in this repo.
GATED_ADDRESS='...'
DATABASE_URL=... REDIS_URL=... bun scripts/email-normalize-dedupe-migration.ts \
  --execute \
  --ack-manual-decision="$GATED_ADDRESS"
```

`--ack-manual-decision=` is **mandatory on every invocation that would park the
known dual-row address**, including re-runs and T7's index-failure recovery loop
— it is not sticky. Every refusal prints the exact command that satisfies the
gates; copy that line rather than reconstructing one. An ack naming any other
address is rejected at parse time (a typo used to be accepted silently and then
hit the same exit 2 with no explanation).

`--skip-cache-purge` is debug-only. Combined with `--execute` it prints a loud warning and writes `email-dedupe-skipped-cache-purge-*.json` with user ids and keys that still need purging — do not use in production. Sweep the fallout with `--purge-user-ids-from=<that file> --execute`.

### Output directory

Exports contain **full lists of production email addresses**. `--output-dir`
defaults to `./.email-dedupe-out`, which is git-ignored, and
`email-dedupe-*.json` is ignored repo-wide as a second line of defence. Do not
redirect them somewhere tracked.

### Timeouts

`getPrismaPgConfig` defaults `query_timeout` to 30s — a web-request budget. This
script issues an unbounded `SELECT` over every in-scope user joined to
`subscriptions`, plus one unindexed full-table `UPDATE`, so it raises both
`query_timeout` and `statement_timeout` to **30 minutes** for its own connection
and prints the effective value on startup. An explicit `?query_timeout=<ms>` in
`DATABASE_URL` still wins if you need something else.

### JSON exports (timestamped)

| File                                 | Contents                                                                                           |
| ------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `email-dedupe-preflight-*.json`      | Counts, duplicate groups, non-normalized sample, `lower()` parity precondition                     |
| `email-dedupe-normalize-diff-*.json` | Every row the normalize pass would rewrite (also the resume source for a cache purge)              |
| `email-dedupe-winners-*.json`        | Full winner list for pre-execution review                                                          |
| `email-dedupe-park-plan-*.json`      | Pre-normalize loser plan for review                                                                |
| `email-dedupe-park-recovery-*.json`  | Final post-normalize park plan, written before the first loser UPDATE; cache-purge recovery source |
| `email-dedupe-manual-gate-*.json`    | Support queue (must be empty to execute) + reason breakdown + re-run command                       |
| `email-dedupe-empty-email-*.json`    | `email = ''` rows — exempt from dedupe by design                                                   |
| `email-dedupe-farm-groups-*.json`    | Suspected trial farms (T\&S hand-off)                                                              |

## Ranking

For each collision group (same normalized email, ≥2 rows):

1. `last_seen_at DESC NULLS LAST`
2. personal subscription `customer_id` **present** beats absent
3. `activated_at DESC NULLS LAST`
4. `created_at DESC`
5. `id ASC` (stable tie-break for idempotent re-runs)

Winner keeps `email`. Each loser: `former_email = email`, `email = NULL`.

## Manual gate

A **loser** is gated (and `--execute` refuses the whole park pass, exit 2) when:

* there is an ACCEPTED `team_memberships` row whose email normalizes to the same address, or
* the user has a personal subscription with `subscription_status <> PENDING`, or
* the group is the known dual-live-row address **and** the operator did not pass
  `--ack-manual-decision="$GATED_ADDRESS"` (after support decides which row wins).
  The dry run names that address; the script never stores it.

Support resolves membership/subscription gated rows **before** re-running `--execute`. For the known dual-row address, decide the winner offline, then re-run with the ack flag. Do not bypass the gate by editing the script.

Normalize may still run; if the gate is non-empty **after** normalize, the script halts before parking. That halt is safe to re-run *because step 3 already purged the normalize-touched users' caches* — see Cache purge ordering.

### Pre-window feasibility query (run this before booking the window)

The gate treats **any** non-`PENDING` subscription status as a block, and `FREE`
is a `SubscriptionStatus`. If production eagerly creates `FREE` rows, essentially
every loser is gated and `--execute` can never proceed. That is a question about
the real distribution, not a bug in the gate — so check it first:

```sql theme={null}
-- Subscription-status distribution across rows that would be dedupe candidates.
SELECT COALESCE(s.subscription_status::text, '(none)') AS status,
       COUNT(*)                                        AS rows
FROM users u
LEFT JOIN subscriptions s ON s.user_id = u.id
WHERE u.email IS NOT NULL
  AND u.email <> ''
  AND lower(btrim(u.email, <js-ws>)) IN (
        SELECT lower(btrim(email, <js-ws>))
        FROM users
        WHERE email IS NOT NULL AND email <> ''
        GROUP BY 1
        HAVING COUNT(*) > 1)
GROUP BY 1
ORDER BY 2 DESC;
```

**Decision it unlocks:** if the gated population is dominated by `FREE`, decide
with support *before* the window whether `FREE` is one of the statuses the plan
meant to gate. Either narrow the gate deliberately (a plan change, not a script
edit) or accept that the queue must be cleared by hand. Discovering this during
the window means the window is wasted.

The dry run reports the same thing from the plan side — `MANUAL-GATE BREAKDOWN`
counts gated losers by reason and by `subscription_status`, and warns explicitly
when every loser is gated.

## Pre-write preconditions

Anything knowable from the plan alone is checked **before the first write**, and
the executor refuses (exit 2) rather than discovering it afterwards:

* no park plan may carry an empty `normalizedEmail` / `emailBefore` (an
  `email = ''` row must never be parked)
* every park plan's stored email must normalize to its own group key
* no plan may park the winner of its own group, and no loser may appear twice
* JS↔Postgres `lower()` parity must hold (see below)

A precondition that can only fail after the write is not a precondition. The
post-run assertions verify the result; they are not the gate.

## Idempotency

* Normalize only updates rows where `email <> lower(btrim(email, <js-ws>))`.
* Park only updates rows that still hold a matching non-null email.
* Re-run after success: zero normalize updates, zero parks, assertions still pass.

## Cache purge ordering

The purge runs **twice**, and the first one is load-bearing:

1. **Right after the normalize `UPDATE`** — for every normalize-touched user,
   before the post-normalize manual gate can halt the run.
2. **After parking** — for winners, parked losers and normalize-touched users.

Without (1), a run that halted at the post-normalize gate left those users
serving their pre-normalize address for the full 24h TTL, **and a re-run could
not repair it**: the touched-user set comes from `normalizeDiff`, which is
computed on the pre-normalize snapshot, so run 2 recomputes it against
already-normalized rows and gets `[]`.

If a run dies harder than that (crash, killed session) between the normalize
`UPDATE` and its purge, the ids are still on disk —
`email-dedupe-normalize-diff-*.json` is written *before* normalization starts:

```bash theme={null}
REDIS_URL=... bun scripts/email-normalize-dedupe-migration.ts \
  --purge-user-ids-from ./.email-dedupe-out/email-dedupe-normalize-diff-<ts>.json \
  --execute
```

Without `--execute` that mode prints the plan and deletes nothing. It also
accepts `email-dedupe-skipped-cache-purge-*.json` and
`email-dedupe-cache-purge-*.json`.

Parking has a separate recovery source because normalization can create a new
collision that did not exist in the preflight park plan. Immediately before the
first loser `UPDATE`, the executor writes
`email-dedupe-park-recovery-*.json`, including the final post-normalize park
set and every customer id it can recover for the credit-summary sweep. If the
process dies during parking or before its Step 5 purge finishes, run:

```bash theme={null}
REDIS_URL=... bun scripts/email-normalize-dedupe-migration.ts \
  --purge-user-ids-from ./.email-dedupe-out/email-dedupe-park-recovery-<ts>.json \
  --execute
```

This intentionally may purge a cache for a plan entry that had not yet been
parked at the moment of the crash; that is safe and ensures no committed loser
is missed. Do not rely on a normal re-run for this recovery: parked rows are
excluded by the loader, so the normal touched-user set cannot rediscover them.

## `lower()` parity (forward-only concern — not a live defect)

`normalizeEmail` is JS `.trim().toLowerCase()`; the SQL is
`lower(btrim(email, <js-ws>))`. The whitespace class is pinned and tested both
directions. The case-folding half is not pinned: PG `lower()` is
`lc_ctype`-dependent and strictly 1:1 per character, while JS `.toLowerCase()`
is locale-invariant with full Unicode mappings. The straggler count cannot see a
divergence — both of its sides use PG's own `lower()`.

For **printable ASCII** the two are identical under every locale including `C`,
so the dry run checks that precondition rather than doing per-row work:

```sql theme={null}
SELECT count(*) FROM users
WHERE email IS NOT NULL AND email <> '' AND email !~ '^[\x20-\x7E]+$';
```

* **0** (production, 2026-07-26) → parity holds by construction; logged, no
  row-level scan.
* **> 0** → the script loads exactly those rows with Postgres' own
  `lower(btrim(…))` and compares row-by-row against `normalizeEmail`. Any
  mismatch is printed and blocks `--execute` via the pre-write preconditions.

**What would actually go wrong:** not an outage. A divergence means two rows for
one mailbox both survive the unique index as distinct strings — JS folds a
trailing `Σ` to final sigma (`ΟΔΟΣ@x.com` → `οδοσ@x.com`) where a 1:1 PG
`lower()` does not. That is a uniqueness leak, not a 500. T7 step 0 records
`datcollate`/`datctype` as the backstop.

## Post-run assertions (automatic on `--execute`)

* Zero duplicate groups among rows inside T7's index predicate
  (`email IS NOT NULL AND email <> ''` — `''` rows are exempt and are *not* a
  duplicate group)
* Zero non-normalized rows
* Every planned parked loser has `email IS NULL` and `former_email` populated
  (a legitimately-empty planned value is not a complaint — and can no longer be
  planned)
* **No cached blob still serves a pre-migration address**

That last one is deliberately content-based, not "the key is absent". These are
read-through caches: any `/api/user` hit repopulates `authenticatedUser:<id>`
with *correct* post-migration data while the sweep is still running, so an
existence check fails a successful migration and gives the operator no way to
tell that from a real one. Reappeared keys are reported as an expected note; the
run only fails if a blob still contains a parked address or a pre-normalize
value.

## Failure / recovery

| Situation                                              | Action                                                                                                                                         |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Manual-gate refuse (exit 2)                            | Resolve queue; re-run dry-run; then `--execute` with the ack flag (the refusal prints the exact command)                                       |
| Pre-write precondition refuse (exit 2)                 | Nothing was written. Fix the plan input; do not bypass                                                                                         |
| Normalize applied, park halted                         | Safe: normalize-touched caches were already purged. Clear the gate, re-run `--execute` (idempotent)                                            |
| Run died between normalize and purge                   | `--purge-user-ids-from=<normalize-diff export> --execute`                                                                                      |
| Run died during/after parking, before Step 5 completes | `--purge-user-ids-from=<park-recovery export> --execute`; do this before declaring a re-run healthy                                            |
| Index build (T7) fails on duplicates                   | **`DROP INDEX CONCURRENTLY IF EXISTS users_email_key` first** — see below — then re-run this script with the ack flag, then recreate the index |
| Mis-ranked user                                        | Support: un-park via `former_email` / reassign email carefully after T7 index exists                                                           |
| Need to un-park                                        | Set `email = former_email`, clear `former_email` only when uniqueness still holds                                                              |

### Why the drop must come first

After a failed `CREATE UNIQUE INDEX CONCURRENTLY`, `users_email_key` remains an
invalid index and reserves its name. `indisready` is **phase-dependent**: a
duplicate encountered during the phase-2 build can leave it `false`, while a
concurrent duplicate caught during phase-3 validation can leave it `true`.
PostgreSQL documents update overhead for failed concurrent builds, so do not use
either value to infer whether the leftover participates in writes or whether it
is safe to keep. The recovery action is the same in both cases: drop the failed
index before retrying so the name is available and no leftover state affects the
retry.

Order is unconditionally: `DROP INDEX CONCURRENTLY IF EXISTS users_email_key`
→ re-run T6 (`--execute --ack-manual-decision=…`) → re-assert T7 step 0 →
recreate the index. The T7 runbook
([`docs/email-uniqueness-check-and-index-runbook.md`](./email-uniqueness-check-and-index-runbook.md))
is authoritative for the DDL half.

## JS whitespace class

Must match `String.prototype.trim()` (see `scripts/email-normalize-dedupe-lib.ts`):

`U+0009..U+000D`, `U+0020`, `U+00A0`, `U+1680`, `U+2000..U+200A`, `U+2028`, `U+2029`, `U+202F`, `U+205F`, `U+3000`, `U+FEFF`.

Postgres `[[:space:]]` / default `btrim` alone are **not** sufficient.

## Out of scope

* CHECK + unique index DDL (T7) — see [`docs/email-uniqueness-check-and-index-runbook.md`](./email-uniqueness-check-and-index-runbook.md). Run T7 only after this script's post-run assertions pass (zero stragglers, zero duplicates).
* authn-v3 write-path changes (T2/T3)
* Farm enforcement / trial clawback (separate T\&S work)
* `team_memberships.email` normalization (noted follow-up)


# Email uniqueness check and index runbook
Source: https://docs.traycer.ai/email-uniqueness-check-and-index-runbook



# Runbook: Email uniqueness — CHECK + partial unique index (T7)

Production ops for the account-linking / email-identity plan (Rev 5, data-model steps 3–4, rollout step 4).

This step **follows** T6. It does not replace it.

| Prior                  | Doc / tooling                                                                                                                                      |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| T6 normalize + dedupe  | [`docs/email-normalize-dedupe-migration-runbook.md`](./email-normalize-dedupe-migration-runbook.md), `scripts/email-normalize-dedupe-migration.ts` |
| This file (T7)         | `packages/common/prisma/ops/users-email-check-and-unique-index.sql`                                                                                |
| Independent, run early | `packages/common/prisma/ops/users-email-lower-index.sql` — the `lower(email)` functional index; see "Companion index" below                        |

## What this does

1. Assert the database locale is the one JS-parity was derived against, **zero
   stragglers**, and **zero duplicate non-empty emails** (hard gates).
2. Add `users_email_normalized_check` as a `CHECK` **`NOT VALID`**.
3. `VALIDATE CONSTRAINT` in a separate statement.
4. `CREATE UNIQUE INDEX CONCURRENTLY users_email_key ON users (email) WHERE email IS NOT NULL AND email <> ''`.
5. Post-deploy: assert the index exists **and is `indisvalid`**.
6. **Deferred (not in this deploy):** switch interim `lower()` lookups to plain strict equality — only after this migration has actually executed in production (execution-run D4).

## Why NOT VALID, then VALIDATE

Adding a CHECK that validates immediately takes an ACCESS EXCLUSIVE lock and full-scans under that lock. Adding **`NOT VALID`** avoids that; `VALIDATE CONSTRAINT` then scans under a weaker lock.

**Trap (do not skip the straggler gate):** a `NOT VALID` CHECK still validates **every UPDATE of an existing row**. `updateUserLastSeen` runs on routine cached `/api/user` traffic. One non-normalized straggler therefore 500s normal sessions with SQLSTATE `23514` (surfaced by Prisma as `P2039` on the delegate path and `P2010` on the raw path — **not** `P2004`, despite the Prisma docs; probed against `@prisma/adapter-pg@7.9`). Zero stragglers is a hard precondition, asserted immediately before step 2 — not a nicety.

`NOT VALID` also does **not** avoid taking the lock, only holding it. The `ALTER TABLE` still needs ACCESS EXCLUSIVE on `users`, and while it waits behind an in-flight long read it blocks every newer statement queued behind it. The `.sql` sets `lock_timeout = '3s'` around steps 1–2 for that reason and explicitly sets it to `0` before step 3 (a timeout would abort a `CONCURRENTLY` build partway). A `55P03` abort means nothing was applied — find the long query, retry when `users` is quiet.

## Measured production facts

Three open questions from the cold review, all answered against production on **2026-07-26**. The `.sql` cites them; step 0 re-checks them at run time.

| Query                                                                             | Value                 | What it settles                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SELECT count(*) FROM users WHERE email = ''`                                     | **629**               | The partial predicate `WHERE email IS NOT NULL AND email <> ''` is load-bearing against real data — a plain full-column `@@unique([email])` would reject 628 of those rows. **Do not** weaken the predicate or fold the index into `schema.prisma`. Note the NULL half of the old justification was wrong: PostgreSQL treats NULLs as distinct by default, so parked dedupe losers never needed the predicate. Empty strings are the whole reason. |
| `… WHERE email IS NOT NULL AND email <> '' AND email !~ '^[\x20-\x7E]+$'`         | **0**                 | Every stored address is entirely printable ASCII, and on ASCII PG `lower()` and JS `.toLowerCase()` map `A-Z → a-z` identically under **every** locale. So `lower()` parity holds by construction for the current data. Cold-review finding 12 is **not a live defect**.                                                                                                                                                                           |
| `SELECT datcollate, datctype FROM pg_database WHERE datname = current_database()` | `C.UTF-8` / `C.UTF-8` | Recorded so the row above can be re-derived if the locale ever changes. Step 0 **pins** this value.                                                                                                                                                                                                                                                                                                                                                |

### What the pin is actually for

It is a **forward-only tripwire**, not a precondition for this run. With the table all-ASCII, existing rows are safe regardless of locale; the pin exists for the day a non-ASCII address first lands — which can only happen via a GitHub verified primary or a GoTrue JWT email, since `update-email` is gated by ajv's ASCII-only `format: "email"`.

Two mappings then diverge regardless of `datctype`, because PG `lower()` is strictly 1:1 per character while JS `.toLowerCase()` applies the full, partly context-sensitive Unicode mappings:

* **final sigma** — JS `"ΟΔΟΣ".toLowerCase()` ends in U+03C2 (`ς`); PG `lower()` gives U+03C3 (`σ`).
* **U+0130 `İ`** — JS yields two code points, `i` + U+0307; PG yields one.

**The consequence is not an outage.** Both divergent forms are already lowercase as far as PG is concerned, so `email = lower(btrim(email))` still holds and the CHECK never fires — no `23514`, no 500. The failure is quieter: `ΟΔΟΣ@x.com` and `οδοσ@x.com` normalize to two different strings under JS's final-sigma rule, so they occupy two rows for one real mailbox and the uniqueness design does not see them as the same address.

Step 0's straggler count **cannot** find any of this — both of its sides use PG's own `lower()`, so it is satisfied by any value PG considers already-folded, including one JS would fold further. The cheap non-ASCII count is the guard, in both this file and T6's dry run, which escalates to a per-row JS↔SQL comparison only when that count comes back non-zero.

## Prerequisites

| Step            | Requirement                                                                                                                                                                               |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| T6 executed     | Normalize + dedupe + cache purge completed in prod                                                                                                                                        |
| T6 verified     | Zero non-normalized rows; zero duplicate non-null emails                                                                                                                                  |
| Auth code       | T2/T3 (and T4 if live) deployed so writes stay normalized and reconcile skips email conflicts                                                                                             |
| Client          | T5 deployed (rollout order)                                                                                                                                                               |
| Companion index | `users-email-lower-index.sql` applied (any time from rollout step 1 — see below). Not a hard gate for this file, but it is what keeps sign-in off a double seq scan during the T6 window. |
| Env             | Admin/**psql** access to the auth users Postgres; no transaction wrapping the whole script. psql specifically: the `.sql` relies on a `\set` meta-command (below).                        |

There is **no local Postgres / Docker / container runtime** on typical agent machines. Do not claim a dry-run of this DDL without a real DB. Unit tests cover the SQLSTATE `23514` application arms only.

## Ordering relative to T6

```text theme={null}
users-email-lower-index.sql  (independent, any time from rollout step 1)
        ·
T6 --audit-only / --execute   →  zero stragglers + zero duplicates
        ↓
T7 step 0                     →  locale pin holds; counts still zero
        ↓
T7 CHECK NOT VALID → VALIDATE → UNIQUE INDEX CONCURRENTLY
        ↓
T7 post-deploy assertions (index + indisvalid)
        ↓
Follow-up (separate change, AFTER prod T7): switch lower() → strict equality
```

If T6 was run days earlier, re-assert counts at T7 step 0 — do not trust an old export.

## Commands

```bash theme={null}
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 \
  -f packages/common/prisma/ops/users-email-check-and-unique-index.sql
```

**`ON_ERROR_STOP` is the difference between a gate and a printed warning.** psql defaults it to **off**: without it, step 0's `RAISE EXCEPTION` is printed and psql runs the *next* statement anyway — adding the CHECK on top of the very stragglers step 0 just refused, which is the `updateUserLastSeen` outage this whole file exists to prevent, reached by following the file.

The `.sql` now carries `\set ON_ERROR_STOP on` as its first executable line, so it is self-guarding. The `-v ON_ERROR_STOP=1` above is belt-and-braces; keep both.

`\set` is a **psql meta-command**. Run this through anything else — a GUI client, a migration runner, `psql -c` per statement — and that line is ignored or rejected, so the file guarantees nothing on its own. In that case you own both halves yourself: abort on the first error, and do not open a transaction around the file (`CREATE INDEX CONCURRENTLY` cannot run inside one).

### Step 0 — assert preconditions

The `.sql` runs all of these inside one enforced `DO` block. They are reproduced here for the case where you are inspecting production before booking the window.

Three abort, two are reported:

```sql theme={null}
-- ABORT (pin / forward-only tripwire): must be C.UTF-8 / C.UTF-8, the locale
-- the lower()-parity argument was derived under. Existing rows are safe
-- regardless — they are all ASCII — so this guards future non-ASCII addresses.
SELECT datcollate, datctype FROM pg_database WHERE datname = current_database();

-- REPORTED: measured 0 on 2026-07-26. While it is 0, PG lower() and JS
-- .toLowerCase() agree by construction and there is nothing to check.
-- (octet_length <> char_length is "multi-byte", i.e. non-ASCII under UTF8.)
SELECT count(*) FROM users
WHERE email IS NOT NULL AND octet_length(email) <> char_length(email);

-- REPORTED: production baseline 629 on 2026-07-26. Exempt from the unique index
-- by predicate. A sharp drop means a dedupe pass consumed them.
SELECT count(*) FROM users WHERE email = '';
```

Then the two counts that can 500 production, which must both be 0:

> **Do not rewrite the whitespace list using `E'...'` escapes.** PostgreSQL
> recognises only `\b \f \n \r \t` (plus octal/hex/unicode) in E-strings and
> takes any other backslashed character literally — so `E'\v'` is the **letter
> `v`**, not U+000B. That puts `v` in the trim set, and every address starting
> with `v` or ending in `.tv` then fails the CHECK. Since `updateUserLastSeen`
> fires on routine `/api/user` traffic, those users would 500 on every request.
> All 25 code points belong in the single Unicode-escape string literal — the
> `U&` form — below.

```sql theme={null}
-- Stragglers (must be 0)
SELECT count(*) AS non_normalized
FROM users
WHERE email IS NOT NULL
  AND email <> lower(
    btrim(
      email,
      U&'\0009\000A\000B\000C\000D\0020\00A0\1680\2000\2001\2002\2003\2004\2005\2006\2007\2008\2009\200A\2028\2029\202F\205F\3000\FEFF'
    )
  );

-- Duplicates (must be 0 rows returned)
SELECT email, count(*) AS n
FROM users
WHERE email IS NOT NULL AND email <> ''
GROUP BY email
HAVING count(*) > 1;
```

If either is non-zero: **stop**. Re-run T6 ([runbook](./email-normalize-dedupe-migration-runbook.md)), then return here. Do not add the CHECK.

Note the straggler query cannot detect a JS↔SQL case-folding divergence — both of its sides use PG's own `lower()`. See "What the pin is actually for" above.

### Steps 1–3 — DDL

As in `packages/common/prisma/ops/users-email-check-and-unique-index.sql`:

1. `SET lock_timeout = '3s'` — then `ALTER TABLE … ADD CONSTRAINT users_email_normalized_check … NOT VALID`
2. `ALTER TABLE … VALIDATE CONSTRAINT users_email_normalized_check`
3. `SET lock_timeout = 0; SHOW lock_timeout;` — then `CREATE UNIQUE INDEX CONCURRENTLY users_email_key ON users (email) WHERE email IS NOT NULL AND email <> ''`

Setting `lock_timeout` to `0` before step 3 is deliberate: `RESET` would restore
any timeout configured at startup, for the database, or for the deploy role.
The `SHOW` records the effective setting. A `CONCURRENTLY` build waits for
existing transactions by design, and a non-zero `lock_timeout` could abort it
partway — leaving the invalid index described below.

## Build-failure loop (expected path)

Index or VALIDATE failures are **normal** if any row slipped past T6 or was written mid-flight. Treat the loop below as the default recovery, not an incident exception.

| Failure                                             | What Postgres left behind                                                                                                                                                                               | Recovery                                                                                                                                                                |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ALTER TABLE` aborts with `55P03 lock_timeout`      | Nothing — the transaction rolled back                                                                                                                                                                   | Find the long-running query holding a lock on `users` (`pg_stat_activity` / `pg_locks`), wait it out, re-run the file. Do not raise `lock_timeout` to force it through. |
| `VALIDATE CONSTRAINT` finds stragglers              | CHECK exists but is not validated (`convalidated = false`)                                                                                                                                              | Drop CHECK → re-run T6 → re-assert step 0 → re-add NOT VALID → VALIDATE → index                                                                                         |
| `CREATE UNIQUE INDEX CONCURRENTLY` finds duplicates | **Invalid** index (`pg_index.indisvalid = false`) still named `users_email_key`. `indisready` can be `false` when the duplicate is found during phase 2, or `true` after the index becomes write-ready. | `DROP INDEX CONCURRENTLY IF EXISTS users_email_key` **first** — before anything else, including before re-running T6 → then re-run T6 → re-assert → recreate index      |
| Concurrent writes re-introduce a bad row mid-build  | Same as above                                                                                                                                                                                           | Same loop; confirm T2/T3 write-path normalization is live                                                                                                               |

### Why the DROP comes first, always

A failed `CREATE UNIQUE INDEX CONCURRENTLY` leaves the index with:

* `indisvalid = false` — the **planner** ignores it. It answers no queries.
* `indisready` is phase-dependent: it can be `false` when a duplicate aborts the
  phase-2 build before the index becomes ready. If it is `true`, every **INSERT
  and UPDATE** still maintains it and therefore enforces its uniqueness.

Either reading has the same recovery: **drop the incomplete index before fixing
data.** `indisready = true` is an enforcing write hazard; either state blocks a
replacement with the same name, and no recovery step benefits from keeping it.
Drop the index, *then* re-run T6.

> The T6 runbook must agree with this ordering. If it says "re-run this script, then retry the concurrent unique index" without a `DROP INDEX CONCURRENTLY` first, that instruction is wrong and this section wins.

```sql theme={null}
-- Drop invalid / incomplete objects before retrying. In this order.
DROP INDEX CONCURRENTLY IF EXISTS users_email_key;
ALTER TABLE users DROP CONSTRAINT IF EXISTS users_email_normalized_check;
```

Confirm the drop landed before touching data:

```sql theme={null}
SELECT i.relname, ix.indisvalid, ix.indisready
FROM pg_class t
JOIN pg_index ix ON ix.indrelid = t.oid
JOIN pg_class i ON i.oid = ix.indexrelid
WHERE t.relname = 'users' AND i.relname = 'users_email_key';
-- expect: zero rows
```

Then:

```bash theme={null}
# Re-dedupe / re-normalize stragglers (T6).
# GATED_ADDRESS is named in the T6 manual-gate export
# (email-dedupe-manual-gate-*.json) — it is not committed to this repo.
GATED_ADDRESS='...'
DATABASE_URL=... REDIS_URL=... bun scripts/email-normalize-dedupe-migration.ts \
  --execute \
  --ack-manual-decision="$GATED_ADDRESS" \
  --output-dir ./email-dedupe-out

# Re-assert step 0, then re-run T7 DDL
```

Repeat until VALIDATE and the concurrent index both succeed.

## Post-deploy assertions

All of these must pass before calling T7 done:

```sql theme={null}
-- 1. CHECK exists and is validated
SELECT conname, convalidated
FROM pg_constraint
WHERE conname = 'users_email_normalized_check';
-- expect: one row, convalidated = true

-- 2. Index exists AND is valid (indisvalid is the CONCURRENTLY footgun)
SELECT i.relname AS index_name, ix.indisvalid, ix.indisready, ix.indisunique
FROM pg_class t
JOIN pg_index ix ON ix.indrelid = t.oid
JOIN pg_class i ON i.oid = ix.indexrelid
WHERE t.relname = 'users'
  AND i.relname = 'users_email_key';
-- expect: one row, indisvalid = true, indisready = true, indisunique = true

-- 3. Still zero stragglers / duplicates (same queries as step 0)
```

If `users_email_key` exists with `indisvalid = false`, T7 is **not** done. Do
not use `indisready` to choose a recovery: `false` is possible when a duplicate
aborts phase 2 before the index is ready, and `true` means it is still enforced
on writes even though the planner cannot use it. In either case the object blocks
a later `CREATE UNIQUE INDEX CONCURRENTLY` with the same name. Drop and rebuild
before data fixes (see [Why the DROP comes first](#why-the-drop-comes-first-always)).

## Application belt-and-braces (SQLSTATE `23514`)

After the CHECK is live, a non-normalized write fails with Postgres `23514`. Detection keys on that SQLSTATE, not on a `P…` code: this stack emits `P2039` (delegate) or `P2010` (raw), never `P2004`.

authn-v3 handles this on user-update paths:

| Path                                                     | Behavior                                                                                                                     |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Sign-in reconcile (`reconcileUserWithEmailConflictSkip`) | Catch → `Logger.error` (Sentry in prod) → **skip email field**, still land non-email writes. **Must never 500 the sign-in.** |
| `POST /user/update-email`                                | Catch → `Logger.error` (Sentry) → **400**, no silent success                                                                 |

Stable log prefix for grepping: `EMAIL_CHECK_VIOLATION` (see `authn-v3` unique-constraint / reconcile modules). Expected steady state after T6+T7: **0**.

### Pre-deploy forced-violation test (needs live DB)

Not runnable without Postgres. Before enabling traffic confidence, on a **staging** clone (or a one-row throwaway):

1. Confirm `users_email_key` is valid.
2. Attempt `INSERT`/`UPDATE` of a second row with the same non-null email → expect unique violation; record Prisma `meta.target` for T1 probe (email index literal).
3. Attempt `UPDATE` setting `email` to a non-normalized value (e.g. `'Foo@Example.com'`) → expect CHECK / SQLSTATE `23514` (Prisma `P2039` or `P2010`).
4. Attempt a non-email `UPDATE` (e.g. `last_seen_at` only) on a **normalized** row → must succeed (CHECK not tripped).

## Deferred step — switch `lower()` lookups to strict equality

**Not part of the T7 code deploy.** Execution-run **D4**: shipping strict equality before production data is normalized forks accounts and re-breaks the incident cohort.

Only after **this runbook's post-deploy assertions pass in production**:

1. Replace interim `lower(email) = $normalized` matchers with plain equality on:
   * sign-in resolution
   * `update-email` duplicate guard
   * `findExistingUser` insensitive email fallback
   * dedupe tooling lookups that still use `lower()`
2. Leave out of scope: `team_memberships.email` joins (un-normalized on the other side — separate follow-up).
3. Ship as its own PR/deploy after T7 ops, with a greppable checklist that prod `non_normalized = 0` still holds.

Until that follow-up lands, T3's interim `lower()` lookups remain correct and required.

## Companion index — `users (lower(email))`

`packages/common/prisma/ops/users-email-lower-index.sql`. Separate file, separate step, **no dependency on this runbook's gates** — run it any time from rollout step 1 onward, and earlier is better.

Every interim email lookup in authn-v3 matches `lower(email) = $1`. `users_email_key` is a plain btree on `email`, so it cannot serve those queries — and neither could the `mode: "insensitive"` form they replaced, so this is not a regression. What changed is the *count*: the reconcile pre-check (`isEmailClaimedByAnotherUser`) adds a **second** full scan of `users` to every sign-in that refreshes an email, on top of resolution's own lookup.

Why it is not folded into the T7 `.sql`:

| Reason       | Detail                                                                                                                                                                                                                                                                                                           |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ordering     | T7 aborts unless stragglers and duplicates are already zero. The functional index is a pure read optimisation, correct at any data-quality state — and the period it is needed *most* is the T6 normalize/dedupe window, i.e. **before** T7 may run at all. Behind T7's gate it would arrive after the pressure. |
| Independence | It has nothing to do with the CHECK or with uniqueness, and nothing in T7's build-failure loop should ever drop or rebuild it.                                                                                                                                                                                   |
| Lifetime     | Not transitional. Execution-run **D4** defers the switch to plain equality indefinitely, so `lower(email) = $1` is the live shape for the foreseeable future.                                                                                                                                                    |

It is non-unique and non-partial on purpose (rationale in the file header). Because it is non-unique, a failed `CONCURRENTLY` build leaves an invalid index that enforces nothing — unlike `users_email_key`, it is not a write hazard, only unusable. Drop and retry: `DROP INDEX CONCURRENTLY IF EXISTS users_email_lower_idx;`

Dropping it later is a deliberate separate step: verify no `lower(email)` matcher remains in authn-v3 first.

## Prisma / schema notes

* The partial unique index is **not** declared as `@@unique` on `User` (inexpressible predicate — and per the measured 629 `email = ''` rows, the predicate is load-bearing, not stylistic).
* `prisma migrate diff` may propose dropping `users_email_key`. **Reject that drop.** The schema comment on `User.email` documents this. The same applies to `users_email_lower_idx` — expression indexes are equally inexpressible in the Prisma schema.
* App code already treats `users_email_key` as a known `P2002` target (`USER_EMAIL_UNIQUE_TARGETS`).
* The `user_identities` migration is split in two — `20260725190000_user_identities_and_email_source` (schema, `lock_timeout = '3s'`) then `20260725190100_backfill_user_identities` (backfill) — so the ACCESS EXCLUSIVE lock from `ALTER TABLE "users"` is not held across a full-table backfill. Both apply in one `prisma migrate deploy`; if the second fails, do not start serving on the half-applied deploy (`user_identities` exists but is empty).
* `.github/workflows/db_migrations.yaml` auto-runs `prisma migrate deploy` against **Dev / Local / Staging** on any push to `development` touching `packages/common/prisma/migrations/**`. A `55P03 lock_timeout` there rolls back cleanly but records a *failed* migration that blocks later deploys — clear it with `prisma migrate resolve --rolled-back <name>` and re-deploy. Recovery details are in each migration's header.

## Failure / recovery summary

| Situation                                            | Action                                                                                                                                                                                                                                                        |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Step 0 straggler / duplicate count non-zero          | Re-run T6; do not DDL                                                                                                                                                                                                                                         |
| Step 0 aborts on `datcollate`/`datctype`             | This is not the locale the parity argument was derived under. Re-derive it (start with the non-ASCII count; escalate to T6's per-row JS↔SQL comparison only if it is non-zero), then update the pin in the `.sql` — do not widen it to make the abort go away |
| Step 0 reports non-ASCII emails > 0                  | Not a blocker, and **not** a 500 risk — the CHECK cannot fire on it. Run T6's per-row JS↔SQL comparison to see whether any pair of rows is one mailbox split in two by JS's final-sigma / U+0130 rules                                                        |
| Step 0 reports `email = ''` well under 629           | Not a blocker, but stop and find out what consumed those rows before adding a unique index over the result                                                                                                                                                    |
| `55P03 lock_timeout` on `ALTER TABLE`                | Nothing applied. Clear the long-running query on `users`, retry                                                                                                                                                                                               |
| VALIDATE fails                                       | Drop CHECK → T6 → retry (build-failure loop)                                                                                                                                                                                                                  |
| CONCURRENTLY fails / `indisvalid = false`            | `DROP INDEX CONCURRENTLY` **first** (it still enforces on writes) → T6 → retry                                                                                                                                                                                |
| `EMAIL_CHECK_VIOLATION` alerts non-zero after deploy | Find non-normalized writes or stragglers; fix data; do not ignore                                                                                                                                                                                             |
| Need to roll back DDL                                | Drop index concurrently, drop CHECK; app remains safe on `lower()` lookups. Leave `users_email_lower_idx` alone — it is independent                                                                                                                           |

## Out of scope

* Switching `lower()` → equality (deferred step above)
* Monitoring dashboards
* `team_memberships.email` normalization
* Farm / trial clawback


# Extension Changelog
Source: https://docs.traycer.ai/extension/changelog

Track updates and improvements to the Traycer IDE extension

<Update label="v2.16.5">
  * Resolved activation issues on Windows x64.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.16.4">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.16.3">
  * Comments in Epic Mode:
    * Add comments to Specs and Tickets to share feedback and collaborate with your team
    * View and reply to comments in real time
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.16.2">
  * In-app notifications:
    * Get notified when you are invited to an Epic or when permission changes occur for your Epic within the extension.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.16.1">
  * Bug fixes
</Update>

<Update label="v2.16.0">
  * Collaboration in Epic Mode:
    * Share complete Epic boards and project specs with your team
    * Invite collaborators directly to a shared Epic board by email or GitHub handle
    * Collaborate on the same board in real time
    * Assign tickets to specific teammates
  * Task history syncs automatically across all your devices - sign in with the same account to pick up where you left off
  * Bug fixes and performance improvements
</Update>

<Update label="v2.15.15">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.15.14">
  * Bug fixes
</Update>

<Update label="v2.15.13">
  * Model Selection:
    * Added support for selecting different model profiles and models.
    * Choose from the best available models currently on the market based on your needs.
    * Model profiles are preconfigured with various model combinations for different Traycer features.
    * Predefined model profiles are available: Balanced and Frontier.
    * Create custom model profiles and save them for future use.
  * Added support for Antigravity on MacOS.
  * Resolved activation issues on Windows ARM64.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.15.12">
  * Organization Bundles:
    * Organizations can now purchase shared credit bundles
    * Credits from these bundles can be distributed as monthly limits to team members
</Update>

<Update label="v2.15.11">
  * Bug fixes
</Update>

<Update label="v2.15.10">
  * Bug fixes
</Update>

<Update label="v2.15.9">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.15.8">
  * Pricing Update:
    * Introduced new credit-based pricing plans
    * All plans now include monthly credits
    * Added bonus credits on top of guaranteed monthly credits
    * Added optional credit bundles
    * Introduced Ultra+ plan for high-volume usage
    * See full details: [Pricing Docs](https://docs.traycer.ai/account/pricing)
  * New Traycer Agile Workflow commands:
    * Two new commands are now available to speed up iteration and improve spec quality:
      * `/revise-requirements`: Useful when the requirements have changed and you need to update the specs, tech plan, and tickets.
      * `/cross-artifact-validation`: Useful to validate the consistency across the specs and tickets in the Epic.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.15.7">
  * Resolved the issue of CLI agents not working on Windows.
  * Resolved the issue of task history not loading after restarting the webview.
  * Bug fixes.
</Update>

<Update label="v2.15.6">
  * Added a new environment variable that allows custom CLI agents to append extra instructions in the system prompt.
  * Bug fixes.
</Update>

<Update label="v2.15.5">
  * Improved history loading performance with reduced load times
  * Bug fixes and performance improvements
</Update>

<Update label="v2.15.4">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.15.3">
  * Bug fixes.
</Update>

<Update label="v2.15.2">
  * Bug fixes.
</Update>

<Update label="v2.15.1">
  * Resolved an issue where full plan content was not visible during streaming
  * Resolved a bug that caused Pay-as-you-go to fail in Epic Chat
</Update>

<Update label="v2.15.0">
  * Executions in Epic Mode
    * Tracks coding agent handoffs
    * Execution details are visible directly within the Epic view

  * Smart YOLO in Epic Mode
    * Automatically executes Epics using your coding agents
    * Steers agents by updating the tickets or tech plan as new facts are discovered during implementation
    * Verifies changes after completion

  * Agent modes in Epic workflows
    * Planner and Reviewer modes tailored for different use cases
    * Each mode uses its own model, reasoning setup, and system prompt
    * Selectable per command when running workflows in Epic mode
</Update>

<Update label="v2.14.13">
  * Bug fixes
</Update>

<Update label="v2.14.12">
  * Resolved issues with default CLI agents.
</Update>

<Update label="v2.14.11">
  * Multi-Chat in Epic Mode
    * Create multiple chat tabs within a single epic
    * Improve context management across chats in an epic
    * Visualize context usage in each chat to show how much context is consumed
</Update>

<Update label="v2.14.10">
  * Bug fixes.
</Update>

<Update label="v2.14.9">
  * Resolved the issue of duplicate text received in the epic chat.
  * Bug fixes.
</Update>

<Update label="v2.14.8">
  * Resolved the problem where tasks wouldn't open from the task history.
  * Bug fixes.
</Update>

<Update label="v2.14.7">
  * Resolved the issue of templates not found errors.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.14.6">
  * Resolved the issue of switcher between plan and review mode not working.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.14.5">
  * Resolved the issue of skip commit not working in YOLO mode.
</Update>

<Update label="v2.14.4">
  * Phase Board enhancements:
    * Added Commit stage to Phases for better version control integration.
    * Mark as done and reset buttons for fine-grained state machine control of Phases on the Phase Board.
  * UI improvements:
    * Added copy button on code blocks in conversation view for easier code sharing.
    * Mention nodes now display as embedded chips for cleaner UI.
    * Introduced extensible file icon library with smart defaults (no more manual icon configuration).
    * Document list layout improvements.
  * Bug fixes:
    * Fixed duplicate user query serialization in plan/review mode.
    * Potential fix for infinite plan streaming issue.
</Update>

<Update label="v2.14.3">
  * Revert changes done for Antigravity on MacOS.
</Update>

<Update label="v2.14.2">
  * Added support for Antigravity on MacOS.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.14.1">
  * Added support for exporting specs and tickets as Markdown files.
  * Fixed the issue with Manage Templates not working in Epic Mode.
  * Resolved the issue where the extension failed to activate on certain VS Code versions.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.14.0">
  * Epic Mode:
    * Introduced Epic Mode, a new workspace for spec-driven development where your engineering work lives as a structured system of Specs + Tickets.
    * Create, edit, and reference multiple Specs inside an Epic, then decompose directly into Tickets for execution.
  * Workflows (guided, command-driven):
    * Epic Mode is driven through workflows, including a default Traycer Agile Workflow that guides users through requirement capture → planning → ticket breakdown.
    * Workflows are flexible and command-driven: you can branch, skip, or go deeper as needed, while Traycer suggests the next-best command to maintain momentum and keep the user experience effortless.
  * Wireframes:
    * For UI changes, Specs include HTML wireframes so you can quickly see what the UI will look like.
    * To update a wireframe, just ask in the Epic chat and we'll revise it there.
  * Execution from Epic:
    * Execute individual or multiple specs/tickets or the entire Epic at once.
    * Execution options from an Epic: Phases or Handoff to Agent-choose the right level of checkpointing based on the task's complexity and your preferences.
    * Each execution mode carries forward the Epic's context, so you don't have to keep rebuilding context from scratch.
  * Streaming Q\&As and Phases:
    * Questions and phases now stream in as they're generated, so you can start reviewing and acting immediately instead of waiting for the full set to load.
  * Performance, stability, and bug fixes.
</Update>

<Update label="v2.13.5">
  * Added support for hand off to Antigravity.
</Update>

<Update label="v2.13.4">
  * Fixed the failures observed in the plan generation.
</Update>

<Update label="v2.13.3">
  * Bug fixes.
</Update>

<Update label="v2.13.2">
  * Bug fixes.
</Update>

<Update label="v2.13.1">
  * Resolved issues with plan iteration.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.13.0">
  * Streaming Plans:
    * Plans now stream in real time, letting you watch Traycer build the plan as it thinks.
    * Improved plan generation performance with more detailed and actionable steps delivered faster.
  * Context Gathering Agents and tool-call visibility:
    * Traycer now surfaces the specialized sub-agents it spins up for complex tasks.
    * You can see which sub-agents are active, which tools they’re calling, and how they collaborate via a live tool-call stream.
  * Interactive Q\&A in Phase Chat:
    * Phase Chat now supports interactive requirement gathering via multiple-choice prompts.
    * Users can respond either through quick-select options or free-form text, reducing ambiguity and errors.
  * Navigation improvements:
    * Added breadcrumbs on Phase Board and Phase Details pages for quick navigation back to the Phase Board or Phase Chat.
    * Introduced a drop-down switcher to jump between phases within the same board while viewing phase details, making comparison and cross-phase navigation smoother.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.12.10">
  * Added support for temporary files in CLI agents to handle large prompts.
  * Bug fixes.
</Update>

<Update label="v2.12.9">
  * Bug fixes
</Update>

<Update label="v2.12.8">
  * Bug fixes
</Update>

<Update label="v2.12.7">
  * Bug fixes.
</Update>

<Update label="v2.12.6">
  * Bug fixes.
</Update>

<Update label="v2.12.5">
  * Custom CLI Agents:
    * Introduced support for adding custom CLI agents to execute CLI-based coding agents of your choice.
    * CLI agents are now also compatible with Windows systems.
  * Bug fixes.
</Update>

<Update label="v2.12.4">
  * Added support for exporting the phases proposed by Traycer.
  * Added a re-review button to easily trigger incremental reviews on top of the proposed review comments.
  * Bug fixes.
</Update>

<Update label="v2.12.3">
  * Bug fixes.
</Update>

<Update label="v2.12.2">
  * Bug fixes.
</Update>

<Update label="v2.12.1">
  * Resolved the issue of YOLO mode failing when plan generation step is skipped.
</Update>

<Update label="v2.12.0">
  * YOLO Mode:
    * Introduced YOLO Mode to enable continuous task execution without manual intervention.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.11.12">
  * Resolved the issue of plan generation requests getting stuck forever.
  * Bug fixes.
</Update>

<Update label="v2.11.11">
  * Added support for additional coding agents:
    * Claude Code Extension
    * Codex Extension
    * Amp
    * Zencoder
  * Bug fixes.
</Update>

<Update label="v2.11.10">
  * Resolved the issue where the plan generation button was not available after summary type plans were generated.
</Update>

<Update label="v2.11.9">
  * Resolved the issue where some previous phases were incorrectly displayed as active.
</Update>

<Update label="v2.11.8">
  * Resolved an issue where incorrect phases were being marked as active.
  * Resolved accessibility issues with the query input box.
</Update>

<Update label="v2.11.7">
  * Resolved the issue of verification failing due to missing implementation plan error.
</Update>

<Update label="v2.11.6">
  * AGENTS.md support:
    * Introducing support for [AGENTS.md](https://agents.md) to provide machine-readable, project-specific instructions.
    * Traycer will automatically detect and utilize AGENTS.md files when generating and executing artifacts; no configuration or setup needed.
  * Enhanced the readability of proposed plans.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.11.5">
  * Resolved issue with trial status not updating.
  * Bug fixes and UX improvements.
</Update>

<Update label="v2.11.4">
  * Resolved the issue of Regenerate Plan button not working.
</Update>

<Update label="v2.11.3">
  * Expanded the number of commits users can select in the git mention.
  * Fixed focus issue in plan iteration chat input form.
</Update>

<Update label="v2.11.2">
  * Fixed the issue of plan generation failing due to missing implementation plan error.
</Update>

<Update label="v2.11.1">
  * Re-enabled the verification request for completed tasks.
</Update>

<Update label="v2.11.0">
  * Introduced Review Workflow:
    * Agentic code review with thorough exploration and analysis.
    * Perfect for comprehensive code quality checks where you want deep insights into implementation details, potential issues, and improvement opportunities.
  * User Query Handoff:
    * You can now bypass the plan and directly send the generated user query to your agent for fixes.
  * Git Mention Support:
    * You can now attach diffs against uncommitted changes, main branch, a specific branch, or a specific commit, while creating a task.
  * Pro+ Plan:
    * Introduced Pro+ plan with higher slot capacity and recharge rate for power users.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.10.20">
  * Resolved the issue of intermittent timed out waiting for a response errors.
</Update>

<Update label="v2.10.19">
  * Bug fixes.
</Update>

<Update label="v2.10.18">
  * Bug fixes
</Update>

<Update label="v2.10.17">
  * Bug fixes
</Update>

<Update label="v2.10.16">
  * Added a selection option for proposed phases to facilitate easy merging or referencing in chat.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.10.15">
  * Resolved the issue where the prompt templates directory gets created in workspace folders when the Traycer extension is activated.
  * Bug fixes.
</Update>

<Update label="v2.10.14">
  * Bug fixes.
</Update>

<Update label="v2.10.13">
  * Added search functionality to the Task history.
  * Enabled visibility of all tasks across all workspaces in the Task history.
  * Enhanced techniques to overcome context window limitations.
  * Bug fixes.
</Update>

<Update label="v2.10.12">
  * Resolved the plan hand-off failure with the Generic template.
</Update>

<Update label="v2.10.11">
  * Reduced verification latency to receive comments more quickly.
  * Improved the quality of phases generated by Traycer.
  * Added support to display the prompt template errors as CodeLens.
  * Added beta support for setting the language preference of Artifacts generated by Traycer through IDE settings.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.10.10">
  * Custom Hand-off Templates:
    * You can now create custom prompt templates to pass personalized instructions for code generation when handing off to any agent.
  * Bug fixes.
</Update>

<Update label="v2.10.9">
  * Resolved the issue of all phases disappearing when deleting a phase.
</Update>

<Update label="v2.10.8">
  * Bug fixes.
</Update>

<Update label="v2.10.7">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.10.6">
  * Bug fixes.
</Update>

<Update label="v2.10.5">
  * Bug fixes.
</Update>

<Update label="v2.10.4">
  * Fixed the issue of verification section not showing up after plan execution.
</Update>

<Update label="v2.10.3">
  * Fixed the problem causing Traycer to restart unexpectedly during plan creation or verification.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.10.2">
  * Bug fixes.
</Update>

<Update label="v2.10.1">
  * Enhanced authentication process.
  * Fixed the light theme issue with verification.
</Update>

<Update label="v2.10.0">
  * Support for MCP servers now available:
    * You can set up remote MCP servers to offer context or execute actions outside the codebase.
  * Verification process enhanced:
    * Support for incremental re-verification added to review changes via proposed comments.
    * Re-verification from the scratch can now be triggered.
    * Comments can be marked as applied manually.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.9.17">
  * Bug fixes.
</Update>

<Update label="v2.9.16">
  * Bug fixes.
</Update>

<Update label="v2.9.15">
  * Bug fixes.
</Update>

<Update label="v2.9.14">
  * Bug fixes.
</Update>

<Update label="v2.9.13">
  * Added "Fix all" button to fix all the review comments on a file at once.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.9.12">
  * Introducing post-phase conversation to enable iteration on generated phases.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.9.11">
  * Improved the verification results by taking the plan chat into consideration.
  * Added "Fix all" button to fix all the verification comments at once.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.9.10">
  * Resolved the issue of plan generation failing due to missing binaries.
  * Set the Phases mode as the default for Task.
</Update>

<Update label="v2.9.9">
  * Bug fixes.
</Update>

<Update label="v2.9.8">
  * Introducing a filter for verification comments according to severity.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.9.7">
  * Resolved the problem of auto analysis getting stuck at pending state.
  * Added support for exporting the plan as Markdown.
</Update>

<Update label="v2.9.6">
  * Resolved the issue of errors occurring during plan generation.
</Update>

<Update label="v2.9.5">
  * Added support for persisting the user query when plan iteration fails.
  * UX improvements around plan iteration.
  * Added a "Generate Plan" button for cases when Traycer offers a plan without any file change suggestions.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.9.4">
  * Added a section to the extension UI for tracking rate limits and plan details.
</Update>

<Update label="v2.9.3">
  * Multi-Agent Planner:
    * At the request of our users, we are re-introducing the multi-agent planner.
  * Improved the authentication process.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.9.2">
  * Bug fixes
</Update>

<Update label="v2.9.1">
  * Bug fixes
</Update>

<Update label="v2.9.0">
  * Introduced Phases mode for handling complex tasks in multiple guided steps.
  * Added support for interactive interviews to gather additional context before plan generation.
  * Implemented phase-by-phase verification to confirm output before progressing.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.8.15">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.8.14">
  * Resolved an issue that prevented the task list from loading.
</Update>

<Update label="v2.8.13">
  * Bug fixes.
</Update>

<Update label="v2.8.12">
  * Resolved the issue of plan iteration not working.
</Update>

<Update label="v2.8.11">
  * Resolved the issue causing plan execution failures in certain cases.
</Update>

<Update label="v2.8.10">
  * Resolved an issue that prevented the task list from loading.
</Update>

<Update label="v2.8.9">
  * Bug fixes and performance improvements
</Update>

<Update label="v2.8.8">
  * Bug fixes and performance improvements
</Update>

<Update label="v2.8.7">
  * Bug fixes and performance improvements
</Update>

<Update label="v2.8.6">
  * Display the reasoning used while generating the plan.
</Update>

<Update label="v2.8.5">
  * Added support for VS Code Server for plan execution.
  * Bug fixes.
</Update>

<Update label="v2.8.4">
  * Added support for Gemini and VS Code Insiders for plan execution.
  * Bug fixes.
</Update>

<Update label="v2.8.3">
  * Bug fixes.
</Update>

<Update label="v2.8.2">
  * Bug fixes.
</Update>

<Update label="v2.8.1">
  * Display a notification if the chosen AI Agent is not installed.
</Update>

<Update label="v2.8.0">
  * Improved the UX for plan iteration.
    * Introduced a new section "Plan Chat" inside the Plan Specification step for clarifications and questions about the plan.
  * Support for your favorite AI Agents for plan execution.
    * Introduced a new setting to select the AI Agent of your choice for plan execution.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.7.3">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.7.2">
  * Bug fixes.
</Update>

<Update label="v2.7.1">
  * Fixed issues observed around plan iteration.
  * Resolved the issue of empty plan being sent to the IDE native agent for execution.
</Update>

<Update label="v2.7.0">
  * One-Click Handoff:
    * Seamlessly execute Traycer’s step-by-step implementation plans in the IDE native agent with a single click.
  * Improved Plan Iteration:
    * Speed up plan iteration.
    * Quote a section of the plan to iterate on it.
  * Bug fixes.
</Update>

<Update label="v2.6.6">
  * Improved the code generation logic to generate more accurate and relevant code.
  * Bug fixes.
</Update>

<Update label="v2.6.5">
  * Bug fixes.
</Update>

<Update label="v2.6.4">
  * Traycer Free Plan:
    * Introducing Traycer Free Plan to allow users to use the extension for free.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.6.3">
  * Quick Agent Planner:
    * Introducing the quick-agent planner for small, focused tasks demanding quick planning and execution.
  * Added a configuration option to turn on/off automatically opening diff view post applying changes.
  * Added support to open the diff view post applying changes.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.6.2">
  * Mermaid Diagram:
    * Introducing Mermaid diagrams to visualize the necessary changes in the codebase for a given task.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.6.1">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.6.0">
  * Multi-Agent Planner:
    * Introducing multi-agent planning that triggers multiple agents to work on a Task in parallel.
    * The agents work on different aspects of the Task to generate a more accurate and efficient plan.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.5.1">
  * Resolved the occasional failures in plan generation.
</Update>

<Update label="v2.5.0">
  * Ticket Assist: Bridge the Gap Between Tickets and Code
    * AI-powered implementation planner that transforms tickets into step-by-step engineering blueprints, what to change, where, and why.
    * Breaks down tickets into steps, sequence diagrams, and proposes file changes so that developers can execute confidently without back-and-forth.
    * Traycer maps out dependencies and requirements for each Task, so developers spend less time interpreting tickets and more time coding.
    * Import tickets in your IDE with a single click.
  * Support for image attachment: You can now attach images to Tasks to provide more context.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.4.2">
  * Bug fixes.
</Update>

<Update label="v2.4.1">
  * Bug fixes.
</Update>

<Update label="v2.4.0">
  * Enhanced context management for large files-Traycer now summarizes and analyzes them in segments, preventing context window overflows during Task planning.
  * Reworked summaries to improve readability, making them easier to scan and act upon.
  * Resolved memory-related issues to enhance long-term stability and performance.
  * Improved the thinking stream to offer a clearer, more accurate reflection of Traycer’s reasoning process.
</Update>

<Update label="v2.3.24">
  * Improved readability of the plan.
  * Bug fixes.
</Update>

<Update label="v2.3.23">
  * Resolved an issue where tasks were not being generated for local repositories.
</Update>

<Update label="v2.3.22">
  * Auto Generate Changes: Introduced a new flag to start auto-generating code changes as soon as a plan is created.
  * Bug fixes.
</Update>

<Update label="v2.3.21">
  * Fixed UI issues related to the rate limit indicator.
</Update>

<Update label="v2.3.20">
  * Resolved issues observed around reviews.
  * Bug fixes.
</Update>

<Update label="v2.3.19">
  * Resolved an issue in which plan changes and chat content were updated incorrectly.
</Update>

<Update label="v2.3.18">
  * Fixed the issue of extension not getting activated.
</Update>

<Update label="v2.3.17">
  * Fixed the issue of extension not getting activated.
</Update>

<Update label="v2.3.16">
  * Improved keyboard bindings for chat.
  * Bug fixes.
</Update>

<Update label="v2.3.15">
  * Chat Enhancements:
    * File Referencing: You can now mention files directly in the chat, making it easier to reference code and resources.
    * Response Accuracy: Fixed an issue that caused non-applied changes from previous responses to be omitted.
  * Bug fixes.
</Update>

<Update label="v2.3.14">
  * Bug fixes.
</Update>

<Update label="v2.3.13">
  * Improved the performance of code indexing.
  * Bug fixes.
</Update>

<Update label="v2.3.12">
  * Resolved an issue where some unhandled exceptions from the extension were reported.
</Update>

<Update label="v2.3.11">
  * Resolved an issue where plan generation would fail if no workspace was open.
</Update>

<Update label="v2.3.10">
  * Fixed the issue of chat send button not working.
</Update>

<Update label="v2.3.9">
  * Improved the performance of comment indicators and code lenses.
  * Bug fixes.
</Update>

<Update label="v2.3.8">
  * Fixed review thread view design and layout issues
</Update>

<Update label="v2.3.7">
  * Bug fixes.
</Update>

<Update label="v2.3.6">
  * Get a peek into Traycer's thinking while it generates a plan.
  * Fixed incorrect line change count display on code changes.
  * Misc bug fixes and performance improvements.
</Update>

<Update label="v2.3.5">
  * Bug fixes.
</Update>

<Update label="v2.3.4">
  * Bug fixes.
</Update>

<Update label="v2.3.3">
  * Fixed the issue of diff view not opening on Windows.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.3.2">
  * Stop Chat Request: Introduced functionality to stop response generation for chat requests.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.3.1">
  * Fixed the issue of horizontal scrollbar appearing in the chat.
  * Fixed the issue of plan generation failing on task chain due to deleted files.
</Update>

<Update label="v2.3.0">
  * Introducing Task Chain Feature: Create follow-up tasks. Relevant context is automatically gathered into subsequent Tasks.
  * Performance Improvements:
    * Lazy loading of objects from persistence layer to reduce memory pressure.
    * Adaptive throttling in indexing layer to alleviate CPU starvation while indexing large codebases.
</Update>

<Update label="v2.2.3">
  * Plan Generation Hangs Fix: Fixed the issue of plan generation hanging when the connection to the server is lost.
  * Code Suggestion Improvements: Improved the quality of code suggestions generated by Traycer.
  * Indexing Performance Improvements: Improved the performance of codebase indexing.
</Update>

<Update label="v2.2.2">
  * Sign in with GitHub Fix: Fixed the issue of Sign in with GitHub notification not getting removed even after successful sign in.
</Update>

<Update label="v2.2.1">
  * Plan Improvements: Enhanced plan generation logic to prevent infinite loading caused by extended connection times.
  * Stop Plan or Code Generation: Introduced functionality to stop plan or code generation.
  * File Mention Search: Resolved a problem that previously prevented accurate file reference lookups.
  * Changes Revert Fix: Corrected an issue that blocked complete rollback of all changes.
</Update>

<Update label="v2.2.0">
  * Plan Improvements: More precise, task-focused plans streamline workflows by aligning closely with objectives.
  * Code Generation Enhancements: Improved issues in code generation like broken code, repeated code blocks etc.
  * UI/UX Enhancements: Shift-enter takes you to newline in text areas, improved change management, and added rate limit time display.
  * Codebase Indexing: Fixed bugs in codebase indexing and retrieval.
</Update>

<Update label="v2.1.7">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.1.6">
  * Fixed an issue observed on older versions of VS Code.
  * Added support to auto-save files when proposed changes are applied.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.1.5">
  * Fixed the issues observed on Windows.
  * Improved the UX for signing in with GitHub for Traycer.
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.1.4">
  * Fixed the issue of plan generation failing when no folders are open in the workspace.
</Update>

<Update label="v2.1.3">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.1.2">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.1.1">
  * Fixed plan editor to correctly render changes when multiple plans exist.
  * Fixed quick attach context bug that caused the webview to crash.
</Update>

<Update label="v2.1.0">
  * Codebase indexing: Traycer now creates a vector index for your codebase. This helps Traycer find files that are relevant to a Task. Additionally it enables the Task agent to explore codebase using semantic search.
  * Back to the plan: You can now revisit and refine your Task plans even after generating changes. This gives you the flexibility to fine-tune the plan if the initial changes aren’t quite right, ensuring you get exactly what you need.
  * Directory Operations: Traycer Tasks now support operations like renaming and creating directories, expanding what you can accomplish beyond individual file changes.
  * Improved Performance: We've resolved bugs and enhanced performance to ensure a faster, smoother coding experience.
</Update>

<Update label="v2.0.10">
  * Improved user experience on webview.
</Update>

<Update label="v2.0.9">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.0.8">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.0.7">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.0.6">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.0.5">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.0.4">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.0.3">
  * Bug fixes and performance improvements.
</Update>

<Update label="v2.0.2">
  * Bug fixes.
</Update>

<Update label="v2.0.1">
  * Bug fixes.
</Update>

<Update label="v2.0.0">
  * Introducing Tasks Feature: Simplify the complexity of software development with Traycer Tasks. Describe high-level objectives, and Traycer will generate a customizable plan with actionable changesets, making code modifications feel like an ongoing conversation with your codebase.
  * Enhanced Code Review System: Traycer's code review has been completely overhauled, providing more insightful and actionable suggestions.
  * UI Improvements: Experience a more seamless and user-friendly interface with our latest enhancements.
</Update>

<Update label="v1.3.2">
  * Bug fixes and performance improvements.
</Update>

<Update label="v1.3.1">
  * Bug fixes and performance improvements.
</Update>

<Update label="v1.3.0">
  * Added support for analyses in all programming languages.
  * Improved the quality of comments generated by Traycer.
  * Added a new command to analyze all local changes at once.
  * Bug fixes and performance improvements.
</Update>

<Update label="v1.2.0">
  * Added support for learning from user feedback to improve the quality of comments.
  * Bug fixes and performance improvements.
</Update>

<Update label="v1.1.1">
  * Fixed the issue of duplicate notifications being displayed.
</Update>

<Update label="v1.1.0">
  * Introduced support for retaining Traycer comments and analysis history after restarting VS Code.
  * Fixed the issue where comments were not correctly updating when files were modified.
  * Fixed login issue in Cursor IDE
  * Bug fixes and performance improvements.
</Update>

<Update label="v1.0.0">
  * Enabled paid plans for Traycer.
  * Introduced "Re-Analyze File" command to re-analyze the current file.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.12.1">
  * Added filter to the "Analysis History" view to filter analyses by status.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.12.0">
  * Introduced "Analysis History" to view the list of analyses triggered by Traycer and their status.
  * Enhanced the comment invalidation logic to ensure comments are updated when the file is modified.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.11.0">
  * Enhanced README with the latest information.
  * Improved UX of the "Traycer Comment" view.
  * Improved the quality of the comments generated by Traycer.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.10.1">
  * Fixed the endpoints of the Traycer services.
</Update>

<Update label="v0.10.0">
  * Replaced the VS Code native comments UX with Traycer's comments UX:
    * Comments generated by Traycer are now listed in the activity bar under the "Traycer" view.
    * Introduced a separate "Traycer Comment" view to display comment details and facilitate conversations with Traycer.
    * Added support for indicating comments in the editor using gutter icons (based on the comment category) and CodeLens.
    * Added configuration options under settings to choose the comment indicators.
  * Enhanced notifications for failed analysis and other errors.
  * Improved the quality of the comments generated by Traycer.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.9.1">
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.9.0">
  * Improved the quality of the comments generated by Traycer.
  * Added "Explanation" with the comments to provide more context.
  * Added Traycer icon on the editor toolbar to trigger analysis on the entire file, regardless of recent changes.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.8.0">
  * Improved the quality of the comments generated by Traycer.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.7.0">
  * Added support for users to reply to the comments generated by Traycer.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.6.0">
  * Added support for PHP programming language.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.5.0">
  * Added support for Rust programming language.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.4.3">
  * Resolved the issue of comments not getting generated for windows.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.4.2">
  * Bug fixes.
</Update>

<Update label="v0.4.1">
  * Bug fixes.
</Update>

<Update label="v0.4.0">
  * Added support for TypeScript React (TSX) files.
  * Added support for JavaScript React (JSX) files.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.3.3">
  * Bug fixes.
</Update>

<Update label="v0.3.2">
  * Bug fixes.
</Update>

<Update label="v0.3.1">
  * Resolved the high CPU utilization by the extension during startup.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.3.0">
  * Added support for passing variable references to reduce the noise in the comments.
  * Fixed the issue which caused high CPU usage when the extension was enabled.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.2.7">
  * Fixed an issue observed with auto analysis of Golang files.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.2.6">
  * Fixed an issue observed while analyzing a file not present in the git repository.
</Update>

<Update label="v0.2.5">
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.2.4">
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.2.3">
  * Improve README.
</Update>

<Update label="v0.2.2">
  * Fixed an issue observed with Golang programming language support.
</Update>

<Update label="v0.2.1">
  * Fixed issues observed for running Traycer on Windows.
</Update>

<Update label="v0.2.0">
  * Added support for JavaScript and Golang programming languages.
  * Added commands `Traycer: Enable Comments Highlighting` and `Traycer: Disable Comments Highlighting` to enable and disable comments highlighting.
  * Improved the UX of the Traycer status bar item.
  * Bug fixes and performance improvements.
</Update>

<Update label="v0.1.0">
  * Initial release.
</Update>


# IDE Extension
Source: https://docs.traycer.ai/extension/index

Docs for the Traycer IDE extension. New Desktop docs live in the main navigation.

These docs are for the Traycer IDE extension.

If you are using Traycer Desktop, start with the [Quickstart](/quickstart). The extension docs are preserved here so existing users and old links keep working.

## Extension Areas

<CardGroup>
  <Card title="Task workflows" icon="list-checks" href="/extension/tasks/index">
    Plan, Phases, Review, Epic, verification, history, and extension workflows.
  </Card>

  <Card title="Integrations" icon="plug" href="/extension/integrations/agents">
    Extension agent handoff, templates, MCP, and custom CLI agent docs.
  </Card>
</CardGroup>


# Agents
Source: https://docs.traycer.ai/extension/integrations/agents

Supported AI coding agents and how Traycer works with them. Traycer is designed to hand off clean and actionable prompts to your preferred AI coding agents.

## Supported agents

The following agents work seamlessly with Traycer Tasks:

* [Custom CLI Agents](/extension/integrations/custom-cli-agents) <Tooltip href="/extension/tasks/yolo-mode"><Icon icon="bolt" /></Tooltip>
* Cursor
* Claude Code CLI <Tooltip href="/extension/tasks/yolo-mode"><Icon icon="bolt" /></Tooltip>
* Claude Code Extension
* Windsurf
* Antigravity
* Augment
* Cline
* Codex CLI <Tooltip href="/extension/tasks/yolo-mode"><Icon icon="bolt" /></Tooltip>
* Codex Extension
* Gemini CLI <Tooltip href="/extension/tasks/yolo-mode"><Icon icon="bolt" /></Tooltip>
* KiloCode
* RooCode
* Amp
* ZenCoder

<Info>
  **<Icon icon="bolt" /> YOLO Mode compatible:** Agents marked with <Icon icon="bolt" /> support automated execution with [YOLO Mode](/extension/tasks/yolo-mode). Other agents require manual interaction. More agents are coming soon. If your preferred agent isn't listed, please contact us at [support@traycer.ai](mailto:support@traycer.ai).
</Info>

## Export options

You can also export the prompts as markdown or copy them directly:

* **Copy** - Copy the prompts directly to your clipboard for immediate use with any AI coding agent. (Always available in the execute dropdown)

<Frame>
  <img alt="Execute dropdown" />
</Frame>

* **Export as markdown** - Generate a clean markdown file containing your complete prompts that can be shared with any AI coding agent or used as documentation.

The "Copy" option is always available. The "Export as markdown" option can be added through the same "Additional agents" configuration section described below.

<Info>
  **Need more control?** You can create [Custom CLI Agents](/extension/integrations/custom-cli-agents) with custom arguments and permissions for any CLI-based coding agent.
</Info>

***

## Adding additional agents

<Frame>
  <iframe title="Adding additional agents" />
</Frame>

Configure additional AI coding agents in Traycer settings:

<Steps>
  <Step title="1. Go to Traycer settings">
    Click the gear-shaped icon on the top right in Traycer's sidebar.
  </Step>

  <Step title="2. Find Additional agents section">
    Scroll down below and find the "Additional agents" settings section.
  </Step>

  <Step title="3. Click Add item">
    Click the "Add item" button to add a new agent configuration.
  </Step>

  <Step title="4. Select and configure">
    Select the agent from the dropdown list and click "OK" to save the configuration.
  </Step>
</Steps>


# Custom CLI Agents
Source: https://docs.traycer.ai/extension/integrations/custom-cli-agents

Create custom CLI agents with custom arguments and permissions for any CLI-based coding agent.

## Overview

Traycer allows you to create custom CLI agent with custom arguments and permissions for any CLI-based coding agent. This powerful feature enables you to pass special flags and create platform-specific configurations tailored to your workflow.

## What are Custom CLI Agents?

Custom CLI agents allow you to:

* Execute any CLI-based coding agent with custom arguments.
* Pass special flags like `--dangerous` or `--force` for elevated permissions.
* Create platform-specific CLI agent for different environments.

## Available Template Tags

Custom CLI agents support the following environment variables set by Traycer at runtime:

| Variable                     | Bash / Git Bash                 | PowerShell                          |
| ---------------------------- | ------------------------------- | ----------------------------------- |
| `TRAYCER_PROMPT`             | `"$TRAYCER_PROMPT"`             | `"$env:TRAYCER_PROMPT"`             |
| `TRAYCER_PROMPT_TMP_FILE`    | `"$TRAYCER_PROMPT_TMP_FILE"`    | `"$env:TRAYCER_PROMPT_TMP_FILE"`    |
| `TRAYCER_PHASE_ID`           | `"$TRAYCER_PHASE_ID"`           | `"$env:TRAYCER_PHASE_ID"`           |
| `TRAYCER_PHASE_BREAKDOWN_ID` | `"$TRAYCER_PHASE_BREAKDOWN_ID"` | `"$env:TRAYCER_PHASE_BREAKDOWN_ID"` |
| `TRAYCER_TASK_ID`            | `"$TRAYCER_TASK_ID"`            | `"$env:TRAYCER_TASK_ID"`            |
| `TRAYCER_SYSTEM_PROMPT`      | `"$TRAYCER_SYSTEM_PROMPT"`      | `"$env:TRAYCER_SYSTEM_PROMPT"`      |

<ParamField type="placeholder">
  The prompt content. At least one of `TRAYCER_PROMPT` or `TRAYCER_PROMPT_TMP_FILE` must be referenced in your CLI agent template.
</ParamField>

<ParamField type="placeholder">
  Temporary file path containing the prompt content. Ideal for large prompts that exceed environment variable size limits.
  Use commands like `cat "$TRAYCER_PROMPT_TMP_FILE"` (Bash) or `Get-Content -Raw "$env:TRAYCER_PROMPT_TMP_FILE"` (PowerShell) to read and pass the prompt content to the CLI agent at runtime.
  The temporary file is automatically cleaned up by Traycer after 30 seconds.
</ParamField>

<ParamField type="placeholder">
  Per-phase identifier for maintaining session across plan and verification.
</ParamField>

<ParamField type="placeholder">
  Phase breakdown identifier for maintaining session across current phase list.
</ParamField>

<ParamField type="placeholder">
  Task identifier for maintaining session across all phase iterations, plans, and verification execution
</ParamField>

<ParamField type="placeholder">
  System prompt to append to the CLI agent (environment variable set by Traycer at runtime). Use this with --append-system-prompt or equivalent flag to pass trusted instructions at the system level.
</ParamField>

## Creating Custom CLI Agents

<Frame>
  <img alt="Custom CLI Agents" />
</Frame>

<Steps>
  <Step title="1. Open Manage CLI Agents">
    Click the three dots on the top of the sidebar to open the context menu, then click "Manage CLI Agents".
  </Step>

  <Step title="2. Click Add CLI Agent">
    Click "Add CLI Agent" to add a new custom CLI agent.
  </Step>

  <Step title="3. Choose scope">
    Select either **User** (personal CLI agents available across all projects) or **Workspace** (project-specific CLI agents stored in workspace settings).
  </Step>

  <Step title="4. CLI Agent Name">
    Provide a descriptive name for your custom CLI agent and click "Create CLI Agent".
  </Step>

  <Step title="5. Add CLI Agent Command">
    Add your custom command to the created file and save it.
  </Step>
</Steps>

## Template Scopes

Custom CLI agents can be created in two different scopes:

* **User scope**: Personal CLI agents that are available across all your projects. These are stored in the home directory under `.traycer/cli-agents` and travel with you.
* **Workspace scope**: Project-specific CLI agents that are stored in your workspace root under `.traycer/cli-agents`. These are ideal for team-shared configurations or project-specific agent setups.

## Popular CLI Agents

Here are some popular CLI-based coding agents you can set up:

<Tabs>
  <Tab title="Claude Code CLI">
    The following are frequently used arguments. For more details, visit the [official documentation](https://docs.claude.com/en/docs/claude-code/cli-reference?ref=traycer.ai).

    **Basic**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      claude "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      claude "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      claude "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>

    **Verbose**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      claude --verbose "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      claude --verbose "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      claude --verbose "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>

    **Dangerous Mode**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      claude --dangerously-skip-permissions "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      claude --dangerously-skip-permissions "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      claude --dangerously-skip-permissions "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Codex CLI">
    The following are frequently used arguments. For more details, visit the [official documentation](https://developers.openai.com/codex/cli?ref=traycer.ai).

    **Auto-approve**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      codex --full-auto "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      codex --full-auto "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      codex --full-auto "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>

    **With Model**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      codex --full-auto --model <MODEL> "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      codex --full-auto --model <MODEL> "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      codex --full-auto --model <MODEL> "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>

    **With Local OSS Model**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      codex --full-auto --oss "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      codex --full-auto --oss "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      codex --full-auto --oss "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Gemini CLI">
    The following are frequently used arguments. For more details, visit the [official documentation](https://geminicli.com/docs/cli/?ref=traycer.ai).

    **Debug Mode**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      gemini --debug "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      gemini --debug "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      gemini --debug "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>

    **YOLO Mode**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      gemini --yolo "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      gemini --yolo "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      gemini --yolo "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Cline CLI">
    The following are frequently used arguments. For more details, visit the [official documentation](https://docs.cline.bot/cline-cli/overview?ref=traycer.ai).

    **Basic**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      cline "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      cline "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      cline "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>

    **Verbose Mode**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      cline --verbose "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      cline --verbose "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      cline --verbose "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>

    **YOLO Mode**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      cline --yolo "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      cline --yolo "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      cline --yolo "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Factory Droid CLI">
    The following are frequently used arguments. For more details, visit the [official documentation](https://docs.factory.ai/cli/getting-started/overview?ref=traycer.ai).

    **Basic**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      droid --file "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      droid --file "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      droid --file "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>

    **Auto-run Mode**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      droid exec --auto <level> --file "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      droid exec --auto <level> --file "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      droid exec --auto <level> --file "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>

    **Specification Mode**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      droid exec --skip-permissions-unsafe --file "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      droid exec --skip-permissions-unsafe --file "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      droid exec --skip-permissions-unsafe --file "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Cursor CLI">
    The following are frequently used arguments. For more details, visit the [official documentation](https://cursor.com/docs/cli/overview?ref=traycer.ai).

    **Basic**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      echo $TRAYCER_PROMPT | cursor-agent
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      echo $TRAYCER_PROMPT | cursor-agent
      ```

      ```powershell Windows (PowerShell) theme={null}
      echo "$env:TRAYCER_PROMPT" | cursor-agent
      ```
    </CodeGroup>

    **Force Mode**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      echo $TRAYCER_PROMPT | cursor-agent --force
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      echo $TRAYCER_PROMPT | cursor-agent --force
      ```

      ```powershell Windows (PowerShell) theme={null}
      echo "$env:TRAYCER_PROMPT" | cursor-agent --force
      ```
    </CodeGroup>

    **Background Mode**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      echo $TRAYCER_PROMPT | cursor-agent --background
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      echo $TRAYCER_PROMPT | cursor-agent --background
      ```

      ```powershell Windows (PowerShell) theme={null}
      echo "$env:TRAYCER_PROMPT" | cursor-agent --background
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Aider">
    The following are frequently used arguments. For more details, visit the [official documentation](https://aider.chat/docs/usage.html?ref=traycer.ai).

    **Auto-approve**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      aider --yes-always "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      aider --yes-always "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      aider --yes-always "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>

    **With Git Auto-commit**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      aider --yes-always --auto-commits "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      aider --yes-always --auto-commits "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      aider --yes-always --auto-commits "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>

    **Verbose Mode**

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      #!/bin/sh
      aider --yes-always --verbose "$TRAYCER_PROMPT"
      ```

      ```bash Windows (Git Bash) theme={null}
      #!/bin/sh
      aider --yes-always --verbose "$TRAYCER_PROMPT"
      ```

      ```powershell Windows (PowerShell) theme={null}
      aider --yes-always --verbose "$env:TRAYCER_PROMPT"
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Using Custom Paths

If your CLI agent is installed at a custom location, you can specify the full path in your template:

<CodeGroup>
  ```bash Linux/macOS theme={null}
  #!/bin/sh
  /usr/local/bin/claude --verbose "$TRAYCER_PROMPT"
  ```

  ```bash Windows (Git Bash) theme={null}
  #!/bin/sh
  "/c/Program Files/Claude/claude.exe" --verbose "$TRAYCER_PROMPT"
  ```

  ```powershell Windows (PowerShell) theme={null}
  & "C:\Program Files\Claude\claude.exe" --verbose "$env:TRAYCER_PROMPT"
  ```
</CodeGroup>

<Warning>
  Flags like `--dangerous` grant elevated permissions to the agent. Always review what permissions you're granting to CLI agents.
</Warning>

## Use Cases

Custom CLI agents are particularly useful for:

* Passing dangerous/elevated permissions flags.
* Using custom model configurations.
* Setting specific output formats.
* Creating environment-specific agent configurations.

## FAQ

<AccordionGroup>
  <Accordion title="Can I pass dangerous or elevated permission flags?">
    Yes, you can pass any flags supported by your CLI agent, including `--dangerous`, `--force`, or other elevated permission flags. However, be cautious as these flags grant the agent more control over your system. Always understand what permissions you're granting before using such flags.
  </Accordion>

  <Accordion title="How do I share custom CLI agents with my team?">
    You can share custom CLI agents with your team by creating them in **Workspace scope**. Workspace-scoped CLI agents are stored in your project's workspace root under `.traycer/cli-agents`, which can be committed to your repository. When team members pull the latest changes, they'll automatically have access to the shared custom CLI agents. This approach ensures consistent agent configurations across your entire team.
  </Accordion>

  <Accordion title="What's the difference between User and Workspace scope?">
    User scope CLI agents are stored in your personal settings and available across all projects. Workspace scope CLI agents are project-specific and stored in the workspace settings, making them ideal for team collaboration.
  </Accordion>

  <Accordion title="Can I edit an existing CLI agent?">
    Yes, you can modify any custom CLI agent by clicking on it within the Custom CLI Agents section of Traycer settings. This will open the file for editing.
  </Accordion>

  <Accordion title="What's the difference between Bash and PowerShell syntax for environment variables?">
    Bash (Linux/macOS/Git Bash) and PowerShell (Windows) use different syntax to reference environment variables:

    | Shell           | Syntax                 | Example                        |
    | --------------- | ---------------------- | ------------------------------ |
    | Bash / Git Bash | `"$VARIABLE_NAME"`     | `claude "$TRAYCER_PROMPT"`     |
    | PowerShell      | `"$env:VARIABLE_NAME"` | `claude "$env:TRAYCER_PROMPT"` |

    **Key differences:**

    * **Bash** uses `$` followed by the variable name directly (e.g., `$TRAYCER_PROMPT`)
    * **PowerShell** uses `$env:` prefix before the variable name (e.g., `$env:TRAYCER_PROMPT`)
    * Double quotes are recommended in both shells to handle prompts containing spaces or special characters

    Choose the appropriate syntax based on which shell your CLI agent script will run in. Git Bash on Windows uses Bash syntax, not PowerShell syntax.
  </Accordion>

  <Accordion title="What happens if I don't include the $TRAYCER_PROMPT or $TRAYCER_PROMPT_TMP_FILE environment variable?">
    The CLI agent validation will fail because at least one of `$TRAYCER_PROMPT` or `$TRAYCER_PROMPT_TMP_FILE` must be referenced in your CLI agent template to pass the task instructions to the agent.
  </Accordion>

  <Accordion title="When should I use TRAYCER_PROMPT_TMP_FILE instead of TRAYCER_PROMPT?">
    `TRAYCER_PROMPT` is the recommended default for most use cases. Use `TRAYCER_PROMPT_TMP_FILE` when:

    * Dealing with very large prompts (multiple files, extensive context)
    * Encountering environment variable size limits (Windows: \~32KB, Linux/macOS: varies)
    * Experiencing prompt truncation issues

    Both variables are always available. Use `TRAYCER_PROMPT_TMP_FILE` directly in your commands just like `TRAYCER_PROMPT` - no need for file reading commands.
  </Accordion>

  <Accordion title="How does TRAYCER_PROMPT_TMP_FILE work internally?">
    Traycer creates a temporary file containing the prompt content and sets `TRAYCER_PROMPT_TMP_FILE` to the file path. When you reference `$TRAYCER_PROMPT_TMP_FILE` in your template, you need to read the file content using commands like `cat "$TRAYCER_PROMPT_TMP_FILE"` (bash/sh) or `Get-Content -Raw "$env:TRAYCER_PROMPT_TMP_FILE"` (PowerShell). This approach bypasses environment variable size limits that can cause issues with very large prompts. The temporary file is automatically cleaned up by Traycer after 30 seconds.
  </Accordion>

  <Accordion title="Can I use custom CLI agents with YOLO Mode?">
    Yes, custom CLI agents work with YOLO Mode for automated execution.
  </Accordion>

  <Accordion title="Can I have multiple versions of the same agent?">
    Yes, you can create multiple custom CLI agents with different names that use the same underlying CLI tool. For example, you could have "Claude Verbose", "Claude Dangerous", and "Claude Standard" - each with different flags but all calling the same `claude` CLI agent.
  </Accordion>

  <Accordion title="What if the CLI tool isn't installed on my system?">
    Traycer does not install CLI agents for you. You must install the CLI tool separately before creating a custom CLI agent. We recommend testing the CLI command in your terminal first to ensure it works correctly before adding it to an agent.
  </Accordion>
</AccordionGroup>


# Model Context Protocol (MCP)
Source: https://docs.traycer.ai/extension/integrations/mcp

Connect external tools and data sources to Traycer using MCP

## What is MCP?

**Model Context Protocol (MCP)** enables Traycer to securely connect to external tools and data sources, allowing your agents to access them at runtime. You can configure custom MCP endpoints to extend your agent's capabilities.

## Connect a Custom Remote MCP Server

<Frame>
  <iframe title="Connect Remote MCP Server" />
</Frame>

<Steps>
  <Step title="1. Open Traycer Platform">
    Go to [Traycer Platform](https://platform.traycer.ai/). By default, you're on your personal account. To manage MCP servers for your organization, use the account dropdown to switch to your organization account.
  </Step>

  <Step title="2. Add custom MCP server">
    Open the "Remote MCP Servers" section from the sidebar and click **"Add Custom MCP"**.
  </Step>

  <Step title="3. Configure details">
    Fill in the required information for your custom MCP server, complete authentication, and save:

    * **Name** - Enter a descriptive name for your MCP server.
    * **Endpoint URL** - Provide the HTTPS endpoint URL of the server.
    * **Authentication** - Select one of the following options:
      * **None** - For public endpoints that don't require credentials.
      * **API Key** - Paste your API key.
      * **OAuth** - You'll be redirected to sign in and grant access.
  </Step>

  <Step title="4. Configure tools">
    Review and configure the available tools from your MCP server:

    * All tools are enabled by default.
    * Disable any tools you don't need or want to use.
    * Click **"Confirm Configuration"** to save your settings.
  </Step>
</Steps>

## Manage MCP Servers

Manage your MCP servers and their available tools from the platform.

### Change server configuration

* Edit Endpoint URL and credentials (for example, API Key).
* Use the master toggle to enable/disable the mcp server **organization‑wide**.

### Enable or disable tools

* Toggle individual tools in the Available Tools list.
* Use Enable All / Disable All for bulk changes.

## Switching to organization account for MCP Servers in Traycer Extension

<Frame>
  <img alt="MCP switch" />
</Frame>

To switch to organization account for MCP Servers in the Traycer extension:

<Steps>
  <Step title="1. Open MCP tab">
    Click the MCP icon in the top toolbar of the Traycer extension.
  </Step>

  <Step title="2. Select account">
    Use the account dropdown to switch between your personal and organization accounts to view the MCP servers configured for each account.
  </Step>

  <Step title="3. Review available servers and tools">
    Click **"Mark as Active"** to switch to the selected account. You'll see a list of your configured MCP servers and their available tools for that account.
  </Step>
</Steps>

<Note>
  To add, remove, or configure MCP servers, use the [Traycer Platform](https://platform.traycer.ai/).
</Note>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Does Traycer support local MCP servers?">
    No, Traycer only supports remote MCP servers. Local MCP servers are not supported at this time. If you need access to tools that don't provide direct remote MCP endpoints, consider using [Composio](https://mcp.composio.dev), which offers many local MCP integrations as managed remote services. This includes 250+ tools like Gmail, Slack, Notion, and Linear with built-in authentication.

    <Frame>
      <iframe title="Local MCP servers with Composio" />
    </Frame>
  </Accordion>

  <Accordion title="Are MCP servers shared across my organization?">
    Only if you add them to your organization account. MCP servers added to your personal account are private to you. When you add an MCP server to your organization account, it becomes available to all organization members. Similarly, disabling any organization-level MCP server or tool will disable it for everyone on your team.
  </Accordion>
</AccordionGroup>


# Templates
Source: https://docs.traycer.ai/extension/integrations/templates

Customize plan prompts with Handlebars templates for your coding agents

<Frame>
  <iframe title="Templates" />
</Frame>

## What are templates?

Templates are a formatting mechanism that allows you to wrap Traycer's generated content (like plans or verification comments) with your own custom instructions. When you hand off to a coding agent, templates let you include additional context before and after the core content.

For example, when Traycer generates a plan, you can use templates to:

* Add project-specific setup instructions before the plan.
* Include testing requirements after the plan.
* Specify coding standards and conventions.
* Integrate with MCPs or other tools.

### Example template structure

In the following example, `{{planMarkdown}}` is where Traycer inserts the generated plan content, surrounded by your custom instructions. The frontmatter defines the template's display name (`displayName`) and type (`applicableFor`).

```handlebars MyTemplate.md wrap highlight={1-4,8} icon="markdown" theme={null}
---
displayName: Auto-Test Plan Template
applicableFor: plan
---

Follow the below plan verbatim. Trust the files and references. Do not re-verify
what's written in the plan.

{{planMarkdown}}

## After Implementation - Always Run Tests

After implementing all the changes above:

1. Run `bun test` to execute the full test suite
2. If any tests fail, fix the issues before considering the implementation complete
3. Ensure all existing tests still pass and new functionality is properly tested
```

## Template types

### Plan Templates (`applicableFor: plan`)

Customize prompts when sending implementation plans to your coding agent.

**Available Handlebars:**

<ParamField type="placeholder">
  Contains the generated implementation plan content.
</ParamField>

### Verification Templates (`applicableFor: verification`)

Customize prompts when sending verification review comments to your agent for fixes.

**Available Handlebars:**

<ParamField type="placeholder">
  Contains the verification review comments and feedback.
</ParamField>

### Review Templates (`applicableFor: review`)

Customize prompts when sending review comments to your agent for fixes.

**Available Handlebars:**

<ParamField type="placeholder">
  Contains the review comments and feedback.
</ParamField>

### User Query Templates (`applicableFor: user query`)

Customize prompts when bypassing the plan and directly sending the generated user query to your agent for fixes.

**Available Handlebars:**

<ParamField type="placeholder">
  Contains the generated user query.
</ParamField>

### Generic Templates (`applicableFor: generic`)

Create reusable templates for both plan and verification contexts, or any custom agent interactions.

**Available Handlebars:**

<ParamField type="placeholder">
  Contains the base prompt content that can be used in any context.
</ParamField>

<Note>More handlebars will be added in the future.</Note>


# Pricing & Usage Limits
Source: https://docs.traycer.ai/extension/pricing

Understand credit-based pricing, plan credits, bundles, and billing details.

This page covers **IDE extension** pricing (credit-based, model rate card). Using Traycer Desktop? See [Desktop Pricing](/account/pricing).

## Plans & Billing

Traycer offers several plan tiers to match your usage and team needs.

| Plan      | Price (per user / month) | Included Credits   |
| --------- | ------------------------ | ------------------ |
| **Lite**  | \$20                     | \$20 credits       |
| **Pro**   | \$40                     | \$50 credits       |
| **Ultra** | from \$100               | from \$150 credits |

<Accordion title="Ultra+">
  | Monthly Price | Included Credits |
  | ------------- | ---------------- |
  | \$200         | \$300 credits    |
  | \$300         | \$450 credits    |
  | \$400         | \$600 credits    |
  | \$500         | \$750 credits    |
</Accordion>

**Annual plans are 20% off** - save when you pay yearly.

### Trials

* 7-day free trial with \$10 credits included.
* No credit card required to start your trial.

<Accordion title="Can I attach my card during the trial to avoid any interruption?">
  Yes. You can add a payment method at any time during your trial on the [platform](https://platform.traycer.ai/). Your subscription will continue automatically when the trial ends.
</Accordion>

***

## Usage & Limits

Traycer uses **credits** to meter usage across artifacts and chat.

### Key Terms

* **Credit:** The billing unit used for usage.
* **Subscription credits:** Credits included in your monthly or annual plan.
* **Bundle credits:** Additional credits you can buy separately, starting at \$10 bundles.
* **Rate card:** Each action has a credit cost based on the operation type.

### Rate Card

<Info>
  Action costs vary based on your selected model profile and reasoning level. Use our interactive pricing calculator to estimate costs for your workflow.

  **[View Pricing Calculator →](/extension/tasks/models#pricing-calculator)**
</Info>

### Model Profile Multipliers

The rate card above is the base action cost. Final cost per action can change based on selected model profile and reasoning level.

* Use **Balanced** for default cost/performance.
* Use **Frontier** for higher quality and deeper reasoning.
* Use a **Custom profile** to override specific steps.

See [Model Profiles & Cost Multipliers](/extension/tasks/models) for:

* Step-level profile defaults
* Reasoning effort multipliers
* Cost multiplier formula used for estimation

<Note>
  If your request exceeds the context window, the request cost is multiplied by 2x.
</Note>

### Bundles

If you run out of subscription credits, you can buy more with credit bundles.

* Bundles are free-form amounts starting at **\$10**.
* The amount you buy is added to your credit balance at checkout.

### FAQ

<Accordion title="Do team members share credits?">
  No. Credits are allocated per seat by default. Enterprise plans provide centralized billing and enforce privacy mode.
</Accordion>

<Accordion title="Do unused credits expire?">
  Subscription credits reset at the end of each monthly billing cycle — unused subscription credits do not carry over. Bundle credits never expire.
</Accordion>

<Accordion title="What happens to my artifacts if I downgrade?">
  All previously generated artifacts remain accessible permanently, regardless of your plan tier.
</Accordion>

<Accordion title="What are Enterprise plans?">
  Enterprise pricing is the same as individual pricing for all plans. It includes:

  * **Centralized Billing** - All team members are billed under a single invoice for easier expense tracking.
  * **Seat Management** - Invite, remove, and manage members from a central dashboard.
  * **Centralized Remote MCP Connections** - Connect and manage servers at the organization level for all team members.
  * **Org-Wide Privacy Mode** - Enforced by default to protect sensitive data.
  * **Dedicated Support Channel** - A private Slack or Discord channel for faster communication and priority support.
</Accordion>

<Accordion title="Does deleting tasks or artifacts refund my credits?">
  No. Deleting previous tasks, plans, or any generated artifacts does not refund consumed credits.
</Accordion>

<Accordion title="What happens if artifact generation fails?">
  If an artifact generation fails, we will automatically refund the consumed credits. In case your credits were not refunded, please reach out to us for assistance.
</Accordion>

<Accordion title="How do upgrades and downgrades work?">
  You can change plans at any time.

  * **Upgrades:** Immediate effect with prorated billing for the rest of the cycle. You pay the difference between plans for the remaining time in your billing period.
  * **Downgrades:** Take effect after the current billing cycle. No loss of access until then. All generated artifacts remain available permanently.
</Accordion>

***


# AGENTS.md
Source: https://docs.traycer.ai/extension/tasks/agents-md

Traycer automatically detects and uses AGENTS.md files to enhance AI task execution with project-specific context

## Overview

AGENTS.md is an open standard that provides AI coding agents with machine-readable, project-specific instructions. Unlike README.md files designed for human developers, AGENTS.md focuses on giving AI agents clear guidance about build processes, testing procedures, coding conventions, and architectural patterns.

Traycer automatically detects and uses AGENTS.md files when generating and executing Tasks - no configuration or setup required.

## How Traycer Uses AGENTS.md

When you create a Task, Traycer automatically searches for AGENTS.md files to gather project context:

1. **Finds the nearest AGENTS.md**: Starts from the location of attached file references or the current working directory during exploration
2. **Traverses to workspace root**: Continues up the directory tree if no AGENTS.md is found nearby
3. **Incorporates into Task context**: Uses the instructions to inform plan generation and execution

This means:

* Place AGENTS.md at your repository root for project-wide instructions
* Add nested AGENTS.md files in subdirectories for component-specific guidance (ideal for monorepos)
* No manual configuration needed - detection happens automatically

## What This Means for Your Tasks

When Traycer finds an AGENTS.md file, it uses the project-specific instructions to:

* **Generate more accurate plans**: Understands your project's structure, conventions, and patterns
* **Follow your standards**: Respects your team's coding style, testing requirements, and workflows
* **Reduce iterations**: Creates plans aligned with your project from the start
* **Support monorepos**: Uses the most relevant AGENTS.md based on your working directory

The result is faster, more accurate Task execution that respects your project's unique requirements.

## Industry Standard

AGENTS.md is supported by AI coding tools including Cursor, GitHub Copilot, Factory, Codex, Jules, and others. By adding an AGENTS.md file to your repository, you provide consistent instructions across all these tools.

<Tip>
  Learn more about the AGENTS.md standard and what to include at [agents.md](https://agents.md).
</Tip>

## Disabling AGENTS.md Detection

You can disable AGENTS.md detection at any time in your Traycer settings if you prefer not to use this feature.


# Collaboration
Source: https://docs.traycer.ai/extension/tasks/collaboration

Share Epic boards with your team and collaborate in real time. Invite collaborators, assign tickets, and work together from requirements to implementation.

Collaboration in Epic Mode enables teams to work together on the same specs and tickets, from requirements through implementation. Share Epic boards with teammates, assign work, and collaborate in real time-all while maintaining a single source of truth for your development process.

## Overview

Epic Mode collaboration provides:

* **Shared Epic boards** - Everyone works from the same set of specs and tickets
* **Real-time editing** - Multiple people can edit specs and tickets simultaneously with live updates
* **Ticket assignment** - Distribute work across team members
* **Organization sharing** - Share boards with your entire organization
* **Cross-device sync** - Access your workspace from any device

## Inviting Team Members

<Frame>
  <iframe title="Inviting team members to Epic boards" />
</Frame>

Share your Epic board with teammates to collaborate on specs and tickets. Click the share button next to `Open Board` in the top bar to open the share dialog.

### How to invite collaborators

<Steps>
  <Step title="1. Open the share dialog">
    Click the share button next to `Open Board` in the top bar.
  </Step>

  <Step title="2. Add collaborators">
    Enter an **email address** or **GitHub handle**, then click `Add`. You can add multiple collaborators before sending invites.
  </Step>

  <Step title="3. Set access level">
    Choose the access level you want to grant for each collaborator.
  </Step>

  <Step title="4. Send invitations">
    Click `Invite` to send access invitations to all added collaborators.
  </Step>
</Steps>

### Sharing with organizations

If your account has access to an organization, the Organizations section in the share dialog lets you share the Epic board directly with your entire organization. Select an access level (`Editor` or `Viewer`), then click `Share`.

## Access Levels

The share dialog shows everyone who currently has access to the board. You can change access levels or remove access at any time.

* **Owner**: Board owner with full control over the Epic and all its contents
* **Editor**: Can collaborate on shared specs and tickets, assign tickets, and make changes to artifacts
* **Viewer**: Can view the shared board and its contents without editing permissions

## Ticket Assignment

<Frame>
  <iframe title="Assigning tickets to team members" />
</Frame>

Distribute work across your team by assigning tickets to specific collaborators. Once you've shared your Epic board with team members, they'll appear in the assignee dropdown and you can assign tickets to them directly.

### How ticket assignment works

* **Assign from ticket view** - Use the assignee dropdown directly in the ticket view
* **Search by name or handle** - Quickly find team members by searching their name or GitHub handle
* **Leave tickets Unassigned** - Keep tickets unassigned if ownership isn't determined yet
* **Track ownership** - The current assignee is visible directly in the ticket list

## Real-Time Collaboration

Multiple people can work in the same Epic board simultaneously:

* **Live updates** - Changes to specs and tickets appear in real time for all collaborators
* **Presence indicators** - See who's currently viewing or editing artifacts
* **Conflict-free editing** - The system handles concurrent edits automatically
* **Synchronized views** - Everyone sees the same state of the board

## Sync Across Devices

Your Epic boards and task history sync automatically across all your devices. Sign in with the same Traycer account on any device to access your complete workspace.

**What syncs:**

* All Epic boards and their contents
* Specs and tickets
* Task history
* Conversation history
* Executions and verification results

<AccordionGroup>
  <Accordion title="Can I collaborate on Plan or Phases mode?">
    Currently, collaboration features are only available in Epic Mode. Plan and Phases modes remain single-user workflows.
  </Accordion>

  <Accordion title="What happens if two people edit the same spec simultaneously?">
    Traycer handles concurrent edits automatically. Both users will see live updates, and the system merges changes intelligently to avoid conflicts.
  </Accordion>

  <Accordion title="Can I remove someone's access after sharing?">
    Yes. Open the share dialog and use the access list to change someone's access level or remove their access entirely.
  </Accordion>

  <Accordion title="Can I see who's currently viewing or editing?">
    Yes. Collaborator presence is visible directly in the editor when someone is actively editing a spec or ticket.
  </Accordion>
</AccordionGroup>


# Epic Mode
Source: https://docs.traycer.ai/extension/tasks/epic

Collaborative artifact management through structured workflows. Perfect for managing specs and tickets with shared boards, real-time collaboration, and AI-guided development processes.

Epic Mode is designed to solve one of the biggest challenges in AI-assisted development: **preserving human intent** from initial idea to implementation. When building with AI agents, critical context often lives scattered across chat messages or exists only in your head - the "why" behind decisions, constraints, edge cases, and invisible rules. This is how drift happens: agents aren't trying to be wrong, they're just filling in gaps.

Epic Mode captures this intent through a **system of specs** - not one giant document that becomes outdated, but focused mini-specs that each address a specific aspect of your project. Combined with structured workflows, actionable tickets, and verification at every stage, Epic Mode keeps your development process aligned with your original intent.

<Frame>
  <img alt="Epic Mode board view showing specs and tickets" />
</Frame>

## Understanding Artifacts

Epic Mode helps you create and manage **artifacts** - structured documents that form a system of interconnected specs and tickets. This system captures your development process from requirements to implementation. Artifacts come in two types:

### Specifications (Specs)

Specs are focused, high-level documents that capture requirements, design decisions, and technical planning. They provide the "why" and "what" of your project. Rather than one giant spec, Epic Mode favors **mini-specs** - each tightly scoped to a specific aspect, making them easier to maintain and update as your project evolves.

**Common spec types:**

* **PRD (Product Requirements Document)**: Defines the problem, who's affected, and the desired outcome at a product level
* **Tech Doc**: Outlines architecture, technical approach, and implementation strategy
* **Design Spec**: Documents user flows, UX decisions, and interaction patterns
* **API Spec**: Defines API contracts, endpoints, and integration requirements

Specs are living documents - they evolve as your understanding deepens and requirements change. When something changes, you update the relevant mini-spec instead of rewriting everything.

<Frame>
  <iframe title="Creating a spec" />
</Frame>

### Tickets

Tickets are actionable work items that break down specs into concrete implementation tasks. Each ticket represents a focused unit of work that can be independently implemented.

**Ticket characteristics:**

* Contains clear acceptance criteria
* Tracks status: Todo → In Progress → Done
* Can be assigned to specific collaborators or left Unassigned
* Can be handed off to coding agents for implementation

Together, specs and tickets form a complete development workflow: specs capture the strategic thinking, while tickets drive the tactical execution.

<Frame>
  <iframe title="Creating a ticket" />
</Frame>

<Info>
  **Full Context Awareness:** All specs and tickets within an epic are automatically in the LLM's context. When you're discussing a ticket or spec, the AI has full awareness of all related artifacts, previous decisions, and conversations - enabling coherent, context-aware development throughout your entire epic.
</Info>

## How It Works

<Steps>
  <Step title="1. Choose a Workflow">
    Select a workflow that will guide you through the development process with structured commands.

    Learn more about [workflows](/extension/tasks/workflows).
  </Step>

  <Step title="2. Start with Requirements">
    Provide your requirements, problem statement, or goals to the workflow's entrypoint command.

    The AI begins processing according to the workflow's instructions.
  </Step>

  <Step title="3. Follow the Workflow">
    Progress through the workflow's commands. Epic Mode emphasizes **dialogue and elicitation** - the AI doesn't just generate documents, it actively asks pointed questions to surface constraints, edge cases, and the "invisible rules" behind your requirements.

    During this process, the AI will:

    * Ask clarifying questions to understand your intent deeply
    * Help you make explicit decisions instead of leaving ambiguity
    * Propose and create specification documents
    * Generate actionable tickets for implementation
    * Guide you through additional workflow-specific steps
  </Step>

  <Step title="4. Handoff to Implementation">
    Once you have the specs and tickets you need, select them and hand off for implementation. Verification is built into Traycer's implementation modes to continuously validate that execution matches your captured intent.

    See [Selection and Handoff](#selection-and-handoff) for details on the available options.
  </Step>
</Steps>

## Executions

Executions provide complete visibility into every agent handoff within your Epic. Each execution represents a discrete unit of work sent to a coding agent, capturing the full lifecycle from handoff to completion.

<Frame>
  <img alt="Executions tracking in Epic view" />
</Frame>

### What Gets Tracked

Every execution captures:

* **Plans**: Implementation plans generated (if any) during execution
* **Verification Comments**: Post-execution verification results with any review comments or issues found
* **Commit**: Git commit created after successful execution
* **Status**: Current state of the execution (running, completed, verification pending, etc.)

### Viewing Executions

All executions are visible directly in the Epic view:

* **Execution History**: See every handoff that's occurred, both manual and automated
* **Execution Details**: Click into any execution to see the full context, what was handed off, and verification results
* **Real-time Updates**: Watch executions progress as agents work

This gives you a complete audit trail of how your Epic was implemented, making it easy to understand what changed, when, and why.

## Smart YOLO

Smart YOLO is Traycer's intelligent orchestrator that can execute entire Epics end-to-end with minimal human intervention. Simply use the `/execute` command or tell Traycer to execute your specs and tickets, and Smart YOLO takes over - automatically coordinating execution, verification, and iterative refinement until your Epic is complete.

**What makes it "smart":** Unlike traditional automation, Smart YOLO dynamically adjusts its execution strategy at runtime. It analyzes each spec and ticket, then intelligently configures every aspect of execution - from selecting the right agents and templates to determining whether to skip planning, which verification levels to address, appropriate timeouts, and whether to auto-commit. Every setting is optimized for the specific task at hand.

Smart YOLO is ideal when you have well-defined specs and tickets ready for implementation and want intelligent automated execution with minimal manual coordination.

For full documentation on Smart YOLO features and all dynamic configuration capabilities, see [YOLO Mode](/extension/tasks/yolo-mode#smart-yolo-for-epic-mode).

## Managing Specs and Tickets

Epic mode provides comprehensive artifact management capabilities. All specs and tickets are organized in the **Documents** panel on the side, where you can view, select, and manage them.

### Specs

* **Create**: Generate specs through AI-assisted conversations or use the **+ Add Spec** button
* **View & Edit**: Select any spec from the list to view and edit its contents
* **Organize**: All specs are grouped in the SPECS section of the Documents panel

### Tickets

* **Create**: Break down work into actionable tickets or use the **+ Add Ticket** button
* **View & Edit**: Select any ticket from the list to view and edit its contents
* **Status Tracking**: Track ticket status from Todo → In Progress → Done
* **Assignment**: Assign tickets to specific collaborators or leave them Unassigned
* **Organize**: All tickets are grouped in the TICKETS section of the Documents panel

**Assigning tickets:** Once you've shared your Epic board with team members, you can assign tickets directly from the ticket view. Learn more about [ticket assignment and collaboration](/extension/tasks/collaboration#ticket-assignment).

### Selection and Handoff

Use the **Select** button to enter selection mode and choose specific specs and tickets. Once selected, you can:

* **Refer in Chat**: Reference selected artifacts in conversation
* **Execute in Phases**: Hand off to Phases mode for implementation
* **Handoff To**: Send to your preferred coding agent

## Collaboration

Epic boards can be shared with your team so everyone works from the same set of specs and tickets. Share boards with teammates, assign tickets to specific collaborators, and work together in real time with live updates and presence indicators.

**Key collaboration features:**

* **Invite by email or GitHub handle** - Add collaborators individually or share with your entire organization
* **Assign tickets** - Distribute work across team members directly from the ticket view
* **Real-time editing** - Multiple people can edit specs and tickets simultaneously with live updates
* **Access control** - Set Editor or Viewer permissions based on each person's role

Click the share button next to `Open Board` in the top bar to get started.

📖 For detailed guides on inviting team members, ticket assignment, access levels, best practices, and use cases, see the [Collaboration documentation](/extension/tasks/collaboration).


# History
Source: https://docs.traycer.ai/extension/tasks/history

Track, manage, and access your complete development history. Traycer automatically preserves and syncs the complete history of all your tasks and phases, allowing you to review, revert, or continue from any previous state, or any device.

<Frame>
  <img alt="History" />
</Frame>

## What is preserved

Traycer maintains a comprehensive record of your development workflow:

* **Task history**: Complete timeline of all generated tasks and their iterations.
* **Phase progression**: Step-by-step history of multi-phase projects.
* **Plan evolution**: How your implementation plans changed over time.
* **Context preservation**: All decisions, file mappings, and rationale from previous sessions.

## Finding your tasks

The Task History interface provides powerful tools to locate and manage your development history:

* **Fuzzy search**: Quickly find tasks using partial matches across task titles and queries.
* **Workspace filtering**: Choose to view tasks from:
  * **Current Workspace**: Show only tasks from your active workspace.
  * **All Workspaces**: Display tasks from all your workspaces for a complete overview.

<AccordionGroup>
  <Accordion title="What happens if I switch devices?">
    Sign in with the same Traycer account on another device. Your synced history will load automatically.
  </Accordion>

  <Accordion title="What happens if I reinstall Traycer?">
    After reinstalling Traycer, sign back in with the same account to restore your synced history.
  </Accordion>
</AccordionGroup>


# Overview
Source: https://docs.traycer.ai/extension/tasks/index

Transform complex requirements into actionable, AI‑executable plans. Traycer Tasks turn ideas into precise, step‑by‑step implementation plans that AI coding tools can follow with zero guesswork.

Traycer analyzes your codebase, identifies exactly which files and functions need changes, and produces clear instructions your preferred AI assistant can execute end‑to‑end.

## What is a Task?

A Task is an intelligent development workflow that converts high-level requirements into executable plans. Each Task combines:

* **Intelligent analysis**: Understands your codebase and requirements in context.
* **Structured planning**: Breaks work into manageable steps or phases.
* **Context preservation**: Maintains full project understanding across steps.
* **Agent integration**: Hands off cleanly to your AI coding assistant.

## Task Modes

Traycer offers four modes for converting your ideas into Tasks:

<Columns>
  <Card title="Phases Mode" icon="shuffle" href="/extension/tasks/phases">
    Best for complex features spanning multiple services or larger work - sequenced steps that preserve context across phases.
  </Card>

  <Card title="Plan Mode" icon="clipboard" href="/extension/tasks/plan">
    Best for well-scoped tasks or features that can be implemented in one go, with clear, ready-to-implement guidance.
  </Card>

  <Card title="Review Mode" icon="magnifying-glass" href="/extension/tasks/review">
    Best for comprehensive code reviews with deep analysis - categorized findings for bugs, performance, security, and clarity improvements.
  </Card>

  <Card title="Epic Mode" icon="layer-group" href="/extension/tasks/epic">
    Best for managing specs and tickets through structured workflows - collaborative development with AI-guided processes.
  </Card>
</Columns>

<Card title="Workflows" icon="wrench" href="/extension/tasks/workflows">
  Learn how to create and manage custom workflows tailored to your team's methodology.
</Card>

<AccordionGroup>
  <Accordion title="When should I use Plan vs Phases?">
    Use **Plan** for focused, well-scoped changes that can be implemented in a single development session. Use **Phases** when
    a feature spans multiple areas, requires coordination, or benefits from
    incremental validation.
  </Accordion>

  <Accordion title="When should I use Epic mode?">
    Use **Epic** when you want to capture requirements as living specs, break work into tickets, share the board with your team, assign ownership, and collaborate in real time from requirements to implementation.
  </Accordion>

  <Accordion title="Can I collaborate with my team in Epic mode?">
    Yes. Epic Mode supports shared Epic boards, invitations, ticket assignment, and real-time collaboration. Learn more in the [Collaboration documentation](/extension/tasks/collaboration).
  </Accordion>

  <Accordion title="How does Traycer preserve context across steps?">
    Traycer carries forward file mappings, decisions, and rationale so later
    steps reference earlier work accurately, avoiding re-analysis.
  </Accordion>

  <Accordion title="Can I switch from Plan to Phases mode?">
    Yes. You can expand a Plan into Phases if scope grows by adding another phase after the current plan is complete.
  </Accordion>

  <Accordion title="Can I create custom workflows?">
    Yes. you can create custom workflows tailored to your team's methodology. Learn more in the [Workflows documentation](/extension/tasks/workflows).
  </Accordion>
</AccordionGroup>


# Mermaid Diagrams
Source: https://docs.traycer.ai/extension/tasks/mermaid

Interactive workflow visualizations automatically generated with implementation plans, featuring copy and full-screen viewing options

<Frame>
  <img alt="Mermaid diagram" />
</Frame>

These diagrams help visualize:

* **Multi-step processes**: Sequential workflows and dependencies.
* **System interactions**: How different components connect and communicate.
* **Decision flows**: Conditional logic and branching paths.
* **Data flows**: Input/output transformations and state changes.

## Interaction Options

You have two convenient ways to work with the diagrams:

### 1. Copy Diagram Text

Click the **"Copy Diagram"** button to copy the raw Mermaid diagram code to your clipboard. This is useful for:

* Pasting into documentation.
* Sharing with team members.
* Using in other Mermaid-compatible tools.

### 2. Full-Screen View

Click the **"Open Diagram"** button to open it in a full-screen PNG view for better visibility and interaction:

* **Better readability**: View complex diagrams without scrolling.
* **Copy as image**: Right-click on the full-screen diagram and select "Copy" to copy it as a PNG image.
* **Perfect for presentations**: Easily include visual workflows in slides or documents.


# Model Profiles and Cost Calculator
Source: https://docs.traycer.ai/extension/tasks/models

Understanding model profiles, selection modes, and cost estimation.

## Introduction

Traycer uses different models for different steps (planning, review, verification, iteration, etc.). You can control this behavior through **profiles** and **model selection modes**.

## Understanding Profiles

A **profile** is a preset configuration that maps specific models to each step in your Traycer tasks.

* Different steps have different requirements-some need deep reasoning, others benefit from speed
* Profiles bundle these step-to-model mappings with specific capability/cost tradeoffs
* Steps include operations like planning, iteration, review, verification, and orchestration

## System Profiles

Traycer provides two built-in profiles that serve as the foundation for model selection:

### Balanced

The default profile for everyday usage. Offers a carefully tuned mix of quality, speed, and cost across all steps.

### Frontier

The premium profile using top-tier models with maximum reasoning capability. Best for complex tasks where quality is the priority.

## Model Selection Modes

Traycer supports three different ways to select models:

### 1. Profile Mode (Default)

Use **Balanced** or **Frontier** as-is. Each step automatically uses its pre-configured model from the selected profile.

### 2. Custom Profile

Start from **Balanced** or **Frontier**, then override specific steps with different models:

* Modify only the steps you want to change
* Unmodified steps continue using the base profile's models
* Save your configuration as a reusable custom profile
* Great for optimizing specific workflow patterns

### 3. Single Model

Select one model to use across **all** steps:

* Simplest option-one model everywhere
* Less optimized than profiles, but easier to reason about
* Useful when you want consistent behavior or have a preferred model

## Cost Calculator and Comparison

Use the interactive calculator below to compare profiles, switch between selection modes, and estimate credit usage for each step.

<ModelPricingCalculator />

## Where to Access Model Selection

Model selection controls are available throughout Traycer:

* **Task features**: Configure models when creating tasks, generating plans, iterating, or running verifications
* **YOLO or Executions configuration**: Define model behavior for autonomous features via the configuration modal


# Phases Mode
Source: https://docs.traycer.ai/extension/tasks/phases

Structured, multi-phase development for complex projects. Break goals into iterative phases with validation between steps.

<Frame>
  <iframe title="Phases mode" />
</Frame>

<Steps>
  <Step title="1. User Query">
    State your goal, expected outcome, and constraints.

    <Accordion title="What context can I provide?">
      Optional context:

      * **Files**: Source files, config files, documentation, test files.
      * **Folders**: Component directories, feature folders, asset directories.
      * **Images**: UI mockups, error screenshots.
      * **Git**:
        * **Diff against uncommitted changes**: Changes that haven't been committed yet.
        * **Diff against 'main'**: Changes compared to the main/default branch.
        * **Diff against branch**: Changes compared to a specific branch of your choice.
        * **Diff against commit**: Changes compared to a specific commit.
    </Accordion>
  </Step>

  <Step title="2. Intent Clarification (if needed)">
    Traycer asks strategic questions to refine scope:

    * Business goals and user flows.
    * Architecture and integration needs.
    * Performance, security, and scalability requirements.
  </Step>

  <Step title="3. Phase Generation">
    Traycer structures work into manageable phases:

    * **Phase identification**: Clear milestones and outcomes.
    * **Sequential breakdown**: Logical progression from start to finish.
    * **Scope definition**: Well-defined boundaries for each phase.

    Learn more about [managing phases](/extension/tasks/phases#managing-phases).
  </Step>

  <Step title="4. Phase Planning">
    Traycer creates a detailed plan for each phase:

    * **Objectives** and deliverables.
    * **File changes** with exact edits.
    * **Architecture** and approach.

    Learn more about [plan](/extension/tasks/plan) for each phase.
  </Step>

  <Step title="5. Hand off to Agent">
    Execute the generated plan with your AI coding assistant. See [supported agents](/extension/integrations/agents).
  </Step>

  <Step title="6. Verification with Traycer">
    Validate each phase before moving on:

    * Compares agent's implementation against your original plan to ensure requirements.
    * Categorizes verification review comments by severity - Critical, Major, Minor, Outdated.

    Learn more about [verification](/extension/tasks/verification).
  </Step>

  <Step title="7. Next Phase">
    Advance with preserved context:

    * Carry forward decisions and mappings.
    * Clear progress tracking.
    * Plans adapt based on learnings.
  </Step>
</Steps>

## Automating phases with YOLO Mode

<Card title="YOLO Mode" icon="robot" href="/extension/tasks/yolo-mode">
  **Fully automated workflow.** Configure once and let Traycer automatically orchestrate planning, coding, and verification across all phases without manual handoff clicks.
</Card>

## Managing phases

After Traycer creates your initial phases, you have full control over the phase structure and can modify it as your project evolves.

### Phase selection mode

You can select multiple phases at once and refer to them in chat or merge them into a single phase using AI.

<Frame>
  <iframe title="Phase selection mode" />
</Frame>

### Adding more phases

<Frame>
  <img alt="Phases add" />
</Frame>

You can add additional phases at any point in your project:

* **Insert new phases**: Add phases between existing ones or at the end.
* **Address new requirements**: Add phases for features or changes discovered during development.
* **Refinement phases**: Add phases for optimization, testing, or documentation.

### Re-arranging phase order

<Frame>
  <img alt="Phases rearrange" />
</Frame>

Traycer allows you to re-arrange the order of phases to optimize your development process:

* **Drag and drop**: Simply drag phases to reorder them in the sequence.
* **Flexible sequencing**: Change the order based on new insights or changing priorities.


# Plan Mode
Source: https://docs.traycer.ai/extension/tasks/plan

Direct, step-by-step implementation for single-PR tasks. Perfect for straightforward development tasks where you want a direct, step‑by‑step guide from idea to implementation.

<Frame>
  <iframe title="Plan mode" />
</Frame>

<Steps>
  <Step title="1. User Query">
    State your goal, expected outcome, and constraints.

    <Accordion title="What context can I provide?">
      Optional context:

      * **Files**: Source files, config files, documentation, test files.
      * **Folders**: Component directories, feature folders, asset directories.
      * **Images**: UI mockups, error screenshots.
      * **Git**:
        * **Diff against uncommitted changes**: Changes that haven't been committed yet.
        * **Diff against 'main'**: Changes compared to the main/default branch.
        * **Diff against branch**: Changes compared to a specific branch of your choice.
        * **Diff against commit**: Changes compared to a specific commit.
    </Accordion>
  </Step>

  <Step title="2. Detailed File-Level Plan with Symbol References">
    Traycer generates a detailed plan including:

    * **File analysis & structure**.
    * **Symbol references**.
    * **Implementation steps**.

    If the plan isn't fully aligned with your goal, *iterate* to refine it until it fits your goal.
  </Step>

  <Step title="3. Execute in Agent">
    Run the plan with your preferred coding assistant. (See [supported agents](/extension/integrations/agents).)
  </Step>

  <Step title="4. Verification">
    Validate in Traycer:

    * Compares agent's implementation against your original plan to ensure requirements.
    * Categorizes verification review comments by severity - Critical, Major, Minor, Outdated.

    [Learn more about verification](/extension/tasks/verification).
  </Step>

  <Step title="5. Complete">
    Finalize, commit, and ship.
  </Step>
</Steps>


# Review Mode
Source: https://docs.traycer.ai/extension/tasks/review

Agentic code review with thorough exploration and analysis. Perfect for comprehensive code quality checks where you want deep insights into implementation details, potential issues, and improvement opportunities.

<Frame>
  <iframe title="Review mode" />
</Frame>

<Steps>
  <Step title="1. User Query">
    State your goal, expected outcome, and constraints.

    <Accordion title="What context can I provide?">
      Optional context:

      * **Files**: Source files, config files, documentation, test files.
      * **Folders**: Component directories, feature folders, asset directories.
      * **Images**: UI mockups, error screenshots.
      * **Git**:
        * **Diff against uncommitted changes**: Changes that haven't been committed yet.
        * **Diff against 'main'**: Changes compared to the main/default branch.
        * **Diff against branch**: Changes compared to a specific branch of your choice.
        * **Diff against commit**: Changes compared to a specific commit.
    </Accordion>
  </Step>

  <Step title="2. Comprehensive Code Review">
    Traycer performs an agentic code review with:

    * **Deep code exploration** across files and dependencies.
    * **Implementation analysis** to understand context and impact.
    * **Review comments** categorized by category - Bug, Performance, Security, Clarity.

    Review the findings and address comments based on category and impact.

    If you are not satisfied with the comments received, and want to provide feedback, *iterate* to refine it until it fits your goal.
  </Step>

  <Step title="3. Complete">
    Finalize, commit, and ship.
  </Step>
</Steps>

## Review comment categories

<Frame>
  <img alt="Review categories" />
</Frame>

Traycer organizes review comments by category to help you understand and prioritize issues:

* **Bug**: Functional issues, logic errors, or incorrect implementations that need fixing.
* **Performance**: Inefficiencies, bottlenecks, or optimization opportunities that affect speed or resource usage.
* **Security**: Vulnerabilities, unsafe practices, or potential security risks that need attention.
* **Clarity**: Code readability, maintainability, documentation, or style improvements.

## Fixing review comments

You have three options for addressing review comments:

* **Fix individual comments**: Use the coding agent icon button next to each comment to address specific issues one at a time.
* **Fix selected comments**: Enable selection mode to choose multiple comments, then send the selected comments to your [agent](/extension/integrations/agents) for fixing.
* **Fix all comments**: Use the **Fix all in** button to have your [agent](/extension/integrations/agents) address all review comments at once.


# Verification
Source: https://docs.traycer.ai/extension/tasks/verification

Verify agent's implementation and manage review comments for iterative improvements. Traycer's verification process ensures that agent's implementation meet your requirements and follow your original plan. When issues are found, it generates actionable review comments that can be handed back to agents for fixes.

## How verification works

Traycer analyzes agent's implementation against your original plan and creates categorized review comments for any issues found. These comments can be handed off to your preferred agent for iterative fixes and improvements.

## Verification comment categories

<Frame>
  <img alt="Verification categories" />
</Frame>

Traycer organizes verification comments by priority level to help you focus on the most important issues first:

* **Critical**: Blocks core functionality or plan requirements and must be fixed first.
* **Major**: Significant issues that affect behavior or UX but may have workarounds.
* **Minor**: Small polish items that don't block functionality.
* **Outdated**: Comments that are no longer relevant due to changes in the implementation.

## Fixing verification comments

You have three options for addressing verification comments:

* **Fix individual comments**: Use the coding agent icon button next to each comment to address specific issues one at a time.
* **Fix selected comments**: Enable selection mode to choose multiple comments, then send the selected comments to your [agent](/extension/integrations/agents) for fixing.
* **Fix all comments**: Use the **Fix all in** button to have your [agent](/extension/integrations/agents) address all verification comments at once.

## Verification options

Choose between focused re-verification or complete fresh verification based on your needs:

* **Re-verify**: Focused pass that checks whether previously identified issues are resolved. Faster and ideal for iterative cycles.
* **Fresh Verification**: Full re-analysis that ignores old comments and reassesses the whole implementation.


# Workflows
Source: https://docs.traycer.ai/extension/tasks/workflows

Create and manage structured development processes. Define custom workflows with commands that guide your team through your unique methodology.

Workflows are structured processes that guide you through development tasks using a series of commands. Each workflow represents a methodology or approach to software development, from initial requirements to implementation.

Traycer comes with default workflows like the **Traycer Agile Workflow**, and you can create custom workflows tailored to your team's unique processes.

## What is a Workflow?

A workflow is a collection of command files that guide you through a development process. Each workflow consists of:

* **Name & Description**: Identify the workflow and its purpose
* **Entrypoint Command**: The starting point (default: `trigger_workflow`, customizable)
* **Command Files**: Additional steps in your process

Workflows are used within [Epic Mode](/extension/tasks/epic) to structure your development process.

<Frame>
  <img alt="Workflow Structure" />
</Frame>

### Workflow Structure

Each workflow has:

* **Workflow Metadata**: Name and description
* **One Entrypoint**: The command file that starts the workflow
* **Multiple Commands**: Each command is a file with instructions for the AI

**Important**: The file name and command name are the same thing.

## Using Workflows

### Triggering a Workflow

To start a workflow in Epic Mode:

1. **Select a workflow** from the dropdown when creating or working in an Epic. Available options include:
   * Your custom workflows
   * **Traycer Agile Workflow** (default)
   * **No Workflow** - Run without a structured workflow

2. **Choose a command** by typing `/` in the chat input to see all available commands from your selected workflow:
   * `/trigger_workflow` (or your custom entrypoint) - Start the workflow
   * `/command-name` - Any other command in the workflow

3. **Provide context** after selecting the command - the slash becomes regular text after selection, allowing you to add your requirements or arguments.

**Note**: Only one command per query. After selecting a command with `/`, the slash character will be treated as regular text.

## Creating Custom Workflows

You can create custom workflows tailored to your team's methodology using the **+ Add Workflow** button.

### Creating a Workflow

1. Click **+ Add Workflow** in the Workflows panel
2. Enter a **Name** and **Description** for your workflow
3. An entrypoint command file is automatically created (default: `trigger_workflow`)

<Frame>
  <img alt="Adding new workflow" />
</Frame>

### Adding Commands

To add commands to your workflow:

1. Click **+ Add Command** in the Workflow Commands panel
2. Give your command a descriptive name (this becomes the file name)
3. Configure the command's properties and content

### Command Configuration

Each command has three key components:

#### 1. Description

A brief explanation of what this command does - shown to users when they type `/` to select commands.

#### 2. Argument Hints

Optional hints that guide what information should be passed when calling this command. Click **Add new hint** to add hints.

See [Using Arguments](#using-arguments) for details on how to reference arguments in your command instructions.

#### 3. Next Steps

Define which commands can follow this one. Click **Add next step** to select commands from your workflow.

See [Multi-Path Workflows](#multi-path-workflows) for details on how the AI suggests next steps.

### Writing Command Instructions

Use the markdown editor to write instructions for the AI. You can structure your instructions however makes sense for your workflow, and reference arguments using `$1`, `$2`, etc. where needed.

## Managing Workflows

### Viewing Workflows

Workflows are organized in the Workflows panel on the left side:

* **Default Workflows**: Marked as "Default (Read-only)" - these are bundled with Traycer and cannot be edited
* **Custom Workflows**: Your own workflows that you can fully edit and customize

Access workflows through:

* The Workflows panel in the sidebar
* Workflow selector when creating a new Epic
* Click the menu (three dots) and select "Manage workflow" to open the workflow viewer

<Frame>
  <img alt="Viewing workflow" />
</Frame>

### Cloning Workflows

**Default Workflows** are read-only but can be cloned. Click **Clone to Edit** to create an editable copy that you can customize.

<Frame>
  <img alt="Cloning workflow" />
</Frame>

### Editing Workflows

**Custom Workflows** are fully editable:

1. Select your workflow from the Workflows panel
2. Click on any command to edit its content
3. Modify command metadata (description, argument hints, next steps)
4. Changes save automatically

### Managing Commands

| Action             | Description                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| **Add Command**    | Create a new command file in your workflow using **+ Add Command**                             |
| **Edit Command**   | Click any command to modify its content and metadata (description, argument hints, next steps) |
| **Delete Command** | Remove a command (entrypoint cannot be deleted)                                                |

### Deleting Workflows

Custom workflows can be deleted from the Workflows panel. Default workflows cannot be deleted.

## Integration with Epic Mode

Workflows are the backbone of [Epic Mode](/extension/tasks/epic):

* **Structured Guidance**: Workflows guide the development process
* **Context Preservation**: Decisions flow between commands
* **Artifact Creation**: Commands generate specs and tickets
* **Flexible Execution**: Follow or adapt workflow as needed

## Advanced Workflow Features

### Using Arguments

Commands can accept arguments that provide context when they're called. Here's how to set them up:

**1. Configure Argument Hints**

When editing a command, add argument hints that describe what information users should provide. For example:

* "Feature name or requirement"
* "Technology or approach"

**2. Reference Arguments in Command File**

In your command instructions, use `$1`, `$2`, `$3`, etc. to reference the arguments:

```markdown theme={null}
<processing_user_request>
The user wants to implement: $1
Using technology: $2
</processing_user_request>
```

**3. Call the Command with Arguments**

When users call the command, they provide the actual values:

```
/create-feature User authentication OAuth2 and JWT
```

The AI automatically maps the arguments:

| Reference | Argument Hint                 | Actual Value        |
| --------- | ----------------------------- | ------------------- |
| `$1`      | "Feature name or requirement" | User authentication |
| `$2`      | "Technology or approach"      | OAuth2 and JWT      |

### Multi-Path Workflows

Use Next Steps to create workflows with alternative paths. The AI will suggest or let the user choose from the configured next commands based on the context.

**Example:** A command might have multiple possible next steps:

* `design-review` - for UI-heavy features
* `tech-plan` - for backend features
* `spike-investigation` - for uncertain requirements

The AI will recommend the most appropriate next step or present options to the user.

### Agent Modes

Workflows support different **agent modes** that can be selected per command. Each mode is optimized for specific use cases with dedicated models, reasoning configurations, and system prompts.

<Frame>
  <img alt="Agent mode selection in workflows" />
</Frame>

#### Available Modes

**Planner Mode**

* Optimized for strategic thinking and planning tasks
* Uses extended reasoning capabilities for complex analysis
* Ideal for commands that create specs, design systems, or break down requirements
* Custom system prompts focused on thorough exploration and documentation

**Reviewer Mode**

* Optimized for evaluation and quality assessment
* Configured for detailed review and verification workflows
* Ideal for commands that validate, critique, or provide feedback on artifacts
* System prompts emphasize thoroughness, edge cases, and improvement suggestions

#### Using Agent Modes

When creating or editing a command, you can specify which agent mode should be used when that command executes:

1. Select the command in your workflow
2. Choose the appropriate agent mode from the dropdown
3. The selected mode will be used whenever that command runs

This gives you fine-grained control over how each step in your workflow behaves, ensuring the right "thinking style" is applied at each stage of your development process.

## Traycer Agile Workflow

The default workflow guides you through feature development with a collaborative, spec-driven approach.

### Workflow Commands

<Steps>
  <Step title="trigger_workflow">
    **Purpose**: Initial requirements gathering and clarification

    * Discuss user's request and goals
    * Ask clarifying questions
    * Build shared understanding
    * No assumptions - alignment first

    **Next Steps**: `epic-brief` or `core-flows`
  </Step>

  <Step title="epic-brief">
    **Purpose**: Define problem and context collaboratively

    * Capture who's affected and current pain points
    * Document the problem at a product level
    * Create concise Epic Brief spec (under 50 lines)
    * No UI specifics or technical design yet

    **Next Steps**: `core-flows`
  </Step>

  <Step title="core-flows">
    **Purpose**: Map out user flows and interactions

    * Explore current product flows
    * Design UX decisions (information hierarchy, user journeys)
    * Document step-by-step user actions
    * Include wireframes or ASCII sketches

    **Next Steps**: `tech-plan` or `ticket-breakdown`
  </Step>

  <Step title="tech-plan">
    **Purpose**: Create technical implementation plan

    * Define architecture and technical approach
    * Identify files and components to modify
    * Document technical decisions and rationale
    * Reference existing code patterns

    **Next Steps**: `ticket-breakdown`
  </Step>

  <Step title="ticket-breakdown">
    **Purpose**: Break down work into actionable tickets

    * Create independently implementable tickets
    * Link tickets to relevant specs
    * Define acceptance criteria
    * Prioritize and sequence work

    **Next Steps**: Implementation via Phases, Plan, or Agent handoff
  </Step>
</Steps>

### Workflow Philosophy

The Traycer Agile Workflow emphasizes:

* **Collaboration First**: Discuss and align before drafting artifacts
* **Questions as Investments**: Clarification prevents costly mistakes
* **Shared Understanding**: Multiple rounds of questions is normal
* **Readable Artifacts**: Optimize for human parsability


# YOLO Mode
Source: https://docs.traycer.ai/extension/tasks/yolo-mode

YOLO Mode (You Only Look Once) automates your entire workflow. From intelligent orchestration that adapts at runtime to fixed-configuration automation, let Traycer handle planning, coding, and verification without manual intervention.

YOLO Mode brings automated execution to Traycer, minimizing manual intervention and letting you focus on higher-level decisions. Traycer offers two flavors of YOLO:

* **Smart YOLO for Epic Mode**: Intelligent orchestrator that learns from implementation and adapts at runtime-updating specs and tickets, steering plans, and adjusting configurations as it executes Epics end-to-end
* **YOLO for Phases Mode**: Powerful automation using fixed configurations you define upfront for phase-by-phase workflows

Both leverage the same underlying configuration options, but Smart YOLO adaptively evolves your Epic (specs, tickets, plans, and settings) while regular YOLO executes with your predefined configurations.

## Smart YOLO for Epic Mode

Smart YOLO brings intelligent orchestration to [Epic Mode](/extension/tasks/epic), automatically executing entire Epics end-to-end while adapting specs, tickets, and plans based on implementation discoveries. It can run multiple executions in parallel when safe to do so, dramatically reducing overall execution time. Unlike fixed automation, Smart YOLO learns from each execution and steers the Epic dynamically with minimal human intervention.

<Frame>
  <video>
    <source type="video/mp4" />

    Unable to load video.
  </video>
</Frame>

<Info>
  **Agent Selection**: Smart YOLO can only select from [YOLO-compatible agents](/extension/integrations/agents) (marked with <Icon icon="bolt" />) that are configured in your workspace settings. The orchestrator dynamically chooses the most appropriate agent for each phase based on the task context.
</Info>

### What Smart YOLO does

1. **Evolves your Epic dynamically** - updates specs and tickets at runtime based on implementation discoveries, refining requirements and acceptance criteria as the codebase reveals constraints or opportunities
2. **Steers execution strategy** - analyzes implementation progress and adaptively adjusts plans, breaking down complex tickets or merging related work items as needed
3. **Runs executions in parallel** - intelligently determines which specs and tickets can be executed concurrently without conflicts, significantly reducing overall execution time for independent work items
4. **Creates Executions** - each handoff to a coding agent is tracked as an [Execution](/extension/tasks/epic#executions) in your Epic, providing full visibility into plans, verification results, commits, and status
5. **Makes smart handoffs** - determines optimal execution strategy for each task based on dependencies and implementation context
6. **Adapts all execution settings** - adjusts plans, agents, templates, verification, timeouts, and commits based on requirements and implementation context
7. **Runs verification loops** - validates changes match intent after each execution
8. **Coordinates iterative refinement** - if verification finds issues or implementation reveals scope changes, orchestrates fixes, plan adjustments, and re-verification
9. **Maintains context** - preserves Epic context throughout the entire execution chain, using learnings from one execution to inform subsequent ones

### Triggering Smart YOLO

To start automated execution in Epic Mode:

* Use the `/execute` command in the Epic chat, or
* Simply tell Traycer to execute your tickets or specs (e.g., "Execute these tickets")

Smart YOLO will take over from there, coordinating the entire execution process.

### When to use Smart YOLO

Smart YOLO is ideal when:

* You have specs and tickets ready for implementation (even if they need refinement during execution)
* You want to execute multiple tickets with minimal manual coordination
* You expect implementation to reveal scope changes or technical constraints
* You want an orchestrator that adapts to discoveries rather than blindly following a fixed plan
* You trust your coding agents to handle implementation details while Smart YOLO steers overall strategy
* You want automatic verification after each execution
* You want full execution tracking with plans, verification results, and commits

You describe the Epic and its requirements. Smart YOLO coordinates the rest - adapting specs, steering plans, and managing execution through verification. All handoffs are tracked as [Executions](/extension/tasks/epic#executions) in your Epic view for complete visibility.

<Tip>
  **Auto-commit Configuration**: You can configure Smart YOLO to automatically commit changes after successful execution, creating a clean commit history as your Epic progresses.
</Tip>

### Smart YOLO FAQ

<AccordionGroup>
  <Accordion title="Can Smart YOLO execute multiple specs/tickets in parallel?">
    Yes! Smart YOLO intelligently parallelizes execution to maximize speed while ensuring correctness. It analyzes your Epic to determine:

    * Which specs or tickets are independent and can run concurrently
    * Which work items have dependencies that require sequential execution
    * How to batch related changes to avoid conflicts
  </Accordion>

  <Accordion title="Can I override Smart YOLO's configuration decisions?">
    Smart YOLO operates autonomously with the `/execute` command. If you need more control over specific configurations, you can use manual handoff options from the Epic view where you can specify exact settings for each execution.
  </Accordion>

  <Accordion title="What happens if an execution fails?">
    Smart YOLO monitors execution results and coordinates fixes:

    * If verification finds issues, it can automatically hand off fixes to agents
    * If an execution fails, Smart YOLO pauses to allow you to address the issue
    * You can resume Smart YOLO after resolving failures
    * All execution results are tracked in the [Executions view](/extension/tasks/epic#executions) within your Epic
  </Accordion>

  <Accordion title="Does Smart YOLO work with all agents?">
    No. Smart YOLO only works with [YOLO-compatible agents](/extension/integrations/agents) (marked with <Icon icon="bolt" />) that are configured in your workspace settings. The orchestrator dynamically selects from these configured agents based on the task requirements.
  </Accordion>

  <Accordion title="Can Smart YOLO modify my specs and tickets during execution?">
    Yes! This is a key differentiator of Smart YOLO. Unlike fixed automation, Smart YOLO can:

    * Update specs and tickets based on implementation discoveries
    * Refine acceptance criteria when the codebase reveals constraints
    * Add or modify requirements as execution uncovers scope changes
    * Split complex tickets or merge related ones based on actual implementation needs

    All updates are tracked in your Epic, so you have full visibility into how specs and tickets evolved during execution. This adaptive approach produces better results than rigidly following initial specs that may not account for implementation realities.
  </Accordion>
</AccordionGroup>

For more details on Epic Mode and execution tracking, see the [Epic Mode documentation](/extension/tasks/epic).

## YOLO for Phases Mode

YOLO Mode for [Phases](/extension/tasks/phases) automates the entire phase workflow using **fixed configurations** you define upfront. Once configured, it executes phases consistently without changing settings mid-execution.

### How it works

YOLO Mode works with two types of workflows:

#### Plan Workflow

For implementation tasks, YOLO Mode automatically executes these steps for each phase:

1. **Planning** - Traycer generates detailed plans or skips directly to coding (based on your config)
2. **Coding** - Automatically hands off to your selected coding agent with optional custom templates
3. **Verification** - Validates implementation and optionally hands off selected comment categories back to your agent
4. **Next phase** - Continues to the next phase automatically until all phases are complete

#### Review Workflow

For code review tasks, YOLO Mode automatically executes these steps for each phase:

1. **Review** - Traycer analyzes code and generates review comments
2. **Coding** - Automatically hands off review comments to your selected coding agent for fixes
3. **Next phase** - Continues to the next phase automatically until all phases are complete

The entire cycle runs without manual intervention using your predefined configuration.

### Activating YOLO Mode

<Steps>
  <Step title="1. Create a Phases task">
    Start by creating a task using [Phases Mode](/extension/tasks/phases). YOLO Mode works with the phase structure you've already defined.
  </Step>

  <Step title="2. Click YOLO Mode button">
    Once your phases are displayed in the Kanban board view, click the **YOLO Mode** button to activate automation.
  </Step>

  <Step title="3. Select phase range">
    Use the side slider to select which phases to automate. You can choose from the current phase to any future phase, allowing you to automate a subset of your phases or all remaining phases.
  </Step>

  <Step title="4. Configure automation settings">
    Set up your automation preferences (see [Configuration Options](#configuration-options) below). These settings will be used consistently across all selected phases.
  </Step>

  <Step title="5. Start automation">
    Confirm your configuration and let Traycer run the entire workflow automatically across the selected phase range.
  </Step>
</Steps>

## Configuration options

Both YOLO for Phases and Smart YOLO use the same underlying configuration options. **For regular YOLO**, you set these configurations upfront and they remain fixed throughout execution.

**For Smart YOLO**, the orchestrator goes beyond just configuration-it **evolves your Epic** based on implementation learnings:

**Epic evolution:**

* Updates specs and tickets based on implementation discoveries
* Refines acceptance criteria and requirements
* Steers plans by splitting, merging, or reordering work items
* Propagates learnings from one execution to inform subsequent ones

**Dynamic configuration adjustments:**

* Skip or generate plans
* Select agents (plan, verification, review) from [YOLO-compatible agents](/extension/integrations/agents) configured in your workspace
* Choose templates (plan, verification, review)
* Adjust execution timeouts
* Configure verification severity levels
* Select review categories
* Enable/disable verification
* Enable/disable auto-commits
* Configure custom commit scripts

The orchestrator analyzes each task, learns from implementation progress, and optimizes both Epic content and execution settings for the specific context.

### User query handoff

<Frame>
  <img alt="User query handoff configuration" />
</Frame>

Skip detailed planning and send the phase query directly to your coding agent.

**Options:**

* **Skip plan generation**: Check this to bypass detailed plan generation for this phase
* **Execution Agent for user query handoff**: Choose from [YOLO-compatible agents](/extension/integrations/agents) (marked with <Icon icon="bolt" />)
* **Template for user query**: Optionally apply a custom [user query template](/extension/integrations/templates) to wrap the query with additional instructions

**When to use:**

* Simple, straightforward implementation tasks.
* When the phase query is already detailed enough for direct coding.
* To speed up execution for phases with clear requirements.

### Plan handoff

<Frame>
  <img alt="Plan handoff configuration" />
</Frame>

Generate a detailed plan and automatically hand it off to your coding agent. This is the default mode when "Skip plan generation" is unchecked.

**Options:**

* **Execution Agent**: Choose from [YOLO-compatible agents](/extension/integrations/agents) (marked with <Icon icon="bolt" />)
* **Template for plan generation**: Optionally apply a custom [plan template](/extension/integrations/templates) to include project-specific instructions, testing requirements, or coding standards

**When to use:**

* Complex implementations requiring structured guidance.
* When you want agents to follow specific architecture patterns.
* For tasks where detailed file-level plans improve code quality.

### Verification handoff

<Frame>
  <img alt="Verification handoff configuration" />
</Frame>

After Traycer verifies the agent's implementation, automatically send selected comment categories back to the agent for fixes.

**Options:**

* **Skip verification**: Check this to bypass verification for this phase
* **Execution Agent**: Choose from [YOLO-compatible agents](/extension/integrations/agents) (marked with <Icon icon="bolt" />)
* **Template for verification**: Optionally apply a custom [verification template](/extension/integrations/templates) to provide fix instructions
* **Severity levels to verify**: Choose which severity levels to hand off (multiple selections allowed):
  * **Critical**: Blocks core functionality or plan requirements
  * **Major**: Significant issues affecting behavior or UX
  * **Minor**: Small polish items that don't block functionality

**When to use:**

* To automatically iterate on critical and major issues.
* When you want agents to polish implementations before moving to the next phase.
* To maintain quality standards across all phases.

<Tip>
  You can select multiple severity levels to balance quality and speed. For example, selecting only **Critical** and **Major** ensures agents address serious issues while skipping minor polish items.
</Tip>

### Review handoff

<Frame>
  <img alt="Review handoff configuration" />
</Frame>

For Review workflow tasks, automatically hand off review comments to your coding agent for fixes.

**Options:**

* **Execution Agent**: Choose from [YOLO-compatible agents](/extension/integrations/agents) (marked with <Icon icon="bolt" />)
* **Template for review**: Optionally apply a custom [review template](/extension/integrations/templates) to provide fix instructions
* **Review categories**: Choose which review categories to hand off (multiple selections allowed)

**When to use:**

* When working with Review workflow tasks in YOLO Mode
* To automatically address code review feedback
* To maintain code quality standards through automated review cycles

<Tip>
  Review handoff is only available for tasks created with the [Review workflow](/extension/tasks/review).
</Tip>

## Managing agents and templates

### Agents

YOLO Mode (both regular and Smart YOLO) only works with [YOLO-compatible agents](/extension/integrations/agents) that support automated execution. These agents are marked with <Icon icon="bolt" /> in the agents documentation.

Available agents must be configured in your workspace settings. If your preferred agent isn't available in the dropdown, see [how to add additional agents](/extension/integrations/agents#adding-additional-agents).

For more control over CLI-based agents, you can create [Custom CLI Agents](/extension/integrations/custom-cli-agents) with custom arguments and permissions.

### Templates

To customize handoff prompts with your own instructions, see [Templates documentation](/extension/integrations/templates) for creating user query, plan, and verification templates.

## Preventing interruptions

### Artifact slots and rate limits

YOLO Mode runs continuously across multiple phases, consuming artifact slots as it progresses. If you run out of slots during execution, YOLO Mode will pause until slots are available again.

<Info>
  To avoid interruptions, consider enabling automatic instant refills in your VS Code settings. Learn more about artifact slots, instant refills, and automatic pay-as-you-go in the [Pricing & Usage Limits](/account/pricing#instant-refill) documentation.
</Info>

### Keep your screen active

**Important:** YOLO Mode requires an active connection to your IDE. If your computer goes to sleep or the screen times out, the automation will stop.

**Recommendations:**

* Disable screen timeout/sleep mode during YOLO Mode execution.
* Keep your IDE window active and visible.
* Consider running long YOLO Mode sessions when you can monitor progress.

## FAQ

<AccordionGroup>
  <Accordion title="What happens if YOLO Mode hits a rate limit?">
    YOLO Mode will pause when you run out of artifact slots. You can either wait for slots to recharge based on your plan's recharge rate, or use instant refills (\$0.50 per slot). To avoid interruptions, consider enabling [automatic instant refills](/account/pricing#instant-refill) in your VS Code settings, which will automatically refill slots without prompting. Once slots are available, you'll need to manually resume YOLO Mode from where it stopped.
  </Accordion>

  <Accordion title="Can I change configuration while YOLO Mode is running?">
    Yes, but only for phases that haven't started yet. You can modify configuration for upcoming phases while YOLO Mode is running. However, you cannot change settings for the currently executing phase or phases that have already completed. To adjust settings for future phases, update your configuration and the changes will apply when those phases begin.
  </Accordion>

  <Accordion title="Can I use different agents for different phases?">
    Yes! Each phase can be configured with its own coding agent selection. This allows you to use specialized agents for specific types of work. For example, you might use one agent for frontend phases and another for backend phases.
  </Accordion>

  <Accordion title="What if my computer goes to sleep during execution?">
    YOLO Mode will stop if your computer sleeps or the screen times out. Make sure to disable sleep/timeout settings before starting long automation runs. You can resume from the last completed step once your computer wakes up.
  </Accordion>

  <Accordion title="Does YOLO Mode work with all coding agents?">
    No. YOLO Mode only works with [YOLO-compatible agents](/extension/integrations/agents) (marked with <Icon icon="bolt" />) that support automated execution. Other agents require manual interaction and are not compatible with YOLO Mode's automated workflow.
  </Accordion>

  <Accordion title="How do templates work with YOLO Mode?">
    Templates wrap Traycer's generated content with your custom instructions. You can select different templates for user query handoff, plan handoff, and verification handoff. This allows you to maintain consistent project standards across automated executions. Learn more in the [Templates documentation](/extension/integrations/templates).
  </Accordion>

  <Accordion title="What's the difference between user query handoff and plan handoff?">
    **User query handoff**: Skips detailed planning and sends the phase query directly to the agent. Faster, but provides less structured guidance.

    **Plan handoff**: Generates a detailed implementation plan first, then hands it to the agent. Takes more time but provides better structure and reduces agent drift.

    Choose based on task complexity and how much guidance your agent needs.
  </Accordion>

  <Accordion title="Can I use Custom CLI Agents with YOLO Mode?">
    Yes! Custom CLI Agents that use YOLO-compatible CLI tools (like Claude Code CLI, Codex CLI, or Gemini CLI) work seamlessly with YOLO Mode. You can create custom templates with special flags like `--dangerous` or custom paths, and they'll appear in the agent selection dropdown. Learn more in the [Custom CLI Agents documentation](/extension/integrations/custom-cli-agents).
  </Accordion>
</AccordionGroup>

## Related documentation

<Columns>
  <Card title="Epic Mode" href="/extension/tasks/epic">
    Learn about Epic Mode and how Smart YOLO automates Epic execution.
  </Card>

  <Card title="Phases Mode" href="/extension/tasks/phases">
    Learn about the underlying Phases workflow that YOLO Mode automates.
  </Card>

  <Card title="Plan Workflow" href="/extension/tasks/plan">
    Understand the Plan workflow for implementation tasks.
  </Card>

  <Card title="Review Workflow" href="/extension/tasks/review">
    Understand the Review workflow for code review tasks.
  </Card>

  <Card title="Verification" href="/extension/tasks/verification">
    Learn how Traycer validates agent implementations and categorizes issues.
  </Card>

  <Card title="Supported Agents" href="/extension/integrations/agents">
    Browse the full list of coding agents and add additional agents.
  </Card>

  <Card title="Templates" href="/extension/integrations/templates">
    Create custom Handlebars templates to enhance automated handoffs.
  </Card>
</Columns>


# Host Changelog
Source: https://docs.traycer.ai/host/changelog

Track the latest updates and improvements to the Traycer Host.

<Update label="v1.1.9">
  The Oh My Pi coding agent, agent roles, and installs that recover instead of leaving you stuck.

  * **Oh My Pi** — the Oh My Pi coding agent is now available.
  * **Agent roles** — an agent can carry a role.
  * **Steer a running agent** — supported coding agents can take a message while their turn is still running. Others queue it for afterwards.
  * **Search** — artifacts and workspaces can be searched within a chosen scope, and a workspace's file list keeps up as files change.
  * **Artifacts** — the Host reports when artifacts have finished syncing, rather than assuming they have.
  * **Notifications** — an agent that stops because it ran out of context, or because its request was refused, now reports which. Terminal agents get their own indicators, and notifications resume after a terminal closes.
  * **Archiving** — chats can be archived.
  * **Install and update** — a failure now offers a way forward instead of leaving you stuck. On macOS, the Host no longer runs slowed down in the background.
</Update>

<Update label="v1.1.8">
  The Hermes coding agent, a rebuilt notification center, and downloads that resume.

  * **Hermes** — the Hermes coding agent from Nous Research is now available.
  * **Rate limits** — Grok account usage is now reported.
  * **Notifications** — rebuilt, with a clear way to dismiss anything needing attention and consistent wording wherever a notification appears.
  * **Agents** — conversations are treated as agents.
  * **Agent messages** — control over what an agent is allowed to do.
  * **Resources** — an agent and everything it started can be stopped together.
  * **Updates** — large downloads resume where they left off.
  * **Sign-in** — the Host, CLI, and desktop app share one sign-in.
  * **Reliability** — repeated requests are coordinated, and retries slow down while waiting on background work.
</Update>

<Update label="v1.1.7">
  Several accounts per provider, two new coding agents, and terminals that run outside a Task.

  * **Several accounts per provider** — use more than one Claude or Codex account, including choosing which one an agent uses when agents message each other.
  * **Devin and Pi** — both coding agents are now available.
  * **Terminals** — terminal sessions can run outside a Task.
  * **Fork a question** — branch a chat from a question.
  * **Claude sign-in** — paste an OAuth code when the browser redirect cannot complete.
  * **Resource tracking** — counts every process running under the Host.
  * **Git status** — updates when files change, rather than on a timer.
  * **Worktrees** — status is kept current without repeatedly reading from Git, and setup failures are reported and recoverable.
  * **Notifications** — hooks that call a URL or run a command, filtered by severity, plus alerts when a workspace fails.
  * **Background work** — background tasks report elapsed time and results, and an agent doing background work is reported as such rather than as mid-turn.
  * **Rate limits** — the composer banner matches the model actually selected.
  * **Performance** — the provider list no longer re-checks in tight bursts.
</Update>

<Update label="v1.1.6">
  * **Fork a pending question** — fork a chat while a question is still waiting for an answer, leaving the original untouched.
  * **Compatibility** — newer clients stay connected to older Hosts; anything unavailable falls back where it can, or asks for an update.
</Update>

<Update label="v1.1.5">
  The Amp coding agent, Windows support, and per-process resource tracking.

  * **Amp** — the Amp coding agent from Sourcegraph is now available.
  * **Windows** — the Host runs on Windows, powering the new Windows builds of Traycer Desktop and the CLI.
  * **Resource tracking** — CPU and memory for everything the Host runs, feeding the app's resource monitor.
  * **Nested agents** — Claude subagents and parallel groups are reported as a tree.
  * **Worktrees** — listings page as they grow, and show which worktrees are stale or already merged.
  * **Terminal agents** — Claude and OpenCode keep the correct session when it changes.
  * **Start without a folder** — supported end to end.
</Update>

<Update label="v1.1.4">
  * **Scheduled wake-ups** — Claude's background work is reported as a tree, including scheduled wake-ups.
  * **Git diffs** — changes made inside Git submodules now appear.
  * **Usage limits** — recover after a temporary failure.
  * Terminal agents no longer die quietly when the connection drops.
</Update>

<Update label="v1.1.3">
  * **Account usage** — reported for Codex, Claude Code, OpenRouter, and Kilo Code.
  * **Named agents** — a name given at creation is kept.
  * **Terminals** — heavy output is faster and more reliable.
  * Provider lists load reliably when the CLI and Host are on different versions.
</Update>

<Update label="v1.1.2">
  * **Model picker** — Traycer models being retired now carry a notice.
</Update>

<Update label="v1.1.1">
  * **Background work** — chats stay visibly active while background work continues after the main reply finishes.
</Update>

<Update label="v1.1.0">
  Eight new coding agents, and providers that no longer hold up a fresh install.

  * **Eight new coding agents** — Grok (xAI), Qwen, Kiro, Kilo Code, Copilot, Kimi, Droid, and OpenRouter.
  * **Faster first launch** — providers appear as they finish loading, so a new install no longer waits for all of them.
  * **Background Claude subagents** — progress keeps updating after the main reply ends.
  * **Diagnostics** — Host logs can be filtered by how much detail you want.
  * **Sign-in** — long-running connections accept a refreshed sign-in without reconnecting.
</Update>

<Update label="v1.0.0">
  First public release of the Traycer Host — the local runtime that powers Traycer. It runs the coding agents, terminals, and Tasks behind Traycer Desktop, entirely on your machine. You do not install the Host directly; the Traycer CLI downloads, verifies, and supervises it for you.

  * **Runs agents locally** — executes your chosen coding agents directly on the repositories you are working in.
  * **Local storage** — stores Tasks, conversations, plans, and history in a local SQLite database.
  * **Terminals, files, and worktrees** — manages terminals, files, and git worktrees, and exposes a versioned protocol that Traycer Desktop connects to.
  * **Managed service** — registers with your OS service manager (launchd on macOS, systemd user on Linux), starting with your session and supervised automatically.
  * **Agent backends** — Claude (Claude Code), OpenAI Codex (with reasoning depth and optional Fast tier), Cursor, OpenCode, and Traycer Inference, selectable per Task.
  * **Skills** — ships Traycer's versioned, integrity-checked workflows for brief, plan, breakdown, execution, and review.
  * **Privacy** — does not log secrets or source code.
  * **Platforms** — macOS (Apple Silicon and Intel) and Linux (x64), delivered as a signed single-file runtime with no separate Node or Bun install. Builds are verified by SHA-256 checksum and minisign signature before installation.
</Update>


# Traycer
Source: https://docs.traycer.ai/index

Plan, preserve, and inspect AI coding work across Tasks, artifacts, agents, files, and git diff.

Traycer is a workspace for working with coding agents without losing intent, context, or visibility.

You organize work into **Tasks**. Inside a Task, you create **agents** and work with them through a **Chat** or **Terminal** interface, alongside files, git diff, and durable **artifacts** like specs, tickets, stories, and reviews.

<Card title="Install Traycer" icon="download" href="/install">
  Download the desktop app, then continue to the Quickstart.
</Card>

## The Traycer Mental Model

<Columns>
  <Card title="Tasks" icon="folder-open" href="/concepts/tasks-and-workspace-folders">
    A Task is the top-level container for related agents, panels, terminals, and
    artifacts.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Select a workspace folder, create your first Task, and run your first agent.
  </Card>

  <Card title="Agents" icon="messages-square" href="/panels/agents">
    Create agents on the Chat or Terminal interface, with composer controls,
    permissions, and child agents.
  </Card>

  <Card title="Panels" icon="panel-left" href="/panels">
    Understand the sidebar panels for agents, artifacts, terminals, files, git
    diff, sharing, and comments.
  </Card>

  <Card title="Artifacts" icon="file-text" href="/panels/artifacts">
    Specs, tickets, stories, and reviews preserve decisions, work items, and
    review context.
  </Card>

  <Card title="History" icon="history" href="/concepts/history">
    Find, filter, reopen, rename, and clean up previous Tasks.
  </Card>

  <Card title="Worktrees" icon="git-branch" href="/concepts/worktrees">
    Choose whether agent work runs in a workspace folder, a new worktree, or an
    existing worktree.
  </Card>

  <Card title="Agents & Models" icon="bot" href="/agents-and-models/coding-agents">
    Set up Codex, Claude Code, OpenCode, Cursor, and Traycer.
  </Card>
</Columns>

## Find What You Need

<CardGroup>
  <Card title="Concepts" icon="book-open" href="/concepts/tasks-and-workspace-folders">
    Learn the vocabulary: Tasks, History, Worktrees, panels, and artifacts.
  </Card>

  <Card title="Agents" icon="terminal" href="/panels/agents">
    Understand the Chat and Terminal interfaces, permissions, child agents, and
    delegated handoff.
  </Card>

  <Card title="Account" icon="credit-card" href="/account/pricing">
    Understand pricing, storage, sync, credits, and teams.
  </Card>

  <Card title="IDE Extension" icon="archive" href="/extension">
    Extension docs are preserved separately for current extension users.
  </Card>
</CardGroup>


# Install
Source: https://docs.traycer.ai/install

Get Traycer Desktop running on your machine.

Download the Traycer Desktop app for your operating system. Links always point to the latest release.

| Platform                  | Download                                                                                                                  | Notes                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| **macOS** (Apple Silicon) | [Download .dmg](https://github.com/traycerai/traycer/releases/latest/download/traycer-desktop-macos-arm64.dmg)            | For M-series Macs (M1/M2/M3/M4).                 |
| **macOS** (Intel)         | [Download .dmg](https://github.com/traycerai/traycer/releases/latest/download/traycer-desktop-macos-x64.dmg)              | For Intel-based Macs.                            |
| **Linux** (AppImage)      | [Download .AppImage](https://github.com/traycerai/traycer/releases/latest/download/traycer-desktop-linux-x86_64.AppImage) | Portable; `chmod +x` then run.                   |
| **Linux** (Debian/Ubuntu) | [Download .deb](https://github.com/traycerai/traycer/releases/latest/download/traycer-desktop-linux-amd64.deb)            | `sudo dpkg -i` the package.                      |
| **Linux** (Fedora/RHEL)   | [Download .rpm](https://github.com/traycerai/traycer/releases/latest/download/traycer-desktop-linux-x86_64.rpm)           | `sudo rpm -i` the package.                       |
| **Windows** (x64)         | [Download .exe](https://github.com/traycerai/traycer/releases/latest/download/traycer-desktop-windows-x64.exe)            | Native installer for 64-bit Windows.             |
| **Windows** (via WSL)     | [Install via WSL](#windows-via-wsl)                                                                                       | Run the Linux desktop app through WSL with WSLg. |

All releases are published on [GitHub](https://github.com/traycerai/traycer/releases).

## Windows via WSL

If your Windows setup supports Linux GUI apps with WSLg, you can alternatively run the Linux desktop app through WSL.

Before installing Traycer in WSL:

* Update WSL with `wsl --update`, then restart your Ubuntu distribution.
* Use WSL 2 on a recent Windows build with WSLg enabled.
* Set a non-Snap browser as the default browser inside WSL. Snap-installed browsers can block the sign-in redirect back to Traycer. Google Chrome installed from a `.deb` package works.

Then install the package that matches your WSL distribution:

**Debian / Ubuntu (`.deb`)**

```bash theme={null}
wget https://github.com/traycerai/traycer/releases/latest/download/traycer-desktop-linux-amd64.deb
sudo apt install ./traycer-desktop-linux-amd64.deb
```

**Fedora / RHEL (`.rpm`)**

```bash theme={null}
wget https://github.com/traycerai/traycer/releases/latest/download/traycer-desktop-linux-x86_64.rpm
sudo dnf install ./traycer-desktop-linux-x86_64.rpm
```

**Other distros (portable `.AppImage`)**

```bash theme={null}
wget https://github.com/traycerai/traycer/releases/latest/download/traycer-desktop-linux-x86_64.AppImage
chmod +x traycer-desktop-linux-x86_64.AppImage
./traycer-desktop-linux-x86_64.AppImage
```

Launch Traycer from WSL (`.deb` / `.rpm` installs):

```bash theme={null}
/opt/Traycer/traycer-desktop
```

You may also see Traycer in the Windows Start menu if WSLg has registered the desktop app.

## macOS via Homebrew

On macOS you can also install the desktop app with [Homebrew](https://brew.sh):

```bash theme={null}
brew install --cask traycerai/traycer/traycer-desktop
```

After installing the desktop app, open Traycer and choose the workspace folder you want to work in.

## CLI

The desktop app bundles the command-line pieces it needs, so most users do not have to install the CLI separately.

To use the CLI on its own — for host control, automation, or CI — install it with npm (requires Node.js 20.18+):

```bash theme={null}
npm install -g @traycerai/cli
```

Or with [Homebrew](https://brew.sh) on macOS and Linux:

```bash theme={null}
brew install traycerai/traycer/traycer
```

Both install the `traycer` command. Verify with `traycer --version`. See the full [command reference](/cli/commands).

## After Install

<Steps>
  <Step title="Open Traycer">
    Launch the desktop app.
  </Step>

  <Step title="Choose a workspace folder">
    Pick the repository or folder Traycer should work with.
  </Step>

  <Step title="Set up a coding agent">
    Configure Codex, Claude Code, OpenCode, Cursor, or Traycer in [Agents & Models](/agents-and-models/coding-agents).
  </Step>

  <Step title="Run the Quickstart">
    Continue with the [Quickstart](/quickstart) to create your first Task and start an agent.
  </Step>
</Steps>


# Agents
Source: https://docs.traycer.ai/panels/agents

Create, organize, and work with agents in a Task using the Chat or Terminal interface. Formerly the Chats panel.

An **agent** is a durable coding-agent session inside a Task. The **Agents** panel is where agents are listed and organized.

You interact with an agent through one of two **interfaces**: **Chat** or **Terminal**. The interface changes how you work with the agent and how much can change after it starts. It does not change what the agent is — both are agents, both live in the Agents panel, and both can be referenced, organized, and nested the same way.

| Interface    | What it looks like                          | What can change after start                                                                                                                                                                             |
| ------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chat**     | In-app conversation with composer controls. | Model, permissions, thinking effort, fast mode, attachments, and voice can change turn by turn.                                                                                                         |
| **Terminal** | Terminal-style coding-agent session.        | Workspace folder or worktree, coding agent, model, thinking effort, and CLI arguments are chosen at launch and stay fixed. Traycer can resume the underlying coding-agent session on its original Host. |

A plain **Terminal** is a different thing entirely: it is a shell session and lives under [Terminals](/panels/terminals). The full distinction is covered in [Terminal Agents VS Terminals](/concepts/terminal-agents-vs-terminals).

<Info>
  The Agents panel was previously called **Chats**. Existing agents, links, and
  history are unchanged — only the naming moved to match the model: the agent is
  the durable thing, and Chat and Terminal are interfaces on it.
</Info>

## What Agents Keep

Every agent keeps:

* conversation history or terminal transcript
* the selected coding agent and model for each run
* permission and thinking-effort choices
* artifacts, file changes, tool calls, and follow-up context it produced

Agents on the Chat interface also use the composer controls for attachments, voice input, per-turn permission changes, and model changes.

Agents are separate sessions. Changing settings on one agent does not rewrite another.

## Composer

The composer is the prompt area for an agent on the Chat interface.

| Control                  | What it changes                                               |
| ------------------------ | ------------------------------------------------------------- |
| **Coding agent / model** | Pick the coding agent and model used for the next turn.       |
| **Permissions**          | Decide what the agent can do before asking.                   |
| **Thinking effort**      | Choose reasoning depth when the selected model supports it.   |
| **Fast mode**            | Use a faster service tier when the selected model offers one. |
| **Attachments**          | Add files, images, or context to the prompt.                  |
| **Voice**                | Dictate a prompt instead of typing.                           |
| **Send / Stop**          | Start the next turn or stop the active one.                   |

Model, permission, thinking effort, and fast-mode changes apply to the next agent turn. They do not rewrite a turn that already started.

## The Terminal Interface

An agent on the Terminal interface starts with a fixed launch setup:

* workspace folder or worktree
* coding agent
* model, when supported
* thinking effort, when supported
* Terminal interface CLI arguments, when supplied

After it starts, those launch choices stay with that agent. Traycer stores the upstream coding-agent session id so the agent can resume the same underlying session on its original Host. Start a new agent when you need a different workspace folder, worktree, coding agent, model, thinking effort, or launch argument set.

Worktree choices are covered in [Worktrees](/concepts/worktrees).

Agents on the Terminal interface also receive Traycer's agent context: artifact guidance, skills, and agent-to-agent instructions. Reading one's transcript and *sending* it a message are narrower than referencing it, and both carry user and Host requirements — see [Agent-to-Agent](/concepts/agent-to-agent) for the capability matrix.

Not every coding agent can back the Terminal interface. The supported set is listed in [Agents & Models](/agents-and-models/coding-agents).

## Permissions

Permissions control how much the agent can do without another approval.

| Permission            | Meaning                                       |
| --------------------- | --------------------------------------------- |
| **Supervised**        | Ask before commands and file changes.         |
| **Auto-accept edits** | Auto-approve edits, ask before other actions. |
| **Full access**       | Allow commands and edits without prompts.     |

Supervised is the safest starting point. Some coding agents expose fewer permission options; those compatibility details live in [Agents & Models](/agents-and-models/coding-agents).

## Thinking Effort And Fast Mode

**Thinking effort** controls the reasoning level for models that support it. The available levels depend on the selected coding agent and model.

**Fast mode** appears only when the selected model offers a faster service tier. It is a Chat-interface control, not a Terminal launch option.

## Attachments And Voice

Attachments add context to the next turn. Use them when the prompt needs a screenshot, file, or specific supporting material.

Voice input turns speech into prompt text. It is useful for longer instructions, quick notes, or hands-free follow-up while reviewing code.

## Creating An Agent

Use the `+` action in the Agents panel to create an agent, then choose its interface:

* **Chat** for an in-app conversation you steer turn by turn.
* **Terminal** for a terminal-style session with a fixed launch setup.

Traycer asks only for the configuration that interface needs. Until the agent has a generated title, it appears as **Untitled agent**.

The `+` on an agent row creates a **child agent** beneath it, so delegated work stays attached to where it came from.

## Hierarchy

The Agents panel is a tree, not a flat list.

Top-level agents appear at the root of the panel. When an agent starts another agent, the new agent appears beneath the agent that spawned it. This creates a visible lineage:

```text theme={null}
Agent: feature planning                  (Chat)
├─ Agent: investigate failing tests      (Terminal)
│  ├─ Agent: summarize the failure cause (Chat)
│  └─ Agent: rerun the focused test      (Terminal)
├─ Agent: review proposed fix            (Chat)
└─ Agent: update release notes           (Chat)
```

These nested entries are often the sub-agents of the original work. They are separate agents with their own history, but the tree shows which agent created them.

The delegation model is covered in [Agent-to-Agent](/concepts/agent-to-agent).

The hierarchy helps answer:

* which agent started which follow-up
* which agents belong to the same branch of work
* where a delegated agent came from
* what context a child agent is attached to

Agents can also be grouped under artifacts, so an investigation or follow-up can sit beneath the spec, ticket, story, or review it belongs to.

Parent and child relationships are navigation and provenance. They do not restrict which agents you can reference — see [Agent-to-Agent](/concepts/agent-to-agent).

## Parents And Children

In the Agents panel, a parent can be:

* a root Task-level agent
* another agent
* an artifact that the agent is grouped under

A child is always another agent, on either interface.

Manual organization is intentionally narrower than agent-spawned lineage. You can group agents under artifacts, but agents are not general-purpose folders for arbitrary items.

## Controls

The panel supports:

* filtering by interface: **All**, **Chat**, or **Terminal**
* sorting by **Last Updated**, **Date Created**, or **Name**
* creating agents with the `+` action
* renaming and deleting entries from row actions

Filtering narrows the interface view only. It does not change agent identity or the hierarchy, and an empty result means no agent uses that interface — not that the Task has no agents.

When a filter is active, Traycer keeps the relevant parent chain visible so a matching child agent does not appear detached from its context.

## Session State

Each agent keeps its own history and active run state. An agent on the Chat interface is flexible turn by turn. An agent on the Terminal interface is fixed after launch, because it runs through a terminal-style coding-agent session.


# Artifacts
Source: https://docs.traycer.ai/panels/artifacts

Use Artifacts to browse, organize, and update specs, tickets, stories, and reviews.

Artifacts are durable documents or outputs inside a Task. They preserve important context so it does not disappear into an agent transcript.

The **Artifacts** panel shows the Task's artifact tree:

* **Spec**
* **Ticket**
* **Story**
* **Review**

## Artifact Types

| Artifact type | Role                                                                                                     | Status | Assignee |
| ------------- | -------------------------------------------------------------------------------------------------------- | ------ | -------- |
| **Spec**      | Captures goals, requirements, constraints, decisions, and plan context.                                  | No     | No       |
| **Ticket**    | Tracks implementation work, what needs to change, and how to verify it.                                  | Yes    | Yes      |
| **Story**     | Organizes a user journey, workflow slice, or larger outcome that may span multiple implementation steps. | Yes    | Yes      |
| **Review**    | Captures review findings, critique, decisions, and follow-ups.                                           | No     | No       |

Specs and reviews are shared context. Tickets and stories are work-tracking artifacts.

## Hierarchy

Artifacts can be arranged in a parent-child hierarchy. This keeps related work grouped inside the Task.

The common shape is:

```text theme={null}
Task
└─ Spec
   ├─ Ticket
   ├─ Story
   └─ Review
```

Use hierarchy to keep planning context close to implementation and review context. For example, a spec can hold the tickets that implement it, and a review can sit next to the work it evaluates.

Deleting a parent artifact also deletes the artifacts nested underneath it, so check the hierarchy before removing a spec or story with children. Nested agents are not deleted with that artifact subtree; they move up to the parent level.

## Status

Tickets and stories use three status values:

| Status          | Meaning                          |
| --------------- | -------------------------------- |
| **Todo**        | Work exists but has not started. |
| **In Progress** | Work is currently active.        |
| **Done**        | Work is complete.                |

Specs and reviews do not have status because they are not implementation units.

## Assignees

Tickets and stories can have assignees. An assignee marks who is responsible for that piece of work.

Specs and reviews are usually shared context rather than assigned work items.

## Controls

The panel supports:

* filtering by artifact type
* filtering by read state
* filtering tickets and stories by status
* sorting by **Last Updated**, **Date Created**, or **Name**
* creating specs, tickets, and stories from the panel
* renaming, deleting, and moving artifacts

## Working With Artifacts

| Action            | What happens                                                                                  |
| ----------------- | --------------------------------------------------------------------------------------------- |
| **Create**        | Adds a new spec, ticket, story, or review to the Task. New tickets and stories start as Todo. |
| **Rename**        | Changes the artifact title shown in the sidebar, tab, and artifact references.                |
| **Move**          | Drag an artifact in the sidebar to change its parent.                                         |
| **Change status** | Updates a ticket or story between Todo, In Progress, and Done.                                |
| **Delete**        | Deletes the selected artifact and its nested artifact children.                               |
| **Comment**       | Adds a thread to selected text inside an artifact.                                            |

## Comments

Artifacts support anchored comment threads. Select text in an artifact, add a comment, reply in the thread, and resolve it when the discussion is complete.

Comments are useful for review findings, unresolved decisions, and collaboration notes that should stay attached to the exact text they refer to.

## Storage

Artifacts are stored as markdown documents on disk and synchronized through Traycer's live document layer when sync is active. The markdown file keeps the artifact type, title, and status metadata with the body content.

## How Artifacts Are Created

Artifacts are created explicitly, whenever something should outlive the conversation or be put in front of you.

Specs, tickets, stories, and reviews are all first-class: they capture intent the code cannot express and drive planning, implementation, and review.


# Comments
Source: https://docs.traycer.ai/panels/comments

Use Comments to work with artifact comment threads.

The **Comments** panel shows comment threads for the active artifact.

It is contextual: if there is no active artifact with comments available, the panel does not need to take space.

## Comment Threads

Comments are anchored to artifact text. Use them for questions, review notes, decisions, and follow-ups that belong to a specific artifact.

Typical flow:

1. Select text in an artifact.
2. Add a comment.
3. Continue the thread.
4. Resolve the thread when the discussion is done.

## Where Comments Appear

Comments are part of artifact collaboration. They belong with specs, tickets, stories, and reviews rather than with plain terminals or file browsing.


# File Tree
Source: https://docs.traycer.ai/panels/file-tree

Use File Tree to browse workspace files.

The **File Tree** panel lets you browse a workspace folder.

Use it to inspect files, open files in an external editor, or copy file paths.

## Workspace Picker

The panel uses a workspace picker to choose which folder the tree shows. Workspace selection affects which file paths are available from the panel.

## File Information

The File Tree can expose:

* path and file context
* file and folder hierarchy
* selected workspace context
* unavailable states when the host cannot load the file tree

## Open In Editor

The panel can open files in an external editor when Traycer can detect or use one. It can also copy file paths for manual use.


# Git Diff
Source: https://docs.traycer.ai/panels/git-diff

Use Git Diff to inspect changed files in a worktree.

The **Git Diff** panel shows changed files for the selected worktree.

Use it to inspect what changed before asking an agent to continue, before creating a review artifact, or before switching context.

For how agents choose worktrees, see [Worktrees](/concepts/worktrees).

## Controls

The panel includes:

* a worktree picker
* a refresh action
* changed-file search
* changed-file rows with file path and change summary

Changed files can be grouped and searched.

## States

The panel shows explicit states for common cases:

* no git worktrees
* no changes in the selected worktree
* loading changed files
* subscription or git-listing errors
* repository warnings such as conflicts or detached HEAD
* binary files that cannot be previewed as text


# Panels
Source: https://docs.traycer.ai/panels/index

Understand the sidebar panels inside a Task.

Panels are the sidebar navigators inside a Task. They help you find and organize agents, artifacts, terminals, files, git changes, sharing, and comments.

You can use panels one at a time, stack them together, or rearrange them around the sidebar as the Task changes.

## Sidebar Panels

| Panel                          | What it shows                                               |
| ------------------------------ | ----------------------------------------------------------- |
| [Agents](/panels/agents)       | Every agent in the Task, on the Chat or Terminal interface. |
| [Terminals](/panels/terminals) | Plain shell sessions.                                       |
| [Artifacts](/panels/artifacts) | Specs, tickets, stories, and reviews.                       |
| [Git Diff](/panels/git-diff)   | Changed files for a selected worktree.                      |
| [File Tree](/panels/file-tree) | Project files and folders.                                  |
| [Sharing](/panels/sharing)     | People and teams with access to the Task.                   |
| [Comments](/panels/comments)   | Comment threads for the active artifact.                    |

Each panel has a header. Headers can collapse or expand the panel, and panels with creation actions show a `+` control.

## Rearranging Panels

Panels can be reorganized from the sidebar.

You can drag a panel to:

* move it above another panel
* move it below another panel
* combine it with another panel group

Combining panels keeps both panels visible in the same sidebar area. This is useful when two views belong together for the work you are doing, such as keeping **Agents** near **Artifacts**, or **Git Diff** near **File Tree**.

When multiple panels are combined, resize handles let you adjust how much vertical space each panel gets.

## Drag And Drop Inside Panels

Some panels also support drag and drop for the items they contain.

Common uses include:

* moving artifacts in the artifact hierarchy
* grouping agents under artifacts
* keeping related follow-up work near the spec, ticket, story, or review it belongs to

Drag and drop changes organization. It does not turn an agent into an artifact, or an agent into a plain terminal.


# Sharing
Source: https://docs.traycer.ai/panels/sharing

Use Sharing to review collaboration access for a Task.

The **Sharing** panel shows collaboration access for a Task.

Use it to understand who can access the Task and how collaboration is scoped.

## What It Covers

The panel belongs to Task-level collaboration. Organization and team behavior is covered in [Organizations and Teams](/account/organizations).

Organization roles and sharing behavior are covered in [Organizations](/account/organizations).

## Shared Task Context

Shared Tasks can include agents, artifacts, files, diffs, and comments. Access determines who can view or collaborate on that Task context.


# Terminals
Source: https://docs.traycer.ai/panels/terminals

Use Terminals for plain shell sessions.

The **Terminals** panel is for plain terminal sessions. These are shells you run yourself, not coding agents.

Terminal Agents do not live here. They live in [Agents](/panels/agents). For the full distinction, see [Terminal Agents VS Terminals](/concepts/terminal-agents-vs-terminals).

## Controls

Use the panel to:

* create a terminal in a selected workspace folder
* find an existing terminal session
* rename a terminal
* stop or delete a terminal session after it exits

Traycer derives a terminal name from its custom title, current folder, shell command, or terminal id.

Use terminal sessions for package scripts, tests, logs, local debugging, and one-off commands.

Plain terminals do not receive Traycer's agent prompt, skills, artifact instructions, or agent-to-agent communication tools.

Cross-host terminal behavior is covered in [Hosts](/concepts/hosts).


# Provider pack store support boundary
Source: https://docs.traycer.ai/provider-pack-store-support-boundary



# Provider pack store: same-machine-only support boundary

**The boundary.** `~/.traycer`'s provider pack store may be shared by any number
of Traycer host processes **on one machine**. It is not supported on storage
shared **across machines** — NFS, SMB, a roaming home directory, or a container
volume mounted into more than one node.

This is a support statement, not a warning about performance. Sharing the store
across machines breaks a correctness precondition, and it fails in a shape that
misdirects whoever investigates.

## Why

Concurrent downloads of the same pack are serialized by a cross-process lease
(`traycer-host/src/domain/providers/provider-pack-lease.ts`). A peer that finds
an existing lease decides whether to wait or to take it over by asking **this
kernel** whether the recorded pid is still running, and whether its
process-start identity still matches.

That question only means something for a process on the same machine. Across a
shared mount, a pid belonging to a live host on machine A either does not exist
on machine B, or exists as an entirely unrelated process. Either answer can read
as *the owner is dead*.

```mermaid theme={null}
sequenceDiagram
    participant A as Host on machine A
    participant S as Shared store (NFS)
    participant B as Host on machine B
    A->>S: acquire lease {pid: 4211}
    A->>S: append bytes to dl-<digest>.partial
    B->>S: read lease {pid: 4211}
    B->>B: is pid 4211 alive here?
    Note over B: No such process — on THIS kernel
    B->>S: adopt lease, append to the SAME partial
    Note over S: Two appenders, one file
    S-->>B: bytes match no digest
    Note over B: reported as `verification`
```

## The symptom you will actually see first

`verification` is the alarming one, and it is not the likely one. The lease
election notices a stalled owner long before two appenders finish corrupting a
partial, so the **first** verdict this misconfiguration produces is usually
`live-owner-stalled`:

> another Traycer process using this Traycer folder stopped making progress on
> the download. Try again to pick it up here.

That sentence is true, and its "using this Traycer folder" is doing careful
work: the lease record carries **no machine identity**, so the host genuinely
cannot say the sibling is local. On a single-machine deployment the two read the
same; in the one topology this document exists to describe, "on this device" —
which is what the copy used to say — is false, and it points the reader at the
wrong machine.

So the escalation order is: repeated `live-owner-stalled` on a store you did not
know was shared → adopt-and-append → `verification`. If a support thread opens
on `verification`, ask whether it was preceded by stalls.

## Reading the evidence on disk

Everything needed to confirm or rule this out is in the partial's sidecar,
`<store>/.tmp/dl-<digest>.lease`:

| Field            | What it tells you                                                    |
| ---------------- | -------------------------------------------------------------------- |
| `pid`            | The owner's process id **on the owner's machine**                    |
| `processStartId` | Boot-relative start identity, used to reject a recycled pid          |
| `heartbeatAt`    | Last progress stamp; older than 90s is what makes an owner adoptable |

**The tell:** a `pid` that does not exist on the machine reading the lease, in a
store whose `heartbeatAt` keeps advancing. A dead owner's heartbeat stops. An
owner that is alive on another node keeps stamping while this kernel insists the
pid is gone — and that combination cannot happen on a single machine.

Confirm the mount before anything else: `df ~/.traycer` (a network filesystem
type, or a device that is not local), or on Linux
`findmnt -T ~/.traycer -o TARGET,SOURCE,FSTYPE`.

## Getting a stuck host moving again

1. **Stop every host sharing the store.** Not just the one reporting the error —
   the whole point is that the other one is invisible to it.
2. **Delete the partials, not the store.** `rm ~/.traycer/…/.tmp/dl-*`. Both the
   in-flight bytes (`dl-<digest>.<host-instance>`) and the sidecar
   (`dl-<digest>.lease`) live under `.tmp`, so one glob covers them. Verified
   blobs are content-addressed and safe to keep; only the in-flight bytes are
   suspect.
3. **Move the store off the shared mount** before restarting, or point each
   machine at its own `~/.traycer`. Restarting without this reproduces the
   failure on the next convergence.
4. A `verification` verdict raised by this cause needs **no registry
   investigation**. That is the whole reason this page exists — confirm the
   mount first, and only escalate to supply chain if the store is local.

## The store also stops reclaiming disk

Every reclaimer in the store — stranded download partials, and the
content-addressed archives under `blobs/` — runs only inside the
sole-participant barrier, at boot. That barrier is what makes deleting bytes
another process may be reading safe, and on a shared store it never reports
`sole`: the second host is always there, so the barrier returns
`other-live-participant` and both hosts skip.

So a shared store is not merely at risk of corrupt downloads. It **never frees
anything**, and it accumulates one multi-gigabyte archive per pack per pin bump,
on every machine's view of the same directory, indefinitely. A store on a shared
mount that has been in use for a while is usually diagnosable by size alone.

A store that is local and still growing is a different problem — look for
`provider pack blob reclamation skipped` in the host log, which names the
retention root that could not be read.

## Why it matters more than a failed download

Two appenders on one partial produce bytes that hash to nothing, and the install
path classifies a digest mismatch as `verification` — a *definitively-invalid*
verdict whose entire meaning is "the published artifact does not match its
signature".

So a deployment misconfiguration reaches the operator wearing the shape of a
**supply-chain tampering alarm**. That is the most expensive possible way to be
wrong about it: the honest response to a `verification` verdict is to stop and
investigate the registry, and none of that investigation will find anything,
because nothing is wrong with the artifact.

## What is not enforced, and why

Nothing checks this at runtime. Liveness across a machine boundary is exactly
the fact the mechanism cannot establish, so a guard would need the evidence it
is missing. The boundary is documented instead.

## Upgrade path, if the boundary is ever lifted

Record a stable machine identity in the lease record alongside the pid, and have
the liveness probe fail to **indeterminate** — never to "dead" — when the
record's machine is not this one.

`indeterminate` already has a defined meaning throughout the lease module
(`holdElection` reports it rather than inventing progress), and it carries the
right bias: an unproven owner keeps its lease, so the worst case becomes a
download that waits rather than two that corrupt each other.

Deliberately not built today. Every supported deployment is single-machine, so
the machinery would sit unused, and an unused enforcement path is one nobody
notices breaking.


# Quickstart
Source: https://docs.traycer.ai/quickstart

Select a workspace folder, create your first Task, and run your first agent.

This guide gets you from a fresh Traycer install to one useful coding-agent interaction. If you have not installed Traycer yet, start with [Install](/install).

<Note>
  This is the Desktop path. If you are using the IDE extension, use the [IDE
  Extension docs](/extension).
</Note>

## Before You Start

You need:

* Traycer installed.
* A local code folder you want Traycer to work with.
* At least one coding agent path available.

## First Run

<Steps>
  <Step title="Open Traycer Desktop">
    Launch Traycer and choose the workspace folder for the repository or project
    you want to work on.
  </Step>

  <Step title="Create a Task">
    A Task is the container for this piece of work. It can hold agents,
    terminals, files, git diff, and artifacts.
  </Step>

  <Step title="Start your first agent">
    Pick a coding agent and model, then describe what you want. Traycer keeps
    the work connected to the Task, workspace, files, and artifacts.
  </Step>

  <Step title="Describe the change">
    Ask for a small, concrete change or investigation. Keep the first run narrow
    so you can inspect the result easily.
  </Step>

  <Step title="Review the result">
    Use the File Tree and Git Diff panels inside the Task to inspect what
    changed.
  </Step>
</Steps>

## What You Just Used

| Thing                | What it means                                           |
| -------------------- | ------------------------------------------------------- |
| **Workspace folder** | The local code folder Traycer is working against.       |
| **Task**             | The top-level container for this work.                  |
| **Artifact**         | A durable spec, ticket, story, or review inside a Task. |

## Next Steps

<Columns>
  <Card title="Learn the Concepts" href="/concepts/tasks-and-workspace-folders">
    Understand Tasks, panels, and artifacts.
  </Card>

  <Card title="Work with agents" href="/panels/agents">
    Understand the Chat and Terminal interfaces, permissions, model selection,
    attachments, voice input, and per-turn settings.
  </Card>

  <Card title="Set up Agents & Models" href="/agents-and-models/coding-agents">
    Configure Codex, Claude Code, OpenCode, Cursor, or Traycer.
  </Card>

  <Card title="Review changes" href="/panels/artifacts">
    Use git diff and review artifacts to inspect work before shipping.
  </Card>
</Columns>


# Troubleshooting
Source: https://docs.traycer.ai/reference/troubleshooting

Common Traycer Desktop issues and what they mean.

Use this page to recognize common unavailable states in Traycer Desktop.

## Host Status

For the Host mental model, see [Hosts](/concepts/hosts). For Host controls, see [Settings > Host](/settings/host).

| State                        | Meaning                                                |
| ---------------------------- | ------------------------------------------------------ |
| **Running**                  | The host is running and reachable.                     |
| **Stopped**                  | The host is installed, but the process is not running. |
| **Not installed**            | The host is not installed for this channel.            |
| **Registry unreachable**     | Traycer could not reach the host registry.             |
| **Update check unavailable** | Traycer could not check for host updates.              |

If Desktop shows **Starting local host…** for too long, use the retry action or open [Settings > Host](/settings/host).

## Report An Issue

Use **Report Issue** when you want to send a bug report with desktop and host details attached.

To open it:

1. Open the desktop **Help** menu.
2. Select **Report Issue**.
3. Fill in the title, what happened, steps to reproduce, expected behavior, and actual behavior.
4. Select **Submit Report**. Traycer uploads the report privately and opens a pre-filled GitHub issue.

You can also open **Report Issue** from the command palette. If an app-update error appears, its toast can include a **Report Issue** button that opens the same dialog.

## Open Logs

Use logs when an issue involves startup, host status, updates, provider setup, terminal sessions, or other desktop/host behavior.

To open logs from the app:

1. Open the desktop **Help** menu.
2. Select **Open Logs**.
3. In the **Open Logs** dialog, expand a log entry to preview recent output.
4. Select **Reveal** to open the selected log file in your file manager.

You can also open logs from the Traycer tray menu with **Open Logs**. The tray path opens **Settings → Host** and the logs dialog.

From a terminal, use:

```bash theme={null}
traycer host logs --tail 200
```

Use `traycer host logs --follow` to stream new host log lines.

## Provider Auth

Provider setup states can include:

| State                          | Meaning                                            |
| ------------------------------ | -------------------------------------------------- |
| **Checking account**           | Traycer is checking provider/account availability. |
| **Not authenticated**          | The provider needs login, API key, or CLI auth.    |
| **API key set**                | A required key is configured.                      |
| **Account status unavailable** | Traycer could not confirm provider status.         |

For Cursor, add the Cursor API key in **Settings → Providers** or export `CURSOR_API_KEY` in the environment used by the host.

## Terminal and Host-Bound Tabs

For why tabs bind to a Host, see [Hosts](/concepts/hosts).

| Message                                                                                                                       | Meaning                                                                                                                                                           |
| ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Host "{label}" is unreachable. This terminal is permanently closed.`                                                         | A raw terminal PTY is gone and cannot move to another Host. Close the tab and start a new terminal session.                                                       |
| `Host "{label}" is unreachable, so this agent is unavailable until that host is back.`                                        | An Agent on the Terminal interface remains bound to its owning Host. The Agent and its transcript are preserved; closing the tab only removes it from the canvas. |
| `Bound host "{label}" is offline. Continuing here creates a new agent on the active host; this one stays bound to "{label}".` | An Agent on the Chat interface can continue by cloning onto the Current Host. The clone is a new Agent; the original stays bound to its Host.                     |
| `This file is on host "{label}", which is currently unreachable.`                                                             | A file preview cannot load until the host comes back.                                                                                                             |
| `This file is on host "{label}". Switch your active host to "{label}" to view it.`                                            | The file is reachable, but not through the Current Host.                                                                                                          |
| `This diff is on host "{label}", which is currently unreachable.`                                                             | A diff cannot load until the host comes back.                                                                                                                     |

The important distinction: an Agent on the Chat interface can clone to another Host; raw terminals and Agents on the Terminal interface cannot migrate. Cloning never moves the original Agent—it creates a second one.

## Worktree Setup

Agent worktree setup can show states such as:

| State                         | Meaning                                          |
| ----------------------------- | ------------------------------------------------ |
| **Creating worktree**         | Traycer is creating the worktree for the run.    |
| **Setting up worktree**       | Setup is still running.                          |
| **Worktree ready**            | The worktree is ready.                           |
| **Setup failed**              | Setup failed before the first message could run. |
| **Setup cancelled**           | Setup was cancelled.                             |
| **Worktree setup incomplete** | The run cannot continue until setup is resolved. |

If a workspace folder no longer exists or became unreachable, choose an available workspace folder and retry the run.

## Model Picker

| State                                | Meaning                                              |
| ------------------------------------ | ---------------------------------------------------- |
| **Loading models**                   | Traycer is loading available model options.          |
| **Couldn't load providers**          | Provider list failed to load.                        |
| **Couldn't load models**             | Model list failed to load for the selected provider. |
| **No models available**              | The selected provider returned no usable models.     |
| **No models match**                  | Search/filtering removed all model choices.          |
| **Connect Cursor** / **Add API key** | Cursor needs a configured API key before use.        |

If a provider is missing from the picker, it may be unavailable, not installed, or not configured.


# Agent selection
Source: https://docs.traycer.ai/settings/agents

Configure the global instructions Traycer uses to pick a coding agent, model, and reasoning effort for delegated work.

**Agent selection** settings store the global instructions Traycer uses when an agent spawns or configures a child agent.

This page configures *how a coding agent gets chosen*. It does not manage the agents inside a Task - those live in the [Agents](/panels/agents) panel. For the coordination model, see [Agent-to-Agent](/concepts/agent-to-agent).

## Agent-Selection Instructions

The global agent-selection guide helps Traycer decide:

* which coding agent to use for delegated work
* which model and thinking effort to prefer
* how to route implementation, review, and exploration work

## Global And Workspace-Specific Guides

The global guide is stored on the Current Host and applies by default.

For a specific repo, add a workspace-level guide at:

```text theme={null}
<workspace>/.traycer/agent-selection-guide.md
```

Workspace-level instructions refine or override the global guide for that workspace. Use them when one repo needs different agent choices, models, review expectations, or implementation preferences.

For how child agents appear in the Agents tree, see [Agents](/panels/agents). For supported coding agents, see [Agents & Models](/agents-and-models/coding-agents).


# Appearance
Source: https://docs.traycer.ai/settings/appearance

Configure Traycer Desktop theme and visual preferences.

Appearance settings change how Traycer Desktop looks locally.

## Options

| Setting                  | What it changes                                                |
| ------------------------ | -------------------------------------------------------------- |
| **Theme**                | Uses system, light, or dark appearance.                        |
| **Preset**               | Applies a visual preset.                                       |
| **Terminal preview**     | Controls terminal preview behavior.                            |
| **Use pointer cursors**  | Changes whether interactive controls use pointer cursors.      |
| **Artifact icon colors** | Shows artifact icons by type color, or disables type coloring. |
| **UI font size**         | Changes app UI text size.                                      |
| **Code font size**       | Changes code and editor text size.                             |

Appearance preferences are local UI preferences. They do not change Task content or shared artifacts.


# General
Source: https://docs.traycer.ai/settings/general

Configure general Traycer Desktop behavior.

General settings cover app-level behavior that is not specific to a provider, terminal, or worktree.

## Options

| Setting                             | What it changes                                           |
| ----------------------------------- | --------------------------------------------------------- |
| **Notify on agent turn completion** | Sends a notification when an agent turn finishes.         |
| **Prevent sleep while running**     | Keeps the machine awake while Traycer work is active.     |
| **Voice settings**                  | Controls voice input behavior used by agent prompts.      |
| **Local snapshots**                 | Manages local snapshot data.                              |
| **Clear local snapshots**           | Removes stored local snapshots.                           |
| **Data migration**                  | Retries the local-to-cloud data migration when available. |

Use General for broad app behavior. Provider setup, shell configuration, and host management each have their own settings pages.


# Host
Source: https://docs.traycer.ai/settings/host

Manage the Traycer host used by this Desktop app.

Host settings show the state of the selected Traycer host and the controls used to manage it.

## Status And Versions

| Area                   | What it shows                                           |
| ---------------------- | ------------------------------------------------------- |
| **Status**             | Whether the host is running, stopped, or not installed. |
| **Installed version**  | The host version currently installed.                   |
| **Available versions** | Versions available for install or upgrade.              |
| **Install path**       | Where the host is installed.                            |

## Actions

| Action        | What it does                                                   |
| ------------- | -------------------------------------------------------------- |
| **Install**   | Installs the host when it is missing.                          |
| **Restart**   | Restarts the host.                                             |
| **Update**    | Upgrades the host when an update is available.                 |
| **Check now** | Checks for available host updates.                             |
| **Doctor**    | Runs host diagnostics and shows repair actions when available. |

For log access and issue-reporting steps, see [Troubleshooting](/reference/troubleshooting).

Host environment variables live in [Shell](/settings/shell), not in Host settings.


# Keybindings
Source: https://docs.traycer.ai/settings/keybindings

Default Traycer Desktop keyboard shortcuts and how to customize them.

Keybindings are local keyboard shortcuts. They are a local UI preference, not shared Task content.

## Customize Shortcuts

Every shortcut below can be changed. Open **Settings → Keybindings**, then:

<Steps>
  <Step title="Find the command">
    Locate the action you want to change in the list.
  </Step>

  <Step title="Capture a new shortcut">
    Click **Capture shortcut**, then press the key combination you want to assign.
  </Step>

  <Step title="Clear or reset (optional)">
    Click **Clear** to unbind an action, or **Reset all to defaults** to restore every shortcut at once.
  </Step>
</Steps>

<Note>
  **Sub-leader configuration** sets the secondary modifier (default <kbd>Opt</kbd> / <kbd>Alt</kbd>) used by the number shortcuts in the tables below.
</Note>

## Default Shortcuts

Number shortcuts are leader chords: hold the modifier and press a digit.

### Tasks

Each tab in the header strip is a Task.

| Command               | macOS                                             | Windows                                            | What it does                                                    |
| --------------------- | ------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------- |
| New Task              | <kbd>Cmd</kbd> + <kbd>N</kbd>                     | <kbd>Ctrl</kbd> + <kbd>N</kbd>                     | Open the landing page to start a new Task.                      |
| Duplicate Task tab    | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>K</kbd>  | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>K</kbd>  | Duplicate the active Task tab and its tiling layout.            |
| Next Task tab         | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>]</kbd>  | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>]</kbd>  | Activate the next Task tab in the header strip.                 |
| Previous Task tab     | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>\[</kbd> | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>\[</kbd> | Activate the previous Task tab in the header strip.             |
| Close active tab      | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>W</kbd>  | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>W</kbd>  | Close the active strip tab — Task, draft, history, or settings. |
| Switch Task by number | <kbd>Opt</kbd> + number                           | <kbd>Alt</kbd> + number                            | Hold and type a tab number to jump to that Task tab.            |

### Tabs

Within a Task, panels open as tabs (agents, terminals, artifacts).

| Command                 | macOS                                                             | Windows                                                            | What it does                                                            |
| ----------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| New tab                 | <kbd>Cmd</kbd> + <kbd>T</kbd>                                     | <kbd>Ctrl</kbd> + <kbd>T</kbd>                                     | Open a new blank tab in the active group; the inline opener is focused. |
| Close tab               | <kbd>Cmd</kbd> + <kbd>W</kbd>                                     | <kbd>Ctrl</kbd> + <kbd>W</kbd>                                     | Close the active tab. The last tab in a non-root group collapses it.    |
| Close other tabs        | <kbd>Cmd</kbd> + <kbd>Opt</kbd> + <kbd>W</kbd>                    | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>W</kbd>                    | Close every tab in the focused group except the active one.             |
| Close tabs to the right | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>Opt</kbd> + <kbd>]</kbd> | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Alt</kbd> + <kbd>]</kbd> | Close every tab to the right of the active tab.                         |
| Close all tabs in group | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>Opt</kbd> + <kbd>W</kbd> | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Alt</kbd> + <kbd>W</kbd> | Close every tab in the focused group.                                   |
| Next tab                | <kbd>Cmd</kbd> + <kbd>]</kbd>                                     | <kbd>Ctrl</kbd> + <kbd>]</kbd>                                     | Activate the next tab in the focused group.                             |
| Previous tab            | <kbd>Cmd</kbd> + <kbd>\[</kbd>                                    | <kbd>Ctrl</kbd> + <kbd>\[</kbd>                                    | Activate the previous tab in the focused group.                         |
| Switch tab by number    | <kbd>Cmd</kbd> + number                                           | <kbd>Ctrl</kbd> + number                                           | Hold and press 1–9 to jump to that tab in the active group.             |

### Groups

| Command                  | macOS                                            | Windows                                           | What it does                                                   |
| ------------------------ | ------------------------------------------------ | ------------------------------------------------- | -------------------------------------------------------------- |
| Split group horizontally | <kbd>Cmd</kbd> + <kbd>D</kbd>                    | <kbd>Ctrl</kbd> + <kbd>D</kbd>                    | Split the focused group, placing an empty group on the right.  |
| Split group vertically   | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>D</kbd> | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>D</kbd> | Split the focused group, placing an empty group on the bottom. |
| Split group to the right | <kbd>Cmd</kbd> + <kbd>\\</kbd>                   | <kbd>Ctrl</kbd> + <kbd>\\</kbd>                   | Create an empty new group to the right; it becomes active.     |
| Focus group above        | <kbd>Cmd</kbd> + <kbd>Opt</kbd> + <kbd>↑</kbd>   | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>↑</kbd>   | Move group focus to the nearest group above.                   |
| Focus group below        | <kbd>Cmd</kbd> + <kbd>Opt</kbd> + <kbd>↓</kbd>   | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>↓</kbd>   | Move group focus to the nearest group below.                   |
| Focus group left         | <kbd>Cmd</kbd> + <kbd>Opt</kbd> + <kbd>←</kbd>   | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>←</kbd>   | Move group focus to the nearest group on the left.             |
| Focus group right        | <kbd>Cmd</kbd> + <kbd>Opt</kbd> + <kbd>→</kbd>   | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>→</kbd>   | Move group focus to the nearest group on the right.            |
| Focus active tab editor  | <kbd>Cmd</kbd> + <kbd>L</kbd>                    | <kbd>Ctrl</kbd> + <kbd>L</kbd>                    | Place the cursor in the editor of the active tab.              |

### App

| Command                           | macOS                                                | Windows                                           | What it does                                                                      |
| --------------------------------- | ---------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------- |
| Toggle left panel                 | <kbd>Cmd</kbd> + <kbd>B</kbd>                        | <kbd>Ctrl</kbd> + <kbd>B</kbd>                    | Show or hide the Task left panel; the rail stays visible.                         |
| Open history                      | <kbd>Cmd</kbd> + <kbd>Y</kbd>                        | <kbd>Ctrl</kbd> + <kbd>Y</kbd>                    | Open Task history, or focus the History tab if present.                           |
| Open settings                     | <kbd>Cmd</kbd> + <kbd>,</kbd>                        | <kbd>Ctrl</kbd> + <kbd>,</kbd>                    | Navigate to the settings screen.                                                  |
| Open command palette              | <kbd>Cmd</kbd> + <kbd>K</kbd>                        | <kbd>Ctrl</kbd> + <kbd>K</kbd>                    | Search commands, navigation targets, and recent actions.                          |
| Voice input                       | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>M</kbd> | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>M</kbd> | Dictate into the composer. Tap to toggle, or hold to talk. Transcribed on-device. |
| Switch settings section by number | <kbd>Opt</kbd> + number                              | <kbd>Alt</kbd> + number                           | On the settings screen, hold and press a digit to jump to a section.              |
| Switch model provider by number   | <kbd>Cmd</kbd> + number                              | <kbd>Ctrl</kbd> + number                          | While the model picker is open, hold and press a digit to switch provider rail.   |
| Switch thinking level by number   | <kbd>Opt</kbd> + number                              | <kbd>Alt</kbd> + number                           | While the model picker is open, hold and press a digit to set thinking level.     |


# Providers
Source: https://docs.traycer.ai/settings/providers

Configure coding agents, provider credentials, CLI binaries, and provider environment variables.

Providers settings control the coding agents and providers Traycer can launch.

For supported coding agents and capability differences, see [Agents & Models](/agents-and-models/coding-agents).

## Common Controls

| Control                              | What it changes                                                                   |
| ------------------------------------ | --------------------------------------------------------------------------------- |
| **Enable provider**                  | Makes a coding agent available or unavailable.                                    |
| **API key**                          | Adds or clears credentials for providers that need a key.                         |
| **CLI binary**                       | Chooses bundled, detected, or custom CLI paths where supported.                   |
| **Provider environment variables**   | Adds variables scoped to the provider Traycer launches.                           |
| **Terminal interface CLI arguments** | Sets default CLI arguments used when starting an agent on the Terminal interface. |
| **Host selector**                    | Chooses which host's provider settings you are editing.                           |

Provider environment variables live here. Shell-wide host environment variables live in [Shell](/settings/shell).

Terminal interface CLI arguments are passed to the underlying CLI. Use bypass or full-auto flags deliberately.


# Shell
Source: https://docs.traycer.ai/settings/shell

Configure the shell and host environment used for terminal sessions.

Shell settings affect terminal surfaces launched by the host.

## Shell Command

| Control                       | What it changes                                          |
| ----------------------------- | -------------------------------------------------------- |
| **Shell program**             | Chooses the executable Traycer uses for shell sessions.  |
| **Startup flags**             | Adds arguments such as login or interactive shell flags. |
| **Effective command preview** | Shows the command Traycer will run.                      |
| **Reset to defaults**         | Restores the default shell configuration.                |

## Using WSL

Selecting WSL as your shell opens terminal tabs inside WSL. Agents always run on Windows, so they use the Windows environment and can't see tools installed inside WSL.

To run agents with your WSL toolchain, run the Traycer host inside WSL.

## Environment Variables

Host environment variables are configured here and apply after host restart.

Per-provider variables live in [Providers](/settings/providers). Use provider variables for coding-agent-specific credentials or endpoints; use Shell variables for host-wide terminal environment.


# Worktrees
Source: https://docs.traycer.ai/settings/worktrees

Manage host-wide git worktrees created by Traycer.

Worktrees settings show the git worktrees Traycer manages for a selected host.

For how worktrees affect agents and Git Diff, see [Worktrees](/concepts/worktrees).

## Controls

| Control           | What it changes                                                |
| ----------------- | -------------------------------------------------------------- |
| **Host selector** | Chooses which host's worktrees are shown.                      |
| **Refresh**       | Reloads the worktree list.                                     |
| **Worktree list** | Shows the worktrees Traycer has created for the selected host. |
| **Delete**        | Removes selected worktrees when they are safe to delete.       |

If the selected host is offline, worktrees can only be managed after that host is reachable again.