Chatty

Why Chatty

Your provider, your data. Connect OpenRouter, Azure OpenAI or a local Ollama instance. Conversations, memory and settings stay in local files and a local SQLite database; nothing is hosted by Chatty.

An agent, not a chat box. The model can plan, call tools, read and edit files in a workspace you choose, run code in a sandbox, query spreadsheets and data files, search the web, and drive a real browser to check its own work. Every side-effecting action goes through an approval mode you control.

Two front ends, one engine. The desktop app and the terminal app share the same core, so the agent behaves the same whether you are chatting in a window or scripting chatty-tui headless in a pipeline. Sub-agents are just headless terminal instances.

Fast and native. Built on GPUI, the GPU-accelerated UI framework from the Zed editor. Markdown, code, LaTeX math, Mermaid diagrams, charts, PDFs and tables render natively in the transcript.

Download

All builds are on GitHub Releases. The app checks for updates in the background and verifies them before installing.

Where to go next

Getting started

When to read this: You are installing Chatty for the first time and want to send your first message.

Chatty is a desktop and terminal AI agent that runs on your own machine: your keys, conversations and files stay local, and the model only reaches what you switch on. Why it exists: the landing page.

1. Install

Download the latest release from GitHub Releases:

On Linux, make the AppImage executable and run it:

chmod +x chatty-linux-x86_64.AppImage
./chatty-linux-x86_64.AppImage

AppImages need FUSE 2. If it fails with error loading libfuse.so.2, install it: sudo apt install libfuse2t64 on Ubuntu 24.04+, sudo apt install libfuse2 on Ubuntu 22.04 and Debian, sudo dnf install fuse-libs on Fedora. Without FUSE, ./chatty-linux-x86_64.AppImage --appimage-extract-and-run works too.

Chatty checks for new releases in the background and offers them in the status footer. Details: Advanced.

2. Connect a provider and add a model

1. Click the gear icon in the title bar to open Settings, then Models & Providers.
2. Manage keys — paste an OpenRouter key, point at a local Ollama, or connect Azure OpenAI. Press Test to check it.
3. Add model — search the provider’s catalogue, tick the models you want, then Add.

Ollama models appear on their own once Ollama is running. Azure fields, the roster, favourites and troubleshooting: Providers & models.

3. Send a message

Close Settings and type. A new conversation opens on a start screen that shows what is switched on — modules, MCP servers, agents, file access, memory and whether a workspace is set — so you know what the agent can reach before you ask. Switch models with the selector at the bottom of the chat.

• Type / for the command picker (↑/↓, Enter).
• Type @ to mention a file from the working directory.

Rendering, attachments, artifacts, cost tracking and search: Chatting.

4. Turn on tools (optional)

Tools are off by default, so at this point Chatty is a chat window. To let the agent read and edit files, run commands and use extensions, open Settings → Code Execution, set a Workspace Directory, switch on Enable Code Execution and choose an approval mode. Walkthrough: Agents & tools. What each approval mode does and how the sandbox works: Security & sandboxing.

Tip

Web access is a separate switch (Settings → Internet) and is on by default, so the agent can fetch pages and search the web even before you enable code execution.

Desktop or terminal?

Both share the same providers and models. Install the terminal app from the desktop app: Terminal interface.

Next

• Providers & models
• Chatting
• Agents & tools

Providers & models

When to read this: You want to connect an LLM provider, add models to the roster, pick a default, or work out why a model is missing.

Everything lives on one page: Settings → Models & Providers. The roster lists every model as a row — favourite star, provider, context window, input price per million tokens and temperature — with a status chip per provider across the top. Changes save automatically.

Connect a provider

Click Manage keys. One sheet holds all three providers; each row shows its status and has Save and Test buttons. Keys are stored with your app settings, never in your project files. Removing a key hides that provider’s models but keeps their settings.

OpenRouter

One key gives access to many upstream models (Claude, GPT, Gemini, Mistral and more). Paste the key (it starts with sk-or-), Save, then Test — a good key shows Key verified and the chip reads Connected · N models. Chatty also pulls the OpenRouter catalogue, including pricing, so the roster’s price column fills itself.

Ollama

No key needed — a local instance is detected automatically. The URL field defaults to http://localhost:11434; change it and Save if Ollama runs elsewhere (another machine, a different port). Test shows Running · N models.

Note

Plain http:// is only for your own network. Provider URLs (and MCP server, remote agent and Hive registry URLs) may use http:// only for localhost/loopback and private-LAN addresses (10.x.x.x, 172.16–31.x.x, 192.168.x.x — for example a model server on the Docker bridge, http://172.17.0.1:8000). Any other host must use https://; there is no override.

Ollama models are added for you: Chatty discovers what is installed shortly after launch and keeps the roster in step, removing models you have deleted from Ollama and detecting per model whether it accepts images.

Note

A pulled model does not show up? Discovery runs at launch, and again every time the Settings window opens or is brought forward — so an Ollama started after Chatty, or a model you ollama pulled while Chatty was open, appears next time you open Settings. No restart needed. If Test fails, make sure Ollama is running (ollama list in a terminal) and that the URL matches where it listens. Models you added by hand under Enter an identifier manually are left alone by discovery.

Azure OpenAI

Azure serves your own deployments rather than a public catalogue, so it needs three things:

1. API key, or switch on Use Entra ID instead of a key to sign in with your Azure account.
2. Endpoint URL — your resource address, e.g. https://my-resource.openai.azure.com. The v1 base URL (https://my-resource.openai.azure.com/openai/v1/) and the deployment or Responses URLs the Azure portal shows work too.
3. Deployment name — the deployment you created in Azure, e.g. gpt-5-chat.

Press Connect & fetch models. Each further deployment is added by name in the Add model sheet.

When a request carries tools (an agent turn), chatty sends it to the resource’s Responses API, the one OpenAI’s reasoning models accept tools on. A plain chat without tools, such as a title or a summary, goes to the deployment’s chat completions, so an older deployment without the Responses API still chats. The API version under Edit… → Advanced applies to those chat completions. A model-inference endpoint (…services.ai.azure.com/models) serves chat completions only: chatty uses it for everything, and a reasoning model with tools there asks you to switch to the resource’s v1 base URL.

Add a model

Click Add model. The sheet opens on the provider’s catalogue: search it, tick as many models as you like, and add them in one go — no identifiers to type. Models already in your roster show as added. If the OpenRouter catalogue is empty, add a key in Manage keys first and reopen the sheet.

For anything the catalogue does not list, expand Enter an identifier manually and give it a display name and the provider’s model identifier (for example qwen2.5:0.5b).

Favourites, default and per-model settings

• Click a row’s star to pin the model to the top; the Favourites and Local chips filter the roster.
• A row’s ⋯ menu offers Set as default (the model new conversations start with), Edit… and Remove.
• Edit… has a Basic tab (name, identifier, temperature, system prompt) and an Advanced tab: max tokens, Max Context Window (turns on the context fill bar in the chat footer), top-p, cost per million input and output tokens, and the Azure API version.

Favourites and the default survive catalogue syncs and restarts.

Capabilities

Chatty records three capabilities per model and uses them to show or hide the attachment buttons and the temperature control:

Starting values by provider: OpenRouter models accept images and PDFs; Azure OpenAI models accept images but not PDFs; Ollama models are detected one by one, so a vision model gets the image button and a text-only model does not.

Next

• Getting started
• Chatting
• Advanced

Chatting

When to read this: You have a model connected and want to know what the chat window can do — rendering, attachments, artifacts, cost tracking, search and themes.

The composer

• Model selector at the bottom switches models mid-conversation; the roster and default come from Providers & models.
• Type / for the command picker (↑/↓, Enter). Saved skills appear there with a skill badge. Full list: slash commands.
• Type @ to mention a file from the working directory. Hidden files and common build folders (.git, node_modules, target, dist, build) are skipped.
• Add attachments attaches images and PDFs. The buttons only appear for models that accept them.
• The folder icon sets a per-chat working directory: Agents & tools.

Sending while a reply streams

Send (or Enter) doesn’t wait for the current reply to finish — a message sent mid-stream is queued and appears as its own bubble below the reply in progress, with × in front to take it back and ↑ to send it now instead, which cancels the current reply and runs that message next. Up to 5 messages can queue at once; a sixth is refused with a notice under the queue. Stop cancels the reply but leaves anything queued in place — nothing runs until you send again, and that send runs the queued messages first, in order.

The running indicator above the composer grows a “· 84s · turn 11 · 11254 tok” suffix — elapsed time once a second has passed, then the running turn count and this turn’s own token total once a round-trip has completed — a way to see a long reply is still making progress now that replies have no default turn cap.

Rich rendering

Responses render as Markdown with:

• Syntax-highlighted code in dozens of languages, with Copy code on every block.

  

• Math — inline $...$ and block $$...$$, drawn in the theme colour, with Copy LaTeX.

  

• Mermaid diagrams from fenced mermaid blocks — flowcharts, sequence, class, ER, Gantt and many more — drawn inline in light or dark to match the theme. Copy Mermaid copies the source; Copy as PNG copies the image.

  

• Image and PDF previews for attachments and generated files.

Models that think out loud (for example Claude extended thinking) get their reasoning folded into a collapsible section so it stays inspectable without filling the transcript.

Artifacts

When the agent produces a document, a card appears in the transcript and the file opens in a panel beside the chat:

• PDFs the agent typesets, paged in the panel.

  

• Charts — bar, line, pie, donut, area and candlestick — drawn natively and theme-aware, with Copy as PNG.

  

• Query results from SQL the agent ran over CSV, Parquet or JSON files in the workspace, shown as a table with the SQL one tab away.

  

• Markdown documents the agent wrote, rendered or as source — including any Mermaid diagrams in the file, drawn inline the same way as in chat.

  

• PowerPoint decks the agent writes, rendered as real slide images and paged with Prev/Next, with the extracted text a tab away.

When browser tools are on, a live view of the page the agent is driving docks in the same panel: Agents & tools.

File explorer

The sidebar doubles as a light IDE over your working directory. A Chats | Files toggle sits in the status bar at the bottom of the window, next to the warning/error indicators; switching to Files replaces the conversation list with a tree rooted at your workspace directory (or the current folder if none is set), folders first, and picks up files the agent adds or removes within a couple of seconds without needing a refresh. Switching conversations re-roots the tree to that conversation’s own working directory. You can also reach it from the caret next to the artifact button in the titlebar (or the floating button on macOS) — pick Files, which expands the sidebar if it’s collapsed and switches it to Files mode.

Drag the edge between the sidebar and the chat to resize it — handy for reading long filenames or deeply nested paths in full.

Click a file to open it in the artifact panel, using the same viewers as agent-produced artifacts (Markdown, code, PDF, PowerPoint, images, tables). Right-click a row, the header, or an empty folder for New file…, New folder…, Rename…, Delete…, Reveal in file manager and Copy path. Deleting asks for confirmation first and cannot be undone.

Ctrl/⌘-click a row to add it to a selection, or Shift-click to select a range; the right-click menu then reads Delete N items… and Copy paths for the whole selection. Drag a selected row onto a folder (or onto the empty area to move it to the workspace root) to move it there — an open file’s tab follows it to the new path.

Press Ctrl/Cmd+P from anywhere to open Go to File, a fuzzy quick-open over every file in the workspace — handy when the sidebar is collapsed or you just want to jump straight to a file. Type to filter, then click or press Enter on a match to open it in the artifact panel.

The Source tab is editable: press Ctrl/Cmd+S or click Save to write your changes back to disk. An unsaved file shows a dot on its tab; switching tabs keeps your edits, and closing a tab with unsaved changes asks before discarding them.

Tool-call traces

Every tool call is a collapsible block showing the name, arguments, output, duration and status (success, error or cancelled). File edits get a proper diff — additions green, deletions red, unchanged runs collapsed with Show N more lines on large patches. Multi-step work also shows a To-dos card that updates in place; see Agents & tools.

Context window

Long agent runs fill the context quickly. The footer shows:

• Fill bar — segments for the system preamble, tool definitions, history and the latest message, coloured green, amber or red as the window fills. It appears once Max Context Window is set on the model (Edit… → Advanced).
• Token popover — hover the bar for per-segment estimates and the provider’s input and output counts.
• /compact — summarises the older half of the history so the run can continue.

Pull request status

When the workspace is a git checkout whose origin is on GitHub, a bar above the composer shows the pull request for the current branch: number, repository, branch, +added −deleted and a CI pill listing each check. Click the number, repository or branch to open the PR in your browser; × hides the bar until the branch or PR changes.

