Crow

English

Español

English

Español

Appearance

Bot Builder ​

New to bots? Start with the step-by-step Your First Bot tutorial — this page is the full reference.

The Bot Builder is where you compose and run your own AI agents. An agent (a "bot") is a persona plus the skills, tools, gateways, and permissions you give it. Everything is configured from the Crow's Nest dashboard in a tabbed editor, with no config files to hand-edit and no separate admin tool.

The Bot Builder is the agentic spine of Crow. The same agent you build here can answer your email, chat on Discord, or run hands-free on your glasses, drawing on Crow's memory, projects, files, and any integration you have installed.

What an agent is ​

An agent is a definition with a few parts. The editor groups them into four tabs, plus an Advanced view for settings most agents never need:

TabWhat it controls
BasicsThe agent's name, its persona and instructions, its model (plus an optional stronger model for hard questions and a fast voice model for glasses, kiosk and companion), and the one channel people reach it on: Gmail, Discord, Telegram, Slack, Meta glasses, an AI Companion kiosk, Crow Messages or Perch. Only the chosen channel's settings are shown.
AbilitiesWhat it can do: read or edit files in its folders, run commands, use memory, and which connected services it may use. Each service is one row with Off / Read-only / All / Custom; Custom opens a searchable list of that service's tools, each marked "reads" or "changes things". Skills are chosen here too.
SafetyWhether email it writes is saved as a draft for you or sent directly, which folders it can look at and change, and the actions it must always ask you about first.
ActivityA readiness checklist, the Enable / Disable switch, skills waiting for your review, and its recent conversations.
AdvancedLearning new skills, helper agents, a list of allowed commands, the board and project it works on, sharing with your other Crows, a tool-connection check, the raw settings, and Delete.

Each tab saves only its own settings, and only the controls you changed: saving a tab without touching anything leaves the agent exactly as it was. If the agent was changed somewhere else while the page was open (for example a skill was approved), the save is refused and you are asked to reload.

Tools and extensions ​

