Skip to content
Docs menu

The Agents app

Start a chat with a coding agent on one of your projects or with an agent on one of your computers, follow it as it works, answer its approvals and read its diffs, from any browser or phone, and install it as an app that notifies you.

View .md

The Agents app is at /agents in the console, on the rail (g g jumps there). It needs the agents add-on (included in Team and up). It opens dark; a light theme you pinned in the console stays light.

Start a chat

A new chat is one big prompt box. Inside it are three pickers:

  • Where: Quick chat (picked by default: no computer at all, the agent works through MCP servers; Quick chats, where the pickers are Servers and Gear), a project on one of your daemons (grouped by daemon, with its git branch), New project… or Scratch (discarded with the chat) on a daemon (Workspaces), one of your computers, or My computer (new).
  • Gear: the model preset the agent runs on, as in the CLI (Gears below).
  • Mode: how much the agent may do without asking.

Each picker opens a list you can drive from the keyboard: arrows move, Enter picks, Esc closes, and typing a letter jumps to the next row that starts with it. A long list has a search box. On a phone the list opens as a sheet from the bottom.

The picker shows how much the agent may do on its own, the way Claude Code does: one arrow (▶) asks first, two arrows (▶▶, in the warning colour) go ahead without asking, two bars (⏸) only plan. You can change the mode at any time, including while the agent is working.

Mode What the agent does
Ask before acting (▶) Reads the project freely; edits, writes and commands your rules don't allow ask first. The default.
Accept edits (▶▶) Edits files in the project without asking; commands still ask unless a rule allows them.
Auto (▶▶) Accept edits, plus a check on the fast model decides what would otherwise ask. Needs the daemon's OS sandbox (without one the chat runs, and shows, Accept edits). In a computer chat it opens sites without asking.
Plan first (⏸) Read-only: it reads and searches, then proposes a plan.

A chat started from a browser always keeps its approval prompts: the modes that turn them off are not offered.

The next new chat starts with what you chose last: the gear, the mode and where it ran. Changing the gear or the mode inside a chat counts too. It is saved with your account, so it follows you to your other devices. A choice that no longer exists (a gear removed, a project or daemon gone, gears locked by your organisation) is skipped, and the chat starts as it did before.

Type what you want and press Enter, or the arrow button. Shift+Enter or Option+Enter (Alt+Enter) starts a new line, and ⌘↵ / Ctrl+↵ send too. Enter never sends while an input method (Japanese, Chinese, Korean) is still composing text. On a phone or tablet with only an on-screen keyboard, Enter is a new line and the arrow button sends. The cloud starts the agent on the daemon and the chat opens at its own address, /agents/c/{id}. Starting can take a few seconds while the daemon starts the session.

Start from an issue

From an issue in Tasks, Start an agent chat (⌘⌥⇧P / Ctrl+Alt+Shift+P, ⌘K, or the issue menu), or ⌘J / Ctrl+J while the issue is open or focused, opens this screen with the issue's brief already in the prompt box and a From ENG-12 chip above it. Nothing starts until you send. The brief is what you can see: the issue's title, status, priority, labels, link and description, its latest three comments, the items linked to it, and its reference (issue:<id>) for the agent to open with workspace_item_get. Edit it as you like. The place, gear and mode are the ones you used last; the brief never changes them. The × on the chip starts the chat without the issue. Several issues: the first is the chip, and the chat is linked to all of them.

A chat started from an item records it as its origin: its header shows From ENG-12 · title (a link; ⌘⌥O / Ctrl+Alt+O goes back to it), and the chat appears on the issue's Linked section as "worked in", with its state (running, needs you, done) updated while it works. A link to /agents?from=ENG-12 opens the composer the same way, with a one-line brief. If the issue is deleted or moved out of your reach before you send, the chip goes and your text stays.

When the agent finishes or asks for an approval, the push goes to you, the person who started the chat (Notifications); the issue's subscribers are not notified by the chat.

Gears