The bar follows Enable Git Integration in Settings → Code Execution. Private repositories need the GitHub CLI (gh) installed and signed in; public ones work without it. No PR, no GitHub remote or no workspace means no bar. The terminal app shows the same thing (#591 open ✓) in its status line.

Conversations, cost and search

• Conversations are stored in a local database on your machine by default.
• Titles are generated automatically. The search icon in the title bar opens Search conversations…, which filters the sidebar as you type.
• Each conversation’s ⋯ menu has Download, which saves the transcript as a Markdown file, Take online…, and Delete.
• The sidebar shows the running cost per conversation; each reply shows its input and output tokens and cost. Pricing uses the per-million-token rates on the model, which the OpenRouter catalogue fills in for you.
• Chatty only ever appends to the prompt it sends — the system instructions, tool list and prior turns already sent are never rewritten — so a provider’s prompt cache keeps recognising them turn after turn. Providers that price cached input lower pass that saving straight through to the cost shown here.
• Regenerate under a reply asks for a fresh answer. Chatty keeps both versions, which is what makes preference-pair export possible (Advanced).

Taking a conversation online

Take online… in a conversation’s ⋯ menu uploads its history to a chatty-server you name and continues it there — useful for a long-running task you want to keep going after you close the laptop. A globe icon badges the conversation in the sidebar while it runs remotely, and while it does the composer’s model chip shows the model the server reported (or “Hosted model” if it reported none) instead of your local pick, with no model picker, since the server decides the model. The same menu offers Bring back here to return it. The confirmation dialog lists exactly what moves (message history, traces, the model id) and what never does (workspace files, attachments, MCP servers, memory, skills, and provider API keys — those stay on this machine). The conversation’s local copy is kept either way, so bringing it back does not lose anything, and a move mid-turn is refused until the turn finishes. The server only accepts requests from a signed-in Hive session, so sign in first (Settings → Extensions → Hive); without it, the move or the hosted turn fails with a message telling you to sign in.

Themes and text

Settings → General offers twenty-odd theme families (Ayu, Catppuccin, Everforest, Flexoki, Gruvbox, Matrix, Solarized, Tokyo Night and more), a Dark Mode switch for the light or dark variant of each, and a Font Size from 8 to 32.

Next

• Agents & tools
• Providers & models
• Advanced

Terminal dock

When to read this: You use the desktop app and want a shell next to the conversation — to run a build, look at git status or try what the agent just wrote — without leaving Chatty.

The desktop app has a terminal panel under the chat, placed and behaving like the terminal panel in VS Code or Zed. (For the terminal app, chatty-tui, see Terminal interface.)

Open and close it

The dock sits under the message box and spans the chat column only: the sidebar and the artifact panel keep their place beside it. The message box stays above the dock and keeps working while it is open.

• Resize: drag the dock’s top edge. The height is remembered.
• Maximise: the square button on the right of the tab strip grows the dock to fill the chat column; the transcript is hidden while it is maximised and the message box stays. Click it again to restore.
• Hide: the chevron on the far right closes the dock, like Ctrl/Cmd+J.

Closing the dock doesn’t stop anything: its terminals keep running and are there again when you reopen it.

Tabs

Each terminal is a tab. + opens another, × closes one, and dragging a tab sideways changes the order. A tab is named after the program running in it and the folder it is in, for example bash — chatty2 at the prompt or cargo — chatty2 during a build; on macOS and Windows it always shows the shell and the folder the terminal started in. Hover a tab for the full title the program set, such as the shell’s user@host: path.

When the shell exits (you typed exit, or it crashed), the tab stays, its name in italics followed by the exit status, for example bash — chatty2 exited 0. One click on × closes it.

Closing a tab while a program is running in it, such as vim or a build, asks for confirmation first; closing a tab that is only showing its prompt doesn’t. On Windows Chatty can’t tell the two apart, so closing a running terminal always asks. Closing the last tab closes the dock.

The Agent tab

The first tab, with the robot icon, is always Agent: the shell the agent runs its commands in for the active conversation. It shows every command the agent ran with its full output, not just the part a tool row has room for, and you can type in it too: it is one shell, shared by you and the agent.

• Switching conversations switches the Agent tab to that conversation’s shell. Your own tabs stay.
• Before the agent used its shell the tab says so and offers Start shell, so you can prepare the environment (activate a virtualenv, cd, export a variable) before you ask. It starts the same shell the agent then uses. With code execution off in Settings → Code Execution the agent has no shell and the tab says that instead.
• Its × hides the dock; the Agent tab can’t be closed, and the shell keeps running.
• Which lines were the agent’s: a small blue bar in the left margin marks each command the agent ran. Commands you typed have none.
• Status: next to its name the tab says what the shell is doing: idle, agent running cargo test, you typing, or you running ….
• Sandbox: when the agent’s shell runs in the sandbox, the tab says sandboxed (or sandboxed · no network with network isolation on). What you type there runs in the same sandbox. When the sandbox can’t run on this machine, the tab says not sandboxed; hover it to see why.

Sharing the keyboard. You can type at any time. While the agent’s command runs, what you type goes to that program: answer its prompt, or press Ctrl+C to stop it (the agent then gets the interrupted output and exit code 130). While you have a half-typed line at the prompt, the agent’s next command waits for you: the tab turns amber and says Agent waiting for you with the command it wants to run. Press Enter or clear the line (Ctrl+U) and it goes ahead. If you don’t within two seconds, the agent is told the terminal is busy and can try again.

Show in terminal. Each shell command row in the conversation has a terminal button: it opens the dock on the Agent tab, scrolled to that command. If the same command ran more than once, it shows the latest run; a command that has scrolled out of the scrollback, or ran in a shell that has since restarted, can’t be shown.

The agent can read its own tab with terminal_read without you sharing it, so it can see what you ran there (“what did I just run?”). A hidden-input prompt, such as a password prompt, is never read.

Where a terminal starts

A new terminal starts in the active conversation’s working directory, the same folder the file explorer shows for it (set with the folder icon in the message box or /cd). Without one, it starts in the workspace directory from Settings → Code Execution, and without that, in your home folder.

Your terminals belong to the window, not to a conversation. Switching to another conversation leaves them running and visible; only new terminals pick up the new conversation’s folder. The Agent tab is the exception: it always shows the active conversation’s shell.

Quitting Chatty ends every shell it started. Terminals are not restored the next time Chatty starts.

Keyboard focus

Click in a terminal to type into it. Escape is passed to the program in the terminal (vim needs it) and does not move you out. To go back to the conversation, click the message box, or press Ctrl/Cmd+J to close the dock.

A few key combinations always go to Chatty, even while a terminal has the keyboard, so the dock can always be closed:

• Ctrl+J / Cmd+J
• Ctrl+`
• Ctrl+Shift+`

In a shell, Ctrl+J only types a newline, which Enter already does.

Sharing a terminal with the agent

Your terminals are yours: the agent can’t see what is in them until you share one. Each tab has an eye icon; crossed out, the tab is not shared.

Click the eye on a tab that is not shared and choose how much the agent gets:

• Read only: the agent can read the screen and the scrollback, for example to answer Why did that fail? after a failing build.
• Read + run: the agent can also run commands in this terminal, each one only after you approve it.

Tick Remember this, don’t ask again to skip the question from then on: the eye shares every tab at that level with one click. Settings → Terminal → When sharing a terminal changes or undoes that choice (Ask brings the question back).

Click the eye on a shared tab to stop sharing it at once.

A tab you haven’t shared is still listed to the agent (its name and folder), so it can tell you it isn’t shared and ask you to share it, but its contents are never read. While a terminal waits at a plain text password prompt (sudo, ssh, su, passwd, a script’s read -s, or gpg with --pinentry-mode loopback), the agent gets “terminal is at a hidden-input prompt” instead of the screen, even from a shared tab. Full-screen passphrase boxes, such as the one gpg usually draws in the terminal (pinentry-curses), and pinentry windows outside the terminal are not caught: the passphrase itself is never on screen there, but the rest of the terminal can be read as at any other moment. Windows has no way to tell that a program is asking for a password, so on Windows don’t leave a shared tab at a password prompt.

Every read shows up in the conversation as a tool row such as Read terminal · bash — chatty2 · 42 lines, naming the tab and how many lines the agent was given; the row’s copy button gives the exact output. The tab it read lights up for a moment.

Letting the agent run a command in your terminal

The agent normally runs commands in its own shell. When you want one to run in a tab of yours instead (your ssh session, your activated virtualenv, the dev server you are watching), share that tab as Read + run and ask for it, for example Restart the dev server in my terminal.

A tab shared this way is your own shell: it is not sandboxed and it holds your credentials. So every command the agent wants to run there first shows an approval card with the exact command, the tab’s name and folder, and the line Runs in your shell, not the sandbox. Nothing is typed until you click Approve; Deny tells the agent no. This card always appears, one per command, whatever the approval mode under Settings → Code Execution: auto-approve never applies to your terminals.

Once approved, the command is typed at your prompt and appears in the tab as if you had typed it, marked with the same small blue bar in the left margin as the agent’s commands in the Agent tab (the margin appears in your tab with the agent’s first command there). The agent gets the command’s output and exit code when it finishes. A command that is still running after two minutes (a server, say) keeps running; the agent is told so and can read the tab later.

The agent is refused, and nothing is typed, when:

• the tab is shared Read only: it is told to ask you to share the tab as Read + run;
• you are typing at the prompt, or a program is running in the tab (vim, a Python prompt, a password prompt, a running build): it waits two seconds, then is told what is in the way;
• the tab’s shell has no shell integration (anything other than bash or zsh, such as fish): without it the agent can’t tell when a command finishes, so it doesn’t type into the tab at all;
• the command has more than one line: only single-line commands are typed at your prompt;
• another command of the agent’s is already waiting or running in that tab.

tmux panes outside Chatty are only ever read, never run in.

The terminal goes with your message

While the dock is open on a terminal the agent may read (the Agent tab, or a tab you shared), each message you send carries a short snapshot of it, so why did that fail? works without pointing the agent at the terminal. A chip above the message box says what goes along, for example Terminal: bash — chatty2 · 32 lines:

• Click the chip to see exactly what the agent gets: the tab’s name and folder, then the last command, its exit code and the last 40 lines of its output. A shell that doesn’t mark its commands gives the last 40 lines on screen instead. A snapshot is at most about 2,000 tokens; longer output is cut from the top, with a line telling the agent to read the terminal itself for more.
• Click its × to send this message without it.
• Nothing changed, nothing sent: a snapshot goes along only when the terminal shows something different from the last one sent in this conversation, so a long chat doesn’t pay for the same screen every message, and the chip isn’t shown.
• Nothing is attached while the dock is closed, from a tab you haven’t shared, or at a password prompt.

Your sent message shows the same chip; click it to see what was sent. Settings → Terminal → Attach terminal context automatically turns this off.

The tmux panes outside Chatty are a separate switch, Enable Terminal Access in Settings → Code Execution (see Agents and tools).

Settings

Settings → Terminal:

Dragging the dock’s top edge updates Dock Height too.

Agents & tools

When to read this: You want to understand how the agent works, switch its tools on, and see what it can do once they are.

How the loop works

Each message builds an agent from your enabled tools and extensions, then runs a streaming multi-step loop:

You send a message
       │
       ▼
  Agent reasons → decides to call a tool
       │
       ▼
  Tool runs (with your approval if required)
       │
       ▼
  Agent reads the result → reasons again
       │        ...repeats until done, or up to Max Agent Turns (default: no limit)...
       ▼
  Agent streams its final answer to you

Tool calls, inputs, outputs and reasoning render as collapsible trace blocks beside the reply (Chatting).

The loop also watches itself while it runs, so a bad turn recovers instead of quietly failing: a model that’s still reasoning is not mistaken for a hung one, a turn that comes back with nothing is retried rather than treated as done, and a model stuck re-issuing the same tool call is nudged onto a different one. A tool’s own error message reaches the transcript intact, so a failure is reported as a failure rather than read back as a success.

For multi-step work the agent writes a plan first: a goal and an ordered to-do list. A To-dos card appears in the transcript and updates in place (pending, in progress, done, blocked) with a progress counter. Scroll past it and a compact Plan N of M strip pins to the top of the transcript — click to unfold the plan, or press Esc to dismiss the overlay without cancelling the run. The agent ticks steps off as it goes and runs a verification step before its final reply. In the terminal interface the card renders inline in the transcript instead, and its position also appears in the status bar — see Terminal interface.

The agent can also pause mid-turn to ask up to 4 clarifying questions, each with pre-made options plus a free-text answer (ask_user). It shows up as a card above the chat input; pick an option or type your own answer, then submit. Questions you leave blank are sent as unanswered so the agent knows what it still doesn’t know. In the terminal interface it replaces the input row instead — see Terminal interface.

Enable tools

Everything below is off until you switch it on in Settings → Code Execution:

1. Set a Workspace Directory (an absolute path). File, shell and git tools can only touch files inside it.
2. Turn on Enable Code Execution.
3. Choose an Approval Mode — what they mean is on Security & sandboxing.

Optional switches on the same page: Enable Terminal Access (read-only view of your tmux panes, below), Enable Git Integration (git tools and the pull request bar), Enable Browser Tools with Allow Browser Access to Private Network, Enable Code Execution Tool with Enable Docker Fallback and a Docker Host field, plus Max Agent Turns, a command Timeout, a Max Output size and Network Isolation. Web access has its own page, Settings → Internet, and is on by default.

Per-chat working directory. The folder icon in the composer (Select Working Directory) overrides the workspace for that conversation; × resets it to the global one. The override is saved with the conversation. /cd <dir> does the same from the keyboard, and /add-dir <dir> widens the workspace by one more directory.

Project instructions (AGENTS.md / CLAUDE.md)

If your project has an AGENTS.md or CLAUDE.md — the instruction files other coding agents read — Chatty’s agent reads them too and follows them. It looks in the working folder and in every folder above it up to the root of the git repository, taking AGENTS.md when a folder has both. A personal file for every project goes in ~/.agents/AGENTS.md (or ~/.claude/CLAUDE.md). The most specific file comes last and wins when two disagree; what you ask in the chat still overrides them. Files are read when a conversation starts or its working folder changes, and very long files are cut off after the first 32 KB.

What the agent can do

Tool names and their exact scopes are in the tools catalog; this is the map.

Files and code

The agent can read files, list directories, search by glob or content, jump to a definition, and create, edit, rename, move or delete files — always inside the workspace. Edits show as diffs in the transcript. With git integration on it can also inspect status and diffs, stage, commit and merge branches.

Rename the User struct to Account across the project and update every import.

Reads never ask. Writes, deletes and git changes follow your approval mode; inside the workspace they apply immediately under either auto-approve mode.

Shell and running code

Shell commands run in a persistent session inside the sandbox, with streaming output, the workspace as its working directory and your secrets available as environment variables. Enable Code Execution Tool adds a code runner: simple Python runs on the host in milliseconds; with Enable Docker Fallback (Docker must be running) the agent can also run JavaScript, TypeScript, Rust, Bash and Python that needs third-party packages, each in a fresh container. Chatty finds the Docker socket on its own, including rootless Docker and Docker Desktop; Docker Host covers unusual setups (for example /run/user/1000/docker.sock).

Run the test suite, fix whatever fails, and run it again.

Shell commands and code runs follow your approval mode; sandboxed commands run without prompting under Auto-approve Sandboxed.

Enable Terminal Access (off by default) lets the agent read your own terminal: the tmux panes you have open, as plain text, through the read-only terminal_read tool. It cannot type into them or run anything there. Without a pane named it reads the one you were in last, so after a failing build in another pane you can simply ask:

What failed in my terminal?

The agent sees whatever the pane shows, secrets included, so leave it off unless you want this. The tool is only offered while tmux is running; in the terminal interface the group is called terminal (--enable terminal, or /tools).

In the desktop app you can also share the terminals in its own terminal dock, one tab at a time, with the eye icon on the tab; that needs no setting, and a tab you never share is never read. A tab shared as Read + run also lets the agent run a command there (terminal_run), and every such command asks for your approval first, even under Auto-approve All: it runs in your own shell, not the sandbox. See Letting the agent run a command in your terminal.

Data and documents

The agent can run SQL over CSV, Parquet and JSON files in the workspace and describe their schema — Excel and ODS files too — read and write Excel, Word and PowerPoint files, extract text and page images from PDFs, typeset PDFs and draw charts. Results open as artifacts beside the chat.

Load sales.parquet, chart revenue by region for the last four quarters, and write a two-page PDF summary.

Reading and querying never ask. Writing spreadsheets and other files follows your approval mode.

Web and the built-in browser

With Settings → Internet on, the agent can search the web (Tavily or Brave if you add a key, a basic fallback otherwise) and fetch any public page as readable text. A rate-limited fetch is retried automatically, and a page that’s blocked or gone is served from the Wayback Machine’s closest archived copy instead, labelled with its capture date. The same page also holds optional cloud services — a hosted browser agent and a cloud code sandbox — which need their own API keys and stay off until you add one.

Better keyless results with a local reranker. Without a search API key, you can have the results reordered by a small cross-encoder model on your own machine. Fill in Rerank Endpoint and Rerank Model under Settings → Internet → Keyless search, then press Test. In our evaluation this took the right page in the top five from 48 % to 57 % of questions, and the right page at the very top from 27 % to 49 %. The cost is about one second per search (p95 went from ~2.3 s to ~3.2 s). If the endpoint is down, search keeps working and returns results in their normal order. The reranker is not used when a Tavily or Brave key is set.

Any server with a Cohere/Jina-style /rerank endpoint works. For BAAI/bge-reranker-v2-m3 (about 1.1 GB of GPU memory at fp16, or ~600 MB as a GGUF on CPU), use one of:

# vLLM (GPU); vLLM recognises the model as a reranker by itself
vllm serve BAAI/bge-reranker-v2-m3 --port 8001 --max-model-len 1024
# endpoint: http://127.0.0.1:8001/rerank   model: BAAI/bge-reranker-v2-m3

# llama.cpp (CPU or GPU), with a GGUF build of the same model
llama-server -m bge-reranker-v2-m3-Q8_0.gguf --reranking --port 8001
# endpoint: http://127.0.0.1:8001/v1/rerank   model: bge-reranker-v2-m3

The browser tools drive a real Chrome on your machine, so the agent can look at what it just built instead of guessing: it renders the page, screenshots it, spots the problem, fixes it, and re-checks. It can also click — a button, a link, a menu item — and fill in text fields, by picking an element out of its own snapshot of the page rather than guessing coordinates or positions; the click or typing is refused if the element moved, is covered by something else, or is off screen. Typing replaces a field’s contents and never submits it — that’s a separate click the agent makes on its own. The agent never types into a password or card-number field; those are always refused, so sign in yourself after taking control. While it works, a live view of the page docks beside the chat; you can click and type in it, and take control at any moment. Hand back & continue gives the browser back to the agent and tells it to take a fresh look at the page and carry on from there.

One limit worth knowing: the screenshot reaches the model on its next turn, not inside the tool result. In practice the agent captures the screenshot, finishes its turn, and reviews the image on the turn after. Say keep going if it stops after capturing.

A link that opens a new tab or window — target="_blank", window.open, a “Sign in with…” popup — is followed automatically: the live view, your clicks and typing, and the agent’s own tools all switch to the new tab. Open tabs sit in the artifact panel’s tab bar next to the open files, each with a globe icon and a × to close it, so you can click back to the page underneath (or to a file) while the popup is still open. Switching to a file leaves the browser tabs in the bar; clicking one brings the page back. Closing the tab you are on shows the one next to it, and closing the last one leaves a blank page. Only the tab you are looking at is streamed live. The same address filtering applies to whatever any tab navigates to, on its own or otherwise: a tab that lands somewhere the browser is not allowed to reach is marked blocked in the bar and shows nothing until it comes back somewhere allowed.

By default the browser is limited to localhost and files inside your workspace — it is for reviewing your own work. With Internet access on it can also open public websites, with the same address filtering as fetch and search so private and internal network targets stay out of reach. If you need it to reach something on your own network — another machine on your LAN, say — turn on Allow Browser Access to Private Network; cloud-metadata addresses (169.254.x.x) stay blocked either way. The browser profile is never signed in to anything, so looking at a page never asks for approval. Clicking and typing are the exception: on localhost and workspace files they’re automatic, but a click or a keystroke on any other site asks you to approve it first, every time — the agent may be acting inside a session you’re logged into under take-control, and that always gets a confirmation. Turn the tools on with Enable Browser Tools; they need a workspace, where screenshots and console logs are kept.

Chrome is not bundled. If you already have Chrome, Chromium or Edge installed, that is used; otherwise the first browser call downloads a pinned Chrome for Testing build — roughly 190 MB, once — showing progress in the panel while it downloads, and verifies it before use. Expect that first call to take a minute.

Open http://localhost:3000, screenshot the checkout page at 375 px wide, and fix anything that overflows.

Memory, skills, sub-agents and planning

The agent can remember facts and preferences across conversations and recall them later, save a procedure it just worked out as a named skill and load it again (Memory & skills), hand independent subtasks to headless sub-agents, call agents you have installed as extensions, list its own tools and MCP servers, and keep the to-do plan described above.

Remember that this project uses pnpm, then split the migration into three sub-agents, one per package.

Memory, skills and planning never ask. Sub-agents run their own tool calls without prompting only under Auto-approve All.

Extensions

MCP servers, agents and modules from the Hive marketplace, the built-in catalog (Hugging Face, Notion, Atlassian, Google) and your own servers plug in under Settings → Extensions: Extensions.

Next

• Security & sandboxing
• Extensions
• Memory & skills

Extensions

When to read this: You want to give the agent more reach — MCP servers, remote agents and modules from the Hive marketplace, the built-in catalog, or a server of your own.

Settings → Extensions is one page with four parts: your Hive account, what is installed, the marketplace, and a form for custom servers. Plugins — WASM modules, from Hive or copied in by hand — are listed on their own page, Settings → Plugins. Enabled extensions show up on the new-conversation start screen and their tools become available on the next message.

Hive marketplace

Hive is the registry Chatty installs extensions from; the address it is talking to is shown next to Hive Account. Sign In or Register (username, email, password) to install from it and to run cloud modules; the session lasts thirty days.

Browse Marketplace searches the registry. Each result shows its type and pricing; Install downloads it into your module directory (the one set in the module settings) and adds it to your Installed list, Uninstall removes it. Chatty refuses a module whose name or version is malformed or whose download is over 64 MiB, and remembers each installed module’s checksum: if its file changes on disk afterwards, it no longer loads. Installed items carry two kinds of badge:

Paid plugins are metered wherever they run, including when an agent spec lists them and when a delegated worker calls them. Each module’s free calls are used first (the count comes from Hive); after that a call needs a positive credit balance, and every call is reported to Hive. If Chatty cannot read your balance — you are signed out, your sign-in has expired, or Hive is unreachable — a paid call is refused with “Cannot verify credits … sign in to Hive” rather than run unbilled. Delegated workers reuse the sign-in the desktop app saved, so if the app has been idle for over an hour, open it once to refresh the session.

The Teams tab next to the plugin listing finds published agent teams and installs them with one click; see Install a team from the marketplace.

Each row has Enable / Disable (🟢 enabled, ⏸ disabled), and modules that support both modes offer Switch to Local / Switch to Cloud.

Built-in catalog

A handful of well-known services are pre-loaded under Installed, disabled until you click Enable:

Sign-in tokens stay on your machine. The maintained list, with each service’s connection notes, is on the curated MCP catalog page.

Add a custom MCP server

Chatty connects to servers you run; it does not launch them.

1. Start the server yourself and note its URL.
2. Add Custom Extension → Add MCP Server.
3. Give it a name (for example github-mcp), the URL (for example http://localhost:3000/mcp) and an optional API key, then Add.

The server appears under Installed with an ↗ External badge. The agent can list your servers at runtime, but any key you enter is masked — the model never sees the real value (Security & sandboxing).

Tip

Servers to try, with their start commands, are collected on the curated MCP catalog page. Write your own against the MCP specification.

Remote A2A agents and private networks

A remote A2A agent (installed from the marketplace or added as a custom extension) is called over HTTP, the same as an MCP server. By default it can only be reached at a public address or localhost: a name that resolves to your LAN, your Tailscale tailnet, or any other private range is refused, so a malicious or compromised marketplace agent can’t be pointed at your own network.

If you run an agent yourself on your LAN or tailnet, turn on its Private network toggle (next to Enable/Disable under Installed) to let that one agent reach a private address. It admits the same ranges as the browser’s Allow Browser Access to Private Network toggle: RFC-1918 LAN addresses, Tailscale’s CGNAT range, and IPv6 unique-local addresses. Cloud-metadata addresses (169.254.x.x) and IPv6 link-local addresses stay refused either way. A private-network agent still needs https://: plain http:// only ever works for localhost.

Turn this on only for an agent whose address you control. The check runs against whatever address the agent’s name resolves to at the moment of each call, not once when you add it — so if the name is ever pointed somewhere else (DNS rebinding), the opt-in lets that new address through too, private range or not.

Build your own module

Modules are small programs that run inside Chatty, locally or on the Hive runner. The developer guide Build a WASM module walks through it, with two worked examples: write a plugin (echo) and give an agent the plugin (benford).

A module is a plugin: tools an agent runs, never an agent of its own. Installing one adds it to the module directory and nothing more; an agent uses it once its spec lists the plugin under [[plugins]] and grants a subset of what the plugin asks for — an LLM call, a file read, billing, and so on. Anything not granted is refused to the plugin, not silently allowed. Settings → Plugins lists every plugin with its tools, what it requests, trust level and the agent specs that use it, each with what it actually grants; Settings → Agents shows the same requests-vs-grants breakdown for each spec’s plugins. A module you copy into the module directory yourself shows Trust: local: Chatty loads it because you put it there, but nothing vouches for it.

If a module fails to load — an invalid module.toml, a missing .wasm file, a name that clashes with another installed module, or an installed .wasm that changed on disk since it was installed (hash mismatch) — its row shows Failed to load: with the reason, instead of failing silently. Reinstall a module that fails with a hash mismatch.

Use a plugin from another MCP client

A plugin whose module.toml sets [protocols] mcp = true is also served to MCP clients outside Chatty, by the desktop’s module gateway (Enable module runtime in Settings → Plugins). Served that way there is no agent spec to grant from, so a plugin gets only logging and config by default. If it asks for an LLM call, a file read or billing, its row in Settings → Plugins shows a switch for each, off until you turn it on; switching one on reloads the gateway. The gateway starts the first time an agent delegates, and Settings → Plugins then shows where it runs.

The gateway has no network port. It listens on a Unix socket in a folder only you can open, and answers only a caller that sends the token Chatty writes there each time it starts the gateway:

• Socket: gateway.sock in $XDG_RUNTIME_DIR/chatty-run. Without XDG_RUNTIME_DIR (macOS, some Linux setups) the folder is chatty-run in your cache folder: ~/Library/Caches or ~/.cache.
• Token: gateway.token, next to the socket, readable only by you. Send it as Authorization: Bearer <token>; it changes every launch, so read it from the file each time.

dir="$XDG_RUNTIME_DIR/chatty-run"
curl -s --unix-socket "$dir/gateway.sock" http://localhost/mcp/echo \
  -H "Authorization: Bearer $(cat "$dir/gateway.token")" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A client that can only reach an HTTP URL needs a local bridge from a port to the socket. The bridge answers anyone who can reach that port, so bind it to 127.0.0.1 and still send the token.

Chatty refuses to start the gateway when the chatty-run folder is someone else’s or can be opened by other users (anything but mode 700); remove the folder and it is recreated correctly. On Windows the gateway does not start yet: it needs an owner-only folder there, which Chatty does not create yet, so external MCP access (reaching a plugin’s tools from another MCP client) is macOS/Linux-only for now.

Next

• Agents & tools
• Security & sandboxing
• Sub-agents

Install a team from the marketplace

When to read this: Someone published an agent team for a job you have — a payment run, an architecture review, a data analysis — and you want to run it on your machine without copying spec files by hand.

A team on Hive is a published agent spec (its leader) plus the specs it delegates to that the same publisher published (its members). Each spec is signed by its publisher, and every plugin a spec uses is locked: pinned at publish time to one exact version and the SHA-256 of its bytes. Installing a team gets you exactly what was published, or nothing.

Find a team

1. Settings → Extensions, and sign in to Hive under Hive Account (installing needs your account; browsing does not).
2. Under Browse Marketplace, switch to Teams and search by name, publisher or task (an empty search lists every team).

Each team shows:

Install it

Click Install team. Chatty then:

1. fetches the leader’s spec and each member’s;
2. checks each spec’s signature chain against the registry root keys built into Chatty, and that it is the name and version asked for. A spec that was changed after signing, or signed by a key the registry never certified, stops the install;
3. downloads each locked plugin through the same signed install path as Install on the Plugins tab, and checks that its bytes have the SHA-256 the lock pins;
4. writes the specs to your global agents folder (~/.local/share/chatty/agents/ on Linux, ~/Library/Application Support/chatty/agents/ on macOS);
5. adds the leader to your roster.

Nothing is written until every check has passed. A confirmation then names the agents that were installed.

If a spec of the same name is already in your agents folder (your own, or part of another installed team), the install stops and tells you which file is in the way. Rename or remove it first.

Paid plugins. A team may use paid plugins. They install like free ones, but each call needs credits and the plugin’s billing grant under Settings → Plugins, the same as a paid plugin you install yourself. The confirmation names each one.

Paid teams (a fee per run) are not available yet. Such a team shows Paid team · not available yet, and installing it is refused.

Run it

Start a chat and type /agent . The leader is in the picker. Pick it and give it the task, e.g. /agent payments-lead Check vendors.csv before Friday's run. The leader delegates to its members as its spec says, and Settings → Agents lists every installed spec as served.

If you declared a roster yourself (virtual_agents in the module settings), Chatty adds the leader and the agents it delegates to there too, and removes them again when you uninstall.

Update or uninstall

• Update team appears when a newer version is published. It runs the same checks and replaces the team’s specs and plugins with the new version’s.
• Uninstall removes the team’s specs, the roster entries it added, and each plugin it installed that no other installed team still uses. A plugin you had installed yourself before the team stays.

From the terminal

chatty-tui --install-team payments-lead          # the latest version
chatty-tui --install-team payments-lead@1.0.0    # an exact version

This does the same checks with the Hive sign-in the desktop saved, prints what it installed, and exits. Run the team in the TUI with chatty-tui --broker, then /agent payments-lead <task>.

Memory & skills

When to read this: You want the agent to remember things between conversations, or to reuse a procedure it has worked out once.

Memory

Memory is on by default. The agent stores facts, preferences, decisions and project conventions as it works — you can also just tell it remember that we deploy from the release branch — and searches them when earlier context would help. Everything is kept in a local file on your machine (where); nothing is uploaded.

Out of the box, recall is full-text search. Semantic Search adds search by meaning, so how do we ship? finds the note about the release branch; it needs an embedding provider.

Settings → Memory

• Enable Agent Memory — the master switch.
• Purge All Memory — permanently delete every stored memory. This cannot be undone.
• Enable Semantic Search, with an Embedding Provider (it can differ from your chat model’s provider) and an optional Embedding Model — leave it empty for the provider’s default.
• Memory Browser — Load Memories, search them, Refresh, and Delete individual entries.

Note

Memory is shared across conversations and across the desktop and terminal apps, so a fact the agent learns in one chat is available in the next.

Skills

A skill is a named, reusable procedure — deploy-to-staging, write-unit-tests — that the agent can load and follow later. Ask it to save one (save what you just did as a skill called deploy-to-staging) and it writes the steps down under that name; on a later task it finds relevant skills through memory search and loads the instructions before starting.

You can also invoke a skill yourself: type / in the composer and pick it — skills appear in the picker with a skill badge.

A skill is a folder holding a SKILL.md file, in the Agent Skills format that Claude Code, Codex, opencode and Cursor also read. The folder name is the skill name; the description: line in the file’s frontmatter is what the picker shows:

---
name: deploy-to-staging
description: Build, tag and push the current branch to staging.
---

1. Run the tests …

Chatty looks for skills in two places:

• Project skills, next to your code so they travel with the repository: .agents/skills/<name>/SKILL.md or .claude/skills/<name>/SKILL.md. Chatty searches the conversation’s working folder and every folder above it up to the root of the git repository.
• Global skills, available in every project: ~/.agents/skills/<name>/SKILL.md or ~/.claude/skills/<name>/SKILL.md in your home folder. The path is the same on macOS, Linux and Windows (%USERPROFILE%\.agents\skills\ on Windows).

Use .agents/skills/ for new skills. Chatty reads .claude/skills/ as well, so skills you already have for Claude Code show up without copying them. When two skills share a name, the project skill wins over the global one, and .agents wins over .claude.

The / picker rescans these folders each time you open it, so a skill you add while Chatty is running shows up the next time you type /.

Next

• Agents & tools
• Sub-agents
• Advanced

Sub-agents

When to read this: You want the agent to split a job into parallel or isolated pieces, or you want to drive Chatty from scripts.

A sub-agent is a separate chatty-tui process the parent agent hands a task to, waits on, and reads the answer from. Each child has its own conversation, its own workspace copy, and the same configured models and tools. The parent asks for one through its invoke_agent tool, addressed to local-agent; the child reports its progress back over the local agent broker while it works. That broker hop was measured rather than assumed safe to add: paired against calling the child directly, its median added cost came out at 3 ms or less, well under the variance of a single model turn.

Why bother?

• Parallelism — independent subtasks run at the same time.
• Isolation — a child’s exploration and mistakes stay out of the parent transcript; only its final answer comes back.
• Composition — one agent’s output can feed the next.
• Focus — each child gets one narrow prompt.

Isolated file changes

Sub-agents work in the conversation’s workspace, the folder its folder chip shows, unless their team asks for isolation. A team whose team.json sets "isolate": true (a coding team would; for a roster in module_settings.json it is "team": { "isolate": true }) gives each spawned sub-agent its own git worktree on a new branch (sub-agent/<name>) instead, when the workspace is a git repository with at least one commit. That means two children editing the same file at the same time no longer silently overwrite each other — each keeps its own copy. The branch name is unique per repository: if sub-agent/<name> is already taken (for example, two sub-agent leaders on the same repo naming a worker the same thing), Chatty picks sub-agent/<name>-2, -3, and so on. When a child finishes, its changes are committed to its branch and the worktree is left on disk; the parent agent merges the branch to take the changes. The tool result includes a fenced evidence block naming the actual branch, its commit count, and a diff summary against the base branch — if the project declares a verification command, its exit code and last lines are in there too. A child that committed nothing gets no evidence block, since there’s nothing to merge. If a worktree can’t be created at all (a repository with no commits yet, for example), the delegation fails before the sub-agent starts, rather than silently falling back to a shared tree: you get a red Could not start card saying what failed and what to do, and the agent that asked stops instead of retrying.

Note

If the workspace isn’t a git repository, sub-agents fall back to sharing the parent’s tree as before, so parallel children editing files can still collide.

From the chat

Type /agent <your prompt> to launch a sub-agent inline and watch its progress in the transcript. /agent <name> <prompt> sends the prompt to a named agent instead: one of your agent specs (see Named workers and roles below; a built-in one such as researcher), or a remote agent you have installed as an extension. A name that is neither is just the first word of the prompt. An agent whose spec sets callers is a team member, not an entry point: /agent <member> is refused with a note naming the team to use instead (for example /agent crosscheck-lead), and the picker lists only team leads and standalone agents. In the desktop app, typing /agent (with the space) opens a list of the agents this conversation can reach; type to filter it, and Enter or Tab puts the chosen name in for you.

/agent hands the task to the same local agents the assistant itself delegates to, so the delegation row — and the swarm tree below, when that agent delegates in turn — looks exactly as if the assistant had made the call. If the agent fails or stops before answering, the row ends with the error.

Every local agent is a spec, whoever wrote it. The desktop lists them all on Settings → Agents — name, model, role, the plugins each runs with and what they may do, whether other agents may call it — along with any spec file that doesn’t load and why. In the terminal, /agents prints the same list.

The swarm tree (desktop)

When a sub-agent delegates in turn, its row in the desktop transcript opens into a live tree of agents. Each line shows the agent, its model (or the tool it is running right now), its status and its spend.

• Click a line to open that agent’s transcript, read-only, in a side sheet. The sheet shows a breadcrumb (lead › writer-0 › drafter-2), the agent’s spec, model, status, turns and spend, its sub-agents and its tool calls. Once a run has finished, the sheet shows its conversation as chat — the prompt, the agent’s text and foldable groups of tool calls; a run still in progress, or one with no captured conversation, lists its tool calls with their arguments and the first lines of each result. A conversation too large to capture says so. The sheet scrolls, as do the footer popovers (agents, MCP, tools, PR checks). Click a sub-agent to go down, or a crumb to go back up. Press Escape or click outside to close it.
• Fold an agent with its arrow, or the whole card from its header.
• An agent with many sub-agents shows the first few plus any that are still running or failed, then a +N more done · show all line.
• Stop on a running agent’s line, or Stop this agent in its sheet, stops that one agent and every agent it started. The rest of the swarm keeps running. The agent that called it is told cancelled_by_user and carries on without it. Any approval or question the stopped agents were waiting on is withdrawn, and the line shows as canceled.
• If you stop a turn, runs still drawn as running show as canceled.

Every running agent at once

While any conversation has agents running, the status bar shows a N running chip next to the agents chip (amber, with how many are waiting, when one of them waits on you). Click it to open the running-agents panel: one row per live agent across all your conversations, with its conversation, the agents above it, whether it is working or waiting on your approval or answer, how long it has run, and what it has spent so far. Click a row to jump to that conversation with the agent’s transcript open; Stop on a row stops that agent and every agent it started, like Stop in the tree. The list updates as the agents report; nothing is polled.

A single delegation with no further delegation keeps its plain row. Its ↗ button (on the “Sub-agented” row, once its activity is unfolded) opens that agent’s transcript in the same side sheet; it is greyed out until the agent has started. While an agent is running, its transcript sheet has a message box under the transcript: what you send is read by that agent at its next tool call, not at the end of its run (in the terminal, /msg <agent> <text> does the same). In the terminal, /swarm prints the same tree as text, /agents running prints the running-agents list, and /stop <agent> stops one agent by the name /swarm shows.

Let the agent decide

With tools on (Agents & tools), the parent can ask for children itself when a task splits cleanly:

Task: "Refactor all modules and write tests for each"

→ sub-agent: "Refactor the authentication module and write tests"
→ sub-agent: "Refactor the billing module and write tests"
→ sub-agent: "Refactor the notifications module and write tests"
→ Parent merges the results into a final summary

Note

A child asks before its side effects the way the parent does. When a worker, however deep in the tree, wants to run a command or write a file, the request climbs the chain to your approval card. The card names the agent that asked and its path (data-coder-0 (root › coordinator › data-coder)). Your answer goes back down to that worker only. See Security & approvals.

Note

Children of one local model server queue rather than run all at once, so a local model is not thrashed by a wide fan-out. The limit is default_endpoint_budget in your module settings (hosted APIs such as OpenRouter allow four at a time).

From the terminal

# One headless call
chatty-tui --headless -m "Summarize the changes in the last 5 commits"

# Pipe input
git diff HEAD~3 | chatty-tui --pipe

# Chain: the first agent lists TODOs, the second works through the list
chatty-tui --headless -m "List all TODO comments in src/" | chatty-tui --pipe

--auto-approve skips approval prompts for scripted runs; --enable / --disable pick tool groups per run. Install, modes and keys: Terminal interface.

Add --broker to let that terminal leader spawn sub-agents of its own — without it, only the desktop app can delegate to local-agent:

chatty-tui --headless --broker -m "Refactor the auth module and write tests"

--broker works with --headless, --pipe, and the interactive TUI, and is Unix only.

Named workers and roles

Out of the box the parent can reach local-agent — your default model with the parent’s tools — the built-in agents (researcher, reviewer, writer and the crosscheck-lead / crosscheck-data-lead team leaders), and every spec of your own that doesn’t opt out with exposed = false under [swarm]. A spec that names its callers (a team’s internal members, such as crosscheck-judge) works only for those agents and is never offered to the parent. You can declare your own named workers, each with its own model, a role that limits what it may do, and standing instructions. The parent sees each one as a card — its name, model, role and the first sentence of its instructions — and picks by reading, the same way it would choose a colleague. Nothing else about the parent changes: the prompt and the tool stay identical whether the roster is empty or five deep.

Declare each worker as an agent spec: a small TOML file named after the worker, in your project’s .chatty/agents/ folder (or in Chatty’s data folder under chatty/agents/ to share it across projects — where that is):

# .chatty/agents/local-coder.toml
[agent]
name = "local-coder"
model = "qwen3:14b"
preamble = "You are the coder. Make the smallest change that makes the task's check pass, run it, and report the files you touched."

[tools]
profile = "coder"

[budget]
max_agent_turns = 30

# .chatty/agents/local-reviewer.toml
[agent]
name = "local-reviewer"
model = "gemma3:27b"
preamble = "You are the reviewer. Read the diff, run the tests, and report what you found; never edit the tree."

[tools]
profile = "reviewer"

A spec file is picked up as soon as it exists (on the desktop, Settings → Agents → Reload). To narrow the roster to just some of them, list them by name in module_settings.json, next to your other settings, and restart. This roster is used by the desktop app and by a terminal leader started with --broker:

{
  "virtual_agents": ["local-coder", "local-reviewer"],
  "team": { "verification": "python3 -m pytest -q" }
}

On the desktop, the enabled field is the Enable module runtime switch in Settings → Plugins. It loads WASM modules; agents do not need it, because the local agent broker runs either way.

A module_settings.json that still describes workers inline (the format before agent specs) no longer loads; move each entry into its own spec file.

A spec in your project folder wins over one of the same name in the data folder, which wins over the built-in ones (the members of the teams below). chatty-tui --agent <name> runs the terminal app as any spec.

The three roles:

A role only ever removes tools: it cannot turn on a tool group you switched off under Settings → Code Execution (or with --disable).

team.verification is one command for the whole roster. When a worker finishes, Chatty commits its branch and then runs that command itself in the worker’s tree — not through the worker — and puts the exit code and last lines into the evidence block the parent reads, next to the branch name, commit count and diff summary. That’s the parent’s proof that the coder’s “tests pass” is true. It is skipped for a worker whose role has no shell, since that worker could not have built anything for it to check.

A worker’s side effects come to you for approval like the leader’s own, whatever its depth (Security & approvals). In an unattended terminal run, --auto-approve lets them through. The full field reference, including how a worker is metered and started, is on the developer page: Named virtual agents.

Teams

--team <id> packages a roster like the one above with a leader and a verification command into one directory, so a run is reproducible and the leader has a role too: a named leader plus co-workers, each with its own model, role and standing instructions, defined once in teams/<id>/team.json, which names the leader’s spec and the workers’ specs. It implies --broker, and for that run the team’s agents replace whatever virtual_agents your module settings declare.

In an unattended run (--headless, --pipe), chatty-tui prints one line to stderr per agent, before the first turn, when that agent’s tool profile (for example coder or reviewer) wants the shell or git but the run has it off (enabled=false, git_enabled=false). It also prints a line when the team’s verification command is set but shell is off. The leader’s --enable, --disable and --only flags are forwarded to every worker, so --enable shell,git gives the whole team a shell and git, and the warnings follow those final settings. These are warnings only; the run goes on unchanged.

Two teams ship built in, both experimental: they are free, run on your own model, and become documented defaults only once a measured result supports them.

See Crosscheck for when it pays and what it costs. chatty-tui --team <id> runs a team from the terminal. The desktop has no team switch: the team’s leader is on the default roster, so /agent <leader> … runs it, since the leader is an agent like any other. Three standalone agents ship too: researcher, reviewer and writer.

--model runs every agent of the team on that model for the run, including agents whose spec names a model of its own; --tools and --preamble override the leader’s settings. Bring your own team by adding <workspace>/.chatty/teams/<id>/team.json, which overrides both the built-in preset and any team of the same id under your data directory. File format and search order: Teams.

A team can also make what one role hands the next explicit and checkable: team.json’s optional handoffs names a JSON Schema per role, as a path relative to the team directory. A worker running as that role must end its final answer with a fenced json block matching the schema — get it wrong once and Chatty sends the answer back listing the schema errors; get it wrong again and the delegation fails, with the errors visible to the leader. A team with no handoffs behaves exactly as before.

Next

• Tutorial: from one agent to a team: the desktop walkthrough with a data team, approvals, the bill and mixed models
• Tutorial: your first named worker — twenty minutes, one reviewer, real hand-off
• Tutorial: a small agentic team — a coding team directory of your own, with its own playbook
• Tutorial: an autonomous dev team — five agents run unattended in a loop, story by story
• Terminal interface
• Agents & tools

Crosscheck: several attempts, one judged answer

When to read this: One answer from the model is too often plausibly wrong for the job — a figure from your data, a list, a fix whose tests must pass — and you would rather spend more tokens than check it yourself.

Crosscheck is a built-in team: several independent attempts at the same task, and a judge picks the strongest. It is free and runs on your own model. It is experimental: it ships so you can use it, and it becomes a documented default only once a measured result supports it (see What it is worth).

What it does

1. Three attempts at once. The leader hands your task, word for word, to three solvers. Each runs as its own agent with its own context: none sees another’s work. They approach the task differently — one directly, one after writing a plan, one after deciding how it will check its answer — so their mistakes are less alike. They run at the same time when your model server takes several requests at once (see Speed).
2. A check, when there is one. If the team declares a verification command (a test suite, a checker script), Chatty runs it on each attempt’s own copy of the project. An attempt that passes wins; the judge is not asked.
3. Otherwise a judge picks. The judge reads every attempt’s final answer and its trace — the commands and code it ran and what they printed — and names one. It never writes an answer of its own: what you get is the chosen attempt’s answer, character for character. When all attempts give the same answer, no judge is needed. The judge never thinks out loud (thinking is off for it), which was both faster and more accurate in our tests.
4. The cost is on screen. The reply starts with a line like 3 attempts + judge, 41,200 tokens (≈3.4× a single run), then the answer, how it was chosen, and each attempt’s answer.

Two versions ship:

Run it

From the terminal:

chatty-tui --team crosscheck-data -m "What was the average transaction value in March 2023, in EUR, rounded to 2 decimals?"

In the desktop app there is no team switch yet: name the team’s agents in virtual_agents in module_settings.json, restart, and send /agent crosscheck-lead <task> (or /agent crosscheck-data-lead <task>):

"virtual_agents": ["local-agent", "crosscheck-lead", "crosscheck-solver-direct",
  "crosscheck-solver-plan", "crosscheck-solver-verify", "crosscheck-judge", "crosscheck-writer"]

The team’s members are not offered to you one by one: they work only for their leader.

What it costs

About three and a half single runs: three attempts, plus a judge when they disagree. The banner shows the real figure for each run, measured against the attempts themselves. It is opt-in per conversation and never the default, because most tasks do not need it.

Use it when a wrong answer is expensive and the task has one right answer: a number from a dataset, a yes or no, a fix with tests. Skip it when the work is long and sequential (a refactor, a report built step by step): independent attempts do not help there, and coordination teams in general have not made sequential work more accurate.

Speed

The attempts run at once only if your model endpoint allows several requests at a time. Chatty sends one request at a time to a model server of your own (on this machine or your network) unless you raise its budget; a hosted API such as OpenRouter already gets four at a time. To raise it: set num_parallel in the provider’s extra_config, or default_endpoint_budget (or a per-endpoint entry in endpoint_budgets) in module_settings.json, to 3 or more. With a budget of one, the attempts queue and the run takes about three times as long.

What it is worth

In our tests, independent attempts plus a judge finished 8 to 22 points more tasks correctly than a single attempt on the same model, at 2 to 3.3 times the tokens. All runs used the local RedHatAI/Qwen3.8-27B-INT4 on vLLM, with both arms sharing the same harness, tools and data:

The judge matters: on the subset’s disagreeing tasks it picked a correct answer 16 times out of 18, against 9 for a majority vote.

Read these as the size of the gain, not as scores. The first two rows used DABstep-specific helpers in both arms, which raises the absolute numbers but not the gain. The last two rows are small. It is one model in one domain so far, and the pre-registered gate on the 18-task run missed its no-harm check by one task, so Crosscheck ships as opt-in and experimental.

Tutorial: from one agent to a team

When to read this: You have Chatty installed and a model connected, and you want to see a team of agents do real work: a lead that plans and delegates, specialists that each do one job, and you in charge of anything that touches your machine. Ten minutes of reading, plus a few minutes of the agents working.

What you will do

You give a sales export to a three-agent team and ask it a real question: revenue fell in August. Why? A lead breaks the question down, an analyst answers it with SQL queries, and a reviewer works out the key numbers again before you see the report. On the way you will:

1. set up the example;
2. look at the agents Chatty ships;
3. start the team with one command;
4. watch the team work, live;
5. approve the file a worker wants to write;
6. read the result, and who spent what, per model;
7. move one agent to a second, smaller model;
8. build a two-agent team of your own.

Note

Agent teams are supported and experimental. The shipped teams show what Chatty can do with a team. They are not a claim that a team beats a single agent; that research comes later. Try them, and compare with a single agent on your own tasks.

Prerequisites

• The Chatty desktop app, on Linux or macOS (Getting started). Teams need the local agent broker, which is not available on Windows yet.
• One model that is good at tool calls. The screenshots use Qwen3.8-27B-INT4 served by a local vLLM, added as an OpenAI-compatible provider (Providers & models). A hosted model works just as well.
• For step 7, a second model, for example qwen3:4b in Ollama.
• A folder for the data. This page uses ~/sales. It does not need to be a git repository, and if it is one, nothing about it matters: the team works in the folder itself.

1. Set up

Write the team. The reviewer ships with Chatty; the lead and the analyst are two short files you write. Create ~/sales/.chatty/agents/ (the sample data goes in ~/sales below) and put these two files in it:

# ~/sales/.chatty/agents/data-lead.toml
[agent]
name = "data-lead"
description = "Team lead: answers a business question about a data file with an analyst and a reviewer"
preamble = """
You lead a data analysis and compute nothing yourself.
1. Turn the question into two to four sub-questions a script can answer: the totals, which segments changed and by how much, and whether volume, price or discount moved in each.
2. Ask data-analyst to answer them, naming the file.
3. Write the report: the answer in one or two sentences, then each finding with its numbers and its share of the change, then what to do next. Every number comes from the analyst, never from you. Where the data shows how much but not why, say so instead of guessing a cause.
4. Send reviewer the report and the file's path. On REQUEST_CHANGES, fix exactly what it lists, asking the analyst again only for a disputed number, and send the report back once.
5. Ask data-analyst to save the reviewed report, exactly as written, as report.md next to the data file.
Your final answer is the reviewed report, with any notes the reviewer still has."""

[tools]
profile = "coordinator"

[swarm]
delegates_to = ["data-analyst", "reviewer"]

[budget]
max_agent_turns = 16

# ~/sales/.chatty/agents/data-analyst.toml
[agent]
name = "data-analyst"
description = "Answers questions about a data file with SQL queries, and reports the exact numbers"
preamble = "You answer questions about data files with numbers you computed, never by eye. Compute every number with query_data (SQL over the file); look at the columns first. Break every change down by period and by each column that could explain it, and give each segment's share of the change. For each segment behind a large share, say whether volume, price or discount moved. Report numbers, not guesses. When you are asked to save a file, write exactly the text you are given."

[tools]
profile = "coder"
disable = ["shell"]

[swarm]
exposed = true

[budget]
max_agent_turns = 16

Add the team to your roster. Quit Chatty, then write module_settings.json (create the file if it is not there) and start Chatty again:

• macOS: ~/Library/Application Support/chatty/module_settings.json
• Linux: ~/.config/chatty/module_settings.json (or $XDG_CONFIG_HOME/chatty/module_settings.json)
• Windows: %APPDATA%\chatty\module_settings.json — teams need the local agent broker, which is not available on Windows yet (see Prerequisites)

{
  "virtual_agents": ["local-agent", "data-lead", "data-analyst", "reviewer"]
}

A file at the wrong path is simply never read: Chatty starts with the default roster (local-agent and your own exposed specs) instead, silently. If /agent data-lead … below ends up answering as local-agent instead, re-check this path first — see Where Chatty stores data for every platform’s config and data directories.

Get the sample data. orders.csv has 793 orders from July and August: date, region, channel, product, units, price, discount, promo code and revenue. Something happened in August.

mkdir -p ~/sales && cd ~/sales
curl -LO https://boersmamarcel.github.io/chatty2/assets/samples/orders.csv

Turn on code execution. In Settings → Code Execution, turn on Enable Code Execution and set the approval mode to Always ask. Reading files and querying data never ask. Running a command or writing a file does, including when an agent deep inside the team wants to do it. The default mode, Auto-approve sandboxed, lets sandboxed commands and writes inside the workspace through without asking. With it, this run asks you nothing.

Point the chat at the folder. Start a new chat. Under the message box, next to +, is the folder chip: it shows the folder this conversation works in. Click it and pick ~/sales. Every agent the team starts reads and writes in this folder, so orders.csv has to be in it.

Check your setup. Three things, before you ask anything:

1. The folder chip reads sales.
2. orders.csv is in that folder: ls ~/sales lists it.
3. Type /agent (with the space) in the message box. The list that opens shows data-lead, data-analyst and reviewer. If it does not, the roster from the first step was not read; see Common issues.

2. Meet the agents

Open Settings → Agents. Every local agent is a spec: a short TOML file that gives the agent a name, a role, a tool profile, plugins, the agents it may call, and a budget. The presets ship with Chatty. Your own specs go in <workspace>/.chatty/agents/.

This tutorial’s team is your two specs and the built-in reviewer:

Each line on the page also shows the agent’s model (none of the presets names one, so they run your default), its tool profile, which agents it may call, and any plugins it runs with. Settings → Plugins lists the WASM plugins an agent can load, with what each asks for and which agents use it. This team needs none; Give an agent a plugin shows how to add one.

3. Ask the team

Start a new chat and type:

/agent data-lead Revenue in orders.csv fell in August. Find out why.

/agent <name> gives the turn straight to that agent: your own model is not asked anything. Your message shows the workspace the team works in under it, so you can see at once that it is ~/sales. The lead gets the question and starts delegating.

If something in the setup is missing, Chatty says so before any agent starts, with a red Could not start card: what failed and what to do. No workspace, or code execution turned off, is caught this way. So is an agent that cannot be started at all; the agent that asked for it then stops, rather than trying to work around it.

4. Watch the team work

The turn opens into a live swarm tree. Each line is one agent: its model, or the tool it is running right now, then its status and the tokens it has used so far. Workers get numbered names (data-analyst-0), so you can tell a second call to the same role from the first.

Click a line to open that agent’s transcript in a side sheet: its spec, model, turns, spend per model, and every tool call it made with the input and result. The breadcrumb at the top (data-lead › data-analyst-0) takes you back up the tree.

5. Approve the report

When the reviewer has approved, the lead asks data-analyst to save the report as report.md. Writing a file is a change to your workspace, so it waits for you. The request travels up the chain, from worker to lead to you, and the card tells you who is asking and from where:

Click Approve (or press Alt+Y). Deny (Alt+Shift+N) sends the worker an error instead, and nothing is written. The decision goes back down the same chain, so only the worker that asked writes the file.

The analyst’s queries never asked: under Always ask, only commands and writes come to you. A worker that wants to run a command asks the same way, with the command on the card.

6. Read the result and the bill

After a few minutes the lead answers with the reviewed report. On the sample data, a good answer has three parts:

• The size of the drop: August revenue is 43,886 against 53,251 in July, 17.6% down.
• The biggest driver: fewer Pro orders (132 down to 91) at an unchanged price, most of them in the EU. EU Pro alone went from 47 orders to 14, about 6,600 or 70% of the drop.
• The second driver: the SUMMER30 code, 30% off Starter bought online from 1 August. It gave away about 1,760 in discounts, and Starter volume did not grow.

The data shows how much and where, not why fewer people bought Pro. A good report says so and suggests what to check, rather than guessing. Reports differ from run to run in how they slice the numbers; in our runs every one found both drivers.

Scroll back up to the tree. When the run has finished, every line shows what that agent used, and the header shows the total for the whole team. The side sheet splits an agent’s spend by model. A model with a price in Settings → Models shows in dollars; a local model like the one here shows in tokens. The conversation’s cost in the sidebar includes everything its agents spent.

7. Mix models

Every preset names no model, so the whole team runs on your default. To change one agent, copy its spec into your workspace and add a model line. A spec in <workspace>/.chatty/agents/ replaces the preset with the same name.

The reviewer’s job is narrow: query the data, compare, give a verdict. A small local model can do it. Add qwen3:4b under Settings → Models (Ollama provider), then create ~/sales/.chatty/agents/reviewer.toml:

[agent]
name = "reviewer"
model = "qwen3:4b"
description = "Checks a report against its sources and answers APPROVE or REQUEST_CHANGES"
preamble = "Verify, do not trust. You check someone else's report against the sources it rests on, and edit nothing. Re-derive at least two of its key facts yourself from the source (query_data on a data file, read_file on a document); take results a named tool or plugin produced as given. Check that every claim is supported and none is overstated. The first line of your answer is APPROVE or REQUEST_CHANGES, then a numbered list: what you checked, or what must change."

[tools]
profile = "reviewer"
disable = ["shell"]

[swarm]
exposed = true

[budget]
max_agent_turns = 12

model is matched against your model list the same way as the model selector: by id, by name, or by part of the model identifier. Ask the same question again. The tree now shows two models, and the side sheet bills each agent by model. A small model on a CPU is slow, so expect the reviewer’s turn to take longer.

A cloud model as the lead. The opposite mix is common too: a strong hosted model plans and writes, and cheaper local models do the legwork. Add a model line to your data-lead.toml and point it at a hosted model from your list:

# ~/sales/.chatty/agents/data-lead.toml: as before, plus the model line
[agent]
name = "data-lead"
model = "claude-sonnet"   # any model in your list: its id, name, or part of its identifier
description = "Team lead: answers a business question about a data file with an analyst and a reviewer"
preamble = """
You lead a data analysis and compute nothing yourself.
1. Turn the question into two to four sub-questions a script can answer: the totals, which segments changed and by how much, and whether volume, price or discount moved in each.
2. Ask data-analyst to answer them, naming the file.
3. Write the report: the answer in one or two sentences, then each finding with its numbers and its share of the change, then what to do next. Every number comes from the analyst, never from you. Where the data shows how much but not why, say so instead of guessing a cause.
4. Send reviewer the report and the file's path. On REQUEST_CHANGES, fix exactly what it lists, asking the analyst again only for a disputed number, and send the report back once.
5. Ask data-analyst to save the reviewed report, exactly as written, as report.md next to the data file.
Your final answer is the reviewed report, with any notes the reviewer still has."""

[tools]
profile = "coordinator"

[swarm]
delegates_to = ["data-analyst", "reviewer"]

[budget]
max_agent_turns = 16

A spec is one complete file. It is not a patch on the preset, so a copy keeps every section. Only the lead’s tokens are billed at the hosted price, and the swarm tree and the sidebar show the split.

8. Build your own two-agent team

A team is just agents that are allowed to call each other. Here is a lead that turns the findings into a memo for your sales director, and a writer it delegates to. Create these two files in ~/sales/.chatty/agents/:

# memo-lead.toml
[agent]
name = "memo-lead"
description = "Turns analysis findings into a short memo for a manager"
preamble = "You write nothing yourself. Give memo-writer the findings you were given and ask for memo.md: at most 200 words, the answer first, then one action per finding with who should take it. Check the memo covers every finding, then answer with its text."

[tools]
profile = "coordinator"

[swarm]
delegates_to = ["memo-writer"]

[budget]
max_agent_turns = 6

# memo-writer.toml
[agent]
name = "memo-writer"
description = "Writes short internal memos into a file"
preamble = "You write short, plain internal memos. Write exactly the file you are asked for, using only the facts you were given, then reply with its text."

[tools]
profile = "coder"

[budget]
max_agent_turns = 4

• delegates_to is the only thing that lets memo-lead call another agent. It can call memo-writer and no one else.
• The coordinator profile can read and delegate, but it cannot write or run commands. The coder profile can write files. Each file it writes still asks you first.
• [budget] caps each agent’s model turns, so a confused agent stops instead of running on.

Add "memo-lead" and "memo-writer" to virtual_agents in module_settings.json and restart Chatty: a roster you name is exactly those agents. Open Settings → Agents; both agents appear. Then paste the findings from step 6 into:

/agent memo-lead Write a memo to the sales director. Findings: <paste the answer and findings from the report>

When memo-writer wants to create memo.md, you get the same kind of card as in step 5. A minute later the memo is in ~/sales/memo.md: the answer first, then one action per finding, each with an owner.

Verify

• Step 6’s report puts the drop at 17.6%, names EU Pro as the biggest driver (about 70%) and the SUMMER30 discount on online Starter as the second (about 27%).
• The swarm tree shows data-lead with data-analyst and reviewer below it. After step 7, reviewer has a different model from the rest.
• ~/sales/report.md exists after step 5, and ~/sales/memo.md after step 8; you approved both writes.
• ~/sales has no .chatty/worktrees folder: this team works in your folder directly.

Common issues

Next

• More teams, all experimental: research-brief ships with this release (a folder of documents to a sourced brief, see Sub-agents), and analyst-panel, where three analysts answer on their own and an adjudicator picks one when they disagree.
• Tutorial: a small agentic team: the terminal version, a coding team with its own playbook
• Security & approvals

Tutorial: your first named worker

When to read this: You have used the agent and want to see delegation for real — one named worker with its own model and a role, doing one job for a leader — before building a whole team. Twenty minutes, nothing to install beyond Chatty and Ollama.

What you will end up with

A worker called local-reviewer that only reads and runs tests, a leader that finds it by name and hands it a review, and a transcript that shows the hand-off, the worker’s report, and the leader relaying it. Everything runs on your machine.

Prerequisites

• Ollama running locally with two models pulled: one for the leader and one for the worker. This page uses qwen3:14b for the leader and qwen2.5-coder:14b for the worker. They need to fit in memory together (about 20 GB of GPU or unified memory); on a smaller machine use one model for both and read the note at the end.
• The terminal app, chatty-tui (install). Delegation works from the desktop app too, but the terminal shows every hand-off as it happens, which is what you want the first time.
• Linux or macOS. The local worker broker is not available on Windows yet.

Steps

1. Make a small project to review

Any folder with some code will do. To follow along exactly, create this one — a bank account with a bug in withdraw and a test suite that does not catch it:

mkdir -p ~/bank/tests && cd ~/bank && git init -b main
cat > bank.py <<'EOF'
class Account:
    def __init__(self, balance=0):
        self.balance = balance

    def deposit(self, amount):
        self.balance += amount
        return self.balance

    def withdraw(self, amount):
        # bug: overdraft is allowed and negative amounts are accepted
        self.balance -= amount
        return self.balance
EOF
touch tests/__init__.py
cat > tests/test_bank.py <<'EOF'
import unittest
from bank import Account

class TestBank(unittest.TestCase):
    def test_deposit(self):
        a = Account(10)
        self.assertEqual(a.deposit(5), 15)
EOF
printf '__pycache__/\n' > .gitignore
git add -A && git commit -q -m "Bank account with a withdraw bug"
python3 -m unittest discover -s tests -t . && echo "one test, passes, bug not caught"

It has to be a git repository: a worker that edits files gets its own branch, and even a read-only worker is told which branch it is looking at.

2. Declare the worker

A named worker is an agent spec: a small TOML file named after the worker. Put it in the project, where it is found first:

mkdir -p .chatty/agents
cat > .chatty/agents/local-reviewer.toml <<'EOF'
[agent]
name = "local-reviewer"
model = "qwen2.5-coder:14b"
preamble = "You are the reviewer. Read the code you are pointed at, run the tests, and report what you found as a numbered list; never edit files."

[tools]
profile = "reviewer"
EOF

Then list it in your module settings file, next to the rest of Chatty’s settings (where that is on your platform). On Linux:

mkdir -p ~/.config/chatty
cat > ~/.config/chatty/module_settings.json <<'EOF'
{ "virtual_agents": ["local-reviewer"], "team": { "isolate": true } }
EOF

If the file already exists, add the virtual_agents list and the team block to it rather than replacing it. There is no settings page for this yet. "isolate": true gives every worker its own git worktree, which step 5 looks at; without it a worker works in your workspace directly.

Four fields, and each one matters:

• name is how the leader will address it, and the file’s name. Keep the local- prefix by convention: the leader’s tools list where each agent runs, and local means this machine.
• model is the worker’s own model. It does not have to be the leader’s.
• profile is the role. reviewer can read, search, look at diffs and run commands — enough to run a test suite — and cannot write, commit or delegate. The other two roles are coder and coordinator; Sub-agents has the full table.
• preamble is the standing instruction. Its first sentence is what the leader sees on the worker’s card, so lead with the role.

3. Run a leader that can delegate

cd ~/bank
chatty-tui --broker --ollama --model qwen3:14b --auto-approve

--broker is the flag that makes the roster reachable: it starts the local worker broker for this session and publishes every worker in your module settings. --ollama finds your local models without any other setup, --model picks the leader’s, and --auto-approve lets the worker run its tools (the test suite) without a prompt you would not be able to answer on its behalf.

The welcome screen lists what is active — model, workspace, tool groups — and the status bar shows the branch, main.

4. Ask for the review

Type this as your first message:

Use list_agents to see who is on the team, then ask local-reviewer to review
bank.py and tests/test_bank.py and report any bugs and missing tests. Do not
read or fix the code yourself; relay the reviewer's findings.

Watch the transcript. First the leader looks at the roster — the folded tool line reads list_agents, and /verbose shows what it saw:

{
  "agents": [
    {
      "name": "local-reviewer",
      "origin": "local",
      "kind": "worker",
      "description": "A chatty agent in its own process, with its own workspace. Delegate a self-contained task to it and it works autonomously and reports back. Model: qwen2.5-coder:14b. Tool profile: reviewer. Role: You are the reviewer.",
      "enabled": true
    }
  ],
  "total": 1
}

That card is all the leader knows about the worker — the model, the role, and the first sentence of your preamble — and it is enough to choose by. Then the hand-off:

⟳ invoke_agent
[agent: local-reviewer] [local] ⟳ running

While that line is spinning, a second chatty-tui process is alive on your machine with --model qwen2.5-coder:14b --tools reviewer and your preamble, working through the files and running the tests in its own workspace. Its progress streams into the leader’s transcript as it goes. When it finishes, the line flips to ✓ completed, its report becomes the tool result, and the leader writes its answer from that — which should name the two problems in withdraw (negative amounts, overdraft) and the tests that are missing for them.

5. Look at what the worker left behind

git status          # clean: main is untouched
git branch          # main, sub-agent/local-reviewer-0
ls .chatty/worktrees/   # local-reviewer-0

With "isolate": true, every worker gets its own copy of the tree on its own branch, sub-agent/<worker>-<n> (the number counts that worker’s delegations in the session), whether or not its role can write. The reviewer’s copy is where it ran the tests. It committed nothing, so the reply carries no evidence block — that block only exists when there is something to merge. Give a coder role the same task and the reply ends with one: the branch, its commit count and a diff summary. That is what the next tutorial builds on.

Worktrees and branches are left for you to inspect and are never removed behind your back. When you are done with one: git worktree remove .chatty/worktrees/local-reviewer-0 && git branch -D sub-agent/local-reviewer-0 (in that order — git will not delete a branch a worktree still has checked out).

Verify

• list_agents showed local-reviewer with Model: qwen2.5-coder:14b. Tool profile: reviewer. on its card.
• The transcript shows invoke_agent → [agent: local-reviewer] [local] ⟳ running → ✓ completed.
• The leader’s answer reports the overdraft and negative-amount bugs and the missing tests; git status is clean and git branch shows sub-agent/local-reviewer-0.

Common issues

• list_agents shows nothing, or only local-agent. The leader was started without --broker, or the settings file is not where Chatty reads it. chatty-tui prints the config directory in --help under Prerequisites; check the file is there and is valid JSON.
• The worker fails with an Ollama error such as llama runner process has terminated. The two models do not fit in memory together and Ollama fell back to CPU or ran out. Use one model for both ("model" on the worker set to the same tag as --model), or pick a smaller worker such as qwen3:4b.
• The leader thinks for a very long time before delegating. qwen3 reasons before every answer. Either accept it, or use a model that does not (for example the coder model for the leader as well), or turn thinking off for that model in your desktop model settings by adding "extra_params": {"think": "false"} to its entry in models.json.
• The worker asks a question. It cannot see your conversation, so the leader answers from the task if it can and otherwise the question reaches you as a clarifying prompt that takes over the input row. Answer it and the worker continues.

Next

• Tutorial: a small agentic team — a coder and a reviewer, a verification command, and a leader that merges only on APPROVE.
• Sub-agents › Named workers and roles — every field and every role.

Tutorial: a small agentic team

When to read this: You have run one named worker and want a team that can take a task from “fix this” to a merged, verified branch: a leader that only delegates, a coder, and a reviewer that does not take the coder’s word for it. About an hour, most of it watching.

What you will end up with

A team directory of your own — team.json plus a SKILL.md playbook — checked into a project, run with one command, that fixes the bank account bug from the first tutorial, has the fix reviewed against acceptance criteria, merges it, and proves it with the test suite. Then you will change the roster and see the difference.

Prerequisites

• Everything from the first tutorial: Ollama with qwen3:14b and qwen2.5-coder:14b, chatty-tui, and the ~/bank project with its one passing test and unfixed withdraw.
• A clean tree in ~/bank (git status shows nothing to commit).

How a team run works

Four things happen that a single worker never does:

1. The leader has a role too — coordinator, which can read, delegate and merge but cannot edit or run commands. It has to work through its team.
2. The coder gets its own branch (sub-agent/local-coder-0; the number counts that worker’s delegations in the session) in its own copy of the tree. When it finishes, Chatty commits that branch and appends an evidence block to its report: branch, commit count, diff summary.
3. The verification command is run by Chatty, not by a worker, in the worker’s tree, and its exit code and last lines go into the same evidence block. A coder that says “tests pass” is checked, not trusted.
4. The reviewer reads the branch itself — the diff, the tests — and its first line is a verdict. The leader merges only on APPROVE.

The playbook that sequences this is a skill the leader is told to follow on its first turn.

Steps

1. Write the team

A team is three things: the agents (each an agent spec), a team.json naming the leader and the roster, and the playbook. Write the three agents as specs, and a team directory naming them, in the project:

mkdir -p .chatty/agents .chatty/teams/bank-fix
cat > .chatty/agents/bank-lead.toml <<'EOF'
[agent]
name = "bank-lead"
preamble = "You lead a two-worker team and edit nothing yourself. Restate the task as acceptance criteria, delegate the change to local-coder, have local-reviewer check the coder's branch, and merge only on APPROVE."

[tools]
profile = "coordinator"
EOF
cat > .chatty/agents/local-coder.toml <<'EOF'
[agent]
name = "local-coder"
model = "qwen2.5-coder:14b"
preamble = "You are the coder. Work only in your own workspace, write a test for each acceptance criterion before making it pass, run the tests, do not commit, and report the files you changed with the test output."

[tools]
profile = "coder"

[budget]
max_agent_turns = 30
EOF
cat > .chatty/agents/local-reviewer.toml <<'EOF'
[agent]
name = "local-reviewer"
model = "qwen2.5-coder:14b"
preamble = "You are the reviewer. Read the branch's diff yourself, run the tests yourself, never edit the tree. The first line of your answer is APPROVE, REQUEST_CHANGES or BLOCKED."

[tools]
profile = "reviewer"
EOF
cat > .chatty/teams/bank-fix/team.json <<'EOF'
{
  "leader": "bank-lead",
  "agents": ["local-coder", "local-reviewer"],
  "verification": "python3 -m unittest discover -s tests -t . -v",
  "isolate": true,
  "skill": "bank-fix",
  "max_agent_turns": 50
}
EOF

What each field does, and why:

Now the playbook. This is the part worth iterating on — it is where a team’s behaviour actually lives:

cat > .chatty/teams/bank-fix/SKILL.md <<'EOF'
# Skill: bank-fix

Deliver one bounded change with a coder and a reviewer.

1. Restate the task as a numbered list of acceptance criteria and record them with the todo tool.
2. Delegate to local-coder with one self-contained prompt: the criteria verbatim, and "work only in your own workspace, write a test for each criterion before making it pass, run the tests, do not commit, and report the files you changed and the test output".
3. The coder's answer ends with the branch its work was committed to (`sub-agent/<name>`). Do not fix the coder's work yourself.
4. Delegate to local-reviewer with one self-contained prompt: the criteria, the branch name, and "find the default branch with git_status, read the branch with the git_diff tool using range = <default>..<branch>, check every criterion has a test, run the tests, do not edit any file; first line of your answer is APPROVE, REQUEST_CHANGES with a numbered list, or BLOCKED: <reason>".
5. On REQUEST_CHANGES: delegate to local-coder again with the original criteria, the branch to continue from, and the reviewer's list; then review again. At most twice.
6. On APPROVE: merge the branch with the git_merge tool (no_ff = true). Then delegate once more to local-reviewer: "run the verification command on the current tree and report its result lines; first line PASS or FAIL".
7. Report: verdict, merge commit or why nothing merged, the criteria with their evidence.

Every prompt to a worker is self-contained: the worker sees none of this conversation.
EOF
git add .chatty/agents .chatty/teams && git commit -q -m "Add the bank-fix team"

Two rules in there carry most of the weight. Every prompt to a worker is self-contained — a worker starts with an empty conversation, so anything the leader does not put in the prompt does not exist. And do not fix the coder’s work yourself — the leader could not anyway (no shell, no writes), but a model will try to reason its way around a missing tool unless told not to.

2. Run it

Give the leader the task. The team file carries the verification command, so the task does not need to:

chatty-tui --team bank-fix --headless --auto-approve --ollama --model qwen3:14b \
  -m "Fix Account.withdraw in bank.py. Acceptance criteria: 1. withdraw raises ValueError when the amount is not positive. 2. withdraw raises ValueError when the amount exceeds the balance. 3. Otherwise withdraw subtracts the amount and returns the new balance. 4. tests/test_bank.py gains a test for each of criteria 1-3. 5. test_deposit keeps passing."

--team implies --broker. The list_agents card the leader reads says Model: qwen2.5-coder:14b. Tool profile: coder. for the coder. The task states the acceptance criteria explicitly because that is what the playbook expects: vague tasks make vague teams.

--headless prints only the leader’s final answer on stdout; the hand-offs go to stderr as they happen. To watch both, drop --headless and -m and type the task into the interactive app instead.

3. Read the run

On stderr you will see the shape of the playbook:

[tool: read_skill] ✓ completed
[tool: write_todos] ✓ completed
⟳ invoke_agent
[agent: local-coder] [local] ⟳ running
  …the coder's own tool calls stream here…
[agent: local-coder] ✓ completed
⟳ invoke_agent
[agent: local-reviewer] [local] ⟳ running
[agent: local-reviewer] ✓ completed
[tool: git_merge] ✓ completed
⟳ invoke_agent
[agent: local-reviewer] [local] ⟳ running
[agent: local-reviewer] ✓ completed

The coder’s report ends with the evidence block Chatty appended:

```evidence
branch: sub-agent/local-coder-0
base: main
commits: 1
diff --stat main..sub-agent/local-coder-0:
 bank.py            |  6 +++++-
 tests/test_bank.py | 15 +++++++++++++++
 2 files changed, 20 insertions(+), 1 deletion(-)
verification: python3 -m unittest discover -s tests -t . -v — exit code 0
test_deposit (tests.test_bank.TestBank.test_deposit) ... ok
test_withdraw_negative (tests.test_bank.TestBank.test_withdraw_negative) ... ok
test_withdraw_overdraft (tests.test_bank.TestBank.test_withdraw_overdraft) ... ok
test_withdraw_ok (tests.test_bank.TestBank.test_withdraw_ok) ... ok
----------------------------------------------------------------------
Ran 4 tests in 0.001s

OK
```

The reviewer’s report starts with APPROVE (or REQUEST_CHANGES and a numbered list, in which case the leader sends a fresh coder back to the branch — at most twice). The leader’s final answer on stdout gives the verdict, the merge commit and a criteria-to-evidence table.

Then look at the tree:

git log --oneline --graph | head -5     # a merge commit bringing in sub-agent/local-coder-0
git branch                              # main, sub-agent/local-coder-0, sub-agent/local-reviewer-0, -1
python3 -m unittest discover -s tests -t . -v   # four tests, OK
ls .chatty/worktrees/                   # local-coder-0  local-reviewer-0  local-reviewer-1

Every delegation is a fresh worker on a fresh branch in its own copy of the tree — the reviewer’s two (the review, then the verification pass) as much as the coder’s — and only the coder’s has commits. If the reviewer sent the coder back once, you will also see local-coder-1, told which branch to continue from. Nothing is cleaned up behind your back; the worktrees and branches stay until you remove them.

4. Change the team and watch the difference

Now that a run is reproducible, experiment. Each is one edit to a spec or team.json:

• Add a role. A third worker, .chatty/agents/local-tester.toml with profile = "reviewer", listed in team.json’s agents, and a preamble that only writes and runs a negative probe, called by the playbook between coder and reviewer. Roles are what you make of the preamble; the tool profile just bounds them.
• Starve the coder. Set its spec’s budget.max_agent_turns to 8 and watch it run out mid-task; the leader is told the delegation failed. What it does next is up to your playbook — add a line for it and see whether the leader follows.
• Take the shell away from the reviewer. disable = ["shell"] under its spec’s [tools], on top of profile = "reviewer": it can still read the diff but no longer run the tests — and Chatty skips the verification command for it, since a worker that could not run anything has no build to check.

Keep the specs, SKILL.md and team.json in the repository. The team is part of how the project gets worked on, and a run with a different team file is a different experiment.

Verify

• After step 2: a merge commit on main, four passing tests, sub-agent/local-coder-0 present, and an evidence block ending in exit code 0 in the coder’s report, with the coder running qwen2.5-coder:14b.
• chatty-tui --team no-such-team … fails immediately, naming the two directories it looked in and the presets it knows. Your team is found because it sits in the first of those directories.

Common issues

• The leader edits files itself or “cannot find” the coder. Its first turn did not follow the skill. Check skill in team.json matches the SKILL.md name and that the file is beside team.json; run without --headless to read what the leader saw.
• The coder’s evidence block is missing. The coder committed nothing (it reported but did not write, or wrote in the wrong place). A worker that changes nothing gets no block, on purpose — there is nothing to merge. Tighten the coder’s preamble: work only in your own workspace.
• git_merge reports a conflict. The leader stops and lists the files; it never resolves conflicts. Merge by hand, or reset and run again.
• The reviewer approves a branch that does not do the job. Make the reviewer reproduce something: tell it to revert one line of the fix and confirm the new test fails. A reviewer that only reads will approve on the coder’s word.
• A worker stalls at the model server. Two workers on one Ollama server queue rather than run at once — that is the endpoint budget protecting a local model from thrashing — so a run with a coder and a reviewer is sequential by design. Only the wall clock is affected.

Next

• Sub-agents › Teams — where teams are searched for and how --model / --tools / --preamble override the leader.
• Security & approvals — what --auto-approve lets a worker do and how to run a team attended instead.
• Tutorial: from one agent to a team: the desktop walkthrough with the shipped data-analysis team, approvals, the per-model bill and mixed models.

Tutorial: an autonomous dev team that builds software story by story

When to read this: You have run a small agentic team and want to see how far a team can go unattended: five agents that turn a product brief into tested, reviewed, committed code, one user story at a time, for hours. This is the experimental end of teams. Plan an evening of mostly waiting, and read Results, honestly before you start.

What you will end up with

A project directory with a five-agent team (devteam), a product brief, and a small shell loop that runs the team in iterations. After every iteration the loop runs the test suite itself and feeds the result into the next prompt, so a red suite gets repaired before anything new is built. When you stop it you have a backlog of user stories, Gherkin feature files, plans, code, unit tests, BDD tests and a git history with one commit per piece of work, on a green main.

The example product is logslice, a command-line tool that filters and summarises JSON-lines log files. Substitute your own brief.

Prerequisites

• chatty-tui (install), version 0.7.9 or later. Everything this page relies on is in it: the sandbox notice, denying approvals nobody can answer, the team warnings and the leader’s --enable reaching the workers. On an older version, turn the shell and git on in the execution settings instead (see Run it in a box).
• A model server: Ollama, or any OpenAI-compatible server (vLLM, llama.cpp, LM Studio). Use the strongest model you can run; this team makes dozens of tool calls per story. The results below came from a 27B model on one GPU.
• Python 3.9 or later (with venv) and git in the environment that runs the team. The example product is written in Python, so the tests are pytest.
• A container, or a throwaway VM or user account. The run uses --auto-approve: read step 2 before you start it.

How the team divides the work

One run of the leader is one story: story, plan and code, tests, review, at most one fix round, merge, tick the story in BACKLOG.md. Each worker gets its own git branch and the leader merges after every worker, so the next worker builds on the previous one’s work. The mechanics are the ones from the previous tutorial.

Steps

1. Create the project

mkdir logslice && cd logslice
git init -q -b main
mkdir -p .chatty/agents .chatty/teams/devteam docs features src/logslice tests/unit tests/bdd
touch tests/__init__.py
printf '__pycache__/\n*.pyc\n.pytest_cache/\n*.egg-info/\n.venv\n.home\n' > .gitignore

You will create the Python virtual environment yourself in step 2, once, because the agents are told not to use the network. Write the product brief to README.md; the team reads it first. A brief states what the tool does and the quality bar, and nothing about stories, since breaking it down is the product owner’s job:

# logslice

A command-line tool that answers quick questions about JSON-lines log files:
one JSON object per line. Pure Python, standard library only. It must work on
files larger than memory (stream, never load the whole file).

* `logslice FILE...` (or `-` for stdin) prints the lines that match the filters.
* Filters: `--level warn`, a time window (`--since`, `--until`: ISO-8601 or
  relative like `15m`), `--where user.id=42`, and `--grep` on the message.
* `--count-by FIELD --top N` prints the most frequent values of a field.
* `--stats` prints counts per level, first and last timestamp, busiest minute.
* Lines that are not valid JSON are skipped and counted, never fatal.
* Gzip files are read transparently. Exit codes: 0 matched, 1 nothing, 2 usage error.

Quality bar: small functions, no network, no third-party runtime dependencies,
unit tests and pytest-bdd scenarios for every story.

Now the three project files that every agent reads. AGENTS.md is the team’s shared rulebook: Chatty loads it into every agent’s context, so the layout and the exact test command live here once:

# How this team works on logslice

Read `README.md` first: it is the product brief.

## Layout

* `BACKLOG.md`: ordered stories, each `- [ ] S00N: As a …, I want …, so that …`; tick `[x]` when done.
* `docs/stories/S00N-<slug>.md`: one story with its acceptance criteria.
* `features/S00N-<slug>.feature`: the same criteria as Gherkin. Strict Gherkin: every step starts
  with a capitalised Given/When/Then/And/But (pytest-bdd rejects lowercase `and`, and one bad
  file makes the whole suite fail to collect).
* `docs/plans/S00N.md`: the developer's short plan before coding.
* `src/logslice/`: the code (standard library only). Entry point `logslice.cli:main`.
* `tests/unit/test_*.py` and `tests/bdd/test_*.py` (pytest-bdd steps bound to `features/*.feature`;
  `pytest.ini` sets `bdd_features_base_dir = features`, so use `scenarios("<file>.feature")`).

## Running the tests

Always run the whole suite from the repo root:

    PYTHONPATH=src .venv/bin/python -m pytest -q

Do not install anything else and do not use the network.

## Rules

* One story per cycle. Small functions named for what they do.
* Never read or write anything outside the repo.
* Commit your own work with `git_commit`, naming the story id (`S002: report empty values`).
* A story is done only when the whole suite passes and the reviewer approved it.
* Main must be green and checked out at the end of every run. A red suite is repaired first.

cat > pytest.ini <<'EOF'
[pytest]
bdd_features_base_dir = features
pythonpath = src
EOF
cat > pyproject.toml <<'EOF'
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "logslice"
version = "0.1.0"
requires-python = ">=3.9"

[project.scripts]
logslice = "logslice.cli:main"
EOF

(Put the README.md and AGENTS.md text above into those files with your editor.)

2. Run it in a box

The loop below starts Chatty with --auto-approve, which lets every agent run shell commands and git operations without asking you. That is what makes an unattended run possible, and it means whatever the model decides to run, runs. Do not do this on your everyday machine. Use a container, a throwaway VM, or a separate user account that owns nothing you care about.

A container is the quickest. This image is all the team needs, apart from the chatty-tui binary, which you mount in:

cat > Dockerfile.devteam <<'EOF'
FROM ubuntu:24.04
RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
      python3 python3-venv git ca-certificates bash && rm -rf /var/lib/apt/lists/*
EOF
docker build -q -t devteam-box -f Dockerfile.devteam .
docker run --rm -it --network host --user "$(id -u):$(id -g)" -e HOME=/work/.home \
  -v "$PWD":/work -v "$(command -v chatty-tui)":/usr/local/bin/chatty-tui:ro \
  -w /work devteam-box bash

Run mkdir -p .home before docker run; .home is already in .gitignore. --network host lets the box reach a model server on your machine. Everything from here on runs inside the box’s shell. Create the virtual environment there, so it matches the box’s Python:

python3 -m venv .venv && .venv/bin/pip install -q pytest pytest-bdd
git config user.name devteam && git config user.email devteam@localhost

The pip install needs network access once; after that the agents never do. The git identity is there so commits work in a fresh box.

Two things to know about the shell tool in a box:

• The shell sandbox. Chatty runs shell commands inside a bubblewrap sandbox when it can. On Ubuntu 24.04 the default AppArmor setting blocks the user namespaces that sandbox needs, so commands run unsandboxed. Since 0.7.9, a headless run prints one line to stderr saying so and why. In a container that is expected, and the container is your boundary. If you would rather a run refuse to start unsandboxed, set "sandbox_required": true in execution_settings.json; Chatty then stops at startup with the reason, before any model call. See Security & approvals.
• No one to ask. In an unattended run (--headless), an approval request nobody can answer is denied at once instead of waiting for five minutes (0.7.9 and later). --auto-approve is what stops requests from arising in the first place.

Workers read execution_settings.json themselves, so a worker’s shell and git come from those settings unless the leader’s flags are forwarded: since 0.7.9 the leader’s --enable, --disable and --only reach every worker. A headless team also prints one stderr line per agent whose profile wants the shell or git that the run has off, which is the line to look for if a worker says it has no shell.

3. Write the team

Five agent files and a team.json. The preamble is where a team’s behaviour lives, and several sentences in them that look fussy (the capitalised Gherkin, the red-suite rule, “merge after each worker”) each answer a failure from real runs.

cat > .chatty/agents/dev-lead.toml <<'EOF'
[agent]
name = "dev-lead"
description = "Leads one story through story, plan, build, tests and review, and merges the work"
preamble = """You lead a small software team building logslice (read README.md and AGENTS.md first). You write no code yourself: you delegate, merge and report. Run exactly ONE story per run, in this order:

1. product-owner: write or refine the user story and its acceptance criteria (story file + Gherkin feature file) and keep BACKLOG.md up to date.
2. developer: write the plan docs/plans/S00N.md, then implement it in src/logslice/.
3. tester: write unit tests and pytest-bdd steps for the story's feature file, run the WHOLE suite with the command in AGENTS.md, and report the pass/fail counts.
4. code-reviewer: review against the acceptance criteria; the first line of its answer is APPROVE or REQUEST_CHANGES.
5. If REQUEST_CHANGES: send the reviewer's list to developer (and tester if tests are affected), then ask code-reviewer once more. At most one fix round.

Every worker works on its own git branch. After EACH worker returns, merge its branch into main with git_merge before you delegate to the next worker. If a merge conflicts, ask that worker to rebase its work on main and try again.

RED SUITE RULE: if the prompt says the suite is failing, or you find main red, your FIRST actions are to delegate the repair: tester for test or feature-file problems, developer for code problems, with the exact failing output from the prompt in the task. Never start a new story while main is red.

When the story is done, ask product-owner to tick it in BACKLOG.md. Finish with a short report: story id and title, files changed, the suite result, the reviewer's verdict, and the next story id."""

[tools]
profile = "coordinator"

[swarm]
delegates_to = ["product-owner", "developer", "tester", "code-reviewer"]

[budget]
max_agent_turns = 80
max_duration = "75m"
EOF
cat > .chatty/agents/product-owner.toml <<'EOF'
[agent]
name = "product-owner"
description = "Writes user stories with clear acceptance criteria and Gherkin scenarios, keeps the backlog"
preamble = """You are the product owner of logslice (README.md is the brief, AGENTS.md the layout). You write user stories in the form "As a <user>, I want <capability>, so that <benefit>", each with 3-6 concrete, testable acceptance criteria, and the same criteria as Gherkin scenarios (Given/When/Then/And/But, capitalised: pytest-bdd rejects lowercase `and`; concrete example files and expected output) in features/S00N-<slug>.feature. Keep stories small: one capability each. Keep BACKLOG.md as an ordered list of small stories, the most valuable first. Write only docs, BACKLOG.md and .feature files; never code. Before you hand a feature file on, re-read every step line: each must start with a capitalised Given/When/Then/And/But. Commit your files with git_commit, naming the story id. Reply with the story id, its title and the files written."""

[tools]
profile = "coder"
disable = ["shell", "code-exec", "docker-exec", "fetch"]

[swarm]
exposed = true
callers = ["dev-lead"]

[budget]
max_agent_turns = 25
max_duration = "20m"
EOF
cat > .chatty/agents/developer.toml <<'EOF'
[agent]
name = "developer"
description = "Plans and implements one story in small, readable Python"
preamble = """You are the developer of logslice (README.md is the brief, AGENTS.md the layout and the test command). For the story you are given: first write a short plan in docs/plans/S00N.md (files, functions, edge cases), then implement it in src/logslice/ with the standard library only. Keep functions small; follow the rules in AGENTS.md. Make sure `logslice.cli:main` works as the entry point. Run the whole suite with the command in AGENTS.md before you finish; fix what you broke. Commit with git_commit naming the story id. Reply with the files changed and the suite result."""

[tools]
profile = "coder"
disable = ["fetch", "docker-exec"]

[swarm]
exposed = true
callers = ["dev-lead"]

[budget]
max_agent_turns = 35
max_duration = "25m"
EOF
cat > .chatty/agents/tester.toml <<'EOF'
[agent]
name = "tester"
description = "Writes pytest unit tests and pytest-bdd steps for a story and runs the whole suite"
preamble = """You are the tester of logslice (AGENTS.md has the layout and the exact test command). For the story you are given: write unit tests in tests/unit/test_<topic>.py for the functions the developer added, and pytest-bdd step definitions in tests/bdd/test_<story>.py bound to the story's features/S00N-<slug>.feature with scenarios("<file>.feature") (pytest.ini sets bdd_features_base_dir = features, so give only the file name). Use tmp_path for example files. Feature files are strict Gherkin: steps start with Given/When/Then/And/But, capitalised; if one does not parse (pytest says so at collection), fix the .feature file yourself rather than working around it. Run the WHOLE suite with the command in AGENTS.md. If a test fails because the code is wrong, say exactly which behaviour is wrong; do not change src/. Commit your tests with git_commit naming the story id. Reply with the files written and the exact passed/failed counts from the last run."""

[tools]
profile = "coder"
disable = ["fetch", "docker-exec"]

[swarm]
exposed = true
callers = ["dev-lead"]

[budget]
max_agent_turns = 35
max_duration = "25m"
EOF
cat > .chatty/agents/code-reviewer.toml <<'EOF'
[agent]
name = "code-reviewer"
description = "Reviews a story's code and tests against its acceptance criteria; APPROVE or REQUEST_CHANGES"
preamble = """You review logslice work and edit nothing. Read the story file, its feature file, the plan, the code and the tests. Run the whole suite with the command in AGENTS.md. Check that every acceptance criterion is implemented and tested and that the code is simple. The first line of your answer is APPROVE or REQUEST_CHANGES, then a numbered list: what you checked, or exactly what must change (file, function, behaviour)."""

[tools]
profile = "reviewer"
disable = ["fetch", "docker-exec"]

[swarm]
exposed = true
callers = ["dev-lead"]

[budget]
max_agent_turns = 20
max_duration = "15m"
EOF
cat > .chatty/teams/devteam/team.json <<'EOF'
{
  "name": "devteam",
  "leader": "dev-lead",
  "agents": ["product-owner", "developer", "tester", "code-reviewer"],
  "max_agent_turns": 80
}
EOF
git add -A && git commit -q -m "Setup: brief, team and tooling for logslice"

Differences from the team in the previous tutorial: there is no verification command or playbook skill here. The suite command lives in AGENTS.md and the leader’s preamble is the playbook, and the objective check happens in the loop, outside the team, in the next step. The [budget] in each spec caps that agent’s tool rounds and wall-clock time, so one stuck worker cannot eat the iteration.

4. Run the loop

One iteration is one headless run of the leader:

chatty-tui --headless --team devteam --max-duration 75m --enable shell,git --auto-approve \
  --ollama http://localhost:11434 --model qwen3:14b \
  -m "<prompt>"

For an OpenAI-compatible server, replace the provider flags with --openai-compat-url http://localhost:8000 --api-key KEY --model NAME. --enable shell,git turns on the tool groups the coder profile needs. --max-duration 75m is the wall-clock limit for the iteration.

A single iteration stops after one story, so a small loop drives the rest. What matters is the gate: the loop runs the test suite itself, so the next prompt is based on what the code does and not on what the team says it did.

cat > run-loop.sh <<'EOF'
#!/usr/bin/env bash
# run-loop.sh: run the devteam in iterations until the backlog is done or MAX_ITER is reached.
set -u
PROVIDER=(--ollama http://localhost:11434 --model qwen3:14b)  # or --openai-compat-url URL --api-key KEY --model NAME
MAX_ITER=${MAX_ITER:-10}
SUITE='PYTHONPATH=src .venv/bin/python -m pytest -q'

prompt='Ask the product-owner for a BACKLOG.md of 6-8 small stories and the story and feature file for S001, then run the full cycle for S001.'
for i in $(seq 1 "$MAX_ITER"); do
  echo "=== iteration $i $(date +%T)"
  chatty-tui --headless --team devteam --max-duration 75m --enable shell,git \
    --auto-approve "${PROVIDER[@]}" -m "$prompt" | tee "run-$i.log" | tail -n 20

  # Objective gate: the suite, not the team's own report.
  git checkout -q main
  if out=$(bash -c "$SUITE" 2>&1); then
    suite_ok=1
    status="The test suite passes: $(echo "$out" | tail -n 1)."
  else
    suite_ok=0
    status="The test suite is FAILING. Repair it first, before any new work. Hand this output to the tester or developer:
$(echo "$out" | tail -n 40)"
  fi
  echo "$status" | head -n 1

  if [ "$suite_ok" = 1 ] && ! grep -q '^- \[ \]' BACKLOG.md 2>/dev/null; then
    echo "Backlog complete."; break
  fi
  prompt="$status
Run the full cycle for the first unticked story in BACKLOG.md."
done
EOF
chmod +x run-loop.sh

Start it with ./run-loop.sh and leave it. run-1.log, run-2.log and so on hold each iteration’s output; git log --oneline and BACKLOG.md show progress. To stop, press Ctrl+C, then check that git status is clean and main is checked out. Add run-*.log, run-loop.sh and Dockerfile.devteam to .gitignore, so the loop’s own files do not dirty the tree.

The first prompt asks for the whole backlog and the first story’s full cycle. Every later prompt is the same sentence, with the gate’s result in front. If an iteration ends before any test exists, pytest exits non-zero and the gate reports the suite as failing; the next prompt then asks for the repair, which is harmless.

5. Read what it built

While it runs, the leader’s hand-offs stream to stderr as in the previous tutorial: invoke_agent, [agent: product-owner] ✓ completed, git_merge, and so on. Between iterations, look at the work itself:

cat BACKLOG.md                       # [x] for done stories, [ ] for open ones
git log --oneline | head             # one commit per piece of work, naming the story id
cat features/S001-*.feature          # the acceptance criteria as scenarios
PYTHONPATH=src .venv/bin/python -m pytest -q

A feature file the product owner writes looks like this:

Feature: Filter log lines by level

  Scenario: Only lines at or above the minimum level are printed
    Given a log file "app.log" with an info line and an error line
    When I run "logslice --level warn app.log"
    Then the output contains only the error line
    And the exit code is 0

Read the stories early. A story that is too large is the commonest reason for a slow run; edit BACKLOG.md yourself, commit, and the next iteration picks it up.

Lessons that make a long run work

Each of these cost real time in real runs.

• Strict Gherkin. Steps must start with a capitalised Given, When, Then, And or But. pytest-bdd rejects a lowercase and, and a single unparseable feature file makes the whole suite fail to collect, which turns every test red and cost hours. Say it in the product owner’s preamble, in AGENTS.md and in the tester’s, and let the tester fix a bad feature file.
• bdd_features_base_dir = features in pytest.ini. Without it the step files cannot find the feature files, and each agent invents its own path. With it, scenarios("S001-x.feature") works everywhere.
• Repair a red suite first, with the output in hand. A red main poisons every later story. The loop hands the failing output to the leader, and the leader’s preamble says to delegate the repair to the tester or developer before anything else. Without the output, the team tends to spend its iteration investigating.
• Keep stories small. One capability each. Small stories finish inside a worker’s turn budget, review cleanly and fail in ways that are easy to read.
• Main green and checked out at the end of every iteration. The loop runs git checkout main before the gate, and AGENTS.md makes it a rule. The next iteration then starts from known ground.
• Check with a script, not with the team. A team that reports “all tests pass” is sometimes right. The loop’s gate does not care.

Results, honestly

Two real runs of this team, both with a local model, RedHatAI/Qwen3.8-27B-INT4 on one GPU served by vLLM:

In run 2 the suite was red in iterations 1 and 2 and was repaired in iteration 3; main was green at the end. That is roughly 2.5 hours per story on this model.

What to take from that: throughput is limited by model speed. The team structure works, the loop recovers from a red suite, and the output is tested code in git, but a local model of this size is slow, and the stories it finishes per night are few. A faster or stronger model will do better; these numbers say nothing about one. Teams are experimental, so expect to read the logs, adjust the preambles and sometimes restart.

Verify

• After step 4, iteration 1: BACKLOG.md lists six to eight stories, docs/stories/S001-*.md and features/S001-*.feature exist, and git log has commits naming S001.
• After a successful iteration: PYTHONPATH=src .venv/bin/python -m pytest -q passes on main, and S001 is ticked in BACKLOG.md.
• chatty-tui --team devteam --headless -m "hello" in the project directory finds the team. From another directory it fails naming the places it looked.

Common issues

• A worker says it has no shell, or commands are refused. Check stderr for the per-agent warning that a profile wants the shell or git that the run has off. On releases that forward the leader’s flags to workers, --enable shell,git is enough; otherwise enable the groups in the execution settings.
• Every test fails at collection. A .feature file does not parse. Run PYTHONPATH=src .venv/bin/python -m pytest -q by hand and read the first error; the usual cause is a lowercase and. Fix it, commit, and let the loop continue.
• The iteration ends with nothing merged. The leader hit its turn or time limit mid-story. The next prompt asks for the first unticked story again, so work continues; if it keeps happening, split the story.
• The model server queues requests. Workers on one local server run one after the other. That is expected and only costs wall-clock time.
• A run refuses to start unsandboxed. You set sandbox_required. Fix the sandbox (Security & approvals) or unset it.

Next

• Tutorial: a small agentic team: the mechanics of leaders, workers, branches and verification in a one-hour setup.
• Sub-agents: where teams are searched for, and how the leader’s flags apply.
• Security & approvals: approval modes and the shell sandbox.

Security & sandboxing

When to read this: You want to know what the agent can and cannot touch, what each approval mode does, and how secrets are handled. Switching tools on is covered in Agents & tools.

The workspace boundary

File, shell and git tools are confined to the Workspace Directory you set in Settings → Code Execution. The agent cannot read or write outside it. The per-chat folder picker and /add-dir widen that boundary explicitly, per conversation, and nothing else does.

Shell sandbox

On Linux and macOS, shell commands run in an isolated process that sees the workspace but not sensitive folders such as .ssh, .aws and .gnupg. On Linux the sandbox needs the bubblewrap package from your distribution; if it is missing, or cannot create the user namespaces it needs (Ubuntu 24.04’s default AppArmor setting blocks them), commands still run but count as unsandboxed, and the terminal dock’s Agent tab says not sandboxed. Headless and --pipe runs print one line to stderr, and the terminal UI shows a notice, saying why and how to fix it (for Ubuntu’s AppArmor case: an AppArmor profile that lets bwrap create user namespaces, or running in a container or VM). To refuse instead of falling back to the host, set "sandbox_required": true in execution_settings.json (off by default): chatty-tui then stops at startup with the reason, before any model call, and the shell never starts unsandboxed. Windows has no shell sandbox, so commands there are always unsandboxed — which matters for the approval modes below.

Two more switches on the same page: Network Isolation stops sandboxed commands from reaching the network at all, and Timeout / Max Output cap how long a command may run and how much output it may return.

Code execution isolation

The code runner has two paths. Simple Python runs on the host in a restricted interpreter with a memory cap and a stripped environment. Everything else — other languages, or Python that needs third-party packages — goes to a fresh Docker container that is isolated from the host filesystem and network, and only when Enable Docker Fallback is on. The cloud sandbox on Settings → Internet runs code on a remote service instead of your machine.

Approval modes

Settings → Code Execution → Approval Mode has three settings:

A pending approval waits five minutes; if you do not answer, the call fails and the agent is told so. Reads, searches, queries, web fetches and the browser tools never ask in any mode. The terminal app uses y / n for the same prompts and --auto-approve to skip them.

Warning

Auto-approve All lets the model run any enabled tool without review. Use it only for a workspace you can afford to lose, and prefer a per-run --auto-approve in the terminal for scripted jobs.

Browser and web

By default the browser and fetch reach only localhost and workspace-local files; opening it to the public web or your own LAN is an explicit setting (Agents & tools). Either way, the same address filter refuses link-local and cloud-metadata addresses, so a page cannot redirect a fetch or a click into your machine’s or your cloud provider’s internal network. Clicking and typing outside localhost and the workspace ask for your approval every time, and the agent never types into a password or card-number field.

The agent’s standing instructions also draw a hard line around anything it reads from a page: text on a page — including text written to look like a system prompt, a task, or a message addressed to the agent — is treated as the page’s content, never as a new instruction. It can report that text back to you; it cannot act on it. That framing is what keeps a malicious or compromised page from hijacking the turn that’s looking at it.

Secrets

• Settings → Secrets holds key–value pairs that are exported as environment variables in every shell session. The agent can use the names in scripts (os.environ["API_KEY"]) but never sees the values; they are not logged and are masked in tool output.
• Provider keys are stored with your app settings, never in your project files, and are not exposed to the model.
• MCP server keys are masked when the agent lists your servers: it may learn that a key exists, never the value.
• No telemetry, no relay. Chatty sends traffic only to the providers, MCP servers, agents and websites you configure or ask it to use, plus GitHub for update checks. Sign-in tokens for catalog extensions stay on your machine.

Next

• Agents & tools
• Extensions
• Advanced

Terminal interface

When to read this: You want to use Chatty from a terminal — interactively, as a one-shot command, or in a pipeline — with the same providers and models as the desktop app.

Install

Where it lands: macOS puts a link in /usr/local/bin (you may be asked for an administrator password); Linux copies the binary to ~/.local/bin — add that folder to your PATH if chatty-tui is not found; Windows adds the app’s install folder to your user PATH, so open a new terminal afterwards.

Note

After a desktop update on Linux, the copy in ~/.local/bin is refreshed the next time the desktop app launches. /update inside chatty-tui does the same on demand.

Modes

Useful flags: --model <id or name> picks a model (exact id, then name, then substring); --enable / --disable switch tool groups for this run (shell, fs-read, fs-write, fetch, git, code-exec, docker-exec, ask-user, terminal; an unknown name is an error), and --only runs with exactly the groups named; --auto-approve skips every approval prompt (Security & sandboxing); --usage-file <path> writes what a headless or pipe run spent (tokens, model and tool calls, how it ended) to a JSON file (below). Full list: CLI flags.

Usage file

chatty-tui --headless --usage-file <PATH> -m "…" (or --pipe) writes what the run spent to PATH as one JSON object; stdout, stderr and the exit code are unchanged. It is written when the run ends however it ends (including SIGINT/SIGTERM/SIGHUP), and rewritten after every model call while it runs, so a run killed from outside leaves its latest totals with "exit": "running". Each write goes through a temporary file and a rename, so a reader never sees half an object.

{"schema":1,"input_tokens":550,"output_tokens":25,"cache_read_tokens":350,"cache_write_tokens":null,"reasoning_tokens":4,"model_calls":4,"tool_calls":2,"tool_calls_failed":1,"turns":3,"follow_up_passes":2,"duration_ms":18,"exit":"completed","model":"llama3.2"}

Totals are summed per model call across every pass, plus what delegated agents reported spending; tool_calls counts this agent’s own calls. A request cut off mid-stream reports no usage and is not counted.

Export a conversation

Export a conversation as ATIF, the trajectory format the desktop app also writes, to debug a run.

• chatty-tui --headless --export-atif <PATH> -m "…" writes the finished conversation when the run ends, also when it fails or is stopped. - writes to stdout.
• /export [path] in the interactive TUI exports the current conversation. Without a path it writes <config dir>/chatty/exports/<conversation-id>.atif.json and prints where.
• chatty-tui --export <conversation-id> [--out <PATH>] exports a saved conversation without running anything.

A run that delegated exports as one tree. Each agent’s turns, reasoning, tool calls with their results, and token usage come right after the step that delegated to it. Each step names its agent by path, for example root/coder-1, and the delegation step that started it. The agents, their models, spend and final status (completed, failed or stopped) are listed together. best_of attempts and the judge sit under the best_of step, which records the attempt kept and the judge’s reason. If a worker’s conversation was over the capture size limit, or a stopped worker left none, the export says so. It does the same when the step token counts do not add up to the run’s total.

API keys and your configured secrets are replaced with [REDACTED] in every export. Text a tool returned is exported as the tool returned it, so check it before sharing a trajectory. --save-conversation is a different file: the restore format, not an analysis export.

Zero-config quick start

Talk to a running model server without opening the desktop app or storing a key:

# Ollama (discovers models at localhost:11434; pass a URL for another host)
chatty-tui --ollama
chatty-tui --ollama --model llama3.2

# vLLM, llama.cpp, LM Studio or any OpenAI-compatible server
chatty-tui --openai-compat-url http://localhost:8000
chatty-tui --openai-compat-url http://localhost:8000 --model my-model --api-key sk-...

Add --think true / --think false to force a reasoning model’s extended-thinking mode on or off for the session — useful here since a zero-config session has no saved model settings to toggle it in otherwise. Works with Ollama and OpenAI-compatible servers that support a reasoning parser (for example vLLM’s --reasoning-parser).

Welcome screen and status bar

An empty interactive session shows what is active: model and context window, workspace and git branch, enabled tool groups, internet capabilities (fetch, search, browser, cloud sandbox, MCP) and runtime features (memory, modules, remote agents). MCP, memory and embeddings load in the background — badges show ⟳ (for example [MCP ⟳]) and the status bar reads loading services… until they are ready.

The status bar always shows the app version, the working directory and the git branch when you are inside a repository, plus the branch’s pull request (#591 open ✓) when git integration is on. Footer hints switch to Enter queues · /now <text> interrupts · Ctrl+C stop · Ctrl+Q quit while a reply streams, and the status line adds · N queued once a message is waiting. Once a provider round-trip has completed, or a second has passed, streaming also gets a · turn 3 · 1:15 suffix — the running turn count and elapsed time — so a long unattended reply still shows it’s making progress. A scrollbar appears when the transcript overflows; scrolling up unpins auto-scroll, End re-pins it. While the agent works through a multi-step plan, the status bar also shows its position (●▸○ Plan 1 of 3 · <step title>), cleared when you send the next message. Once the agent has edited files, a change tray segment (4 files +58 −4) tallies every edit made so far in the conversation.

Tool calls in the transcript are folded by default — a single call shows the tool and its main argument on one line, the result trimmed to a few lines with a … +N lines marker, and a run of several calls that all succeed collapses further into one counted line (for example explored 3 files, ran 1 command). A settled call is one line with a ▸ marker; click it to open its result (▾), and click again to close it. The counted line is clickable too and lists the calls it covers. The call still running shows its whole command, wrapped over up to four rows. A command that needed your approval renders inline with its verdict (Approve [host] <command> — allowed), and a file edit gets its own stat line (± path +a −r). Errors are always shown in full and never folded. Press Ctrl+R or run /verbose to switch to the full, untrimmed input/output for every tool call; the footer hint shows which mode is active.

A multi-step plan renders as a single card instead — a goal, a progress count and one line per step (pending, in progress, done, blocked, with its reason) — redrawn in place as the plan advances rather than logging each update as its own row. /verbose still shows the raw plan tool calls.

Keys

A pending clarifying question replaces the input row and takes over the keyboard until answered — Ctrl+C/Ctrl+Q still work. Multiple questions are answered one at a time; press Esc while typing a custom answer to go back to the options.

The terminal app has a few commands of its own — /model, /tools, /modules, /update, /paste, /now, /unqueue, /export, /swarm, /msg, /stop, /quit — alongside the shared ones. All of them: slash commands.

/swarm prints the agent tree for the conversation’s latest delegation as an indented list, one row per agent: name, model, status (running, done or failed) and spend. With no delegation yet, it says so.

/msg <agent> <text> sends a message to a running agent, by the name /swarm shows. The agent reads it at its next tool call rather than waiting for its run to end.

/stop <agent> stops one agent of the running swarm, by the name /swarm shows, and every agent it started. The rest keeps running, and the agent that called it carries on without it.

/agents running lists only the agents still running, one per line: name, conversation, the agents above it, whether it is working or waiting on you (for an approval or an answer), how long it has run, and what it has spent so far. The desktop shows the same list across all conversations (see sub-agents).

Sending a message while a reply is still streaming doesn’t get refused — press Enter as usual and it queues, showing up in the transcript as Queued #1: <text>, Queued #2: <text> and so on, and runs as its own turn once the current one ends. /now <text> instead cancels the running turn right away and sends <text> next. /unqueue takes back the message queued last. Up to 5 messages can wait; a sixth is refused. Ctrl+C cancels the current turn but leaves the queue as it is — nothing runs until you send (or /now) again, which then runs the queue’s front first.

/online is an unfinished feature, off by default: it only does anything once Settings → Execution → Developer → Hosted Conversations is on (a moved conversation carries its transcript and nothing else yet). With it on, /online shows where the current conversation runs and, before anything moves, a table of what a move would and would not carry. /online <server-url> uploads the conversation’s history to that chatty-server and continues it there; /online off brings it back to this machine. Workspace files, attachments, MCP servers, memory, skills and provider API keys never leave this machine. The server needs a Hive sign-in: /online reuses the one saved by the desktop app (Settings → Extensions → Hive) without refreshing it, so sign in there first.

Pasting more than 6 lines or 800 characters replaces the pasted text in the input box with a short reference, [Pasted text #1 +45 lines], so a stack trace or log dump doesn’t fill the screen — shorter pastes (a URL, a path, a one-line error) are inserted as-is. The model still receives the full text when you send the message. Run /paste 1 to print a reference’s full text back to the transcript. The reference acts as a single character: the cursor steps over it, and backspace at its edge removes the whole thing.

Use chatty as an agent in Zed or VS Code

chatty-tui acp runs chatty as an Agent Client Protocol (ACP) agent, so an editor can use it as its coding agent. Each editor thread is its own chatty conversation, rooted at the folder you have open. It uses your chatty providers, models, tools and MCP servers. Tool calls, the files they touch and the agent’s todo plan show up in the editor, and when a tool needs approval the editor asks you with Allow / Deny.

The command. The editor starts chatty-tui itself, so give it the full path:

• macOS app: /Applications/chatty.app/Contents/MacOS/chatty-tui
• Linux: the chatty-tui binary inside the AppImage, or one you built
• From source: cargo build --release -p chatty-tui, then target/release/chatty-tui

Put other flags before acp, e.g. "args": ["--model", "claude-sonnet", "acp"] or "args": ["--ollama", "acp"].

Zed

Zed supports ACP agents natively. Open Agent Settings → External Agents → Add Custom Agent, or add this to your settings file:

{
  "agent_servers": {
    "Chatty": {
      "type": "custom",
      "command": "/path/to/chatty-tui",
      "args": ["acp"],
      "env": {}
    }
  }
}

Then pick Chatty in the Agent Panel. dev: open acp logs shows the protocol messages; chatty’s own log goes to stderr, which Zed writes to its log.

VS Code

VS Code has no built-in ACP support, and chatty does not appear in Copilot Chat. Install an ACP extension instead, such as ACP Client (also on Open VSX for Cursor and Windsurf), and add chatty to your settings.json:

{
  "acp.agents": {
    "Chatty": {
      "command": "/path/to/chatty-tui",
      "args": ["acp"],
      "env": {}
    }
  }
}

Open the ACP panel in the Activity Bar and click Chatty to connect. Keep acp.autoApprovePermissions at ask so chatty’s approval prompts reach you; allowAll approves everything. ACP: Show Protocol Traffic shows the protocol messages.

Not supported yet

• The model asking you a clarifying question (ask-user is off over ACP).
• MCP servers configured in the editor (chatty uses its own).
• Images in the prompt.
• Reopening an earlier thread or session.
• --team.

Other ACP editors should work the same way — JetBrains IDEs and Neovim (CodeCompanion, avante.nvim) among them — but only Zed and VS Code are described here.

Install a team

chatty-tui --install-team NAME[@VERSION] installs a published team from the Hive marketplace, with every spec and locked plugin signature-checked, then exits. See Install a team from the marketplace.

Shared configuration

chatty-tui reads the same settings as the desktop app — providers, models, tools, secrets and memory — so run the desktop app once to set things up, or skip that entirely with --ollama / --openai-compat-url. Where the files live: Advanced.

Next

• Sub-agents
• Getting started
• Advanced

Advanced

When to read this: You want to export conversations for fine-tuning, find where Chatty keeps its files, or understand how updates are installed.

Training-data export

Settings → Training Data turns on automatic export: with Auto-export ATIF or Auto-export JSONL on, every finished reply re-exports its conversation. Re-exporting replaces that conversation’s previous entry rather than duplicating it.

ATIF (Agent Trajectory Interchange Format) is structured JSON for agent pipelines, following the Harbor trajectory format: messages, tool calls, reasoning, timestamps, token counts, thumbs feedback and regeneration pairs (rejected versus chosen). One file per conversation. A conversation that delegated to agents includes their turns too, each under the step that delegated to it. The terminal guide describes the layout.

JSONL produces two append-only files:

• sft.jsonl — supervised fine-tuning rows in ChatML, as accepted by OpenAI, Anthropic, Together AI and similar APIs. Tool calls can be included.
• dpo.jsonl — preference pairs. Every time you press Regenerate, the original reply becomes the rejected answer and the new one the chosen answer.

Both land in the exports folder listed below.

Where Chatty stores data

Nothing leaves your machine unless a provider, extension or website you use receives it. Windows keeps everything under %APPDATA%\chatty\; macOS under ~/Library/Application Support/chatty/; Linux splits configuration from data as shown (respecting $XDG_CONFIG_HOME / $XDG_DATA_HOME).

The caches can be deleted at any time; they are rebuilt on demand (the first browser call after deleting the Chrome cache downloads it again). Settings and conversations are plain files, so back them up by copying the folder.

API keys and sign-in tokens

Provider API keys, MCP and A2A tokens and your Hive sign-in are kept in the operating system’s keychain, filed under chatty:<settings folder>. The settings files only name them ("api_key_ref": "provider/OpenRouter"), so copying or syncing the settings folder does not copy a key. On a new machine, enter the keys again in Settings.

A Linux machine without a Secret Service (a server, a container) has no keychain. Chatty then keeps the keys in secrets.json in the settings folder, readable only by you, and logs one warning saying so. To control this, set CHATTY_SECRET_STORE:

• keychain — use the keychain or refuse to start; never write secrets.json.
• file — always use secrets.json, without touching the keychain.

Runs without a person at the keyboard (chatty-tui --headless, --pipe, and ACP) wait at most 2 seconds for the keychain. If it does not answer, for example because no Secret Service session is unlocked, they fall back to secrets.json and print one warning: line on stderr. The desktop app and the interactive TUI keep waiting, so a slow first unlock does not switch them to the file.

Environment variables and command-line flags that pass a key to chatty-tui (for example --api-key) work as before and are never stored.

Auto-update

Chatty checks GitHub Releases shortly after launch and then hourly. When a newer version exists, it downloads in the background, verifies the file’s SHA-256 checksum, and the status footer changes to Click to restart and install v…. A Check for updates button in the same footer runs a check on demand.

Installing differs by platform:

• macOS — the app quits, the bundle is replaced in place and the app relaunches.
• Linux — the running AppImage is replaced and relaunched; a chatty-tui installed from the desktop app is refreshed on the next launch.
• Windows — the installer runs silently and restarts the app.

If a download fails its checksum it is discarded and the footer shows Update failed; nothing is installed.

Next

• Chatting
• Terminal interface
• Security & sandboxing

Build and run in 10 minutes

When to read this: You have just cloned the repository and want the desktop app, the terminal app and the test suite working before you touch any code.

Goal

A compiled workspace, the terminal app answering a prompt from a local Ollama model with no API key, the desktop app open, and the same checks CI runs passing on your machine.

Prerequisites

• Rust via rustup. The workspace is edition 2024 and declares rust-version = "1.94" in the root Cargo.toml; rustup default stable satisfies it.
• Git and a checkout of https://github.com/boersmamarcel/chatty2.
• Linux: Debian/Ubuntu packages for GPUI (make setup installs them). macOS: Xcode Command Line Tools. Windows: see the repo README.md.
• Optional: Ollama for a zero-configuration local model.

Warning

A full cargo test --all-features needs about 16 GiB of target/ even with the workspace’s trimmed debuginfo profile (at Cargo’s defaults it is more than 28 GiB and does not finish on a 30 GB disk). Read Build disk usage before building on a small disk; sharing one CARGO_TARGET_DIR across worktrees is the biggest single saving.

Steps

1. Clone and install system dependencies

git clone https://github.com/boersmamarcel/chatty2.git
cd chatty2
make setup

On Linux, make setup runs scripts/setup-linux.sh: the lib*-dev package list from CI plus rustup target add wasm32-wasip2. On macOS and Windows it prints what to install by hand and adds the wasm32-wasip2 target.

2. Build the WASM modules and test fixtures

make wasm-modules

Some integration tests load real plugins: echo, benford and the adversarial fixtures under modules/fixtures/. make wasm-modules runs scripts/build-wasm-fixtures.sh, which builds them all and stages each at target/wasm-fixtures/<name>/<name>.wasm beside its module.toml. It is build output, so run it once after every fresh clone (and again after cargo clean).

3. Run the terminal app headless against Ollama

No provider configuration is needed: --ollama queries a running Ollama for its models and injects a provider and model list for the session only. Nothing is written to disk.

ollama serve                      # if it is not already running
ollama pull qwen2.5:0.5b          # any small model works
cargo run -p chatty-tui -- --ollama --model qwen2.5:0.5b --headless -m "Say hello in five words"

--ollama with no value means http://localhost:11434; pass a URL for a remote instance (--ollama http://remote:11434). --headless prints the full response to stdout and exits; logging is suppressed so stdout stays clean. Two related modes:

# Pipe mode: stdin is the prompt
cat src/main.rs | cargo run -p chatty-tui -- --ollama --model qwen2.5:0.5b --pipe

# Interactive TUI
cargo run -p chatty-tui -- --ollama

Without --ollama (or --openai-compat-url), chatty-tui reads the providers and models the desktop app saved, so either run the desktop app once and add a provider, or keep using the direct-connect flags. cargo run -p chatty-tui -- --help lists every flag; the CLI reference summarises them.

4. Run the desktop app

cargo run -p chatty-gpui          # or: make run-gpui

The desktop app detects a running local Ollama and lists its models, so the same zero-configuration setup works here. For hosted models, open Settings → Models and add an OpenRouter API key.

On a Linux machine with no session bus (a headless VM, a container), export XDG_RUNTIME_DIR first or X11 window creation fails with BadMatch:

export XDG_RUNTIME_DIR=/tmp/xdg-runtime-$(id -u) && mkdir -p "$XDG_RUNTIME_DIR" && chmod 700 "$XDG_RUNTIME_DIR"

5. Run the fast tests

make test-fast                    # cargo test -p chatty-core --lib

Most logic lives in chatty-core, so this is the inner loop while you iterate on tools, services and settings models. It needs no display server.

6. Run what CI runs

make ci

make ci is make wasm-modules, then cargo test --all-features, cargo fmt --check, cargo clippy --all-features -- -D warnings, and the reserved-symbol and rig-pin checks. The full suite is the one that needs the disk space above. Make targets & CI workflows lists every target.

Verify

• Step 3 printed a reply and exited with status 0.
• Step 4 opened a window with your Ollama models in the model picker.
• Step 5 and step 6 finished green.

Checklist

• make setup ran (or the equivalent packages and the wasm32-wasip2 target are installed)
• make wasm-modules staged the modules under target/wasm-fixtures/
• chatty-tui --headless answered a prompt
• cargo run -p chatty-gpui opened the desktop app
• make test-fast and make ci pass

Common mistakes

Next

• Your first change: add a tool
• Where do I…? — the how-to index
• Contributing patterns — the conventions the code follows

Your first change: add a tool

When to read this: You have built and run Chatty and want to make a real, end-to-end change: expose a new capability the model can call.

Goal

A word_count tool the agent can invoke, wired the way every built-in tool is wired, with its error path routed through map_tool_error, its schema guarded by the Gemini-compatibility test, its name in the registry, and its row in the tools catalog. Same shape, bigger tool, next time.

Prerequisites

• make test-fast passes on your checkout.
• Read the tool error section of Contributing patterns once; it explains why step 2 is a hard rule.
• Two files open for reference: remember_tool.rs (small, stateful) and execute_code_tool.rs (typed output). The skeleton below is theirs with the business logic removed.

Steps

1. Write the tool

Create crates/chatty-core/src/tools/word_count_tool.rs:

#![allow(unused)]
fn main() {
use rig_agent::tool::{Tool, ToolContext, ToolExecutionError};
use serde::{Deserialize, Serialize};

use crate::tools::ToolError;

#[derive(Debug, Deserialize, Serialize)]
pub struct WordCountArgs {
    /// The text to count
    pub text: String,
}

#[derive(Debug, Serialize)]
pub struct WordCountOutput {
    pub words: usize,
}

/// Count the words in a piece of text.
#[derive(Clone, Default)]
pub struct WordCountTool;

impl Tool for WordCountTool {
    const NAME: &'static str = "word_count";
    type Error = ToolError;
    type Args = WordCountArgs;
    type Output = WordCountOutput;

    fn description(&self) -> String {
        "Count the whitespace-separated words in a piece of text.".to_string()
    }

    fn parameters(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "text": {
                    "type": "string",
                    "description": "The text to count"
                }
            },
            "required": ["text"]
        })
    }

    /// Keep the real failure text in front of the user and the model:
    /// rig's default `map_error` redacts it to "the tool failed".
    fn map_error(&self, error: Self::Error) -> ToolExecutionError {
        crate::tools::map_tool_error(Self::NAME, error)
    }

    async fn call(
        &self,
        _context: &mut ToolContext,
        args: Self::Args,
    ) -> Result<Self::Output, Self::Error> {
        if args.text.trim().is_empty() {
            return Err(ToolError::OperationFailed("text is empty".into()));
        }
        Ok(WordCountOutput {
            words: args.text.split_whitespace().count(),
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn counts_words() {
        let mut ctx = ToolContext::new();
        let out = WordCountTool
            .call(&mut ctx, WordCountArgs { text: "one two  three".into() })
            .await
            .unwrap();
        assert_eq!(out.words, 3);
    }

    #[test]
    fn empty_text_is_an_error_the_model_can_read() {
        let err = WordCountTool.map_error(ToolError::OperationFailed("text is empty".into()));
        let feedback = err.model_feedback().unwrap_or_default();
        assert!(feedback.starts_with("Error: word_count: "), "{feedback}");
    }
}
}

ToolError is the shared one-variant error in tools/mod.rs; use it unless your tool has genuinely distinct failure categories. Every JSON schema object needs a type (step 5 checks this).

2. Route the error path through map_tool_error

The map_error override above is not optional. rig’s default Tool::map_error redacts any source error to a per-kind message — for the common Other kind that message is the literal string "the tool failed", and that is all the model and the transcript ever see. map_tool_error(tool_name, error) in tools/mod.rs keeps the message and writes it as Error: {tool_name}: {message}.

That prefix is also load-bearing: the streamed tool result carries no error flag, so llm_service::tool_result_looks_like_error recognises a failure by the Error: prefix. A tool that bypasses map_tool_error is filed as a success, with its error text in output. Only route errors you authored through it; raw provider or third-party error text is what rig’s redaction exists for.

3. Export it

In crates/chatty-core/src/tools/mod.rs, next to the other modules:

#![allow(unused)]
fn main() {
pub mod word_count_tool;
// …
pub use word_count_tool::WordCountTool;
}

4. Register it

Tool registration is spread over three files in crates/chatty-core/src/factories/agent_factory/; the compiler walks you through each.

1. tool_collector.rs — add a field to NativeTools, a .tool(t) call in apply_to_builder, and the field to the native_tools! macro (both its parameter list and the struct literal it expands to). rig registers typed tools with repeated .tool(T) calls, which is why the struct exists:

   #![allow(unused)]
   fn main() {
   pub word_count_tool: Option<WordCountTool>,
   // in apply_to_builder:
   if let Some(t) = self.word_count_tool {
       b = b.tool(t);
   }
   }

2. mod.rs (from_model_config_with_tools) — construct the tool where the others are built, gated on whatever setting should enable it (Some(WordCountTool) for an always-on tool), and pass it in the single native_tools!(…) call.

3. tool_registry.rs — add a word_count: bool flag to ToolAvailability and insert "word_count" in active_native_tool_names when it is set (or add the name to the always-on set at the top of that function). Then set the flag in both ToolAvailability { … } literals in mod.rs. These names are what list_tools reports, what the preamble’s tool summary lists, and what filter_mcp_tool_info uses to drop MCP tools that would collide with a native name — a tool that is registered but not named here is invisible to the model’s own inventory. The registry tests spell out every flag (all_flags_enabled_produces_superset), so the new field breaks them until you add it; if you chose the always-on set, always_includes_baseline_tools counts them.

Note

A delegated worker started with --tools <profile> sees only the tool names that profile lists in tool_profile.rs (coordinator, coder, reviewer; AGE-405). A new tool is invisible to every team worker until you add its name to the profiles that should have it — the read set if every role needs it, coder for a write-side tool. Leaders and plain sessions are unaffected.

5. Add the Gemini schema guard

Gemini rejects any schema node with an empty type. gemini_compat_tests in tools/mod.rs converts each tool’s definition to a Gemini Tool and walks the result. Add one:

#![allow(unused)]
fn main() {
#[tokio::test]
async fn word_count_tool_gemini_compat() {
    use crate::tools::word_count_tool::WordCountTool;
    check_gemini_compat(rig_agent::tool::tool_definition(&WordCountTool));
}
}

6. Add the catalog row

make docs-check-reference diffs every const NAME under crates/chatty-core/src/tools/ against the tools = [ table in scripts/gen-docs-reference.sh, so CI fails without a row. Add one (("word_count", "text", "word_count_tool.rs", "Always available") follows the existing shape), then make docs-gen regenerates the tools catalog.

7. Run it

cargo test -p chatty-core --lib word_count      # your tests + the gemini guard
make test-fast
cargo run -p chatty-tui -- --ollama --headless -m "Use the word_count tool on: the quick brown fox"
make ci

Verify

• Both unit tests and word_count_tool_gemini_compat pass.
• /tools in the TUI (or list_tools in a conversation) shows word_count.
• Asking for a count produces a tool call in the transcript; an empty string produces Error: word_count: text is empty in the tool row, not “the tool failed”.
• make ci and make docs-check-reference pass.

Checklist

• impl Tool with const NAME, description, parameters, call
• map_error delegates to map_tool_error(Self::NAME, error)
• Exported from tools/mod.rs
• NativeTools field, apply_to_builder call, native_tools! macro entry
• Constructed in from_model_config_with_tools, flag set in both ToolAvailability literals
• Name in active_native_tool_names
• gemini_compat test added
• Row in scripts/gen-docs-reference.sh, make docs-gen run
• Side effects go through an approval store (below)

Approval

Tools with side effects — running commands, writing files — must ask before acting. Shell tools go through ExecutionApprovalStore (models/execution_approval_store.rs); file writes through WriteApprovalStore (models/write_approval_store.rs). Copy the pattern from shell_tool.rs or filesystem_write_tool.rs. Read-only tools like word_count skip approval.

Common mistakes

Tutorial: write a plugin (echo)

When to read this: your first WASM plugin: three tools, built, installed, and called by an agent.

Full source: modules/echo/ (~80 lines). Also see modules/echo/README.md for build commands and the integration-test checklist.

Prerequisites: the wasm32-wasip2 target — make setup, or rustup target add wasm32-wasip2 — before the “Build and install” step below; without it cargo build --target wasm32-wasip2 fails with “the wasm32-wasip2 target may not be installed”.

What a plugin is

A plugin contributes tools to a chatty agent. It never runs a loop of its own and is never an agent itself: an agent spec lists it under [[plugins]], the agent’s model sees its tools as <plugin>__<tool>, and chatty calls the plugin when the model asks for one. The contract is the WIT world chatty:plugin@0.3.0 (WIT reference).

Core: the Plugin trait

Every plugin implements three functions and wires them with export!:

#![allow(unused)]
fn main() {
use chatty_module_sdk::{
    export, Plugin, PluginMetadata, ToolCallRequest, ToolDefinition, ToolError, ToolResult,
};

pub struct Echo;

impl Plugin for Echo {
    fn metadata() -> PluginMetadata { /* … */ }
    fn list_tools() -> Vec<ToolDefinition> { /* … */ }
    fn invoke_tool(call: ToolCallRequest) -> Result<ToolResult, ToolError> { /* … */ }
}