Each agent only sees the tools you grant it. The Abilities tab lists every connected service (Crow's own servers and every installed extension) as one row. Read-only grants just the tools that look things up; All adds the ones that change things. Tools a service adds later are never switched on by themselves: an agent set to All then shows Custom until you choose again. Crow judges each tool by its name, and anything it cannot recognise counts as "changes things"; a tool whose name sounds like a lookup but that shows, shares or clicks something (a kiosk display, a download link, a browser that navigates) counts as changing things too. A service can mark more of its tools as changing things, never fewer.

When one service is connected more than once (two Google accounts, say), each row shows its account. Set the label with an optional "account" entry on that server in ~/.pi/agent/mcp.json or mcp-addons.json (for example "account": "alex@example.com"); without one, the row shows the server name.

When you select an extension's tools, the Bot Builder wires that extension into the agent automatically. You do not edit MCP server entries by hand. If an extension provides a tool that the agent's channel cannot reach (for example a tool with no voice equivalent on the glasses path), the editor warns you rather than dropping it silently.

Skills ​

Skills are behavioral prompts (Markdown files with a small front-matter header) that teach an agent a specific workflow. Choose them on the Abilities tab, grouped by the extension that provides them.

Skills are portable across agents and across channels. Language variants (English, Spanish, and so on) are just different skill files that call the same underlying tools.

Gateways: one agent, the channels you choose ​

A gateway connects an agent to a place where people talk to it. The same agent definition can run on more than one channel.

  • Gmail: The agent reads and replies to email on a connected mailbox.
  • Discord: The agent joins a Discord server as a bot and answers in channels and DMs, with a per-agent user allowlist.
  • Meta Glasses: A paired pair of Ray-Ban Meta (Gen 2) glasses binds to one agent. That agent then drives the fast voice turn: its persona, its skills, its scoped tools, and its permissions, spoken through the speech and voice profiles you picked. See the Meta Glasses guide.
  • Crow Messages: The agent becomes reachable as a contact. People you invite can message it, you can browse and add the bots running across your Crows, and you can put people and bots together in a group room. See the Crow Messages guide.
  • Perch: The agent becomes chattable right on the board in your own dashboard. There is nothing to configure — choosing the channel is the whole setup, and nothing to install. See Perch below.

Which bot answers voice ​

Each bot's card says where it answers voice: Answers voice on: names the glasses or AI Companion bound to it, Phone & dashboard when it answers Talk to Crow (marked (automatic) when nobody chose one and Automatic picked it), and each kiosk display it is on. With the Kiosk extension installed, the card's ⋯ → Use for voice… gives it Phone & dashboard or a display in one step. It saves the same settings as the Kiosk panel. A display switches right away; Phone & dashboard applies the next time Talk to Crow opens. Glasses and the companion are set in the bot's channel settings, which the dialog links to. A display can't be left without a bot, so to move one off this bot, choose another bot for it.

Binding glasses to an agent is one-to-one: a device drives one agent at a time, and choosing a new agent for a device releases the old binding.

Perch: talk to an agent from your own dashboard ​

Perch is the dashboard's own chat surface for agents — the Perch hub at /dashboard/perch (a nav entry under Agents). One page holds a live session list, a launcher to start a new session, and the chat itself. The board also carries a compact roost strip above the cards that links into the hub. There is nothing to install and nothing to configure beyond attaching the channel.

Nothing about it is exposed to the internet. It runs as part of the gateway, listens only there, and is reachable only through your dashboard login.

1. Attach the Perch channel to an agent ​

Open the agent in Bot Builder, and on the Basics tab choose Perch (dashboard chat) as the channel and save. There are no fields to fill in. You can also pick Perch as the channel while creating an agent in the wizard.

Perch turns run on the same bot engine that Gmail and Discord use, so if the engine is not installed yet Crow will offer to install it before letting you save.

Agents without the channel attached still appear in the hub's list, but there is no session to open until you attach them — jump to Bot Builder to do that.

2. Start a session — optionally in any directory ​

Open the Perch hub. The launcher at the top of the list starts a new session: pick the agent (when there is more than one), optionally pick a model, and optionally pick a working directory.

The directory field is the open-anywhere control. Leave it empty and the session runs in the agent's own default directory. Fill it in — by typing a path or by tapping Browse…, which opens a picker fed by the server (it lists directory names only, never file contents) — and the agent runs there: it can read and write that directory, and its per-agent MCP tools follow it. This is how you point an agent at a real project checkout instead of its own sandbox. The chosen directory must already exist; the picker only ever offers directories that do.

Perch does not jail an agent to a directory on this machine — the picker can reach any directory the gateway user can. The barrier between agents is each one's own tools and permissions, not the directory. Treat the Perch hub like the shell access it is (see Before you attach it).

Tap New session. The chat opens on the conversation.

3. The chat: four tabs ​

The chat has four tabs across the bottom (phone) or top (desktop). Switching tabs never interrupts the session — the live connection belongs to the session, not the tab.

  • Chat — the transcript, a composer to send a message or steer a running turn, and any question card the agent is waiting on. Tool activity and log lines do not clutter this view; they go to Activity.
  • Session — the model, thinking level, permission mode and plan-mode controls; the session's state; Rename and Close; and the working directory with a Change directory button. Changing the directory puts the session to sleep and wakes it in the new directory on your next message (an agent's process cannot change directory mid-run) — the button says so before you commit, and it is refused while a turn is in flight.
  • Files — what the agent has written to its outputs directory this session, newest first, each row a download. This is the session's own deliverables folder, not the working directory you chose.
  • Activity — the timestamped log/tool/error rail: what the agent did, which tools it called, and any gateway notes, so the Chat tab stays a clean conversation.

Each session carries a state: Awake while the agent can take a message right now, hibernating once it has gone idle and quietly shut itself down (nothing is lost — the next message wakes it back up mid-conversation, in its chosen directory and on its chosen model), and Stopped once you or Close have ended it for good. A stopped session cannot be woken again — start a new one if you want to keep talking to that agent this way.

Only one session per agent runs at a time by default, and every session competes for the same processing slots every other agent turn uses — Gmail replies, Discord replies, background jobs. Leaving a session awake and idle for a long stretch can make those wait; let it hibernate (it will, on its own) or stop it when you're done.

4. Narrow an agent's tools for one session ​

