aq.dev / docs/bots

Bots

A bot in AQ is a named agent: a name, a role, instructions, a default model and rules. Each person who uses a bot has one ongoing chat with it. Side discussions are threads anchored to a message in that chat, and jobs the bot does on its own are routines. Every person also has Genie, their own bot, which is where AQ opens.

Create a bot

  1. Choose + in the sidebar, then New bot.
  2. Give it a name, an optional role (a short label such as Triage) and an avatar.
  3. Its chat opens. Say what the job is ("every weekday at 8, brief me on mail and the PRs that need me") and the bot proposes routines as cards you can edit before they start.

The bot's header holds its name (which opens Bot settings: instructions, default model, rules, spend, accounts), the Threads, Routines, Library and Work panels, Share, and a menu with Start fresh and pause.

Your chat and its threads

  • One chat per person: everything you say to the bot and everything it does for you on its own (routine results, briefs, Needs you cards) share one timeline. Older history loads as you scroll.
  • Threads: Reply in thread on any bot message, run row or card opens a thread beside the chat, with that item pinned on top. In the thread the bot sees the chat up to that item, plus the thread, and nothing after it. Your reply reaches the chat only when you tick Also send to the chat. A bot answer has its own Send to chat action.
  • The Threads panel lists every thread, newest activity first, with its replies. Rename, archive or delete a thread from it; deleting leaves a "Thread deleted" marker where it was.
  • Start fresh (the chat's menu) stops the current turn and starts a new context: the bot no longer carries the old conversation, its summary or old approvals. The old timeline stays readable above a divider, threads and routines stay, and the bot's memory is kept until you manage it in Bot settings. It is not a deletion.
  • Long chats stay coherent through a rolling summary the bot keeps of your chat, plus the recent messages.

Routines

A routine is a job the bot does on its own: a name, an instruction, one trigger, who it runs as, a posting rule, and paused or active. Create one by asking in the chat or with + on the Routines panel. A routine runs as the person who created it, on their accounts and funding, and can use its own model instead of the bot's default.

Triggers

TriggerWhen it fires
ScheduleAt a time of day in an IANA time zone, on the weekdays you pick.
MonthlyOn a day of the month (1 to 31), the last day, or the first or last weekday, at a time in a time zone. A month without the chosen day is skipped; pick "last day" to never skip.
Every N minutesEvery 5 to 1,440 minutes. Missed ticks are coalesced, never replayed in a burst.
Linear labelWhen issues get a label, read through the routine owner's Linear connection.
GmailWhen unread mail matching a search arrives in the routine owner's Gmail.
Google CalendarA set number of minutes before a meeting starts, or after one ends.
GitHubA new pull request, a new issue, a push or a release on a repository you connected.
Failing check, review commentOn the pull request of a work item. These routines run inside that work item, in its branch, and end when the pull request merges or closes.
WebhookA POST to the routine's own address, with its secret in a header. Bodies up to 256 KB.
ManualRun now, or Test (below).

The Routines panel previews the next three times a timer routine will run before you save it. Only new events fire a routine. While it is paused, events do not queue up and are not replayed when you resume it.

Runs

Each firing is a run with its own record: why it woke, what it did, what it produced (drafts, pages, files, work items, messages), approvals and their answers, and what it cost. Open a run from its row in the chat or the routine's history, and Reply in thread to discuss it. One run of a routine runs at a time; a bot runs up to 3 routines at once.

Test is a live run labeled "Live test · uses credits": it runs the routine now with outward actions set to Ask, so anything that leaves AQ waits for your yes. Approved actions do happen. A test does not move the routine's event position and does not post to other people's chats.

What reaches the chat

SettingChoices
Post whenSomething happened (default: the run produced something, changed something or needs someone), every run, or never (visible only in the run history). Consecutive quiet runs fold into one line.
Post toMy chat (the routine owner's), or on a team bot, everyone's chat. Members see the run's shared report, never its private transcript.
NotifyWhen it needs me (default), every run, or when it fails. Needs you cards appear even when posting is set to never.

Rules, approvals and money

  • Built-in rules, each Allow, Ask or Never: start work items, share guest links, send anything outside AQ (mail, a Slack post, a comment on a ticket), delete or close things, and pay or move money. New bots ask for all of them and never pay.
  • Connected tools keep their own Allow, Ask or Off permission per tool. A bot rule can only add an Ask, never remove one.
  • Approvals are Needs you cards for the person whose account is used. A run waits 30 minutes; an unanswered approval is denied and the run ends without acting.
  • Spending: the bot's monthly cap covers the AQ credits its routines spend, whoever they run as, and an optional ceiling stops a single run. When the month reaches the cap the next run is skipped and you are told once. Your chats and threads with a bot are your own usage, on your subscription or credits under your personal limits.

Work it starts

A bot starts real coding work as work items (a branch, a worktree, an agent or a crew, a pull request) under the start work items rule. The Work panel lists every work item the bot started, which routine started it and its pull request state. A work item keeps its own sharing; listing it in the Work panel shows it only to people who can already open it.

Sharing a bot

Share opens the same choices as a work item: only you, specific people, or the whole team. Sharing needs the AQ Pro plan.

  • Members get their own private chat with the bot, which runs as them, on their accounts. The owner cannot post into it or delete it.
  • Managers edit the bot's instructions, routines, library and settings. Only the owner deletes or transfers it.
  • Can share with others lets a person add teammates, never remove them.
  • Routine changes need the payer: when someone other than the person a routine runs as changes it, the routine stops dispatching until that person accepts the change from a card that shows the full difference.

Who can read chats

Set in the Share dialog, and always stated under the composer:

  • Only the member (default).
  • The member, the owner and managers.
  • Everyone the bot is shared with.

Widening never reveals what was said before: each member confirms the new audience before their next message, and the bot starts a new context so it cannot quote the private part. Narrowing takes effect at once. A member can also share a single thread, or their whole chat, with the owner. Admins can limit these choices for the organization. The owner and managers always see the bot's activity log (runs, calls made with shared accounts, work items started, pages published) without anyone's words.

Shared accounts

In Bot settings the owner can share a connected account with members. Only the tools the owner set to Allow on that account are offered in members' chats; tools set to Ask or Off are not shared, and the chat says so. Every call is logged under the owner. Repositories are never shared this way: each person's own access applies.

Library

The Library panel holds what the bot keeps: files, pages and links. What a run makes in your chat stays private to you until you add it to the shared library, where you see the audience before you confirm. Managers maintain shared items; members can keep private ones. Edits to the same file never overwrite each other silently; a conflict keeps both versions for you to resolve.

Move from Grok Bot, Dots, Muse or Duet

Bring the bots you set up elsewhere. Open aq.dev/import/grok-bot (or /import/dots, /import/muse, /import/duet), or choose Import in Settings, Bots. It works the same on your first visit: sign in and the importer opens.

  1. Copy the prompt AQ shows and paste it into your Grok Bot. It writes out its own bots, routines and memories as JSON. Passwords, keys and tokens are left out, and AQ drops any that slip through.
  2. Paste what it replied, or upload it as a .json file. AQ shows each bot with its instructions and routines, when each routine runs, and the memories it found.
  3. Choose the bots to bring and whether to keep the memories, then import.

Each bot arrives as your own private bot with its routines paused. Run a test to see what a routine does, then turn it on. A routine that runs on something AQ cannot watch yet is kept as a note in the bot's library, named in the review, so nothing is lost. Memories you keep become your personal notes in Memory.

Copies

From the bot's menu, Duplicate makes a fresh copy of a bot: its profile, instructions, routines, rules and starter library. The copy's routines start paused, and it never carries chats, threads, runs, memory, secrets, connected accounts or sharing.

Pausing, deleting and transferring

  • Pause stops all routines; chats keep working. Pausing one routine is separate, so resuming the bot does not turn on a routine you paused yourself.
  • Delete (owner): routines stop at once and chats become read-only. Restore within 30 days from Settings, Bots; a restored bot comes back paused. Work items and pages it made stay with the people who own them. Genie cannot be deleted.
  • Transfer hands a bot to a teammate who accepts it. Routines that ran as the previous owner wait for a new owner to set them up.
  • A disconnected account puts the routines that use it in Needs setup, with a reconnect link.

Limits

WhatLimit
Routines per bot50
Bots per organization100, plus each person's Genie
Timer routinesAt most every 5 minutes
Runs at once1 per routine, 3 per bot
Runs per hour200 per routine, 300 per bot
Library1 GB per bot, 25 MB per file
Instructions20,000 characters for the bot, 12,000 per routine
Approval wait30 minutes
Run transcriptsKept 90 days
Deleted botRestorable for 30 days
Webhook body256 KB

Bots and routines are on every plan; sharing a bot with teammates needs the AQ Pro plan. Product overview: AQ Bots.