export!(Echo);
}

Plugin and export! are generated by wit-bindgen from the WIT file, so the component’s export names always match what chatty loads.

Step 1 — Metadata

metadata says who the plugin is and which host capabilities it needs. name and version match [module] in its module.toml. echo only logs, and logging is always granted, so it requests nothing:

#![allow(unused)]
fn main() {
fn metadata() -> PluginMetadata {
    PluginMetadata {
        name: "echo".to_string(),
        version: "0.2.0".to_string(),
        description: "Reference plugin: echo, reverse and count_words tools".to_string(),
        requested_capabilities: vec![],
        config_keys: vec![],
    }
}
}

A plugin that calls the model through llm::complete would request Capability::Llm; one that reads [config] values, Capability::Config.

Step 2 — Define tools

list_tools advertises each tool with a JSON Schema for its arguments:

#![allow(unused)]
fn main() {
fn list_tools() -> Vec<ToolDefinition> {
    vec![
        tool("echo", "Returns the input string unchanged.", "String to echo"),
        tool("reverse", "Returns the input string with characters in reverse order.", "String to reverse"),
        tool("count_words", "Returns the number of whitespace-separated words in the input string.", "String to count words in"),
    ]
}
}

(tool is a small helper in src/lib.rs that builds the {"input": string} schema.)