Per-session tool narrowing lives in the hub: open a session, go to its Session tab, and toggle Envelope & tools. You see the agent's full envelope: every tool it is allowed to use, each with a checkbox, plus its model and skills. The same pane is still on the board — open the drawer of the card a session is working — and both read and write the same per-session narrowing. Grants themselves are Bot Builder's alone; the pane can only take away.

Uncheck a tool and it is switched off for that session only, from the next message onward. The agent's definition is untouched, and every other session keeps the full set. This is for the moment when you want an agent to answer without touching your files, without editing anything, without reaching out over the network — for this one session, right now.

Tools shown with a padlock are ones the agent is not allowed at all. They are not togglable from either pane; only Bot Builder grants a tool. The session can only ever take away.

5. Answering a question the agent asks you ​

Some skills ask you something mid-task instead of guessing — pick from a list, confirm before doing something, type free text, or edit a block of text. That shows up on the Chat tab as a card in place of the reply: the question, and the way to answer it. Answer it and the agent continues right where it left off. If a card is still waiting on you when you navigate away, it is there again when you come back to the session — the hub's list shows the session as waiting on you in the meantime.

6. Coming back later ​

Reload the hub and every attached agent's sessions pick up right where you left them — reopen a session and the transcript, live state, chosen directory and model, and any pending question are all still there. You never have to hunt for which session was which.

Before you attach it ​

A few things are worth knowing, because Perch does not hide them.

Everyone who can sign in to your dashboard can read every agent's transcripts in the hub. There is no per-agent access control.

Messaging or steering a session extends that from reading to driving: anyone who can sign in can hold a live conversation as any agent, using that agent's own tools and permissions, not just watch what it already did. This is not a new trust boundary — a dashboard session could already trigger an agent by messaging it through its real channel (an email, a Discord message). Perch just makes that reachable straight from the board, without going out and back through a channel.

Attach the Perch channel only on a Crow whose dashboard login you treat as seriously as shell access on that machine — a live session can run any tool the agent's own permission policy allows, including ones that start programs on the machine it runs on.

Permissions and safety ​

Every agent carries a permission policy that governs what it may do without asking:

  • Confirm: Named actions require a confirmation step before they run.
  • Deny: Named actions are refused outright.
  • Draft-only outbound: Outbound sends and publishes are downgraded. A blog publish becomes a draft, and a true send (such as an email) is blocked and reported, so an agent cannot speak to the outside world on your behalf unless you allow it.

These rules are enforced on the underlying action, not just the surface tool name. If an agent tries to reach a protected action through a general-purpose tool wrapper, the policy still applies. On the voice path, the same gate runs before any tool executes, and a blocked action is spoken back to you.

Opt-in self-authoring ​

An agent can help write its own skills, but only if you turn it on under Advanced → Learning new skills. It is off by default; you can let it suggest skills for your approval, or learn on its own with guardrails (an agent that can send email or run commands only ever suggests).

When you enable it for an agent:

  1. The agent may draft a new skill file into a confined staging area that belongs to that agent. The draft is inert. It is not loaded, it is not attached to the agent, and it cannot take effect.
  2. The drafted skill appears in the Bot Builder for review. You can read it, edit the text, and either approve or reject it. Phrasing that could weaken a guardrail is flagged for your attention.
  3. On approval, Crow promotes the skill into your skills library and attaches it to the agent. Only then does it load.

A self-authored skill is prompt text only. Approving one cannot grant the agent new tools and cannot change its permission policy, because those come from the Abilities and Safety tabs, not from a skill. The operator-approval gate is the boundary.

This is the core of Crow's stance versus auto-authoring bot platforms: an agent can propose, but a human approves before anything an agent wrote for itself becomes real.

Deep work ​

For tasks that take longer than a single turn, an agent can hand work to Crow's orchestrator. The agent acknowledges the request immediately and the result arrives on a later turn, so a long research task does not block a conversation. Ask "what did you find?" on a follow-up turn to collect it.

Deploy and monitor ​

The Activity tab shows whether the agent is ready to run and lets you switch it on or off. Once deployed, an agent runs against the same Crow database as every other connection, so its memories, projects, files, and messages are visible everywhere else in Crow.

Released under the MIT License.