A gear is a preset of the main model and its thinking level, the same gears /gear offers in the CLI (Gears has the full table). The gear picker lists:

  1. Your organisation's gears first, when an admin has defined some on the Gears page. The org's default gear is marked and picked for you.
  2. The daemon's own gears: the cloud asks the daemon's venom serve for its gears (GET /v1/gears), so you see what the CLI on that machine sees: venom's nine built-ins (1 eco, 2 normal, 3 power, 4 local, 5 delegate, 6 open, 7 qwen, 8 china, 9 auto) plus any in that machine's venom.yaml, each with its key and the model it resolves to there. A gear whose models the daemon doesn't serve is listed as unavailable.

When the daemon can't answer (it is offline, or its daemon is older than this list), the picker shows the nine built-ins with their first-choice model and says so. A computer chat's picker shows the built-ins too; the cloud resolves the gear on the computer's daemon when the chat starts.

If your organisation turned on "Members can only use these gears", only its gears are listed, as in the CLI.

Default leaves the choice to the daemon: its venom.yaml gear, else the orchestrator's defaults.

Each gear also says where its model runs: on the daemon's own keys (· this machine) or on your organisation's cloud keys (· cloud keys), as Model runs on (Auto, This machine's keys, Cloud keys) in the same box decides; a gear that can run in neither place says why. See Where a daemon chat's model runs.

Starting a chat in a gear starts the session on the model the gear resolves to on that daemon, with the gear's thinking level, and the chat records the gear. The chat's header shows it like the CLI's status line (3 power). In a running chat you can shift to another gear from the same picker: the agent switches to the new gear's model at once when it is idle, or at its next turn when it is working. The session keeps its thinking level. Someone reading another member's chat sees its gear but can't change it.

Follow the agent

The prompt box moves to the bottom and the conversation streams above it:

  • The agent's answer appears as it writes, as formatted text with code blocks.
  • Each tool call is one line: a mark (running, done or failed), the tool, and its command or file. Open the chevron to see what it was given and what it printed.
  • When the agent wants approval, the request appears in the stream with Allow once, Allow for this chat and Deny. When it asks a question, its options are buttons, and you can type your own answer instead.
  • After a turn that changed files, a Changed N files line appears. Open it to list the files, then open a file for its diff. The diff is read from the daemon when you open it; the cloud does not keep it. Secret files (.env and the like) and files the session may not read show why they are hidden instead.

While the agent works:

  • Send steers it: the message reaches the turn that is running.
  • After this turn queues the message for when the agent would stop.
  • Stop (or Esc) stops the turn. The chat stays open for the next message.

A screen reader hears when the agent starts working, needs an answer, or finishes.

If the connection drops, the page reconnects and picks up from the last event it had. If the daemon no longer holds the oldest part of a long chat, a note offers to load the earlier conversation from the session's transcript.

Computer chats

A computer chat shows the computer's live screen beside the conversation, with Take control, the address box and Start above it, and My computer (new) in Where starts one from a prompt alone. See Computer chats.

The sidebar

Your chats are listed on the left, grouped by project (with the daemon's name) and by computer, the most recent first. A dot shows which ones are working. Hover a chat (or focus it) to rename it (or press F2) or archive it. Archiving stops the agent and closes its session on the daemon. New chat (⌘J, or ⌘⇧O inside Agents; Ctrl+J on Windows and Linux) goes back to the prompt box with the cursor in it. ⌘J works from every app in the workspace, including while you type in a note or an issue, and ⌘K lists it as New agent chat. Hover Agents on the app rail to see it.

On a phone the app is one column and the chat list is a drawer behind the menu button.

Workspaces

A code chat needs no setup on the daemon. Under each daemon in Where:

  • New project… asks for a name and, optionally, a repository to clone (https:// only). The daemon makes the folder in its own workspaces folder, empty with git init or cloned, and the chat starts there. The project stays on the daemon, listed with the others, until someone deletes it. Leave tokens out of the URL: a public repository clones as is, and a private one uses the git login already on the daemon's machine (a credential helper, gh auth setup-git, the macOS keychain). A clone stops past 2 GiB or 4 minutes.
  • Scratch (discarded with the chat) runs the chat in a new empty folder. Archiving the chat deletes it; if the daemon was offline then, it deletes the folder itself after 7 days without a change.

The daemon picks every path and keeps the folders inside its workspaces folder. Its owner sees them on the daemon's dashboard and in venom-daemon projects list, marked as made from Venom Cloud, and can delete any of them. In the cloud, the member who made a workspace or an org admin can delete it (agents_workspace_delete). Anyone who can start code chats on a daemon can make workspaces on it. A daemon too old to make workspaces offers only its project folders; update the desktop daemon.

Add a project

To work in a folder that is already on the machine, its owner adds it on the daemon: on the dashboard under Projects, or:

venom-daemon projects add ~/src/my-repo

The folder then appears in the picker, with each git repository directly under it. A daemon whose venom serve is too old to list projects is named in the app; update venom and the daemon. Computer chats work without any project.

Who sees what

Only the member who started a chat can send to it, answer its approvals and questions, and archive it. Org owners and admins can open any member's chat from its link to read it, without the prompt box. See Venom Agents for usage and keys.

Install the app

Venom installs as an app that opens on Agents:

  • Android (Chrome, Edge, Samsung Internet): the menu, then Install app or Add to Home screen.
  • iPhone and iPad (Safari): Share, then Add to Home Screen.
  • Desktop (Chrome, Edge): the install button in the address bar, or the menu's Install Venom.

The installed app opens on /agents. A long press on its icon (a right click on desktop) offers shortcuts: a new agent chat, Computers, Tasks, Notes and Capture a person. It is still the share target for People capture (Share to Venom). An app installed before it opened on Agents updates itself.

The app keeps its shell offline: the Agents page, the app's code and icons, and an offline page. It never keeps a chat, an answer from the API or anything you typed. With the network down, it shows the Agents page or the offline page and reconnects when you are back. Signing out drops the saved page.

Notifications

Turn on Notifications at the foot of the sidebar to be told on this device when an agent needs you or finishes while you are not looking at its chat. Your browser asks for permission first. Turn it on in each browser or phone you want notified; turn it off there the same way. Send a test checks that this device receives them.

You are notified when:

  • an agent asks for an approval or asks you a question, and the request is still open;
  • an agent finishes a turn.

The same switch serves Venom Tasks: the service worker also shows Tasks notifications (assignments, mentions, reminders) on a device subscribed here or in Tasks' settings.

A chat you started from a Venom Tasks issue also reports back in your Tasks Inbox, on that issue: when it finishes, when it needs you (an approval or a question) and when a quick chat's turn fails. Only you are told, not the issue's other followers, and also when the chat is open in your browser (Agent chats from an issue). On the issue's Linked section every kind of chat, code and computer chats too, shows needs you while it waits.

You are not notified about a chat you have open in a browser: you see it there. Each approval, question or finished turn notifies you once. Tapping the notification opens the chat. The cloud checks your running chats about once a minute, so a notification can come up to a minute or so after the agent asked.

On an iPhone or iPad, notifications need the app on your Home Screen (iOS 16.4 or later). If the switch is greyed out, notifications for the site are blocked in the browser's settings.

What the push service receives

A notification travels through your browser maker's push service (Google's for Chrome, Mozilla's for Firefox, Apple's for Safari). That service receives the address your browser gave it, your Venom install's public key and contact, and a message encrypted to your browser that only your browser can read. The message holds the chat's id, the kind (needs_you or done) and a fixed title such as "An agent needs you", in your language. It never holds what the agent said, a file name, a command or your prompt.

When a push service says a device is gone (it was unsubscribed or reset), Venom deletes it. Leaving the organisation deletes your devices.

For operators: VAPID keys

Notifications are off until the install has its own VAPID key pair (RFC 8292). Generate one:

node -e "const e=require('crypto').createECDH('prime256v1');e.generateKeys();console.log('VENOM_PUSH_VAPID_PUBLIC_KEY='+e.getPublicKey('base64url'));console.log('VENOM_PUSH_VAPID_PRIVATE_KEY='+e.getPrivateKey('base64url'))"

Set both, plus VENOM_PUSH_VAPID_SUBJECT (a mailto: address or an https: URL a push service can reach you at), in the cloud's environment. With any of the three unset the switch is hidden and the cloud sends nothing. Keep the keys: replacing them makes every browser subscribe again. Push is the one outbound call the Agents app adds, and only for members who turn it on; an air-gapped install has no push service to reach and leaves the keys unset.