Step 3 — Run a tool call

invoke_tool gets a ToolCallRequest: the tool’s name and the model’s arguments as one JSON object in arguments_json, shaped by the schema the tool declared. It returns the text the model sees, or a typed error the model reads as <kind>: <message>:

#![allow(unused)]
fn main() {
fn invoke_tool(call: ToolCallRequest) -> Result<ToolResult, ToolError> {
    chatty_module_sdk::log::info(&format!("echo: invoke_tool name={}", call.name));

    let run: fn(&str) -> String = match call.name.as_str() {
        "echo" => |input| input.to_string(),
        "reverse" => |input| input.chars().rev().collect(),
        "count_words" => |input| input.split_whitespace().count().to_string(),
        other => return Err(ToolError::unknown_tool(other)),
    };
    Ok(ToolResult::text(run(&input_argument(&call.arguments_json)?)))
}
}

input_argument parses arguments_json and answers ToolError::invalid_arguments when input is missing.

Full implementation → src/lib.rs

Build and install

cd modules/echo
cargo build --target wasm32-wasip2 --release
cp target/wasm32-wasip2/release/echo.wasm .

# Linux: install into chatty's module directory (Settings → Modules shows it)
cp -r . ~/.local/share/chatty/modules/echo/

module.toml beside the .wasm names it:

