# How AQ works

> How AQ works: work items with their own branch and git worktree on a machine the team controls, agents on the subscriptions you already have, bots, Genie, live previews with comments, Linear and GitHub, and machines that belong to your team.

Updated November 13, 2026 (first published July 10, 2026) · by the AQ team · Canonical: https://aq.dev/docs/

AQ is where teams put AI agents to work: code that lands as a reviewed pull request, bots that run the jobs that repeat, and Genie, an assistant that starts each day, on the agents and subscriptions the team already has. This page explains the moving parts. It is a concepts overview, not an API reference: everything here is what you see in the product. If you just heard the name and want the short answer first, start with [What is AQ?](https://aq.dev/docs/what-is-aq/)

## Work items: one task, one branch, one worktree

The unit of coding work in AQ is a **work item**. Creating one (manually, from a Linear issue, or from a GitHub PR or branch) gives the task its own [git worktree](https://aq.dev/guides/git-worktrees-for-ai-coding-agents/): a separate working directory and branch (`ai/{id}-{slug}`) that shares the repo's history but never collides with anyone else's files. AQ installs dependencies in the worktree, runs your setup command, and tears it down when the work item closes. Ten agents on ten tasks means ten worktrees, each working without sharing a checkout.

## Agents: the subscriptions you already have

You work with the agent in a conversation inside the work item. It runs on the subscriptions your team already connected (**Claude Code, Codex, Cursor, Kimi Code, Grok, Antigravity, Devin** and others, several accounts each), and AQ uses them first with no markup. AQ's own models are there too, each with its price shown before you pick, and Auto chooses a model for each turn and says why. On a cloud machine the work keeps going when you close your laptop; open the work item from your phone and the same conversation is there. A shell tab is there when you want to run a command yourself.

## Together: the work item is a shared place

Any teammate with access opens the same work item and sees the same conversation, diff and preview. Tag @AQ to hand the agent something, tag a teammate to pull them in, and each person's messages run on their own connected accounts. That changes what "handoff" means: instead of describing what the agent did in Slack, you send a link. Every work item starts private and can be shared with the team or with specific people. **Guest links** go further: someone outside the team (a founder, a client) can view a preview without a seat and without the work item going public.

## Previews and comments: review behavior, not just diffs

A work item can run its dev server and expose it as a live preview with a shareable URL. Reviewers pin comments directly on elements of the running app (with screenshots and attachments), draw regions, and comment from mobile. Any comment can be handed to the agent as a follow-up prompt with one action: see an off-center button, pin a comment on it, send it to the agent, watch the fix land in the same preview.

## Linear and GitHub: intake and exit

Work enters AQ from wherever it already lives. With the [Linear integration](https://aq.dev/guides/linear-coding-agent-workflow/), labeling an issue `ai-task` creates a work item in the team's sidebar and moves the issue to In Progress; status syncs both ways, and ownership follows the Linear assignee. AQ deliberately does not start agents from labels: a person opens the work item and hands the agent the task. On the exit side, agents commit, push, and open pull requests using each user's own GitHub access, and AQ attaches every PR to its work item, tracking opened, merged, and closed.

## API, webhooks, and MCP

The work item lifecycle is scriptable. The [AQ API](https://aq.dev/docs/api/) exposes work items over versioned REST (create, monitor, close, plus their events, pull requests, and preview URLs), signed webhooks notify your systems when agents open or merge PRs or hit errors, and an MCP server at `aq.dev/mcp` gives Claude, Cursor, or any MCP client the same surface, plus tools to find, read, and message any work item or bot: one URL, a browser sign-in once, no key copying.

## Bots, Genie, crews and the rest

Beside work items, AQ has [bots](https://aq.dev/docs/bots/): named agents you talk to, one chat per person with threads, and routines that run the jobs that repeat on schedules and events. [Genie](https://aq.dev/docs/genie/) is your own assistant, and it opens each morning with what needs you. [Crews](https://aq.dev/docs/crews/) put a Lead and roles around a task, with review on another vendor. Review and merge happen in the [Changes panel](https://aq.dev/docs/changes/). Agents share [memory](https://aq.dev/docs/memory/) and get [secrets](https://aq.dev/docs/secrets/) as environment variables, every process can tell and [prove which work item and person](https://aq.dev/docs/execution-identity/) it runs for, long-lived processes run as supervised [background workers](https://aq.dev/docs/background-workers/), machines honor your [pinned Python and Node versions](https://aq.dev/docs/machine-toolchain/) and can join [your own private network](https://aq.dev/docs/private-networks/), and all of it works [on your phone](https://aq.dev/docs/mobile/). Every feature in one place: [features](https://aq.dev/features/).

## Machines: your team's, nobody else's

Agents run on a machine that belongs to your team: an always-on cloud machine that AQ manages in your team's own isolated project (included with the Pro plan, with bigger sizes and more machines a click away), a server you connect yourself, or your own Mac with the AQ Mac app. Either way the code, the worktrees, the agent's work and the sign-ins live on that machine, not on shared infrastructure. Machine health is visible in the product, the installer for your own server checks its own requirements, and `aq-runner doctor` diagnoses a misbehaving machine. For the wider landscape and the do-it-yourself route, see [self-hosted AI coding agents](https://aq.dev/guides/self-hosted-ai-coding-agents/) and the [hands-on setup guide](https://aq.dev/guides/self-hosted-ai-coding-agent-setup/).

## What AQ is not

- **Not an IDE plugin.** AQ runs in the browser, on iPhone and as a Mac app, and complements whatever editor your team uses.
- **Your subscriptions, unmetered.** Connect your own accounts and AQ never marks them up. AQ's built-in agent is there, with credits included, when you want a model without one.
- **Not a black box.** Every agent turn, tool call and bot run has a record, you decide what each tool may do, and merging is an explicit action that still goes through your required checks and review.

## Frequently asked questions

### Which AI coding agents does AQ support?

Claude Code, Codex, Cursor, Kimi Code, Grok, Antigravity, Devin, Muse Code, Command Code and OpenCode, each connected with the person's own account, plus AQ's own models.

### Does AQ work on Windows and Linux?

Yes. AQ runs in the browser, so any teammate on macOS, Windows, or Linux gets the same work items and bots. On the Pro plan agents run on your team's cloud machines, not on anyone's laptop. The Free plan runs agents on your own Mac.

### Can agents keep working when I close my laptop?

Yes, on a cloud machine. The agent's work runs on the machine, not in your browser, so it survives laptop sleep, network changes, and browser restarts. Reopen the work item and the conversation is where you left it. On your own Mac, agents pause while the Mac sleeps.

### Where does our code live?

On your team's machine: an AQ-managed cloud machine in your team's own isolated project, a server you connect, or your own Mac. Worktrees, the agent's work, and sign-ins stay on that machine.

---

About AQ: AQ is where teams put AI agents to work on everything they do: code that lands as a reviewed pull request, bots that run the jobs that repeat, and an assistant that starts each day, all on the agents and subscriptions they already have, like Claude Code and Codex, on private cloud machines of their own or on their own Mac. Start at [aq.dev](https://aq.dev/).