[module]
name = "echo"
version = "0.2.0"
wasm = "echo.wasm"

[capabilities]
tools = ["echo", "reverse", "count_words"]

[protocols]
mcp = true

Call it from an agent

A plugin does nothing until an agent loads it. Write a spec that lists it, e.g. .chatty/agents/echo-user.toml in your workspace:

[agent]
name = "echo-user"
preamble = "Use the echo tools when asked to transform text."

[[plugins]]
module = "echo"

Then:

chatty-tui --agent echo-user --headless -m "Reverse the word hello."

The model sees echo__echo, echo__reverse and echo__count_words beside its other tools; a call runs the plugin in-process, under its sandbox limits. The next tutorial gives a real agent a plugin: give an agent the plugin (benford).

Expose it to external MCP clients

With [protocols] mcp = true, the desktop’s protocol gateway (Settings → Plugins, module runtime on) also serves the tools to any MCP client that holds its launch token, over a Unix socket rather than a port (Use a plugin from another MCP client):

dir="$XDG_RUNTIME_DIR/chatty-run"
curl -s --unix-socket "$dir/gateway.sock" http://localhost/mcp/echo \
  -H "Authorization: Bearer $(cat "$dir/gateway.token")" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"reverse","arguments":{"input":"hello"}}}'

There is no OpenAI or A2A route for a plugin: it has tools, not a loop.

Automated tests

From the repo root:

make wasm-modules
cargo test -p chatty-protocol-gateway --test echo_plugin_e2e
cargo test -p chatty-tui --test plugins_headless

echo_plugin_e2e covers registry load, the three exports and the MCP route; plugins_headless runs chatty-tui --headless with a spec that calls echo__reverse against a scripted model.

Next steps

• Scaffold your own plugin: templates/module/
• Give an agent a plugin: Tutorial: benford
• Quick start, project layout and testing: Build a WASM plugin
• The contract: WIT reference

Tutorial: give an agent the plugin (benford)

When to read this: you have a plugin (or want one) and want an agent that uses it: a preamble that tells the model what to do, and the plugin’s tools to do it with.

Full source: the plugin in modules/benford/ and the agent spec below, which you write yourself (no preset ships it).

Prerequisites

Complete Tutorial: write a plugin first if you are new to the Plugin trait and module.toml. You need the wasm32-wasip2 target (make setup installs it) and a configured model provider.

The split: the loop is the agent’s, the tools are the plugin’s

A Benford audit is “compute the first-digit distribution, test it, write a report”. Two parts of that are arithmetic, one is judgement:

• The plugin (benford) does the arithmetic, deterministically, in the WASM sandbox: compute_benford_distribution and chi_square_test.
• The agent (auditor) is chatty’s own harness: a spec with a forensic-auditor preamble and plugins = [benford]. Its model decides when to call each tool and writes the report, with everything a chatty agent has: approvals, trace, usage and budgets.

The plugin never calls the model and never loops:

sequenceDiagram
  participant Model as auditor's model
  participant Harness as chatty harness (AgentSession)
  participant Plugin as benford plugin (WASM)

  Harness->>Model: preamble + question, tools incl. benford__*
  Model-->>Harness: call benford__compute_benford_distribution
  Harness->>Plugin: invoke-tool(compute_benford_distribution, numbers)
  Plugin-->>Harness: observed_counts, total_analyzed
  Harness->>Model: tool result
  Model-->>Harness: call benford__chi_square_test
  Harness->>Plugin: invoke-tool(chi_square_test, counts, total)
  Plugin-->>Harness: χ², risk level
  Harness->>Model: tool result
  Model-->>Harness: audit report

Step 1 — The plugin’s tools

benford is a plugin like echo: two tools, each parsing its JSON arguments and returning JSON. It requests no capability.

#![allow(unused)]
fn main() {
fn invoke_tool(call: ToolCallRequest) -> Result<ToolResult, ToolError> {
    let run = match call.name.as_str() {
        "compute_benford_distribution" => compute_benford_distribution,
        "chi_square_test" => chi_square_test,
        other => return Err(ToolError::unknown_tool(other)),
    };
    run(&call.arguments_json)
        .map(ToolResult::text)
        .map_err(ToolError::invalid_arguments)
}
}

Full source → src/lib.rs

Unit tests for the statistical functions run on the host target. The crate’s .cargo/config.toml defaults the build target to wasm32-wasip2, so pass the host target explicitly:

cd modules/benford
cargo test --target x86_64-unknown-linux-gnu   # or your host's triple

Step 2 — Build and install the plugin

One command, from the repo root, builds the plugin and installs it into the module directory the desktop app scans by default:

make example-plugin-benford

Set MODULE_DIR to install somewhere else, e.g. a workspace-local .chatty/modules/benford. Without make (or on Windows), do the same two steps by hand:

cd modules/benford
cargo build --target wasm32-wasip2 --release
mkdir -p ~/.local/share/chatty/modules/benford
cp target/wasm32-wasip2/release/benford.wasm ~/.local/share/chatty/modules/benford/
cp module.toml ~/.local/share/chatty/modules/benford/

Step 3 — The agent spec

An agent is a spec (TOML): who it is, what it is told, what it may use. Write this one to .chatty/agents/auditor.toml in a workspace (or <data_dir>/chatty/agents/auditor.toml):

[agent]
name = "auditor"
description = "Audits a list of amounts against Benford's Law with a chi-square test"
preamble = "You are a forensic auditor. Call benford__compute_benford_distribution with the numbers, then benford__chi_square_test with its observed_counts, and total_analyzed as total. Report the risk level, the chi-square statistic and the digits that deviate most. Every number comes from the tools, never from your own arithmetic."

[tools]
profile = "reviewer"
disable = ["shell"]

[[plugins]]
module = "benford"
version = "^0.2"

• preamble is the system prompt. It names the tools the way the model sees them: <plugin>__<tool>.
• [tools] narrows the native tools: a reviewer, and no shell.
• [[plugins]] loads the plugin into this agent (one instance per agent), resolved by name in the module directory; version is a semver range. The spec is the plugin’s allow-list: a tool profile does not hide plugin tools.
• No grants: the plugin only computes, so it needs nothing beyond logging, which is always on.

Step 4 — Run it

chatty-tui --agent auditor --headless \
  -m "Analyze these invoice amounts: 1234 4521 891 2340 567 8901 234 456 789"

The first digits are 1, 4, 8, 2, 5, 8, 2, 4, 7, so the plugin answers χ² ≈ 10.49 on 8 degrees of freedom: under the 15.507 critical value, risk LOW, digit 1 the most deviant. With nine numbers, that is the expected verdict; the report should say the sample is too small to show an anomaly.

crates/chatty-tui/tests/plugins_headless.rs (a_spec_with_the_benford_plugin_gives_the_chi_square_verdict) runs exactly this spec against a scripted model and checks the verdict the plugin hands back.

Step 5 — Other ways in

• Over MCP, for an external client, the plugin’s tools alone: POST /mcp/benford on the desktop’s protocol gateway ([protocols] mcp = true). The caller orchestrates; there is no report. See the benford README.
• There is no OpenAI or A2A route for the plugin: it is not an agent. The agent is the spec.

Design notes

• Deterministic work in the plugin, judgement in the agent. The model never does the statistics; the preamble tells it to take the χ² and the risk level from the tool.
• Typed errors. Bad arguments come back as invalid-arguments: …, which the model reads and can correct on its next call.
• Nothing to re-implement. Before PL-U3 the module ran its own six-turn loop and fed tool results back as user messages; now the harness does the loop, so compaction, approvals, trace and budgets apply for free.

Further reading

• Build a WASM plugin — quick start, project layout, testing your plugin
• WIT reference — the chatty:plugin@0.3.0 contract

Where do I…?

When to read this: You know the task but not which file or doc to open. This page is the index of the how-to guides; each guide follows the same shape (goal, prerequisites, steps, verify, checklist, common mistakes).

flowchart TD
  Start[What do you need?] --> UI{Change UI?}
  UI -->|Desktop view| V["chatty-gpui/src/chatty/views/ · add-gpui-view.md"]
  UI -->|Settings page| S["chatty-gpui/src/settings/views/"]
  UI -->|Terminal UI| T["chatty-tui/src/ui/"]
  UI -->|Slash command| SC["add-slash-command.md"]
  UI -->|No| LLM{Change LLM behavior?}
  LLM -->|New tool| Tool["chatty-core/src/tools/ · first-change.md"]
  LLM -->|New provider| Prov["ProviderType + agent_factory/ · add-provider.md"]
  LLM -->|Stream bug| SM["stream-manager.md · debug.md"]
  LLM -->|WASM plugin| WASM["build-wasm-module.md + tutorials"]
  LLM -->|No| Data{Change data/settings?}
  Data -->|New setting| Set["settings/models + repositories + GPUI settings"]
  Data -->|Persistence| Repo["repositories/ or settings/repositories/"]
  Data -->|No| Infra{CI / docs / release?}
  Infra --> WF[".github/workflows/ · ci-reference.md"]
  Infra --> Doc["docs/ + docs-site/ · contribute-docs.md"]
  Infra --> Rel["RELEASE_PROCESS.md"]

How-to guides

Tutorials (learn by building) live under Start here: your first change, write a plugin (echo), give an agent the plugin (benford).

Cheat sheet

Add an LLM provider

When to read this: Integrate a new LLM API into Chatty — or find out that you do not need to, because the endpoint already speaks an API Chatty supports.

Goal

A new ProviderType that can be configured in Settings, builds a rig agent with the full native and MCP tool set, streams, reports token usage correctly, and declares sensible default capabilities for its models.

Prerequisites

• Build and run done; make test-fast green.
• Know the three current providers and how they differ: the provider matrix.
• Files to read first: providers_store.rs (ProviderType, ProviderConfig, configured_providers), provider_builder.rs (one match arm per provider), llm_service.rs (streaming and usage normalisation).

Tip

You may not need a new variant. Any OpenAI-compatible chat-completions endpoint (vLLM, llama.cpp, LM Studio, Groq, Together, …) already works as ProviderType::OpenRouter with a custom base_url; that is exactly what chatty-tui --openai-compat-url injects. Add a variant only when the wire format, auth or usage accounting genuinely differ.

Steps

1. Add the ProviderType variant

In crates/chatty-core/src/settings/models/providers_store.rs:

1. Add the variant. The enum is #[serde(rename_all = "snake_case")], so the variant name is the persisted JSON string (AzureOpenAI uses an explicit rename = "azure_openai"). Do not rename an existing variant without a #[serde(alias)]; users’ saved settings would stop loading.
2. Add its arm to display_name().
3. Add its arm to default_capabilities() — (supports_images, supports_pdf) for models created under it: (true, true), (true, false) or (false, false).
4. Decide what counts as configured in configured_providers(). The default arm requires a non-empty api_key; Ollama is always included; Azure needs base_url plus a key or Entra ID.

2. Let the compiler find the other matches

cargo check --all-features

Every non-exhaustive match fails to compile. Today those are build_provider_agent in provider_builder.rs (step 3), the provider string in exporters/atif_exporter/steps.rs, and on the desktop the display-name-to-type mapping and provider list in settings/views/models_page/mod.rs and the per-provider model catalog in add_model_sheet.rs.

3. Build the agent

Add a match arm in build_provider_agent (crates/chatty-core/src/factories/agent_factory/provider_builder.rs). All tool construction happens before this function; the arm only creates the client, configures the builder and attaches tools. The Ollama arm is the smallest template:

#![allow(unused)]
fn main() {
ProviderType::MyProvider => {
    let key = api_key.ok_or_else(|| anyhow!("API key not configured for MyProvider"))?;
    let client = rig_core::providers::my_provider::Client::builder()
        .api_key(&key)
        .build()?;

    let mut builder = client
        .agent(&model_config.model_identifier)
        .preamble(preamble);
    if model_config.supports_temperature {
        builder = builder.temperature(model_config.temperature as f64);
    }
    if let Some(max_tokens) = model_config.max_tokens {
        builder = builder.max_tokens(max_tokens as u64);
    }

    let builder = native_tools.apply_to_builder(builder);
    let agent = build_with_mcp_tools!(builder, mcp_tools, native_tool_names);
    Ok(AgentClient { agent, task_controller, provider: ProviderType::MyProvider })
}
}

Points that differ per provider:

• Client. Prefer a native rig_core::providers::* client when rig has one; otherwise reuse the OpenAI-compatible path with base_url. Check the rig pins in Cargo.toml before relying on a new provider module.
• Auth. ProviderConfig carries api_key, base_url and a free-form extra_config map (Azure keeps its auth_method there). If a credential must be refreshed per request, wrap the HTTP client the way azure_auth_http.rs does rather than awaiting a token inside the stream handler; on_chunk is synchronous.
• Temperature. Only when model_config.supports_temperature; reasoning models reject it.
• OpenAI-family schemas. Call sanitize_mcp_tools_for_openai(mcp_tools) before attaching MCP tools, as the OpenRouter arm does.
• Prompt caching. The OpenRouter arm builds from completion_model(..).with_prompt_caching() and a PromptCachingHttpClient; copy that only if the upstream honours cache_control breakpoints.

4. Check token-usage semantics

stream_prompt in llm_service.rs normalises every provider request’s usage with normalize_usage(UsageSemantics, …). It is currently hard-coded to UsageSemantics::InputIncludesCache because OpenRouter, Azure and Ollama all report OpenAI-style numbers (cached tokens inside prompt_tokens). A provider that reports cached tokens separately (Anthropic-native) needs InputExcludesCache, selected from agent.provider; otherwise input + cache_read + cache_write no longer equals the prompt and the cost and hit-rate figures are wrong. The LLM completion call usage log line is the check (Debug).

5. Settings UI (desktop)

• settings/views/models_page/provider_keys_sheet.rs — one section per provider: key and URL inputs, status line, test-connection label. Add yours.
• settings/controllers/providers_controller.rs — creates or updates the ProviderConfig and persists it through the existing JSON repository; no new repository is needed.
• add_model_sheet.rs — the model catalog shown when adding a model (OpenRouter has one; Ollama and Azure show Catalog::Unavailable).

6. Optional: model discovery

If the API lists models, add crates/chatty-gpui/src/settings/providers/<name>/sync_service.rs following ollama/sync_service.rs or openrouter/sync_service.rs. Keep the HTTP discovery itself UI-agnostic in chatty-core (settings/providers/ollama/discovery.rs is the precedent) so the TUI can reuse it for a direct-connect flag (discover_* + inject_discovered in chatty-tui/src/main.rs). Without discovery, users type model ids by hand.

7. Update the references

Add the provider to the provider-matrix block in scripts/gen-docs-reference.sh and run make docs-gen; describe it for users in Providers & models.

8. Test

cargo test --all-features
cargo clippy --all-features -- -D warnings

Then manually: configure the provider, add a model, send a message and watch it stream; trigger a tool call; attach an image or PDF according to the capabilities you declared.

Verify

• ProviderType round-trips through serde with the string you intended (settings/models/mod.rs has the round-trip tests for the existing variants; add one).
• A conversation streams text and completes a tool call.
• The LLM completion call usage line shows input + cache_read + cache_write equal to the prompt size the provider reports.
• Attachments are offered only for the capabilities you declared.

Checklist

• ProviderType variant, display_name, default_capabilities, configured_providers rule
• Every match updated (cargo check --all-features clean)
• build_provider_agent arm: client, temperature gate, tools, MCP
• Usage semantics correct for the provider’s accounting
• Provider section in provider_keys_sheet.rs; controller persists it
• Provider matrix regenerated; user page updated
• cargo test --all-features and clippy pass; manual chat, tool call and attachment checks done

Common mistakes

audience: [contributor, agent] source_files:

• crates/chatty-gpui/src/chatty/views/chat_input/slash.rs
• crates/chatty-gpui/src/chatty/controllers/app_controller/slash_commands.rs
• crates/chatty-tui/src/engine/commands.rs related:
• ./dev/reference/slash-commands.md
• ./dev/start/first-change.md

Add a slash command

When to read this: Expose a new /command in the chat input. Desktop (GPUI) and terminal (TUI) register commands in different files — there is no shared command table.

Full lookup table: slash commands reference.

Two command shapes

Skills from the project and global skill directories (.agents/skills/, .claude/skills/; see SkillService) appear in both pickers with a skill badge, rescanned each time the picker opens. Do not register a skill as a built-in command.

GPUI (desktop)

1. Add a SlashCommand to SLASH_COMMANDS in crates/chatty-gpui/src/chatty/views/chat_input/slash.rs (command, description, insert_text, execute_immediately).
2. Immediate commands: add a match arm in ChattyApp::handle_slash_command (crates/chatty-gpui/src/chatty/controllers/app_controller/slash_commands.rs).
3. Arg-based commands: handle the prefix in ChattyApp::try_handle_arg_slash_command in the same file. Return true so the message is not forwarded to the LLM.
4. ChattyApp already routes ChatInputEvent::SlashCommandSelected and intercepts Send for arg-based commands — no extra subscribe.

TUI (terminal)

1. Add a Command variant and a parse_command match arm in crates/chatty-tui/src/engine/commands.rs.
2. Handle the variant in the engine (same file / ChatEngine).
3. The TUI slash menu builds from the same Command parse list plus skills (crates/chatty-tui/src/ui/input.rs). If the new command should appear in the / picker, add it there too.
4. Add a parse test in crates/chatty-tui/src/engine/helpers.rs (parses_new_slash_commands).

TUI-only today: /model, /tools, /modules, /update, /quit, /exit. GPUI has no /quit (window chrome handles that).

Parity checklist

• Same command string and argument syntax in both UIs, or document the exception in slash-commands.md (scripts/gen-docs-reference.sh)
• Immediate vs arg-based behavior matches
• Unknown /foo is ignored (TUI) or logged (GPUI) — never sent as a user message if you claimed it as a command
• make docs-gen after changing the reference table

audience: [contributor, agent] source_files:

• crates/chatty-gpui/src/chatty/views/
• crates/chatty-gpui/src/chatty/views/sidebar_view.rs
• crates/chatty-gpui/src/chatty/views/conversation_item.rs
• crates/chatty-gpui/src/chatty/views/app_view.rs
• crates/chatty-gpui/src/chatty/controllers/app_controller/mod.rs
• docs/entity-communication.md related:
• ./dev/architecture/entity-communication.md
• ./dev/reference/event-catalog.md
• ./dev/guides/add-slash-command.md

Add a desktop GPUI view

When to read this: Add a new panel, dialog, or persistent surface in the desktop app (chatty-gpui). Settings pages and the TUI live in different trees — pick from the table first.

Full event lookup: GPUI event catalog. Design rationale: entity communication.

Pick the right kind of UI

Transcript block types (transcript/) render history in the desktop app. Do not leak those types into chatty-core; persistence stays untyped (MessageEntry + system_trace JSON).

Walkthrough: owned entity (SidebarView)

SidebarView is the pattern to copy: typed events, Entity on ChattyApp, one cx.subscribe() in setup_callbacks(), composed in ChattyApp::render.

1. File and module

Create crates/chatty-gpui/src/chatty/views/your_view.rs (or a your_view/ directory with mod.rs if it will grow). Export from crates/chatty-gpui/src/chatty/views/mod.rs:

#![allow(unused)]
fn main() {
pub mod your_view;
pub use your_view::YourView;
}

2. Typed event enum + EventEmitter

#![allow(unused)]
fn main() {
/// Events emitted by SidebarView for entity-to-entity communication
#[derive(Clone, Debug)]
pub enum SidebarEvent {
    NewChat,
    OpenSettings,
    SelectConversation(String),
    DeleteConversation(String),
    ExportConversation(String),
    ToggleCollapsed(bool),
    LoadMore,
}

impl EventEmitter<SidebarEvent> for SidebarView {}
}

Add a variant when the view needs the app to do something. Exhaustive match in the subscriber is the checklist that nothing is unwired.

3. Struct, constructor, mutators

Keep view state on the struct. After mutating, call cx.notify() so GPUI re-renders. Emit from a method when the mutation is the user-visible action:

#![allow(unused)]
fn main() {
pub fn toggle_collapsed(&mut self, cx: &mut Context<Self>) {
    self.is_collapsed = !self.is_collapsed;
    cx.emit(SidebarEvent::ToggleCollapsed(self.is_collapsed));
    cx.notify();
}

pub fn set_conversations(
    &mut self,
    conversations: Vec<(String, String, Option<f64>)>,
    cx: &mut Context<Self>,
) {
    self.conversations = conversations;
    cx.notify();
}
}

4. Render: emit from the entity

In impl Render, clone cx.entity() once and use it from on_click closures. The view entity emits; ChattyApp handles:

#![allow(unused)]
fn main() {
impl Render for SidebarView {
    fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        let sidebar_entity = cx.entity().clone();

        v_flex().id("sidebar").child(
            Button::new("new-chat").label("New Chat").on_click({
                let entity = sidebar_entity.clone();
                move |_event, _window, cx| {
                    entity.update(cx, |_, cx| {
                        cx.emit(SidebarEvent::NewChat);
                    });
                }
            }),
        )
        // ...
    }
}
}

5. IntoElement children keep callbacks — route them through the entity

ConversationItem is #[derive(IntoElement)]. It cannot implement EventEmitter. It takes Arc<dyn Fn> setters, and the parent wires those to cx.emit:

#![allow(unused)]
fn main() {
ConversationItem::new(id.clone(), title.clone())
    .on_click({
        let entity = sidebar_entity.clone();
        let id = id.clone();
        move |_conv_id, cx| {
            entity.update(cx, |_, cx| {
                cx.emit(SidebarEvent::SelectConversation(id.clone()));
            });
        }
    })
}

Same shape for on_delete / on_export. Callbacks stay at the entity/widget boundary only.

6. Own it on ChattyApp

Field + construct in ChattyApp::new (crates/chatty-gpui/src/chatty/controllers/app_controller/mod.rs):

#![allow(unused)]
fn main() {
pub struct ChattyApp {
    pub chat_view: Entity<ChatView>,
    pub sidebar_view: Entity<SidebarView>,
    // ...
}

let sidebar_view = cx.new(|_cx| SidebarView::new());
}

Store WeakEntity<T> in globals (GlobalChattyApp), never a strong Entity — strong refs in globals create cycles.

7. Subscribe once in setup_callbacks()

#![allow(unused)]
fn main() {
cx.subscribe(
    &self.sidebar_view,
    |app, _sidebar, event: &SidebarEvent, cx| match event {
        SidebarEvent::NewChat => {
            app.start_new_conversation(cx);
        }
        SidebarEvent::OpenSettings => {
            cx.defer(|cx| {
                SettingsView::open_or_focus_settings_window(cx);
            });
        }
        SidebarEvent::SelectConversation(conv_id) => {
            app.load_conversation(conv_id, cx);
        }
        // ...
    },
)
.detach();
}

.detach() keeps the subscription alive. Prefer storing a Subscription field (_sub) when the subscriber is a short-lived nested view (see SearchConversationsView).

cx.defer() is required when the handler would re-enter an entity that is already being updated (OpenSettings, ChatInputEvent::ModelChanged, TraceEvent).

ChattyApp can subscribe to a nested entity without owning it, for example self.chat_view.read(cx).chat_input_state() → ChatInputEvent.

8. Compose in the parent’s Render

impl Render for ChattyApp lives in crates/chatty-gpui/src/chatty/views/app_view.rs. Clone the entity into the tree:

#![allow(unused)]
fn main() {
.child(self.sidebar_view.clone())
.child(self.chat_view.clone())
}

AppTitleBar and StatusFooterView are RenderOnce widgets constructed during render — they are not stored on ChattyApp.

9. Catalog a new event enum

If you added a new event enum (not just a variant on an existing one), add a row in the event-catalog.md block in scripts/gen-docs-reference.sh and run make docs-gen.

Dialogs

Two shapes, both opened with window.open_dialog:

Dialogs are not EventEmitter parents of ChattyApp. To trigger app-level work, upgrade GlobalChattyApp and emit on an owned view (search selection emits SidebarEvent::SelectConversation on sidebar_view), or call a ChattyApp method directly.

Nested entities

ChatView subscribes to SystemTraceView (TraceEvent) and to ArtifactView. Child → parent still uses EventEmitter / cx.subscribe(). That TraceEvent handler cx.defers into ChatView to avoid re-entrancy.

App-level actions (send message, new chat, persist feedback) still go up to ChattyApp (ChatViewEvent, ChatInputEvent, SidebarEvent). Do not add Arc<dyn Fn> from ChatView to ChattyApp.

Rules

• Entity-to-entity communication is only EventEmitter / cx.subscribe(). No Arc<dyn Fn> between entities.
• IntoElement / RenderOnce widgets may take callbacks, but those closures must entity.update(cx, |_, cx| cx.emit(…)) on a parent entity.
• Store WeakEntity<T> in globals, never a strong Entity.
• cx.notify() after mutating view state; cx.emit when a parent must act.
• cx.defer() if you need to update an entity that is already being updated.
• Always .detach() a subscription (or keep the Subscription handle).
• Log UI-update failures with warn!() — do not .ok() them away.

Checklist

• File under crates/chatty-gpui/src/chatty/views/ (settings → settings/views/)
• Exported from views/mod.rs
• Entity view: event enum + impl EventEmitter<…>
• ChattyApp (or parent) owns Entity<T> and subscribes in setup_callbacks()
• Composed in the parent Render tree
• IntoElement children route clicks through cx.emit on the parent entity
• New event enum listed in scripts/gen-docs-reference.sh + make docs-gen
• No transcript block types imported into chatty-core

Common mistakes

Reference

• Entity communication
• GPUI event catalog
• Existing emitters: SidebarEvent, ChatInputEvent, ChatViewEvent, StreamManagerEvent, TraceEvent
• Layout/styling: .claude/skills/gpui and .claude/skills/gpui-component

Build a WASM plugin

When to read this: you want to ship tools that a chatty agent loads as a sandboxed WASM plugin.

Goal

A wasm32-wasip2 component targeting chatty:plugin@0.3.0, built from the repo template, installed in the module directory, and listed in an agent spec so the agent’s model can call its tools.

A plugin contributes tools; it never runs a loop and is never an agent. It implements the Plugin trait: metadata (name, version, the host capabilities it requests, the config keys it reads), list_tools and invoke_tool. The host provides one import per capability: llm::complete (a completion on the calling agent’s model; API keys stay on the host), config::get (the manifest’s [config] table), logging::log (always granted), file::read-bytes (reads under a manifest-granted root) and billing (paid plugins). The host links only the capabilities the agent’s spec grants ([[plugins]].grants, a subset of what metadata requests); an ungranted import answers capability <x> not granted to this agent. The contract is in the WIT reference.

Prerequisites

• The wasm32-wasip2 target: make setup, or rustup target add wasm32-wasip2.
• cargo-generate if you want to scaffold from the template (cargo install cargo-generate).

Steps

1. Scaffold

# From a clone of the repo
cargo generate --path templates/module --name my-plugin

# Or straight from GitHub
# cargo generate --git https://github.com/boersmamarcel/chatty2 --name my-plugin templates/module
cd my-plugin

2. Know the project layout

my-plugin/
├── Cargo.toml              # cdylib; standalone [workspace]
├── .cargo/config.toml      # default target = wasm32-wasip2
├── module.toml             # registry manifest
├── src/lib.rs              # impl Plugin + export!
└── my_plugin.wasm          # built artifact (next to module.toml)

The SDK is a path dependency when the plugin lives under modules/ in the repo:

[dependencies]
chatty-module-sdk = { path = "../../crates/chatty-module-sdk" }

The template’s module.toml declares name, version, description and wasm under [module], [capabilities] tools, [protocols] mcp (serve the tools to external MCP clients at /mcp/{name}) and [resources] (max_memory_mb, max_execution_ms; a manifest may only lower the host ceilings). [config] and [files] root are optional. Parsing is strict: an unknown key is an error that names it (the 0.2.0 keys chat and openai_compat included).

3. Implement Plugin

Fill in src/lib.rs: metadata, list_tools, invoke_tool, and export!(MyPlugin). A tool reads its arguments out of call.arguments_json (one JSON object, shaped by the schema it declared) and returns ToolResult::text(...) or a ToolError (unknown_tool, invalid_arguments, denied, failed); the model reads an error as <kind>: <message>.

A tool that needs the model requests Capability::Llm in its metadata and calls:

#![allow(unused)]
fn main() {
use chatty_module_sdk::{llm, Message, Role};

let messages = [Message::new(Role::User, question)];
let reply = llm::complete("", &messages, None).map_err(ToolError::failed)?; // "" = the calling agent's model
}

The call goes through the calling agent’s provider client and its usage is counted as the plugin’s own line in the turn. Worked examples: Tutorial: write a plugin (echo) and Tutorial: give an agent the plugin (benford).

4. Build and install

cargo build --target wasm32-wasip2 --release
cp target/wasm32-wasip2/release/my_plugin.wasm .

# Linux example; macOS is ~/Library/Application Support/chatty/modules/, Windows %APPDATA%\chatty\modules\
mkdir -p ~/.local/share/chatty/modules/my-plugin
cp -r . ~/.local/share/chatty/modules/my-plugin/

5. Give an agent the plugin

List it in a spec, e.g. .chatty/agents/my-agent.toml:

[agent]
name = "my-agent"
preamble = "Use my-plugin's tools to …"

[[plugins]]
module = "my-plugin"

and run chatty-tui --agent my-agent. The model sees each tool as my-plugin__<tool>.

6. Test your plugin

Unit tests for pure-Rust logic run on the host target inside the plugin directory (pass --target <your host triple>: the template’s .cargo/config.toml defaults to wasm32-wasip2, so a bare cargo test tries to execute the .wasm). For the load/export/MCP round trip and a real agent calling the plugin, the repo’s echo suites are the model to copy:

# From the repo root — builds every plugin and fixture
make wasm-modules
cargo test -p chatty-protocol-gateway --test echo_plugin_e2e
cargo test -p chatty-tui --test plugins_headless

Verify

• chatty-tui --agent my-agent --headless -m "…" calls my-plugin__<tool>.
• With the desktop’s module gateway on, tools/list on /mcp/my-plugin over its socket, with its launch token, shows your tools (if [protocols] mcp = true; see Use a plugin from another MCP client).
• A plugin built against another WIT world is refused at load with module targets …; this chatty supports chatty:plugin@0.3.0 — rebuild it with the current SDK.

Checklist

• wasm32-wasip2 target installed
• metadata().name/version match [module] in module.toml
• Every host import the plugin calls is in requested_capabilities (logging needs no request)
• .wasm copied next to module.toml
• An agent spec lists the plugin under [[plugins]], with grants naming the capabilities it may use
• Host-target unit tests for your tool logic

Common mistakes

Reference

Test

When to read this: You want to run the right part of the suite for the change you made, understand why CI runs tests the way it does, or add a test in the place the next reader will look.

Goal

Know which make target or cargo test invocation covers your change, and be able to update a characterization golden deliberately rather than by accident.

Prerequisites

• Build and run: make setup done.
• make wasm-modules has been run (scripts/build-wasm-fixtures.sh). It stages every fixture and the echo and benford plugins under target/wasm-fixtures/<name>/, which is git-ignored; the integration and conformance suites fail with a missing-file error without it.

How the suite is organised

Steps

1. Inner loop

make test-fast                    # cargo test -p chatty-core --lib
cargo test -p chatty-core --lib my_module::   # one module

2. The crate you touched

make test-tui       # cargo test -p chatty-tui
make test-gpui      # cargo test -p chatty-gpui
make test-gateway   # cargo test -p chatty-protocol-gateway

3. Everything, the way CI runs it

make test           # cargo test --all-features

--all-features matters: the excel, docx, pdf, pptx, math-render, mermaid, duckdb and browser tool groups only compile with their feature on, so a plain cargo test never sees them. make ci adds formatting, clippy and the repository check scripts; see Make targets & CI workflows.

Note

Tests run in parallel. CI used to pass --test-threads=1 because chatty-core tests intermittently died with SIGTRAP. The cause was pdfium, which is not thread-safe, being used from several test threads at once; create_pdfium() now hands out a PdfiumHandle that serialises every use (AGE-176). If a SIGTRAP, SIGSEGV or SIGABRT comes back under cargo test, look for a new pdfium call that bypasses create_pdfium() rather than re-adding the flag.

4. Characterization goldens

Turn orchestration — which chunk produces which event, which chunks end a turn, that cancellation produces a cancelled outcome, that sub-agent progress is drained ahead of stream chunks — is pinned by golden files rather than by assertions scattered across tests.

The scripted streams live in chatty_core::services::stream_fixtures (scenarios(), clarification_scenario(), scripted_stream, assert_golden). The module is compiled under #[cfg(any(test, feature = "test-support"))]; chatty-tui and chatty-gpui enable chatty-core/test-support from their dev-dependencies only, so it never reaches a release build.

Both frontends and the core loop drive the same scenarios and record their own event type, so a divergence between the two UIs shows up as a difference between two golden directories:

Each directory holds one file per scenario: text_only, tool_call_then_result, tool_error, approval_granted, approval_denied, clarification_requested, provider_error_mid_stream, cancelled_mid_stream, sub_agent_progress, token_usage_on_done.

When a golden fails, the assertion prints both sequences. If the change is deliberate, rewrite the files and explain the diff in the PR:

UPDATE_GOLDENS=1 cargo test -p chatty-core --lib loop_callback_sequence
UPDATE_GOLDENS=1 cargo test -p chatty-core session::
UPDATE_GOLDENS=1 cargo test -p chatty-tui characterization
UPDATE_GOLDENS=1 cargo test -p chatty-gpui characterization

Deliberately not pinned: the real-time interleaving of progress events with chunks (racy in production, so scenarios queue progress before the chunks it accompanies), and anything wall-clock based — the stall watchdog has its own tests in stream_processor.rs.

5. Where mocks live

• crates/chatty-core/src/tools/test_helpers.rs — MockMcpRepository and MockA2aRepository, in-memory repositories with injectable load/save errors, #[cfg(test)] only. Used by the MCP and A2A tool tests.
• Providers are not mocked; the scripted streams above stand in for a provider whenever a test needs “what the model sent”.
• The desktop characterization test talks to real entities (a ChatView in a headless test window, a live StreamManager), not stubs, so what it records is what the UI receives.
• browser_live.rs builds a throwaway workspace with tempfile rather than fixtures on disk.

Verify

• make test-fast is green after a core change; the crate target is green after a frontend change.
• make test (full, serialised) is green before you push.
• A golden you changed on purpose has its diff explained in the PR.

Checklist

• make wasm-modules has been run on this checkout
• New logic in chatty-core has a unit test beside it
• A new tool has a gemini_compat guard (see Your first change)
• Turn-lifecycle changes re-recorded all three golden directories, not one
• make test passes

Common mistakes

Debug

When to read this: Something is wrong at runtime — a stuck stream, missing or duplicated text, a layout glitch, a tool that “failed” with no message, a cache hit rate that never rises — and you need the switches that expose what happened.

Goal

Find the log line, overlay field or file that explains the symptom, using only what the binaries already emit.

Prerequisites

• A debug build launched from a terminal (cargo run -p chatty-gpui / cargo run -p chatty-tui), so you can set environment variables and see stderr.
• For rendering bugs: Rendering pipeline. For stream bugs: Stream lifecycle.

Steps

1. Turn on logs

Both binaries use tracing with an EnvFilter, so RUST_LOG narrows or widens what you see.

Useful filters:

RUST_LOG=debug cargo run -p chatty-tui                         # everything at debug
RUST_LOG="warn,chatty_core=debug" cargo run -p chatty-gpui     # core only
RUST_LOG="info,chatty_gpui::render=trace" cargo run -p chatty-gpui 2>&1 | tee /tmp/chatty-render.log

The desktop render path logs under the targets chatty_gpui::render::list, ::message, ::stream and ::handler; all four match chatty_gpui::render. Other environment variables the binaries read are in the environment variables reference.

2. The CHATTY_DEBUG_UI overlay

Set CHATTY_DEBUG_UI=1 (any value other than empty or 0) before launching the desktop app to get a monospace overlay in the top-right of the chat pane, one row per message. The flag is read once at process start and costs nothing when unset.

ChatView debug
  msgs: 4 visible / 5 total   awaiting: false   skeleton: false   filtered: 1
  [0] User       s=0 m=0 ti=0 c=23  trace=none
  [1] Assistant  s=1 m=1 ti=2 c=148  trace=live

awaiting: true together with s=1 c=0 on the last assistant row is the expected “waiting for the first token” state; the layout jump when the first token replaces the thinking indicator is what usually gets reported as “whitespace”.

3. Trace a rendering bug

Capture a log with the render targets at trace (the tee command in step 1), reproduce, then grep:

grep -E "render_message_list|render_message |interleave_segment|append_assistant_text|finalize_assistant_message" /tmp/chatty-render.log
grep '"conversation_id":"<id>"' /tmp/chatty-render.log     # one conversation

Events in the order they fire during a streaming turn:

What to look for:

• Whitespace during streaming. A render_message_list transition from visible=1 … is_awaiting=true thinking_visible=true to visible=2 … is_awaiting=false; the frame between them is the jump. With tools involved, render_message showing content_len=0 trace_items>0 followed by a large content_len is the reflow from “trace only” to “text + trace”.
• Overlapping or duplicated text. Across the interleave_segment events of one message, text_before_len must be non-decreasing and each last_text_end must equal the previous text_before_len. If not, two segments render overlapping byte ranges.

Use the existing target convention when adding events (target: "chatty_gpui::render::<area>"), structured fields rather than formatted strings, trace! for per-render events, debug! for one-or-two-per-turn transitions, warn! only for states that should not happen.

4. Stuck or stalled streams

Every stream goes through StreamManager; the loop itself is run_stream_loop in stream_processor.rs and is shared with the TUI, so a lifecycle bug is a core bug.

• Cancellation is a flag (Arc<AtomicBool>) checked at the top of every iteration, not a task drop. A “Stop” that does nothing means the flag never reached the loop, or a stale StreamEnded from a superseded stream (each registration carries an epoch; older epochs are ignored).
• The stall watchdog wakes every STALL_TICK (5 s). After STALL_TIMEOUT (180 s) with no chunk and no sub-agent progress it logs Stream produced nothing for too long; ending the turn as stalled at warn and ends the turn with the error text The model stopped responding (no output for 3 minutes)… (the duration is the timeout that fired: while a tool call runs it is TOOL_STALL_TIMEOUT, 13 minutes). A long tool call is silence from the stream’s point of view, which is why the timeout is generous. --headless resumes a stalled turn itself — a short “continue” prompt on the same history, at most HEADLESS_STALL_RESUME_ATTEMPTS (2) times per task, logged as Auto-resuming the stalled turn (n/2). on stderr; the desktop and interactive TUI leave that to the human.
• The expected event order for each scenario is pinned by the characterization goldens; diff a failing run against them (Test).

5. A tool “failed” with no message

If the transcript or the model sees the literal text the tool failed, the tool’s map_error bypassed map_tool_error. Every impl Tool must route errors through crate::tools::map_tool_error(Self::NAME, error), which writes Error: {tool_name}: {message}. That prefix is also the only failure signal the stream carries — llm_service::tool_result_looks_like_error sniffs it — so a tool that drops it is filed as a success and its error prose lands in output. See Your first change.

6. Prompt caching that does not hit

Each provider request logs one line:

LLM completion call usage turn=2 input=412 cache_read=18220 cache_write=0 output=96 hit_rate=98

input is the uncached share of the prompt, so input + cache_read + cache_write is the whole prompt regardless of provider convention. A hit_rate that stays low from the second request onwards means the prompt prefix is changing between requests — the preamble, the tool block, or the message history is not byte-stable. Never sum calls first and divide later; the rate is per request. Background in Token budget and the token-usage section of Contributing patterns.

7. Browser tool output

browser_console and browser_network return a short summary plus a dump_path. The full capture is written to <workspace>/.chatty/browser/console-<uuid>.log or network-<uuid>.log only when there is something to write; grep the dump when the summary says entries were elided. When a browser tool call appears in the transcript, the desktop docks a live screencast panel next to it, so you can watch the agent drive the page.

8. Reading a system_trace

Assistant messages persist a system_trace JSON column alongside the text in <data dir>/chatty/conversations.db (SQLite; same data directory as the TUI log above). Its shape is SystemTrace from models/message_types.rs:

{
  "items": [
    { "Thinking":  { "content": "…", "summary": "…", "duration": null, "state": "Completed" } },
    { "ToolCall":  { "tool_name": "read_file", "…": "…" } },
    { "ApprovalPrompt": { "…": "…" } },
    { "ClarificationPrompt": { "…": "…" } }
  ],
  "total_duration": null,
  "active_tool_index": null
}

The transcript renders these items; the ATIF and JSONL exporters read them. The tool-call and tool-result messages rig recorded for the turn are persisted as separate rows in front of the final text entry (they carry no trace), so when you count or export turns skip them with services::is_tool_message and count exchanges with services::exchange_count.

Verify

You can name the log line, overlay row or file that shows the bug, and the fix makes that evidence change.

Checklist

• Reproduced with RUST_LOG narrowed to the relevant target
• Rendering bugs: overlay and render trace captured for the same run
• Stream bugs: checked the cancel flag, the epoch and the watchdog line before touching the loop
• Tool failures: confirmed the Error: <tool>: prefix is present

Common issues

Build & package

When to read this: Produce release artifacts or run CI locally.

Goal

The same compile, test and lint path GitHub runs, executed on your machine; and, when you need them, the platform packages the release workflow builds.

Prerequisites

• Build and run done once (make setup, make wasm-modules).
• About 16 GiB of target/ for the full test build (Build disk usage).

Steps

Local CI

make setup        # Linux deps + wasm32-wasip2 (once)
make wasm-modules # WASM plugins and fixtures for tests
make ci           # matches the Rust path of GitHub Actions

make ci runs cargo test --all-features, cargo fmt --check, cargo clippy --all-features -- -D warnings, and the reserved-symbol and rig-pin scripts. GitHub skips that compile path when a PR only changes docs; use make docs and make docs-check for documentation-only work. Every target is listed in Make targets & CI workflows; which tests to run for a smaller change is in Test.

Platform packages

Release builds write a separate target/release/ tree; only build one locally when you are packaging.

Cutting a release

Version bumps, changelog generation, tagging and the cross-platform release build are driven by labels on the PR and the Prepare Release workflow. See the Release process.

Docs site

make docs-gen
make docs
make docs-serve

Verify

make ci exits 0; a package script leaves its artifact in the location it prints.

Common mistakes

Release Process

When to read this: You are about to cut a Chatty release, or a release run did not produce the artifacts you expected.

Closed-system security contract

Only github.repository_owner and github-actions[bot] may arm releases. Forks and outside collaborators cannot:

• Dispatch release.yml / prepare-release.yml manually
• Apply privileged labels (ship:auto, release:patch|minor|major, cut-release)
• Enable ship-auto auto-merge
• Trigger prepare-release from a fork PR head

Linear projects Chatty auto-ship and Chatty tech debt membership is Marcel (and agents he runs). Weekly dependency-check filings go to Linear only.

Emergency rebuild (owner only), when a published release event did not fire. Dispatch against the tag ref (never from main with only an input):

gh workflow run release.yml --ref vX.Y.Z -f tag_name=vX.Y.Z

release.yml verifies the checked-out commit matches refs/tags/vX.Y.Z, asserts that commit is an ancestor of origin/main, and matches Cargo.toml before building.

Authz gate regression check: bash scripts/check-release-authz.sh (also run in CI).

Preferred paths (use these)

A. PR merge with a release label (human path)

1. Open a PR to main with exactly one of release:patch, release:minor, release:major (owner-applied; unauthorized labelers are stripped by privileged-labels.yml).
2. Merge when CI is green. ship-auto-guard enforces the path deny-list on any release-labeled PR.
3. prepare-release.yml bumps Cargo.toml on a release/vX.Y.Z PR (cut-release, not release:patch), merges that PR (main is protected — a direct push gets GH006), generates the changelog, tags vX.Y.Z, creates the GitHub Release with that changelog as its body, and calls release.yml via workflow_call to build artifacts. Runs are serialised by a prepare-release concurrency group so two merges cannot race on the version bump or the tag.

On a PR branch, /create-release patch (or minor/major) only adds the label — it does not create a tag by hand.

B. Auto-ship (zero-human patch releases)

For low-risk work filed in Linear project Chatty auto-ship or Chatty tech debt (with ship:auto + owner:ai, not owner:human):

1. Agent opens PR: branch auto/*, title auto: …, labels ship:auto + release:patch (owner/Actions only).
2. ship-auto-guard.yml enforces patch-only + path deny-list; ship-auto-merge.yml enables squash auto-merge only for same-repo heads when the sender is the owner or the actor is github-actions[bot]. Later synchronize events from other same-repo actors do not re-arm; if auto-merge is already on, the prepare-release waiter still starts.
3. When required checks are green, auto-merge squash-merges to main. The ruleset requires the branch to be current with main; update-next-queued-pr.yml presses “update branch” for the oldest auto-merge-armed PR whenever main moves (and every 30 min as a fallback), so PRs land one at a time without a human. It needs the AUTO_UPDATE_TOKEN secret: a fine-grained PAT scoped to this repo with contents + pull-requests write. GITHUB_TOKEN cannot be used because its branch updates do not trigger CI. A PR in that queue is also in care of pr-nurse.yml (hourly, after any failed CI run, or on dispatch): scripts/pr-nurse-triage.sh picks one PR that is conflicted with main or has a red required check; a Sonnet session resolves the conflict or fixes the check without committing; the workflow validates the tree (no conflict markers, none of .github/workflows/, RESERVED.md, scripts/check-*.sh, .cursor/rules/ touched) and pushes a nurse: commit with the same token. After two nurse commits on one PR, scripts/pr-nurse-decide.sh (AGE-705) decides what happens next from CI on that second push: still pending, it waits; green, it clears the attempt budget and leaves auto-merge armed; red, it disarms auto-merge and labels blocked:human. Removing blocked:human by hand also resets the budget, so the next run does not immediately re-label it. Arming auto-merge is the only way into care; the nurse never merges here.
4. If Actions performed the squash (GITHUB_TOKEN does not emit pull_request.closed), ship-auto-merge dispatches prepare-release (bump=patch). Owner merges still use the pull_request closed path.
5. Same prepare-release → bump PR → tag → release.yml pipeline as (A).

Never hand-tag for auto-ship.

Deprecated for routine releases: GitHub UI release

release.yml has three triggers: the workflow_call from Prepare Release, an owner-only workflow_dispatch (the emergency rebuild above), and the published event of a GitHub Release. There is no tag-push trigger: pushing a vX.Y.Z tag by hand builds nothing.

Publishing a release from the GitHub UI still works and is the way to ship custom release notes, but hand-editing Cargo.toml is easy to desync from the tag. Prefer (A) or (B).

1. Update version in Cargo.toml

   vim Cargo.toml  # Set version = "0.1.21"
   git add Cargo.toml
   git commit -m "Bump version to 0.1.21"
   git push origin main
   

2. Create release via GitHub UI:

   • Go to: https://github.com/boersmamarcel/chatty2/releases/new
   • Choose tag: v0.1.21 (or create new tag)
   • Target: main branch
   • Release title: v0.1.21 or custom title
   • Description: Write custom release notes
   • Important: Click “Publish release” (NOT “Save as draft”) — only the published event triggers the workflow

3. Workflow runs automatically:

   • Validates the tag against Cargo.toml and origin/main
   • Builds for all platforms
   • Uploads artifacts to your release, preserving your release notes

What Gets Built

Each release includes:

• Linux: chatty-linux-x86_64.AppImage
• macOS: chatty-macos-aarch64.dmg (ARM, code-signed if secrets configured)
• Windows: chatty-windows-x86_64.exe (Inno Setup installer)
• Checksums: checksums.txt (SHA-256 for all files)
• Release signature: checksums.txt.sig, an Ed25519 (minisign) signature over checksums.txt, once RELEASE_SIGNING_ENABLED is on — see release-signing.md

The desktop app’s auto-updater (crates/chatty-gpui/src/auto_updater/) polls the GitHub releases API for these assets, so a published release reaches existing installs without any further step. It verifies checksums.txt.sig against the release keys compiled into it before it trusts a hash, and on macOS checks the new bundle’s code signature and Team ID before the swap.

Version Validation

The workflow validates that:

• Tag version (e.g., v0.1.21 → 0.1.21) matches Cargo.toml version
• The tag commit is an ancestor of origin/main
• If either check fails, the workflow fails with an error

Fix version mismatches:

# If you accidentally created tag v0.1.21 but Cargo.toml has 0.1.20:

# Option 1: Update Cargo.toml and re-tag
vim Cargo.toml  # Change to 0.1.21
git add Cargo.toml
git commit -m "Fix version mismatch"
git push origin main
git tag -d v0.1.21           # Delete local tag
git push origin :v0.1.21     # Delete remote tag
git tag v0.1.21              # Recreate tag
git push origin v0.1.21

# Option 2: Use correct version tag
git tag v0.1.20              # Tag matching Cargo.toml
git push origin v0.1.20

Code Signing (macOS)

See scripts/setup-codesigning.md for details.

Quick summary:

• Without secrets: Ad-hoc signed (works locally, Gatekeeper warnings)
• With secrets: Developer ID signed (no warnings, notarization optional)

Required secrets (optional):

• MACOS_CERTIFICATE - Base64 P12 certificate
• MACOS_CERTIFICATE_PASSWORD - P12 password
• KEYCHAIN_PASSWORD - Random keychain password
• MACOS_SIGNING_IDENTITY - Certificate name

Troubleshooting

Workflow fails at validation

Error: “Version mismatch! Tag version (X.Y.Z) does not match Cargo.toml version (A.B.C)” or “Tag … is not an ancestor of origin/main”

Fix: See “Version Validation” section above

Assets not uploaded

Common causes:

1. Build job failed (check Linux/macOS/Windows build logs)
2. Artifact upload failed (check artifact names match)
3. fail_on_unmatched_files: true - files missing
4. Prepare Release created the GitHub Release but release.yml did not build. Reusable workflows inherit the caller’s github.event_name, so the reusable-call path is marked with an explicit from_prepare: true input rather than keyed off the event name.

Rebuild an existing tag (owner only; runs the workflow from that tag):

gh workflow run release.yml --ref vX.Y.Z -f tag_name=vX.Y.Z

Debug:

• Check the “Prepare release assets” step for warnings and the file list
• Ensure build scripts produced expected files

macOS code signing fails

Error: “No identity found” or certificate import fails

Check:

• Secrets are correctly set (base64 encoding, no extra newlines)
• Certificate hasn’t expired
• Keychain password is correct

Fallback: Remove/comment out the “Import code signing certificate” step to use ad-hoc signing

Monitoring Releases

• Actions: https://github.com/boersmamarcel/chatty2/actions/workflows/release.yml
• Releases: https://github.com/boersmamarcel/chatty2/releases

Best Practices

1. Let Prepare Release bump the version — hand-edit Cargo.toml only for a UI release
2. Use semantic versioning: MAJOR.MINOR.PATCH (e.g., 0.1.21, 1.0.0)
3. Tag format: Use v prefix (v0.1.21) for consistency
4. Release notes: Use the GitHub UI path for releases that need hand-written notes
5. Test locally first: Run cargo build --release and ./scripts/package-macos.sh before releasing
6. Check Actions: Monitor the workflow to ensure all platforms build successfully

Not yet automated

• macOS Intel builds (only aarch64 is built)
• Windows code signing (the installer is unsigned)

audience: [contributor] source_files:

• crates/chatty-gpui/src/auto_updater/signature.rs
• crates/chatty-gpui/src/auto_updater/release_keys.txt
• crates/chatty-gpui/src/auto_updater/platform.rs
• .github/workflows/release.yml related:
• RELEASE_PROCESS.md

Release signing and update authenticity

When to read this: you are setting up or rotating the release key, a release failed at sign-checksums, or a user’s update was refused.

Security note (SEC-10, AGE-817)

checksums.txt proves a download is intact, but it comes from the same GitHub release as the binary. Anyone who can write the release (a leaked token, a compromised workflow) can replace both. Two checks close that gap:

• Signed checksums, every platform. release.yml signs checksums.txt with an Ed25519 release key in minisign format and uploads checksums.txt.sig. The updater downloads both and verifies the signature against the public keys compiled into it (auto_updater/release_keys.txt) before it trusts any hash. A missing, malformed or foreign signature refuses the update; there is no unsigned fallback.
• macOS Team ID before the swap. After the DMG is mounted and before anything is copied out of it, the install helper requires: the DMG passes Gatekeeper as Notarized Developer ID (its stapled ticket), the app inside passes codesign --verify --deep --strict, and its TeamIdentifier equals the Team ID compiled into the running app (CHATTY_MACOS_TEAM_ID, set by release.yml from the NOTARIZE_TEAM_ID secret). On refusal the helper leaves the installed app untouched and relaunches it; the reason is in ~/Library/Logs/chatty_update.log.

Not covered: Windows has no code-signing certificate and releases carry no build provenance (decided in AGE-736). An attacker holding the release private key can still ship a signed update; the key therefore lives only in a protected environment that a single job can read.

The one unpinned state

While release_keys.txt lists no key, the updater skips the signature check and logs No release signing key is pinned in this build. That is the state before the runbook below has run. A build without a compiled Team ID (local builds, or releases with MACOS_SIGNING_ENABLED off) skips the Team-ID check the same way: its own releases carry no Team ID.

Where things live

release.yml enforces the pairing both ways: with the switch on, a missing secret or a signature that no pinned key accepts fails the release; with the switch off, a pinned key fails the release. Either way no unsigned release reaches pinned clients.

Runbook: first key

Run on your own machine with minisign installed (brew install minisign or apt install minisign). None of these commands prints the private key.

1. Generate the key in a private scratch directory, without a password (the CI job cannot type one; the protected environment is the access control):

   umask 077 && mkdir -p ~/chatty-release-key && cd ~/chatty-release-key
   minisign -G -W -p release.pub -s release.key
   

2. Create the environment and set the secret. Restrict the environment to the refs releases run from (main for prepare-release.yml, v* tags for the published-release and dispatch paths). Do not add required reviewers: releases are cut automatically and would wait forever.

   gh api -X PUT repos/boersmamarcel/chatty2/environments/release-signing \
     -F 'deployment_branch_policy[protected_branches]=false' \
     -F 'deployment_branch_policy[custom_branch_policies]=true'
   gh api -X POST repos/boersmamarcel/chatty2/environments/release-signing/deployment-branch-policies \
     -f name=main -f type=branch
   gh api -X POST repos/boersmamarcel/chatty2/environments/release-signing/deployment-branch-policies \
     -f name='v*' -f type=tag
   base64 < release.key | tr -d '\n' \
     | gh secret set RELEASE_SIGNING_KEY --env release-signing --repo boersmamarcel/chatty2
   

3. Flip the switch. From now on every release carries checksums.txt.sig (current installs ignore it; the signing job warns that no key is pinned yet).

   gh variable set RELEASE_SIGNING_ENABLED --body true --repo boersmamarcel/chatty2
   

4. Pin the public key. Add the second line of release.pub (the one starting with RW) to release_keys.txt in a PR. Merge it after step 3, never before: a build that pins a key must never be followed by an unsigned release.

5. Release. The signing job now also checks the signature against the pinned key. Installs that update to this release enforce the signature from then on.

6. Store and clean up. Put release.key and release.pub in your password manager, then rm -P (macOS) or shred -u (Linux) both files. Ask the coordinator to add the key ID (minisign -V prints it) to the vault key inventory.

Rotation (two-key window, SEC-3)

1. Generate the new key (step 1) and add its public line to release_keys.txt next to the old one. Release: installs now trust both.
2. Replace the RELEASE_SIGNING_KEY secret with the new key (step 2, last command). Release: signed by the new key, accepted by every install that took step 1’s release.
3. Remove the old line from release_keys.txt. Release.

On a suspected private-key leak, skip the window: pin only the new key, set the new secret, release at once. Installs still on old builds trust the leaked key until they update, so revoke the leaked secret immediately.

When a release fails at signing

• RELEASE_SIGNING_ENABLED is true but the RELEASE_SIGNING_KEY secret is not set: step 2 did not run, or the secret was set at repo level instead of in the release-signing environment.
• does not verify against any key in release_keys.txt: the secret and the pinned public key are from different pairs. Fix whichever is wrong; never remove the pin to get a release out.
• release_keys.txt pins a release key but RELEASE_SIGNING_ENABLED is off: turn the switch back on.

Contribute to the docs

When to read this: You are adding or changing a page on this site and want to know which file to edit, how to preview it, and what CI checks before it merges.

Goal

A change to the right source file, previewed locally, passing make docs-check, landing in the same PR as the code it describes.

Prerequisites

• mdBook (cargo install mdbook) for make docs / make docs-serve.
• lychee (cargo install lychee --locked) and python3 for make docs-check-links and the other check scripts.

Steps

1. Find the file to edit

Most of the site is synced from the repository by make docs-sync. Editing the copy under docs-site/src/dev/ is lost on the next sync.

Hand-written pages, edited in place under docs-site/src/: index.md, user/*, dev/start/*, dev/guides/*, dev/where-to-look.md, dev/crates.md, dev/contributing-patterns.md, dev/glossary.md, dev/ci-reference.md, dev/doc-frontmatter.md. CLAUDE.md and docs/INDEX.md are not synced.

2. Pick the page type

• Tutorial (dev/start/): learn by building; ends with something running.
• How-to (dev/guides/): one task, done. Use the template below.
• Explanation (docs/*.md, synced to dev/architecture/): why it is built this way.
• Reference (dev/reference/, dev/crates/, dev/ci-reference.md, dev/glossary.md): lookup tables.

Working notes — point-in-time plans, audits, bug lists — go to Linear, never into the repo. Experiment write-ups go to the private harbor-chatty repo.

3. Write to the template

Every page starts with the title and a one-line reader test:

# Add a widget

**When to read this:** You need a new panel in the desktop app.

How-to pages then follow goal · prerequisites · steps · verify · checklist · common mistakes, skipping a section only when it would be empty. Rules that keep the site coherent:

• Links inside docs-site/src are relative to the page’s own directory (../architecture/stream-manager.md from a guide). Link Rust source files with full GitHub URLs (https://github.com/boersmamarcel/chatty2/blob/main/...), never with relative paths, since the page moves when it is published.
• User guides (src/user/*) must not carry contributor material: no ticket ids, crate paths, .rs file names or GPUI internals. make docs-check-leakage fails otherwise.
• Do not add docs.rs badges: no workspace crate is published, and the links 404.
• Prefer describing the behaviour over citing the ticket that introduced it.

Callouts use GitHub’s alert syntax and render as boxes on the site:

> [!NOTE]
> Background the reader can skip.

> [!TIP]
> A shortcut.

> [!WARNING]
> Something that costs time or data if missed.

4. Optional frontmatter

A page may begin with a YAML block declaring audience, source_files and related. The schema and the lint are in Doc frontmatter schema.

5. Register a new page

A new docs/*.md needs a row in docs/INDEX.md and an entry in docs-site/src/SUMMARY.md; a new hand-written page needs the SUMMARY.md entry. make docs-check-nav fails when either is missing. A new tool, event, setting or env var needs a row in scripts/gen-docs-reference.sh; make docs-check-reference diffs those tables against the source.

6. Preview and check

make docs-serve        # docs-gen + docs-sync + mdbook serve, opens http://localhost:3000
make docs-check        # everything below

CI runs the same scripts from .github/workflows/docs.yml. Docs-only PRs do not compile the workspace.

7. Ship it in the same PR

Same-PR rule. If a change alters a fact a page claims, update that page in the same PR. A page is stale when someone following it would do the wrong thing, look in the wrong place, or miss a step; internal refactors that keep documented facts true, formatting, comments and dependency bumps need no doc change. The follow-up workflows (update-agent-docs.yml, update-readme.yml) are a safety net, not a reason to skip this. Found a stale page you are not fixing? File a Doc drift issue. The full policy is in CONTRIBUTING.md.

Verify

make docs-check exits 0 and the page reads correctly at http://localhost:3000, in both light and dark theme.

Checklist

• Edited the source file, not the synced copy
• # Title and **When to read this:** line present
• How-to sections in template order
• Relative links within the site; GitHub URLs for source files
• New page listed in SUMMARY.md (and docs/INDEX.md for docs/*.md)
• make docs-check green
• Docs change is in the PR that changed the behaviour

Common mistakes

AGENTS.md

Research crates carry reserved symbols; read RESERVED.md before touching them. It also holds the issue-label and auto-ship rules. Ordinary chatty2 work is unaffected.

Quick-start guide for AI coding agents working in this repository. Optimized for limited context windows: read this first, then dive deeper via the links below.

For human-oriented documentation, see the user guides (published at https://boersmamarcel.github.io/chatty2/). The repo README.md is a short landing page (download, links, dev quick-start). For coding patterns see CLAUDE.md. For architecture, see docs/INDEX.md.

What is this repo?

Chatty — a desktop and terminal AI agent built in Rust. Two binaries (GPUI desktop app, Ratatui terminal app) backed by a shared, UI-agnostic core crate.

Workspace map

crates/
├── chatty-core/              # UI-agnostic: models, services, tools, settings,
│                             #   repositories, factories, exporters
├── chatty-gpui/              # Desktop binary `chatty` (GPUI)
├── chatty-tui/               # Terminal binary `chatty-tui` (Ratatui)
│                             #   also: --headless, --pipe, and acp (stdio) modes
├── chatty-terminal/          # Embedded terminal model: PTY + alacritty Term (no UI)
├── chatty-wasm-runtime/      # Wasmtime runtime for WASM agent modules
├── chatty-module-registry/   # Module discovery, manifest, lifecycle
├── chatty-protocol-gateway/  # HTTP gateway: OpenAI / MCP / A2A protocols
├── chatty-fabric/            # Broker's pure state: Directory, TaskTable, EdgeLog, Transport trait,
│                             #   EndpointBudget/RunPermit, swarm.rs (nested-run event forwarding)
├── chatty-module-sdk/        # SDK for `wasm32-wasip2` modules (standalone)
├── chatty-trace/             # Research: traces / ATIF / FeedbackFn (AGE-5, ships)
├── chatty-playbook/          # Research: ACE playbook (AGE-17, ships)
├── chatty-flow/              # Research: AFlow WorkflowRepr + IR (AGE-13, ships)
├── chatty-optimize/          # Research: GEPA/AFlow + paired stats + QA loaders
├── hive-client/              # Hive registry client
├── hive-e2e/                 # Nightly chatty × Hive contract/trust suite (ignored, run by plugin-e2e.yml)
└── hive-billing-sdk/         # Billing SDK (separate Cargo.lock)

modules/                      # Reference WASM agent modules (echo, benford)
docs/                         # Deep-dive architecture and design docs
scripts/                      # Packaging + setup scripts

Dependency direction: chatty-gpui and chatty-tui depend on chatty-core. chatty-core never depends on a UI crate. GPUI’s Global trait impls live behind the gpui-globals feature.

Where things live (cheat sheet)

Build / test / lint — single source of truth

The CI workflow (.github/workflows/ci.yml) is the ground truth. If a command is not here, it is not what CI runs.

Docs-only PRs (and other diffs that do not match the Rust path filter in ci.yml) skip compile, test, and clippy. The required test check still goes green. Stale CI runs on the same PR are cancelled on the next push.

make setup            # one-time: install Linux deps + wasm32-wasip2 target
make build            # cargo build (debug)
make test             # cargo test --all-features -- --test-threads=1  (matches CI)
make test-fast        # cargo test -p chatty-core --lib  (quick inner loop)
make test-tui         # cargo test -p chatty-tui          (TUI changes only)
make test-gpui        # cargo test -p chatty-gpui         (GPUI changes only)
make test-gateway     # cargo test -p chatty-protocol-gateway  (gateway changes only)
make lint             # cargo clippy --all-features --all-targets -- -D warnings  (matches CI)
make fmt              # cargo fmt
make fmt-check        # cargo fmt --check
make wasm-modules     # build every WASM module and test fixture (needed by tests)
make wasm-template    # cargo-generate a module from templates/module and build it (needs cargo-generate)
make test-benford     # the benford plugin's own unit tests, on the host target
make lint-module-sdk  # clippy chatty-module-sdk for wasm32-wasip2
make test-billing-sdk # hive-billing-sdk's tests, on the host target
make docs-gen         # regenerate docs/generated reference pages
make docs             # sync + build mdBook site (docs-site/book/)
make docs-serve       # local preview at http://localhost:3000
make docs-check-links # lychee link check, sources + built site (AGE-117)
make docs-check-nav   # INDEX.md + SUMMARY.md drift check (AGE-116)
make docs-check-frontmatter  # optional YAML frontmatter schema (AGE-115)
make docs-check-leakage      # user guides must not carry contributor material
make docs-check-reference    # reference tables match tool_registry.rs and friends
make docs-check       # all of the docs checks above
make animations       # re-record README/docs GIFs (scripts/animations/README.md)
make ci               # everything the Rust CI path runs, locally, in order

Or use cargo directly:

cargo build
cargo test --all-features
cargo fmt --check
cargo clippy --all-features --all-targets -- -D warnings

Test-thread footgun (pdfium fixed, AGE-176; CI/make test still serialize, AGE-600)

chatty-core tests used to intermittently die with SIGTRAP because pdfium, which is not thread-safe, was driven from several test threads at once (concurrent FPDF_InitLibrary hits a Chromium CHECK = int3 = SIGTRAP; concurrent rendering corrupts its heap). create_pdfium() now returns a PdfiumHandle that holds a process-wide lock for as long as the caller uses pdfium (crates/chatty-core/src/services/pdfium_utils.rs), so never take a second handle while holding one on the same thread — that SIGTRAP is fixed. Despite that fix, ci.yml’s “Run tests” step still passes --test-threads=1 (GitHub-hosted runners have shown other, unrelated intermittent SIGTRAPs under parallel cargo test), and make test was brought back in line with it for the same reason (AGE-600) — don’t remove --test-threads=1 from either as if it were a leftover pdfium workaround. If a SIGTRAP, SIGSEGV or SIGABRT comes back, look for a new pdfium call that bypasses create_pdfium() first.

Windows footgun

ci.yml never compiles for Windows on a PR — windows-latest only runs in warm-release-cache, which is gated if: push && ref == main (a cache warmer, not a required check). A Windows-only compile error (e.g. code that should be #[cfg(unix)], like the broker/participant modules, AGE-339) rides straight to main and isn’t caught until build-windows fails during a release, shipping an assetless tag. If you touch platform-conditional code, don’t trust a green PR as proof Windows still builds.

Disk footgun

A full cargo test --all-features needs about 16 GiB of target/ even with the workspace’s trimmed dependency debuginfo ([profile.dev.package.*] in the root Cargo.toml); at Cargo’s defaults it needs 28+ GiB and can run a small disk out of space mid-link. See docs/build-disk-usage.md before building on a constrained sandbox or CI runner.

WASM module prebuild

Tests that load real plugins (echo_plugin_e2e, the sandbox, registry and conformance suites, plugins_headless) read them from target/wasm-fixtures/, which is build output. Build them (once per checkout) before running the full test suite; without them those tests fail at once with the path they looked at and this command:

make wasm-modules   # scripts/build-wasm-fixtures.sh; needs the wasm32-wasip2 target

Running

cargo run -p chatty-gpui              # desktop app
cargo run -p chatty-tui               # terminal app
cargo run -p chatty-tui -- --help     # CLI options (headless / pipe / direct providers)

Conventions to follow

These are the patterns the codebase already uses. Follow them; don’t invent new ones. See CLAUDE.md for full rationale and examples.

• Event-driven entity communication — Use EventEmitter + cx.subscribe(). No Arc<dyn Fn> callbacks between entities. See docs/entity-communication.md.
• Optimistic updates — Update the in-memory global immediately, then persist asynchronously with logged errors.
• Entity refs in globals — Default to GlobalWeakEntity<T> (avoids circular ownership); use GlobalStrongEntity<T> only when the global must keep the entity alive itself (e.g. StreamManager, ModelsNotifier).
• Stream lifecycle — All LLM streams go through StreamManager with cancellation tokens; the stream loop never updates UI directly, it emits events. Streams carry a monotonic epoch so a stale StreamEnded can’t tear down a newer turn, and a shared stall watchdog (chatty-core/src/services/stream_processor.rs) ends a turn after 180s of silence; --headless auto-resumes a stalled turn itself, up to HEADLESS_STALL_RESUME_ATTEMPTS (2) times, before failing the run. See docs/stream-manager.md.
• Turn budget — TurnBudget (chatty-core/src/services/turn_budget.rs) is a rig hook every stream_prompt call registers: it tells the model how many tool turns are left once most of the budget is spent, and gives it one final tool-free call to answer instead of letting rig’s MaxTurnsError swallow an in-progress reply. max_agent_turns defaults to 0 (no cap, not the old 10); an unattended run with no cap (--headless, --pipe, a delegated worker) instead runs under a wall-clock budget, chatty-tui --max-duration <secs|30m|2h> (default 30m).
• Error handling — Don’t .ok() away errors silently. Log as warn!() for non-critical paths; propagate with ? for critical I/O.
• Tool errors — Every impl Tool’s error path must go through map_tool_error(tool_name, error) (chatty-core/src/tools/mod.rs), not rig’s default Tool::map_error, or the model/transcript only ever see the redacted string "the tool failed". See “Tool Error Reporting Pattern” in CLAUDE.md.
• MCP API keys — When sending MCP config to the LLM, report has_api_key(), never the api_key field; a "****" (MASKED_API_KEY_SENTINEL) sent back by the model means “keep the stored value”. See “Security Practices” in CLAUDE.md.
• Rust edition — 2024. Use LazyLock/OnceLock (std) rather than lazy_static/once_cell.
• GPUI / gpui-component skills — When changing desktop UI, load .claude/skills/gpui and .claude/skills/gpui-component (vendored from npx skills add longbridge/gpui-component; lockfile skills-lock.json).
• Desktop screenshot harness — A desktop UI change is not done until it has been seen running. .claude/skills/desktop-screenshot starts the app under Xvfb on an isolated config, drives it with XTest (x.py), and screenshots it; read the PNGs and attach them to the Linear issue. It also lists the gpui traps that only a live run shows.
• Transcript blocks — Typed block/turn types in chatty-gpui/src/chatty/views/transcript/ render the transcript; persistence stays untyped (MessageEntry + system_trace JSON) in chatty-core. Don’t leak transcript block types into chatty-core. chatty-tui has its own parallel MessageBlock enum (chatty-tui/src/engine/mod.rs) matching the desktop’s behaviour (activity folds, inline approvals, plan, error, diff) without sharing widgets or a chatty-gpui dependency — see CLAUDE.md. The gpui transcript list uses gpui’s list/ListState (measured heights), not v_virtual_list (predicted heights) — see CLAUDE.md.
• Tool failure signal is text, not a flag — map_tool_error()’s Error: {tool_name}: {message} prefix is the only thing that tells llm_service::tool_result_looks_like_error a tool call failed. Don’t drop or reword that prefix. See CLAUDE.md.
• Stale docs — If a change alters a fact a page claims, update that page in the same PR. update-agent-docs.yml only safety-nets AGENTS.md / CLAUDE.md. See the Documentation section of CONTRIBUTING.md.
• Experiments live in harbor-chatty, not here — pre-registrations, run reports, spikes, benchmark harnesses and their task fixtures go in the private harbor-chatty repo under experiments/. chatty2 keeps the research crates’ design notes (docs/research/modules/), process docs, baselines its own benches check against, and a short summary in the user guide for any result a shipped feature relies on. Never commit one-off helper scripts or agent work notes (implementation summaries, plans).

Known gotchas

1. No chatty-gpui::chatty::* re-exports. crates/chatty-gpui/src/chatty/mod.rs used to re-export auth, exporters, factories, repositories, tools from chatty_core; those re-exports were removed so call sites import chatty_core::… directly. If grep finds no definition under chatty-gpui/, look in chatty-core/. scripts/check-no-core-reexports.sh (in CI) fails the build if they come back.

2. Test parallelism. See “Test-thread footgun” above: the pdfium SIGTRAP is fixed, but CI and make test intentionally still pass --test-threads=1 for an unrelated runner flake — that isn’t a regression to “fix”.

3. WASM plugin prebuild. The tests that load plugins fail immediately, naming the missing path and make wasm-modules, if you haven’t built them on this checkout.

4. Linux system packages. GPUI needs a long list of lib*-dev packages. Run make setup (or scripts/setup-linux.sh) on a fresh machine.

5. Standalone crates, own lockfiles, wasm32 by default. crates/hive-billing-sdk/, modules/benford/ and crates/chatty-module-sdk/ each declare their own [workspace] and Cargo.lock (intentional) — bump their deps in that lockfile, not the root one. hive-billing-sdk and benford also default to wasm32-wasip2 via their own .cargo/config.toml, which has no libtest runner, so cargo test there needs an explicit host target: cargo test --manifest-path <crate>/Cargo.toml --target x86_64-unknown-linux-gnu (make test-billing-sdk / make test-benford do this; CI runs the same, AGE-600).

6. The gpui-globals feature. chatty-core types implement gpui::Global only when this feature is enabled. chatty-gpui enables it; chatty-tui does not. If a Global impl is missing, add it in crates/chatty-core/src/gpui_globals.rs.

7. Sub-agent worktrees. Delegated workers (invoke_agent → local-agent or a named virtual agent; sub_agent was retired in AGE-303) each get their own git worktree under <workspace>/.chatty/worktrees/<name> on a sub-agent/<name> branch (AGE-314), passed to the child via chatty-tui’s --workspace <DIR> flag. <name> is a wish, not a guarantee: if that branch or directory already exists in the repository (another root process’s worker, or a tree left from an earlier run), the first free <name>-N (from 2) is used instead, and the evidence envelope names the branch actually created (AGE-402). Worktrees are left in place after a worker exits (never auto-removed) and are excluded via .git/info/exclude, not .gitignore — they won’t show in git status but can still accumulate on disk. In a git repository, a worktree that cannot be created now fails the delegation instead of silently sharing the tree; only a workspace that isn’t a git repo falls back to the old shared-tree behavior. See CLAUDE.md.

8. Large module directories. Several complex areas have been split into sub-module directories (chat_view/, chat_input/, auto_updater/, trace_components/, transcript/, etc.). Start with the mod.rs and its module-level docstring to scope what you need before loading sibling files. The largest single files are message_ops.rs (~1260 lines) and main.rs (~1225 lines).

9. rpptx is pinned to a fork. The root Cargo.toml patches rpptx, oxml-layout and oxml-pdf to boersmamarcel/rdocx via [patch.crates-io] (AGE-343/AGE-474) — the published rpptx = "0.12.1" doesn’t compile alongside usvg and mishandles real decks. cargo update will not move it off the fork; don’t “fix” the patch block without checking whether upstream has actually shipped a release with those fixes. See CLAUDE.md.

10. The agent shell loads the login profile, but still starts --norc --noprofile. shell_service runs bash on a PTY (chatty-terminal) and sources /etc/profile and the first of ~/.bash_profile/~/.bash_login/~/.profile in its init, before the first prompt (output discarded, PS1 unset while it runs), so a project’s conda env or PATH additions reach the model’s commands. Command completion is read from OSC 133 / OSC 6973 marks in the byte stream, not printed marker lines. If you’re debugging a shell tool that behaves differently interactively vs. under the agent, check what the login profile does, not .bashrc (never sourced). See CLAUDE.md.

Deeper reading

Cloud VM notes

Build/test/lint/run commands are unchanged — use the make targets above. These are only the non-obvious caveats of a headless cloud build VM.

• Toolchain. The workspace is edition 2024 and declares rust-version = "1.94" in the root Cargo.toml (the research crates inherit it). If a build fails with feature edition2024 is required, the VM’s default toolchain is too old: run rustup default stable. CI uses dtolnay/rust-toolchain@stable, so it always runs ahead of the declared MSRV; if a dependency raises the floor, bump rust-version and name the dependency in the commit.

• Use GNU cc/c++, not clang. The bundled DuckDB C++ build and the desktop binary link fail under the system clang (fatal error: 'memory' file not found, unable to find library -lstdc++). If you see either, run sudo update-alternatives --set cc /usr/bin/gcc and sudo update-alternatives --set c++ /usr/bin/g++.

• The WASM fixtures under target/wasm-fixtures/ are build output and required by some integration tests; run make wasm-modules after a fresh checkout.

• Disk. A full --all-features test build needs about 16 GiB of target/; see docs/build-disk-usage.md before running it on a small VM.

• Running the desktop app headlessly. The VM has no GPU but software Vulkan (Mesa llvmpipe/lavapipe) works on the existing X11 display (DISPLAY=:1). Export XDG_RUNTIME_DIR first, e.g. export XDG_RUNTIME_DIR=/tmp/xdg-runtime-$(id -u) && mkdir -p "$XDG_RUNTIME_DIR" && chmod 700 "$XDG_RUNTIME_DIR", otherwise X11 window creation fails with BadMatch. chatty-tui needs none of this.

• No LLM API key is configured. To chat from either frontend, use a local Ollama: ollama serve (systemd is not running, so launch it in a background/tmux session), ollama pull qwen2.5:0.5b, then ./target/debug/chatty-tui --ollama http://localhost:11434 --model qwen2.5:0.5b --headless -m "...". The desktop app auto-detects a running local Ollama and lists its models with no configuration.

• Clippy is clean workspace-wide. cargo clippy --workspace --all-features --all-targets -- -D warnings passes (AGE-174). CI added --all-targets so tests/benches/examples are linted too — without it, lints inside tests/ go unreported (a finding sat unnoticed in chatty-protocol-gateway’s e2e test until this was added). make lint/make ci now pass --all-targets too (AGE-600), so a clean make lint matches CI’s clippy invocation exactly.

• Local rustc lints strictly less than CI’s. This VM’s default toolchain (1.94.1) can be behind the stable CI uses (e.g. 1.98.1) — clippy findings visible only on newer stable (such as redundant glob imports) can pass locally and fail CI. Run rustup run stable cargo clippy ... before trusting a green local clippy if CI still fails.

System overview

When to read this: You need a one-page mental model of Chatty before diving into crate-level or file-level docs.

Chatty is a Rust agent framework with two user-facing frontends (desktop GPUI and terminal TUI) sharing one UI-agnostic core. Optional WASM modules and an HTTP gateway extend the same tool and conversation model to external protocols.

Three layers

flowchart TB
  subgraph frontends [Frontends]
    GPUI["chatty-gpui<br/>Desktop app"]
    TUI["chatty-tui<br/>Terminal + headless"]
  end

  subgraph core [chatty-core — shared brain]
    Models["Models & stores"]
    Services["Services"]
    Tools["LLM tools"]
    Factories["AgentFactory"]
    Repos["Repositories"]
  end

  subgraph extensions [Extensions]
    WASM["WASM modules<br/>chatty-module-*"]
    Gateway["protocol-gateway<br/>OpenAI / MCP / A2A"]
    Research["Research crates<br/>trace / playbook / flow / optimize"]
  end

  subgraph external [External]
    LLM["LLM providers"]
    MCP["MCP servers"]
    Docker["Docker sandbox"]
    Marketing["Marketing site<br/>github.com/boersmamarcel/chatty"]
    Docs["Developer docs<br/>GitHub Pages mdBook"]
  end

  GPUI --> core
  TUI --> core
  Gateway --> core
  WASM --> core
  Research --> core
  Factories --> LLM
  Tools --> MCP
  Tools --> Docker
  GPUI -.-> Marketing
  GPUI -.-> Docs

Role of each major crate

Dependency rule: frontends → core. Core never depends on GPUI or Ratatui. See workspace-crate-split.md for the feature flag that lets core types act as GPUI globals.

Startup sequence (desktop)

chatty-gpui/src/main.rs runs, in order:

1. Create the Tokio runtime and enter it for the whole process lifetime.
2. Initialise the settings repositories (RepositoryRegistry) and resolve — but do not open — the SQLite conversation database path (ConversationSqliteRepository::deferred).
3. Start the GPUI Application; inside run, do only what the first frame needs: gpui_component::init, the theme registry (baked-in default applied now, theme pack loaded later), and every global the root view reads, registered with defaults (GeneralSettingsModel, ProviderModel, ModelsModel, McpServersModel, ExecutionSettingsModel, TokenTrackingSettings, GlobalStreamManager, approval stores, …). No I/O happens here.
4. Open the window and create the ChattyApp entity; open_window paints the first frame synchronously.
5. Only then spawn the async tasks that load settings JSON, conversation metadata (the first query opens the SQLite pool), token-tracking settings, the memory service, the skills listing and enabled MCP servers from disk, overwriting the defaults as they arrive. The updater poll and the MCP update channel start here too.

Since AGE-161 the rule is: anything that reads a file, touches the network or spawns a task belongs after open_window. Nothing on the UI thread waits for disk or network; each loader updates its global and refreshes the windows when done. boot_timing::checkpoint marks each stage (main_to_run, run_to_open_window, …) and log_summary prints the timeline at info level once the conversation list has loaded and the app is ready to send.

End-to-end message path

sequenceDiagram
  participant User
  participant UI as GPUI or TUI
  participant App as ChattyApp / ChatEngine
  participant SM as StreamManager
  participant AF as AgentFactory
  participant LLM as LLM provider
  participant Tools as Native + MCP tools

  User->>UI: Type message
  UI->>App: Submit event
  App->>AF: Build AgentClient
  App->>SM: Register stream
  App->>LLM: stream_prompt (multi-turn)
  loop ReAct loop
    LLM->>Tools: Tool call
    Tools-->>LLM: Tool result
  end
  LLM-->>SM: Stream chunks
  SM-->>UI: StreamManagerEvent
  UI-->>User: Render response
  App->>App: Persist conversation

Key design decisions

1. Central controller. ChattyApp (chatty-gpui/src/chatty/controllers/app_controller/) owns the top-level view entities, subscribes to their events and coordinates services, stores and views. It is deliberately a “fat controller” so the event flow stays traceable in one place; the module is split by concern (message_ops, conversation_ops, slash_commands, export_ops).
2. Event-driven communication. Entities talk only through EventEmitter / cx.subscribe(); there are no Arc<dyn Fn> callbacks between entities. See entity-communication.md.
3. StreamManager owns the stream lifecycle. The stream loop never touches a view; it updates the Conversation and forwards chunks to StreamManager, which emits typed events that handlers route to views. Cancellation is a shared AtomicBool. See stream-manager.md.
4. Global state via GPUI. App-wide state implements Global and is reached with cx.global(); entity references inside globals default to WeakEntity<T> so globals do not keep entities alive by accident.
5. Provider abstraction. ProviderType::default_capabilities() seeds a new model, ModelConfig persists per-model capabilities, and AgentFactory builds the provider-specific client.
6. Tools are rig Tool implementations registered by AgentFactory; side-effecting tools (shell, file writes) go through the approval stores first. The full list is the tools catalog.

Where to go next

Component map

When to read this: You need to see how runtime pieces connect — which entity owns what, where events flow, and which module to open for a given concern.

Workspace crate relationships

flowchart LR
  subgraph ui [UI layer]
    GPUI[chatty-gpui]
    TUI[chatty-tui]
  end

  subgraph core [chatty-core]
    direction TB
    CModels[models/]
    CServices[services/]
    CTools[tools/]
    CFactory[factories/agent_factory]
    CSettings[settings/]
    CRepos[repositories/]
    CSandbox[sandbox/]
  end

  subgraph wasm [WASM stack]
    Reg[module-registry]
    RT[wasm-runtime]
    GW[protocol-gateway]
    SDK[module-sdk]
  end

  GPUI --> core
  TUI --> core
  GPUI --> Reg
  GPUI --> GW
  GW --> Reg
  GW --> RT
  Reg --> RT
  SDK -.-> RT

  CFactory --> CTools
  CFactory --> CServices
  CServices --> CSandbox
  CSettings --> CRepos
  CModels --> CRepos

chatty-core internal modules

Each box is a top-level module under crates/chatty-core/src/.

flowchart TB
  subgraph core [chatty-core]
    models["models/<br/>Conversation, Message,<br/>ConversationsStore, approvals"]
    settings["settings/<br/>ProviderModel, ModelsModel,<br/>McpStore, JSON repos"]
    repositories["repositories/<br/>SQLite conversations"]
    factories["factories/<br/>AgentFactory per provider"]
    services["services/<br/>LLM, shell, MCP, math,<br/>browser (CDP), A2A client, sync"]
    tools["tools/<br/>LLM Tool impls"]
    sandbox["sandbox/<br/>Docker + Monty"]
    token_budget["token_budget/<br/>count, summarize, cache"]
    exporters["exporters/<br/>ATIF, JSONL"]
    auth["auth/<br/>Azure OAuth"]
  end

  factories --> tools
  factories --> services
  services --> sandbox
  services --> settings
  models --> repositories
  settings --> repositories
  token_budget --> models
  exporters --> models

GPUI desktop architecture

ChattyApp is the hub; views emit events upward; services live in core.

flowchart TB
  subgraph views [chatty-gpui views]
    Sidebar[SidebarView]
    ChatView[ChatView]
    ChatInput[ChatInput]
    Settings[Settings pages]
  end

  subgraph controller [app_controller]
    ChattyApp[ChattyApp entity]
    MsgOps[message_ops]
    ConvOps[conversation_ops]
    Slash[slash_commands]
  end

  subgraph gpui_models [GPUI-specific models]
    StreamMgr[StreamManager]
    ErrorNotif[ErrorNotifier]
  end

  subgraph core [chatty-core]
    Stores[Global stores]
    AgentFactory[AgentFactory]
    ConvRepo[ConversationRepository]
  end

  Sidebar -->|SidebarEvent| ChattyApp
  ChatInput -->|InputEvent| ChattyApp
  ChatView -->|ChatViewEvent| ChattyApp
  ChattyApp --> MsgOps
  ChattyApp --> ConvOps
  ChattyApp --> Slash
  MsgOps --> AgentFactory
  MsgOps --> StreamMgr
  StreamMgr -->|StreamManagerEvent| ChattyApp
  ChattyApp --> ChatView
  ChattyApp --> Stores
  ConvOps --> ConvRepo
  Settings --> Stores

Entity event bus (simplified)

flowchart LR
  Sidebar -->|SelectConversation| App[ChattyApp]
  Input[ChatInput] -->|PressEnter| App
  App -->|append_text| ChatView
  StreamMgr[StreamManager] -->|TextChunk| App
  App -->|append_text| ChatView
  StreamMgr -->|StreamEnded| App
  App -->|finalize| ChatView
  App -->|refresh list| Sidebar

Full topology: entity-communication.md.

Stream lifecycle ownership

stateDiagram-v2
  [*] --> Active: StreamManager.register
  Active --> Active: TextChunk / ToolCall events
  Active --> Completed: LLM done
  Active --> Cancelled: user stop / cancel_flag
  Active --> Error: stream error
  Completed --> [*]: ChattyApp finalizes + saves
  Cancelled --> [*]: ChattyApp finalizes partial
  Error --> [*]: ErrorNotifier + UI message

The async stream loop only updates Conversation and StreamManager — never GPUI views directly. See stream-manager.md.

Tool execution path

flowchart TB
  LLM[LLM tool_call] --> Rig[Rig Agent loop]
  Rig --> ToolImpl[chatty-core Tool]
  ToolImpl --> Approval{Needs approval?}
  Approval -->|yes| ApprovalStore[ExecutionApprovalStore]
  ApprovalStore --> UI[GPUI prompt / TUI y/n]
  UI --> ToolImpl
  Approval -->|no| Execute[Run operation]
  Execute --> Shell[shell_service]
  Execute --> FS[filesystem tools]
  Execute --> MCP[McpService]
  Execute --> Sandbox[sandbox / execute_code]
  Execute --> Result[Tool output to LLM]

WASM module stack

flowchart LR
  Author[Module author] --> SDK[chatty-module-sdk]
  SDK --> WASM[".wasm artifact"]
  WASM --> Registry[module-registry]
  Registry --> Runtime[wasm-runtime]
  Runtime --> Tools[invoke_agent / list_agents]
  Gateway[protocol-gateway] --> Runtime
  External[External HTTP client] --> Gateway
  Runtime --> LLM[Host llm::complete import]
  LLM --> Providers[LLM providers]

See build-wasm-module guide (sequence diagrams) and agents-and-specs.md and plugins.md.

Research touchpoints

Production components above are where promoted research mechanisms land. For a bidirectional map (memory → M4 ACE, token budget → M3/M4, sub-agents → M2 AFlow, …) see research/app-research-bridge.md.

Workspace crate split

When to read this: You are about to add code and need to decide which crate it belongs in, or you need to know how chatty-core types become GPUI globals.

Chatty is a Cargo workspace. The three application crates:

chatty-core never depends on either frontend. The dependency direction is:

chatty-gpui ──depends on──► chatty-core (with the gpui-globals feature)
chatty-tui  ──depends on──► chatty-core (without it)

The other workspace crates (WASM runtime, module registry, protocol gateway, module SDK, Hive clients, research crates) are listed in system-overview.md. One of them sits below chatty-core:

Both chatty-core and chatty-protocol-gateway depend on chatty-fabric, so it depends on neither, and never on axum, wasmtime, hive-client, gpui or reqwest (crates/chatty-fabric/tests/no_heavy_deps.rs fails the build if it does). chatty-core payloads (InvokeAgentProgress, conversations, usage) cross it as serde_json::Value; chatty-core converts them at its edge (services::fabric_transport, from BI-4).

The gpui-globals feature

chatty-core types (stores, settings models, services) must implement GPUI’s Global trait for chatty-gpui to use cx.set_global() / cx.global(), but chatty-core must not link GPUI for the terminal build. The impl Global blocks therefore live in one conditional module:

# crates/chatty-core/Cargo.toml
[features]
gpui-globals = ["dep:gpui"]

[dependencies]
gpui = { workspace = true, optional = true }

#![allow(unused)]
fn main() {
// crates/chatty-core/src/lib.rs
#[cfg(feature = "gpui-globals")]
mod gpui_globals;

// crates/chatty-core/src/gpui_globals.rs
impl Global for crate::settings::models::GeneralSettingsModel {}
impl Global for crate::models::ConversationsStore {}
// … every type that needs cx.set_global()
}

chatty-gpui enables the feature in its chatty-core dependency; chatty-tui does not, and instead holds core services and models as fields on its ChatEngine.

To add a new global type: define it in chatty-core, add impl Global for crate::…::MyStore {} to gpui_globals.rs, then call cx.set_global(MyStore::new()) from chatty-gpui as usual.

Decision criteria

Ask: “Does this code need GPUI’s Context, Window, Entity, Render, or EventEmitter?”

• Yes → chatty-gpui
• No, but it is terminal rendering or TUI-only orchestration → chatty-tui
• No → chatty-core

Anything that both frontends could run — stream processing, tool execution, settings persistence, token counting — belongs in chatty-core even if only one frontend uses it today. The ui-sync-check workflow flags a change in one UI crate without the other.

No re-exports of core modules

chatty-gpui and chatty-tui import chatty-core’s UI-agnostic modules (auth, exporters, factories, repositories, tools) as chatty_core::… at every call site rather than re-exporting them under a local path, so a definition’s crate is visible from its import; scripts/check-no-core-reexports.sh, run in CI, fails the build if either crate re-introduces such a re-export.

Note

If you grep for a definition under crates/chatty-gpui/src/ and find nothing, it lives under crates/chatty-core/src/.

Contributing patterns

When to read this: You are about to change Rust code in chatty-core or chatty-gpui and want to know which conventions a review will hold you to, and why.

Chatty is a GPUI desktop app with a shared, UI-agnostic core. Most of the rules below exist because GPUI’s entity/context model has sharp edges: ownership cycles are easy to create, async work has to re-enter the app through a context, and a swallowed error is invisible in a GPU-rendered UI. The rules are short; the “why” is what makes them stick.

The four non-negotiables

1. Entities talk through events, not callbacks

Entity-to-entity communication uses EventEmitter and cx.subscribe(). Never hand one entity an Arc<dyn Fn> pointing into another: the closure captures an entity handle, the handle keeps the other side alive, and you have built a reference cycle that GPUI cannot see. Events keep ownership one-directional and let the parent decide what a child event means. IntoElement components (plain structs such as ConversationItem) may still take on_click-style callbacks, but those callbacks must do nothing except cx.emit() on the owning entity.

#![allow(unused)]
fn main() {
// WRONG — callback captured by another entity, ownership cycle
sidebar.set_on_select(Arc::new(move |id, cx| app.load_conversation(id, cx)));

// RIGHT — child emits, parent subscribes
impl EventEmitter<SidebarEvent> for SidebarView {}

cx.subscribe(&self.sidebar_view, |app, _sidebar, event: &SidebarEvent, cx| {
    if let SidebarEvent::SelectConversation(id) = event {
        app.load_conversation(id, cx);
    }
})
.detach();
}

2. Weak entity references in globals, strong only when the global is the owner

crates/chatty-gpui/src/global_entity.rs provides two wrappers. GlobalWeakEntity<T> (new(WeakEntity<T>), try_upgrade() -> Option<Entity<T>>) is the default: the entity’s lifetime is owned by a window or a parent entity, and the global is just a lookup. GlobalStrongEntity<T> (new(Entity<T>), get() -> Option<Entity<T>>) is for the handful of entities that nothing else owns and that must outlive any single window — StreamManager and ModelsNotifier are the existing examples. Reaching for the strong wrapper by habit reintroduces the cycles rule 1 avoids.

#![allow(unused)]
fn main() {
// WRONG — the global now keeps a view alive after its window closes
pub type GlobalChatView = GlobalStrongEntity<ChatView>;

// RIGHT — weak by default; upgrade at the call site
pub type GlobalMyNotifier = GlobalWeakEntity<MyNotifier>;
cx.set_global(GlobalMyNotifier::new(entity.downgrade()));

if let Some(notifier) = cx.try_global::<GlobalMyNotifier>().and_then(|g| g.try_upgrade()) {
    notifier.update(cx, |_, cx| cx.emit(MyEvent::Ready));
}
}

3. No silent .ok() on UI updates

cx.update(...), entity.update(cx, ...) and friends return Result because the target may already be gone. Discarding that result with a bare .ok() hides the one signal you have when a background task outlives its view. Log it with warn! first. Propagate with ? instead when the failure is a real error (file I/O, downloads, persistence).

#![allow(unused)]
fn main() {
// WRONG — failure disappears
cx.update(|cx| cx.refresh_windows()).ok();

// RIGHT — logged, then discarded on purpose
cx.update(|cx| cx.refresh_windows())
    .map_err(|e| warn!(error = ?e, "Failed to refresh windows"))
    .ok();
}

4. Tool errors go through map_tool_error

Every impl Tool implements map_error by calling map_tool_error(Self::NAME, error) from crates/chatty-core/src/tools/mod.rs. rig’s default Tool::map_error redacts the source error to a per-kind string — for ToolErrorKind::Other that is the literal "the tool failed", which is all the model and the transcript would ever see. map_tool_error formats the message as Error: {tool_name}: {message} and classifies it (timeout, permission, not-found, network, other) for rig’s retry hint. The prefix is load-bearing: the streamed tool result carries no error flag, so llm_service::tool_result_looks_like_error decides success or failure by sniffing for Error:. Drop or reword it and every failure is filed as a success. Only route errors the tool authored itself through it; raw provider text is what rig’s redaction exists for.

#![allow(unused)]
fn main() {
// WRONG — model sees "the tool failed"
fn map_error(&self, error: Self::Error) -> ToolExecutionError {
    ToolExecutionError::from_error(error)
}

// RIGHT — tool name and real message survive; prefix stays sniffable
fn map_error(&self, error: Self::Error) -> ToolExecutionError {
    crate::tools::map_tool_error(Self::NAME, error)
}
}

Six everyday patterns

Globals. App-wide state (settings, model lists, stores) implements gpui::Global and lives in the app: cx.set_global(value) at startup, cx.global::<T>() to read, cx.update_global::<T, _>(|state, cx| ...) to mutate, cx.try_global::<T>() when it may not be initialised yet. chatty-core types get their Global impls in chatty-core/src/gpui_globals.rs behind the gpui-globals feature, so the terminal app never links GPUI.

#![allow(unused)]
fn main() {
cx.update_global::<ModelsModel, _>(|models, _cx| models.replace_all(new_models));
}

Event subscriptions. Define an event enum, implement EventEmitter<E> for the entity, emit with cx.emit(...), and subscribe from the interested entity. Always .detach() the subscription (or store the Subscription handle); a dropped subscription silently stops delivering.

#![allow(unused)]
fn main() {
cx.subscribe(&notifier, |app, _notifier, event: &ModelsNotifierEvent, cx| {
    if matches!(event, ModelsNotifierEvent::ModelsReady) {
        app.refresh_chat_input_models(cx);
    }
})
.detach();
}

Async work. A Tokio runtime is entered in main.rs for the whole process, so cx.spawn futures can await Tokio-based I/O directly. Inside the future you hold an AsyncApp, not an App: every touch of app state goes through cx.update(|cx| ...), and the closure returns a Result because the app may be shutting down. Detach fire-and-forget tasks; return the Task when the caller needs the result.

#![allow(unused)]
fn main() {
cx.spawn(async move |cx: &mut AsyncApp| {
    match GENERAL_SETTINGS_REPOSITORY.load().await {
        Ok(settings) => cx
            .update(|cx| cx.set_global(settings))
            .map_err(|e| warn!(error = ?e, "Failed to store settings"))
            .ok(),
        Err(e) => warn!(error = ?e, "Failed to load settings"),
    };
})
.detach();
}

The four contexts. App is the full application context (globals, entity creation) and is what main.rs and top-level constructors receive. Context<T> is App plus “you are inside entity T”: it adds cx.emit, cx.notify, cx.subscribe, and cx.entity(). AsyncApp is what a spawned future holds; it can only reach the app through cx.update. Window carries window-scoped operations (focus, sizing) and is passed alongside cx to render and constructor code. If a function needs to emit or notify, it must take Context<Self>; if it only reads globals, &App is enough and keeps it callable from more places.

Optimistic update. For anything persisted: mutate the global first, refresh the UI, then save asynchronously and log the failure. The user never waits on disk, and a failed save shows up in the log rather than as a stuck button.

#![allow(unused)]
fn main() {
cx.global_mut::<ModelsModel>().add_model(config);
let to_save = cx.global::<ModelsModel>().models().to_vec();
cx.refresh_windows();
cx.spawn(async move |_cx: &mut AsyncApp| {
    if let Err(e) = MODELS_REPOSITORY.save_all(to_save).await {
        error!(error = ?e, "Failed to save models");
    }
})
.detach();
}

Deferred updates. Calling entity.update(cx, ...) on an entity that is already being updated higher in the call stack panics with a double borrow. When an event handler needs to reach back into the entity that dispatched it, schedule the work with cx.defer(move |cx| ...); it runs after the current update returns.

#![allow(unused)]
fn main() {
let chat_view = self.chat_view.clone();
cx.defer(move |cx| {
    chat_view.update(cx, |view, cx| {
        view.chat_input_state().update(cx, |input, _cx| {
            input.set_capabilities(supports_images, supports_pdf);
        });
    });
});
}

Security in short

MCP server configuration reaches the model through tools, so secrets must never be serialised into tool output. Today McpServerConfig (crates/chatty-core/src/settings/models/mcp_store.rs) carries a single secret, api_key: Option<String>, sent as a bearer token by McpService. Two conventions keep it out of the transcript: