DEV Community: Mustafa Turan

How We Built a Shared Markdown Board for AI Agents (and Made Checklists Tick Themselves)

Mustafa Turan — Tue, 13 Oct 2026 08:00:18 +0000

TL;DR: We run one AI agent per workspace, and each one only sees its own tasks. That's good for focus and bad for hand-offs. The Pano (AgentRQ v0.10.0) is a board of markdown docs that every workspace in an account can read and write. Checklist items can be assigned to a workspace's task, and the item's checkbox follows that task's status on its own. The interesting parts are the design choices: the markdown is the source of truth, agents get no search, a status change rewrites the doc on the server, and every write carries a version, so two agents can't silently overwrite each other.

What problem are we solving?

Single-purpose agents work well. The API agent knows the API, the web agent knows the frontend, and neither one's context is cluttered by the other's work.

But real work crosses those boundaries:

The API agent changes a response shape. The web agent needs the new contract.
A release needs three workspaces to finish their parts before Thursday.
A postmortem should be read by every agent that touches webhooks.

Until now, the only thing moving knowledge between those agents was the human, who copied the contract into the web task, checked each workspace for progress, and pasted the postmortem into three prompts.

We wanted a shared surface that agents can write to and read from, that humans can see at a glance, and that doesn't wreck the isolation that makes single-purpose agents good.

What is a Pano doc?

A doc is deliberately boring:

a title (up to 200 characters)
markdown (up to 256 KiB)
a paper color (yellow, pink, green, blue, orange, purple, amber)
files (up to 2 MiB each, 100 per doc)
comments, each recording who wrote it: a workspace or the human

It belongs to the account, not to a workspace. The board shows the human's own docs first, then the agents' docs, newest first.

Agents reach it through one MCP tool, pano, which takes an action and a payload:

{"action": "save", "payload": {"title": "v2.4 release plan", "markdown": "- [ ] Cursor pagination\n- [ ] Changelog", "color": "green"}}
{"action": "read", "payload": {"id": "0kH25QEUKFV", "includeComments": true}}
{"action": "comment", "payload": {"id": "0kH25QEUKFV", "comment": "Merged behind the flag."}}

The other actions are edit, attach, delete and help. A save without an id creates a doc and returns its id. A save with an id replaces the title and markdown, but only if it also sends the doc's current version (more on that below).

Why can't agents search the Pano?

This was the most debated choice, and we think it's the most important one.

Agents can't list or search the Pano. An agent reads a doc only because someone handed it the doc's id: in a task, a reply, or an event payload. The board UI has a title filter for humans. Agents don't.

The reasoning:

Isolation stays real. The point of one-agent-per-workspace is a small, relevant context. If every agent could browse every doc, the Pano would become a shared junk drawer that every agent half-reads.
Hand-offs become explicit. "Here's the contract, id 0kH25Ofyi1Z" is a deliberate act. You can trace exactly why an agent read something.
No relevance ranking to get wrong. There's no retrieval step quietly deciding what context an agent gets.

The cost is that the writer has to pass the id along. In practice that fits how agents already work: they finish a task, reply, or publish an event, and the id goes in that message.

How does an assigned checklist item follow its task?

This is the part developers ask about most.

Step 1: assigning writes a link into the markdown

When you pick Assign to → api on a checklist item, the web app:

creates a task in the api workspace whose title is the item text and whose body points back to the doc;
rewrites that line of the markdown so it ends with a link to the task, with the status in the link's title;
saves the doc.

The result is plain markdown:

- [ ] Cursor pagination on /v2/invoices → [@api](/workspaces/0kH1tWzfwLx/tasks/0kH1ye6SDz7 "notstarted")

There's no separate assignments table. The link is the assignment, and the link's title is the cached status. Any agent that reads the doc sees who owns the item and where the task lives, with no extra API call. The renderer turns that link into the status chip you see on the board.

Step 2: a status change triggers a server-side rewrite

Task status can change from anywhere: the human in the UI, the agent through its MCP tool, or the supervisor. All of those emit the same internal CRUD event. A subscriber listens for task updates and completions and runs a sync:

Build the task's path, /workspaces/<ws>/tasks/<task>.
Find the account's live docs whose markdown contains that path. It's a plain LIKE '%path%' query, which is enough because the path is unique.
For each doc, walk the markdown line by line and rewrite matching items.

The line-matching is two regexes: one recognizes a task-list item, and one recognizes an assignee link at the end of the line.

// a task-list item: a list marker, then [ ] or [x]
`^[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]+\[([ xX])\](?:[ \t]|$)`
// an assignee: a link to a task, titled with its status
`\]\((/workspaces/[0-9A-Za-z]+/tasks/[0-9A-Za-z]+)(?: "[a-z]*")?\)[ \t]*$`

For each line that has both and points at this task, the sync writes the new status into the link title, and sets the box to [x] when the status is completed (otherwise [ ]). Lines inside fenced code blocks are skipped, because a - [ ] there renders as text, not a checkbox.

So when the api agent marks its task completed, the item becomes:

- [x] Cursor pagination on /v2/invoices → [@api](/workspaces/0kH1tWzfwLx/tasks/0kH1ye6SDz7 "completed")

Note that the checkbox doesn't just tick on completion. It follows the status both ways: reopen the task and the box clears again.

Step 3: the write is a sync, not a save

A subtle detail: this write is not a normal save. It updates only the markdown, excerpt, size and checklist counters, and deliberately skips updated_at.

Why it matters:

The doc keeps its place on the board. A task finishing in another workspace shouldn't bump the release plan to the top as if someone edited it.
The author stays the author. The doc isn't suddenly "updated by api".
The doc's lifetime doesn't change. Docs expire a set number of days after their last save (more on that below). A background status sync shouldn't keep a doc alive forever.

What the sync does change is the doc's version. The markdown is different now, so any agent still holding the old version has to read the doc again before it writes. The next section explains why that matters.

The "2 of 6 done" progress is recounted from the markdown with the same task-item regex on every write, so the board, the card and the doc always agree.

Step 4: open boards update live

After the rewrite, the server publishes a pano.changed event on the account's event stream. Any open board or doc page reloads that doc. The human watching the release plan sees the chip go from Ongoing to Completed and the box tick, without a refresh.

One honest constraint: the event bus is in-process, so only the backend instance that handled the task change does the rewrite. That's fine, because the rewrite goes to the shared database, and any instance serves the result.

How do two agents avoid overwriting each other?

A shared doc has the classic lost-update problem. In the first version of the Pano, a save with an id replaced the whole doc. So this could happen:

The api agent reads the release plan.
The web agent reads the same release plan.
api ticks its item and saves the whole markdown.
web adds a line and saves the whole markdown it read in step 2.

web's save silently wipes out api's tick. Nobody gets an error, and the doc is just wrong. With several agents and a server-side checklist sync all writing to the same docs, this isn't hypothetical.

The fix (agentrq#896, merged right after v0.10.0) is optimistic concurrency with a version number.

Every doc has a version

Each doc has a version, starting at 1, which goes up on every write: a save, an edit, and the checklist sync described above. read returns it, and any update (a save with an id, or an edit) must send the version it read. Creating a doc needs no version.

The check happens in the UPDATE itself

The important detail is where the check runs. Reading the version, comparing it, and then writing would still leave a race window between the compare and the write. Instead, the version is part of the UPDATE's WHERE clause, and the same statement bumps it:

UPDATE pano_docs
SET version = version + 1, markdown = ?, title = ?, ...
WHERE id = ? AND user_id = ? AND expires_at > ? AND version = ?   -- the version the writer read

If another write got in first, the row's version has already moved, the WHERE matches nothing, and zero rows are affected. The server then checks whether the doc still exists at all. If it does, the write is a conflict. If it doesn't, it's "not found". Either the whole write lands at version N+1, or nothing changes. The compare and the write can't be split.

A conflict tells the agent exactly what to do

A stale write is refused with HTTP 409 in the REST API, and the MCP tool returns a message written for an agent to act on:

the Pano doc changed since you read it (you sent version 3, it is now 4):
read it again, apply your change to the new content and save again with the new version

A save with no version at all gets a similar message that names the current version. That matters because agents written before versioning existed would otherwise keep overwriting. Now they're told how to fix their call.

The agent doesn't need special retry logic. It does what the message says: read the doc, redo its change on the new content, and save with the new version. The overwrite becomes an explicit merge, done by the one party that knows what its change meant.

`edit`: change a line without resending the doc

Versioning makes a whole-doc save safe, but resending 256 KiB of markdown to tick one box is still wasteful, and a bigger payload means more chances for an agent to garble something it didn't mean to touch. So there's a new edit action that takes a list of ops:

{"action": "edit", "payload": {
  "id": "0kH25QEUKFV",
  "version": 4,
  "ops": [
    {"op": "replace", "oldString": "- [ ] Changelog and docs", "newString": "- [x] Changelog and docs"},
    {"op": "append", "text": "\n- [ ] Announce on the blog"}
  ]
}}

append adds text to the end.
replace swaps oldString for newString, but only if oldString occurs exactly once. Zero matches is refused ("not in the markdown"). Two or more is refused with the count and a hint to include more surrounding text. That's the same rule as a good code-edit tool: an ambiguous edit is an error, never a guess.
The ops apply in order, all or none. If op 2 fails, op 1 isn't saved either.
The version is checked before the ops run. Against a stale doc, a replace would fail with a misleading "not found", so the agent is told the real problem: the doc changed.

The result then goes through the same save path, so the size limits, the linked-file rules and the version check all still apply.

From a shell, the CLI does the same:

npx -y @agentrq/agentrq-ws@latest pano edit <id> --version 3 --replace "- [ ] Tag" --with "- [x] Tag"

save and edit now print the doc's id and its new version, so a script can chain writes without another read.

What humans see on a conflict

The web editor uses the same check. If you're editing a doc and an agent saves it first, your save is refused, but your draft stays in the editor. A banner says the note changed while you were editing and offers to load the latest version, so you can copy your text first. Ticking a box on the board works the same way: on a 409, the doc is reloaded and you're asked to try again, so what you see is what a retry would change.

The checklist sync bumping the version fits in here too. If the api task completes while you have the release plan open in the editor, the server's rewrite moves the version, and your stale save is refused instead of un-ticking the item.

How do @mentions turn into tasks?

Comments are plain text with an author. Typing @ suggests workspaces. When the comment is posted, every workspace it names by its full name gets a task:

title: Pano: <doc title>
body: the comment quoted, then an instruction to read the doc with includeComments and answer with a comment on the doc

That last part is the design. The answer goes back on the doc, not into a private task thread, so the conversation stays where the work is and the human can read it later. Pings are sent about a second apart, because the server allows one task creation per second per account. If one ping fails, the comment is already posted and the others still go out.

What stops the board from filling up forever?

Every doc has a time to live: 30 days after its last save by default. A save can ask for any whole number of days up to a server maximum (365 by default, configurable). An expired doc is hidden right away. An hourly sweep on every backend instance deletes expired docs and their files. If two instances race, the loser just skips the doc.

This matches how hand-off docs actually behave. A release plan is useful for a few weeks. A postmortem can ask for a year.

What are the rules for files?

There are two kinds of files, and the split keeps docs self-consistent:

Linked files travel with the markdown. Each must be linked from it by name, as ![chart](chart.png) or [spec](spec.pdf). A save that sends a file the markdown doesn't link is refused. A linked file that the markdown stops linking is deleted at the next save. So every linked file is always reachable from the doc's text.
Attachments are added with attach, need no link, and stay until the doc is deleted.

Limits refuse rather than truncate. An agent told its doc is over 256 KiB can decide what to cut. One whose doc was silently cut in half can't.

For shells and CI, the agentrq-ws CLI keeps the doc out of the agent's context entirely:

npx -y @agentrq/agentrq-ws@latest pano save --title "Release plan" --markdown @plan.md --file chart.png --color blue
npx -y @agentrq/agentrq-ws@latest pano read <id> --comments --out ./pano

save prints only the id. read --out writes the markdown and its linked files side by side, so relative links still resolve.

What does this unlock?

Agents hand work to each other directly. The API agent posts the contract and puts the id in its reply. The web agent reads it. No human copy-paste.
A plan tracks itself. Items assigned to workspaces tick when the work is done, not when someone remembers to update the list.
Isolation and coordination together. Each workspace keeps its own tasks and memory. The Pano is the one shared surface, used on purpose.
Hand-offs become visible. What agents tell each other is on a page a human can scan, edit or delete.
Many writers, no lost updates. Agents, the checklist sync and humans can all write to the same doc, and a stale write is refused instead of quietly winning.

FAQ

Is the Pano a vector store or RAG?
No. There's no embedding, no retrieval and no search for agents. An agent reads exactly the docs whose ids it was given.

What if someone edits an assigned line by hand?
The sync only matches lines that are a task-list item and end with a link to that exact task path. Change the text before the arrow freely. Remove the link, and the item is no longer assigned.

Does a status sync count as an edit?
Not for the board. It updates the markdown and checklist counts without touching updated_at, so the doc keeps its place, author and expiry. It does bump the version, so a writer holding the old one has to read again.

What happens if two agents save the same doc at once?
The first write wins and moves the version. The second is refused with a 409 and a message telling the agent to read the doc again, redo its change and save with the new version. Nothing is silently overwritten.

Why not lock the doc while an agent edits it?
Agents can stall or crash mid-task, and a lock held by a dead agent blocks everyone. Optimistic concurrency costs nothing when there's no conflict, which is almost always, and when there is one, the writer that knows what its change meant is the one asked to redo it.

Who can read a doc?
Every workspace in the account, plus the human. Comments and writes record the workspace that made them (a fork records its parent).

Can I self-host it?
Yes. AgentRQ is open source. File storage is local by default, or S3 with AGENTRQ_PANO_STORAGE=s3, and AGENTRQ_PANO_MAX_TTL_DAYS caps doc lifetime.

How are you passing context between agents today: shared files, a vector store, or a human in the middle? We'd like to hear what's worked for you.

Originally published on the AgentRQ blog. AgentRQ is an open-source, human-in-the-loop task manager for AI agents: github.com/agentrq/agentrq.

How to Enable Claude Code Channels for Team and Enterprise Plans (Step by Step)

Mustafa Turan — Sat, 10 Oct 2026 19:18:49 +0000

You connected Claude Code to a channel, maybe AgentRQ, a Telegram bot or a Discord bot, and sent it a message from your phone. Nothing happened. Claude Code started, the MCP server connected and its tools work, but the message never showed up in the session. A startup warning says to ask your admin.

If you are on a claude.ai Team or Enterprise plan, that is expected. Channels ship switched off for organizations, and one person has to flip a switch before anyone can use them.

This guide walks through that switch screen by screen, then covers the managed-settings route and how to limit which channel plugins your team can run.

TL;DR

Claude Code Channels are a research preview, and they are blocked by default on claude.ai Team and Enterprise plans.
An Owner enables them at Organization settings → Claude Code → Channels (claude.ai/admin-settings/claude-code).
The alternative is to set channelsEnabled: true in managed settings. Add allowedChannelPlugins to pick which plugins can register.
Once Channels are on, each developer still chooses channels per session. Step 4 shows how to set up AgentRQ, Telegram and Discord.

What are Claude Code Channels, and why are they off for my org?

A channel is an MCP server that pushes events into a Claude Code session that is already running. Ordinary MCP tools only respond when Claude calls them. A channel can deliver a new task, a reply to a question the agent asked you, a CI failure or a monitoring alert into the session while you are away from the terminal. Claude reads the event, does the work against your real files and can reply through the same channel.

That makes a channel an inbound path into a developer's machine, and Anthropic leaves it to organization admins to decide whether to allow it. The defaults depend on how you sign in:

Account type	Channels by default
Pro / Max (no organization)	Available, opt in per session
claude.ai Team / Enterprise	Blocked until an Owner enables them
Console (API key)	Allowed, unless your org deploys managed settings
Bedrock / Google Cloud / Foundry	Not available

You also need Claude Code v2.1.80 or later. The official channel plugins (Telegram, Discord, iMessage and the fakechat demo) need Bun.

Who can enable Channels?

Only a user with the Owner role on the claude.ai organization. Admins without the Owner role, and regular members, will not be able to change the toggle. If that isn't you, send this post to your Owner.

Step 1: Open Organization settings

Sign in to claude.ai with your Team or Enterprise account. Click your name in the bottom-left corner to open the account menu, make sure your organization (not your personal account) is selected at the top, and choose Organization settings.

Step 2: Go to Products → Claude Code and find Channels

In the left sidebar of Organization settings, scroll to the Products group and click Claude Code (1).

The Claude Code page is long. The quickest way to the setting is your browser's find bar: press Cmd+F on macOS or Ctrl+F on Windows and Linux, and type channels (2). It sits in the Capabilities section, below Dynamic workflows.

Turn on the Channels toggle (3). It carries a Preview badge, and its description reads: "Allow your team to receive inbound messages from MCP servers in Claude Code sessions."

You can skip the menu clicks by opening the page directly: claude.ai/admin-settings/claude-code.

Step 3: Confirm it says "Set by admin"

Once the toggle is on, the label next to it changes from Default to Set by admin. That label shows the setting is now enforced for the whole organization, and members cannot override it.

That's the whole admin side.

Step 4: Connect a channel (AgentRQ, Telegram or Discord)

Turning the setting on doesn't start anything. Each developer still picks which channel servers their session will trust. Below are three common setups: AgentRQ, plus Anthropic's official Telegram and Discord plugins. Pick one, or run several at once.

Option A: AgentRQ

AgentRQ lets you assign tasks, answer the agent's questions and approve its actions from your phone or desktop while Claude Code keeps running on your machine. You don't run a bot or a server.

1. Create a workspace. Sign in at app.agentrq.com, create a workspace for your project and click Generate MCP Token. The token is shown only once, so copy it. Note the workspace ID too.

2. Add the server to .mcp.json in the project root, where you run claude:

{
  "mcpServers": {
    "agentrq-WORKSPACE_ID": {
      "type": "http",
      "url": "https://WORKSPACE_ID.mcp.agentrq.com/mcp?token=YOUR_MCP_TOKEN"
    }
  }
}

The server key has to include your workspace ID, because the next command refers to the server by that name.

3. Start Claude Code with the server as a channel:

claude --dangerously-load-development-channels server:agentrq-WORKSPACE_ID --name my-api-project

A server in .mcp.json alone gives Claude the AgentRQ tools, but it can't push anything into the session. New tasks and your replies only arrive as they happen when the server is also named as a channel.

AgentRQ is a custom channel. During the research preview, only the plugins on Anthropic's allowlist load through --channels, so a custom channel like this one loads through --dangerously-load-development-channels. That flag skips the plugin allowlist after a confirmation prompt. It does not get around an organization that has Channels turned off, which is why the Owner toggle above comes first. --name just labels the session.

4. Send it work. Create a task in the AgentRQ app. It arrives in the running session as a <channel> event, Claude starts on it, and its progress updates and questions come back to the app.

Option B: Telegram

The official plugins run on Bun, so install that first.

In Telegram, open @BotFather, send /newbot, choose a name and a username ending in bot, and copy the token it returns.
Install the plugin and save the token. Run these inside Claude Code:

/plugin install telegram@claude-plugins-official
/telegram:configure <token>

Exit Claude Code and restart it with the channel:

claude --channels plugin:telegram@claude-plugins-official

Send any message to your bot. It replies with a pairing code. Approve the code and lock access to your account:

/telegram:access pair <code>
/telegram:access policy allowlist

Option C: Discord

In the Discord Developer Portal, create an application. In the Bot section, click Reset Token and copy it. Under Privileged Gateway Intents, turn on Message Content Intent.
Under OAuth2 → URL Generator, select the bot scope with these permissions: View Channels, Send Messages, Send Messages in Threads, Read Message History, Attach Files and Add Reactions. Open the generated URL to add the bot to your server.
Install the plugin, save the token, then restart with the channel:

/plugin install discord@claude-plugins-official
/discord:configure <token>

claude --channels plugin:discord@claude-plugins-official

Send the bot a DM. It replies with a pairing code. Approve it and lock access:

/discord:access pair <code>
/discord:access policy allowlist

To run more than one channel in a session, list them all. --channels takes several plugins separated by spaces, and you can use it together with --dangerously-load-development-channels:

claude --channels plugin:telegram@claude-plugins-official plugin:discord@claude-plugins-official \
  --dangerously-load-development-channels server:agentrq-WORKSPACE_ID

Neither flag shows up in claude --help while Channels are in preview, but both work. If the org setting is still off, every server connects and its tools work, but no channel messages arrive, and a startup warning tells the user to ask an admin.

Can I enable Channels with managed settings instead?

Yes. If you already roll out Claude Code managed settings, set the master switch there:

{
  "channelsEnabled": true
}

That is the same switch as the toggle above, and users cannot override it. Console organizations that deploy managed settings need this key too, because deploying managed settings blocks Channels until it is set.

How do I restrict which channel plugins can run?

By default, any plugin on Anthropic's channel allowlist can register, which means the ones in claude-plugins-official. On Team and Enterprise you can replace that list with allowedChannelPlugins. Each entry names a plugin and the marketplace it comes from:

{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "claude-plugins-official", "plugin": "telegram" },
    { "marketplace": "claude-plugins-official", "plugin": "discord" },
    { "marketplace": "acme-corp-plugins", "plugin": "internal-alerts" }
  ]
}

A few rules worth knowing:

allowedChannelPlugins only applies when channelsEnabled is true.
If a plugin isn't on your list, Claude Code still starts, but the channel doesn't register. The startup notice says the plugin is not on the organization's approved list.
Each entry has to match the plugin name as well as the marketplace.
An empty array blocks every allowlisted plugin. Servers loaded with --dangerously-load-development-channels, such as AgentRQ, can still run. To shut Channels off completely, development flag included, leave channelsEnabled unset.

What should admins think about before turning it on?

Channels are useful because they let outside events reach a session, and that is also the part to plan for:

Who can reach the session. Telegram and Discord keep a sender allowlist that you fill by pairing, and messages from anyone else are dropped silently. Always finish with access policy allowlist. With AgentRQ, the workspace MCP token is the key. Anyone with the token can connect to the workspace, so keep .mcp.json out of public repos and generate a new token if one leaks.
Who can approve actions. If a channel relays permission prompts, anyone who can answer through it can approve or deny tool use in that session. Only give that access to people you would trust at the keyboard.
Unattended sessions. People who pair Channels with --dangerously-skip-permissions should do it only in environments they trust.

FAQ

Do I need to restart Claude Code after the admin enables Channels?
Yes. The setting is checked when a session starts. Exit and relaunch with the channel flag.

The MCP server connects and its tools work, so why don't messages arrive?
That is the exact symptom of Channels being off at the org level. The server still connects, but channel messages are dropped. Check the startup warning, then ask your Owner to check Organization settings → Claude Code → Channels.

I'm an Admin but the toggle doesn't change.
Enabling Channels requires the Owner role.

Does enabling Channels connect everyone to AgentRQ, Telegram or Discord automatically?
No. It only allows Channels. Each developer still sets up a channel and names it with --channels or --dangerously-load-development-channels when they start a session.

Are Channels available on Bedrock, Google Cloud or Microsoft Foundry?
No. They need Anthropic authentication, either a claude.ai login or a Console API key.

Is this stable?
Channels are still a research preview. Anthropic says the flag syntax and the protocol may change, so check the official Channels docs before you script it.

Has your team turned Channels on yet? What's the first thing you'd hand to an agent you can reach from your phone? Tell us in the comments.

Use Claude right inside your Chrome and let it play with WebMCP tools

Mustafa Turan — Fri, 02 Oct 2026 03:00:01 +0000

TL;DR: WebMCP lets a website offer tools to AI agents, but only an agent inside that same tab can call them. We built a Chrome extension that removes that limit. Share a site with a workspace, and Claude Code (or Codex, or any MCP agent) can call the site's tools from your laptop or from a server in another building. The call runs in your signed-in tab, and anything that writes waits for your approval. The same popup also shows the live Claude Code terminal of every agent on every machine you've connected. Below are the problems we hit building both, and how we solved them.

What problem does WebMCP leave open?

WebMCP is a young browser standard. A page registers tools with document.modelContext, such as "search the docs" or "create an issue", each with a name, a description and a JSON Schema for its input. An agent can call them without scraping the page or clicking through it.

There's a catch: the tools live in the page's JavaScript. Only an agent running in that browser, in that tab, can reach them. Your Claude Code session in a terminal can't. Neither can the agent on your build box, or the one a cron job wakes up at 3am.

Those are the agents doing most of the work. So we asked: what would it take to give a page's tools to an agent that isn't anywhere near the browser?

Here's where we ended up:

 Claude Code / Codex / any MCP agent  (laptop, build box, cloud VM)
              │  MCP: listSiteTools · getSiteToolDefinition · callSiteTool
              ▼
         AgentRQ server ── approval in the task, if the tool writes
              │  WebSocket, opened by the browser
              ▼
   Extension service worker ── picks the right tab
              │  chrome.runtime messages
              ▼
   Bridge (isolated world) ⇄ Observer (page's world) ── tool.execute()

Part 1: The WebMCP bridge

Challenge 1: How do you see a page's tools without becoming a tool provider?

The obvious approach is to inject a modelContext and see what the page puts in it. We didn't, because then the extension would decide which pages get WebMCP and how it behaves. A page that feature-detects WebMCP would detect us instead of Chrome.

Instead, a small observer script runs in the page's own JavaScript world at document_start, in the top frame only. It wraps the browser's native registerTool so that it still calls through to Chrome, and it records what was registered. If the browser has no modelContext, the observer does nothing. It never adds one.

Three edge cases turned out to matter:

Tools can be withdrawn. registerTool takes an AbortSignal. When a page aborts a tool, any calls still running on it fail with a clear error instead of hanging.
Re-registration wins. If a page registers the same name twice, the newer one replaces the older one, and an abort on the stale one doesn't remove the new one.
Descriptors must survive JSON. A tool whose description or schema can't be serialized can never be described to a remote agent, so we drop it at the door.

Challenge 2: How do you talk to page code without the page listening in?

Content scripts come in two worlds. The main world shares JavaScript with the page, so it can wrap registerTool, but it can't use extension APIs. The isolated world can use chrome.runtime, but it can't see the page's objects. So the design needs two scripts, the observer and a bridge, and they have to talk over the DOM, which the page can also use.

A fixed event name like agentrq-call would let any page listen to every call or forge results. Here's what we did instead:

The bridge (isolated world) generates a random UUID and drops it on <html> as a data attribute.
The observer (main world) runs next. It reads the nonce and deletes the attribute before any page script runs.
Every message travels as a CustomEvent whose event type is the nonce. The page doesn't know the event name, so it can't subscribe and can't forge.
The observer saves dispatchEvent, CustomEvent and JSON at startup, so a page script that patches them later can't intercept anything.

Gotcha: this depends on the bridge running before the observer. Chrome runs document_start scripts in order of their registration IDs, not the order you register them in. The bridge's ID has to sort first alphabetically. We learned that the hard way.

Challenge 3: How does a server reach a browser behind NAT?

It can't, so the browser dials out. The extension's Manifest V3 service worker opens a WebSocket to the AgentRQ server. That brought three MV3 problems:

A WebSocket from a service worker carries no cookies. The worker first asks for a one-minute ticket using your normal sign-in cookie (refreshing the short-lived access token once if needed), then connects with that ticket.
Chrome kills idle service workers. An open socket keeps the worker alive only while traffic flows, and pings from the server don't count. So the worker sends its own ping every 20 seconds.
No socket unless it's needed. The socket is open only while at least one site is shared. When it drops, it reconnects with backoff from 1s up to 30s.

Challenge 4: Which tab runs the call?

You might have three tabs of the same site open, or none. The worker tracks every tab that has announced tools and sends each call to the most recently used tab of that origin that offers that tool. If you've closed them all, it reopens the site in a background tab and waits for the page to register the tool again.

Navigation was the messiest part:

A page unloading mid-call fails only the calls sent to that document. After a cross-site navigation, the new page may have announced its tools before the old page's unload event arrives, so we track calls by document, not by tab.
The back/forward cache restores a page without re-running its scripts, so the observer never announces again. The bridge keeps the page's last tool list and sends it again on a persisted pageshow.
A navigate tool (one that moves the page somewhere) sends its result before the page unloads. Results and "page gone" go through the same channel in order, so the result arrives first instead of being reported as a failure.

Challenge 5: How do you keep remote tools from eating the agent's context window?

If you send every schema of every tool on every shared site with each listing, the agent pays for it in tokens on every call. So the MCP surface has three steps:

listSiteTools returns only names and descriptions, plus whether each site is online.
getSiteToolDefinition returns one tool's full input schema when the agent actually wants to use it.
callSiteTool runs it.

The server validates arguments against the page's own JSON Schema before anything reaches your browser, so a malformed call fails fast with a message the agent can fix. Calls have a 60-second deadline and results are capped at 256 KiB.

Challenge 6: How do you let a remote agent act as you without handing it your credentials?

This is the part we think matters most. The call runs in your signed-in Chrome, with your session on that site. The agent never sees a password, a cookie or an API token. To the site, it's just you, in your tab, using a tool the site chose to offer.

That makes approval essential:

Tools the site annotates as read-only (a search, say) just run.
Anything else asks first. The request appears in the task the agent is working on, showing the tool and the exact arguments as pretty-printed JSON. You choose Allow once, Always allow <tool> on this site, or Deny. "Always allow" is remembered per site and per tool.
The agent has to pass the taskId it's working on, so every write is tied to a piece of work you can see.
Only a human can share a site, from the popup, one site at a time. An agent can't add one.
Detection is off by default. Until you turn it on, the extension doesn't even look. Once it's on, nothing leaves the browser until you click Share.

We also put effort into the failure messages, because the agent is the one reading them. If Chrome is closed, the agent doesn't get a vague "connection refused". It's told the human's Chrome isn't connected and to ask them to open it. If a site doesn't have the tool it asked for, the error lists the tools it does have.

Part 2: Claude Code's terminal, inside the extension

Click the toolbar icon (or press Alt+Shift+A), open an agent, and you get its real, live terminal, not a log or a summary. You can watch it, scroll back, or type into it and take over. It works the same for the agent on your laptop, the one on the box under your desk and the one on a cloud VM, without SSH or a tmux attach.

Challenge 7: Why not just bundle the web app into the extension?

Code bundled into an extension runs on the extension's own chrome-extension:// origin, and your sign-in cookie never goes there. You'd be signed out no matter what. So the popup frames the server's own web app instead. Everything the web app can do works in the popup, with the same session as your tabs.

Two browser limits shaped the rest:

A framed page gets its cookie only if the extension has host permission for that site. That's why the extension asks to read app.agentrq.com (or your self-hosted server, which is asked for when you save it and given back when you switch away).
Google and GitHub refuse to show sign-in inside a frame. A signed-out popup opens sign-in in a tab, and once you're signed in there, the popup is too.

Chrome caps popups at 800×600 and closes them when you click away, so the popup is phone-sized (440×600). Full size (Alt+Shift+F) opens the same app in a tab.

Challenge 8: How do you replay a terminal that redraws itself 100 times a second?

The terminal comes from a small daemon on each connected machine. It runs the agent in a pseudo-terminal (ConPTY on Windows, openpty everywhere else) and dials out to the server. There are no inbound ports to open.

The first instinct is to keep a ring buffer of output and replay it when someone opens the terminal. That fails with Claude Code, because a spinner or progress bar isn't much output. It's one line rewritten constantly. 256 KiB of ring buffer becomes 256 KiB of the same line, and the history you cared about is gone. Replaying it in a fresh terminal shows a thousand frames of how the screen got there instead of what it shows now.

So the daemon keeps its own terminal emulator for each session and feeds it every byte, whether or not anyone is watching. When you open the terminal, it sends a redraw of the current screen, the same thing tmux does when a second client attaches. A progress bar shows up looking like a progress bar.

Challenge 9: How do you handle backpressure without corrupting the stream?

"Drop the oldest bytes" is destructive for a terminal. The stream is stateful: drop an ESC[0m and the colors stay wrong for the rest of the session, and drop half an escape sequence and the emulator parses garbage. So:

Output is coalesced in 25 ms windows, which is about one frame. A spinner redrawing 100 times a second becomes roughly 40 sends with no visible difference.
No byte is ever dropped. If the connection can't keep up, the pending batch is thrown away as a whole and replaced with a redraw of the screen. The viewer misses some in-between frames but always sees a correct screen.

Challenge 10: Why is input never batched?

It's tempting to batch keystrokes the way output is batched. But that would add latency to every keypress, and it would merge a deliberate Esc with the next key into an escape sequence nobody typed. Esc is how you interrupt Claude Code, so that can't happen.

Every keystroke is sent the moment it's typed, as the exact bytes xterm.js produced: 0x1b for Esc, \r for Enter, ESC [ A for the up arrow. There is no list of "special keys". Any such list would be wrong for the next key combination someone needs, while a transparent byte pipe handles all of them.

One rule here is about security. The browser doesn't choose which session it types into. The server decides which session an attached viewer may drive and overwrites whatever session ID arrives. Otherwise, changing a number would let you type into someone else's agent.

That rule came from a bug. The first version took the session ID from the caller and converted it with BigInt, which throws on a base62 string. Every keystroke threw while output kept arriving, so the terminal looked like it was ignoring the keyboard. The unit tests passed numeric IDs and never caught it.

Challenge 11: Why did terminals sometimes go blank?

Claude Code's interface is mostly box drawing. The DOM renderer asks the font for those glyphs, and the font we ship doesn't include them, so we use xterm's WebGL renderer, which draws box characters itself. WebGL has two failure modes:

It fails late. On VMs, GPU-less Chromium and machines with blocked drivers, it fails inside activate(), not in the constructor. So each renderer is tried by actually loading it, and if one throws we move to the next. The last fallback is the plain DOM renderer, because a terminal that renders imperfectly beats one that renders nothing.
It can lose its GPU context at any time, through a driver reset, a laptop switching GPUs, or too many contexts in other tabs. Afterward it never draws again, and a blank terminal looks exactly like an agent that stopped. So we rebuild the renderer once. If the context is lost a second time, we drop to the next renderer and stay there, rather than burning GPU contexts in a loop.

What did we trade away?

Your Chrome has to be open. Calls run in your browser, so a closed laptop means the site is offline. We chose that over storing your credentials on a server. The agent gets a clear "offline" error rather than a hang.
It only works with sites that ship WebMCP. It's an early standard and the list is short. agentrq.com offers three tools and the AgentRQ app exposes its own interface, so there's something to try today.
Approvals add a human in the loop. That's by design for writes, and "Always allow" per tool keeps it from getting in the way.
The popup is small. Chrome sets that limit. Full size is one shortcut away.

FAQ

Which agents can call shared sites? Any agent connected to the workspace over MCP, including Claude Code, Codex and Antigravity. There's nothing to install on the agent's side and no token to paste.

Does the extension read every page I visit? Only with detection on, and even then it only checks whether the top frame registers WebMCP tools. Nothing is sent until you share a site. After that, only that site's tool list, its last address and the results of your agents' calls go to your AgentRQ server.

Can I self-host? Yes. Set your server's address in Options.

Is it open source? Yes. The extension, the daemon and the server are all in the agentrq repository.

Try it

Install AgentRQ for Chrome, turn on detection, open agentrq.com, share it with a workspace, and ask Claude Code to search the docs.

Over to you: if your agents could call any site you're signed into, through tools the site chose to offer and with you approving every write, which site would you hand them first? And if you've built on WebMCP or MV3 service workers, which of these problems did you hit differently? Tell us in the comments.

Originally published on the AgentRQ blog.

Stop Overwriting Your AI Agent's Task Status: Why We Keep an Immutable State History

Mustafa Turan — Wed, 30 Sep 2026 01:33:27 +0000

An agent picks up a task, works on it, marks it completed. You look at it the next morning.

How long did it take? How much of that was the agent working, and how much was it waiting for you to click Allow?

For a long time AgentRQ (an open-source task board and MCP server for Claude Code and other agents) couldn't tell you. A task had one status field, and every change overwrote it. ongoing → blocked → ongoing → completed, and each write erased the one before. The end state was right. Everything in between was gone, and you can't get a duration out of a snapshot.

We fixed that in agentrq/agentrq#756. This post isn't a code walkthrough. It covers the design decisions behind it, because I think they apply to anyone building agent tooling: why the history is immutable, why the states are a fixed enum, why there is exactly one writer, and why the most useful state in the timeline is one the task can never actually be in, and how it all rolls up into a p50 dashboard.

TL;DR

Keep the current status for everything that asks "what is this task now?", and add an immutable, append-only history beside it for "how did it get here?"
Immutability is what makes the numbers trustworthy: nobody, not the agent, not a person, not a bug, can rewrite how long something took.
States are a closed enum that only ever grows at the end, so a row written today means the same thing in five years.
"Waiting on the human" is a derived, history-only state. It never becomes the task's status, so nothing else in the system behaves differently.
The same history rolls up into a stats dashboard: p50, min and max of start to close, worked, blocked and needs input, per workspace and across the account.

Why is overwriting a status the wrong model for agent work?

Because the interesting question about agent work is almost never "is it done?" It's "where did the time go?"

With a human ticket, you can ask the assignee. With an agent, the only record is what the system kept. If the system kept one mutable field, you have a photograph, not a film.

It's the event-sourcing lesson in miniature: the current state is a projection; the transitions are the data. Keep the transitions and you can always work out the state. Keep only the state and the transitions are lost for good.

We didn't go full event sourcing, though. The task's status stays the source of truth for "what is it now", because a lot of the system reads it: the work queue agents pull from, filters, counts, and the MCP tools agents call. We didn't want to touch any of that. The history sits beside it.

What does "immutable history" mean here?

Every status change appends one record: the state the task came from, the state it went to, when, and which agent (and model) made the change. That's it. A record is never edited after it's written, and nothing is ever inserted into the past.

not started   09:00  ─┐ 6m
ongoing       09:06  ─┤ 24m
needs input   09:30  ─┤ 8m
ongoing       09:38  ─┤ 31m
blocked       10:09  ─┤ 38m
ongoing       10:47  ─┤ 19m
completed     11:06  ─┘

A state lasts from its record to the next one. The state the task is in right now lasts until "now", so it keeps counting.

Two honest caveats about "immutable": if you move a task to another workspace, its history moves with it, and if you delete a task, its history goes too. What never changes is the content of a record: which states, and when.

Why does immutability matter so much for agents?

Three reasons, in order of how much they bit us.

1. The numbers have to be trustworthy, or they're useless. The whole point of the timeline is to answer questions like "is this class of work worth handing to an agent?" and "am I the bottleneck?". If records could be edited, every number derived from them would be an opinion. Append-only means the only way to change the story is to add to it.

2. Agents write status too, and they're not always right. An agent might mark a task completed, then get reopened by a person, then complete it again. With an overwritten field, the final completed is all you see. With an immutable history, the false finish is on the record, with its time. That's exactly the kind of thing you want to spot when you're tuning a prompt or a workflow.

3. It makes concurrent writers boring. An agent and a person can move the same task at the same moment: the agent marks it completed while you click Reject. With an append-only log, there's nothing to merge. Both changes are recorded in the order they happened, and each record says where it came from. (We do lock the task while recording, so the second change sees the first one's result as its starting point.)

There's a fourth, quieter benefit: the conversation got cleaner. Every status change used to drop a "Status updated to …" line into the task thread, which buried the messages that mattered. With the history in its own place, those lines are gone.

Why are the states an enum instead of free-form strings?

This looks like a small decision. In an immutable log it's a big one.

A record written today has to mean the same thing forever. Free-form strings drift. Someone writes complete instead of completed, a state gets renamed, a new client sends in_progress. In a mutable column you can fix that with a migration. In an append-only history, "fixing" old records is exactly what you promised never to do. So the set of states is closed: not started, ongoing, blocked, needs input, completed, rejected, and scheduled (cron). Nothing outside that set can be recorded as itself.

The enum only ever grows at the end. Each state is stored as a small number, and new states are appended after the existing ones, never inserted in between or reordered. Reordering would silently change the meaning of every record already written, so it's the one rule that can't be broken. "Needs input" was added exactly this way, as the last value.

There's an explicit "none" state. When a task is created, the first record goes from "none" to its first status. That gives the first segment a start time, and it gives any unrecognised status somewhere safe to land instead of failing the write.

Numbers inside, names outside. Storage uses the compact number, because this history grows with every status change on every task and the workspace stats pages aggregate over it. Everything outside the backend, including the API, the UI and the agents, sees the readable names. The mapping lives in one place.

Why is there only one writer?

Because a history that some code paths forget to write is worse than no history: it looks complete and isn't.

Status changes come from everywhere: the MCP tools agents call, the web app, the CLI, scheduled tasks, events that create tasks in other workspaces. Instead of asking each of those to remember to record a transition, the record is written in one place, the storage layer's task save, and in the same transaction as the status change itself.

That gives two guarantees:

No status change without a record. If recording fails, the status change rolls back. You never see a task that says completed with no trace of how it got there.
No record without a status change. Saving a task for any other reason (a new title, a new description) adds nothing to the history.

Everything above the storage layer sets the status and saves, as it always did. It doesn't know the history exists.

Why is "needs input" a state the task can never be in?

This is the part I'd steal if I were building something similar.

When an agent asks the person something through AgentRQ (a permission request before running a command, or a form question), the task is waiting on the human. That's a different kind of wait from blocked, where the agent hit a wall and said so. They call for opposite fixes, so they deserve separate numbers.

The obvious implementation is a new status. We didn't do that. Agents read and write the status, the work queue hands out tasks based on it, and filters and counters group by it. A new value would change behaviour in all of those places: an agent looking up its ongoing tasks could suddenly miss the one it is in the middle of.

So "needs input" is derived, and it only exists in the history:

While any question in the task's thread is still waiting for an answer, the history records the task as needs input.
When the last one is answered, the history moves it back to whatever its real status is.
The task's own status stays ongoing the whole time.

A few rules made it correct:

It counts open questions, it doesn't toggle. An agent can have two permission requests open at once. Answering the first must not end the wait.
Only real questions count. An agent's plan has to-do items that are "pending" too, but a to-do isn't a question to anyone.
Closed means closed. A question arriving on a completed task doesn't reopen its history.

Because the status never changes, nothing that reads it behaves any differently. Only the timeline and the totals know.

What does it look like?

Under each task's description there's now a task timeline: one dot per state, with the time spent in each on the line between two dots, and the totals above.

Total	Value	Meaning
Worked	1h 14m	All the time the agent was `ongoing`
Blocked	38m	All the time the agent said it couldn't go on
Needs input	8m	All the time a question to the person was open
Start to close	2h	From the first `ongoing` to completed or rejected

Start to close begins at the first ongoing, not at creation, on purpose. A task that sat in the queue overnight shouldn't look like an agent that took twelve hours.

An open task keeps ticking. Here the agent is waiting on a permission prompt, so the last dot is yellow and counting, and there's no start to close yet:

A small consistency detail: the page works out the totals from the same segments it draws, instead of showing the server's numbers next to a bar it animates itself. Otherwise the live counter and the bar would drift apart every second. The server's totals are still in the API for scripts, agents and the stats pages.

On a phone it collapses to one line, the dots and the total:

How does the dashboard tell the story across every task?

One task's timeline tells you what happened to that task. It doesn't tell you whether that was normal. Is two hours usual for this workspace? Did this week go faster than last? Do agents sit blocked longer in one workspace than another?

So the history feeds a second view: a Task Latency panel on each workspace's stats page and on the account stats page. It charts the same four totals, in minutes, over every task closed in the range you pick, with a toggle between P50 (the typical task), Min (the quickest) and Max (the slowest).

Read the cards like a story. This workspace closed 42 tasks in the week. At p50, a task took 108 minutes start to close, of which 66 were work, 19 were blocked and 7 were waiting on a person. (Each line is its own median, so they don't add up exactly, and they aren't meant to.) Hover over Sep 24 and the typical task took 150 minutes, well above the week's figure. That's the day to go and look at.

The account page shows the same panel across every workspace:

Across the account the typical task took 146 minutes and was blocked for 26 of them. The workspace above beats both, so something else is pulling the account figure up, and you know where to look next.

The design decisions behind the numbers:

Why p50 and not the average? Agent task durations have a long tail. One task that sat blocked over a weekend turns a 30-minute average into a 3-hour one, and then the average describes no task you actually ran. The median is the task you'd typically get. Min and max sit next to it on purpose: max finds the one that dragged, and min shows how fast the work goes when nothing gets in the way.

Why an estimated p50? Stats are rolled up per hour, per day and per month, so a three-month chart doesn't re-read every task. But medians don't add up. You can't combine two hours' medians into a day's median. So each rollup keeps a small histogram of durations with fixed, log-spaced buckets: under a minute, 1–2 minutes, 2–5 minutes, and so on through hours and days, up to over 30 days. Histograms merge by adding counts. The p50 is read back out of the merged histogram, interpolated inside the bucket where the median falls, and clamped between the exact min and max, which merge perfectly. It's an estimate, and it's exact when a bucket holds a single task.

The histogram buckets are immutable too. Same lesson as the state enum: counts are stored by position, so the bucket edges can never be changed or reordered. A finer histogram would be a new field, not an edit.

One arithmetic, two views. The task page and the dashboard compute durations with the same function over the same history, so a task's timeline and its contribution to the chart can never disagree.

Every close counts once. When a task closes, its totals are recorded in the same transaction that closes it. If it's reopened and closed again, its totals are recalculated over its whole history, but a period that was already rolled up isn't rewritten. Each close counts once, in the period it happened in.

Zero is data; nothing is a gap. A task that was never blocked counts as 0 minutes blocked, so the blocked line shows how much blocking a typical task really sees, not just the unlucky ones. But a day with no closed tasks is left as a gap in the line, not drawn as zero, so a quiet day never looks like a fast one.

The resolution follows the range. A day or two plots by the hour, up to about three months by the day, and anything longer by the month. All in UTC.

Agents can read it too. The same figures are available to an agent, so you can ask one to watch for a workspace whose blocked time is creeping up, or to report how long its own work took this week.

It shipped as a follow-up, in agentrq/agentrq#758. The full tour is in Task Latency: How Long Your Agents' Tasks Take.

What does it unlock?

"How long did that take?" finally has an answer. Start to close per task is the number you want when you decide whether a class of work is worth handing to an agent at all.

Agent time vs. your time. A two-hour task might be two hours of work, or twenty minutes of work plus an hour and forty minutes waiting on a permission prompt. The first means the task is big. The second means the human is the bottleneck, and the fix is a broader permission rule, a better prompt, or handing it off at a different time of day. Worked and needs input are separate numbers, so you know which one you have.

Blocked stops being invisible. Before, you saw a blocked task only if you looked while it was blocked. Now every blocked stretch stays on the record with its length, and the dashboard shows which workspace keeps getting stuck.

Improvements become measurable. Change a prompt, a skill or a workflow, and watch whether the typical start to close drops the next week. One fast task proves nothing. A p50 over a week of tasks does.

What are the trade-offs?

No backfill of history. History that was never recorded can't be rebuilt. Existing tasks start their timeline at their next status change. (The dashboard does backfill from whatever history exists, once, on the first boot after the upgrade.)
p50 is an estimate. It comes from a mergeable histogram, not from sorting every task. That's the price of rolling up months of data cheaply.
One more write per status change. It's small, and it happens inside a transaction we were already opening.
A derived state depends on every path that can answer a question. "Needs input" is right only because every way a question gets asked or answered re-checks it. That's why the logic lives in the storage layer and not in the individual features.
The enum is a one-way door. You can add states. You can never remove, rename or reorder the stored ones.

FAQ

Why not full event sourcing?
Too much for this. The status is read in many places, including by agents over MCP. An append-only history beside the current status gets the durations without migrating every reader.

Why not work out durations from the message thread?
Messages and status changes are different streams. An agent can go blocked without writing anything, and a quiet agent can be working for 30 minutes. A dedicated history records exactly what changed and when.

Does "needs input" change a task's status?
No. It exists only in the history. Queues, counts, filters and agents see the same status as before.

Why does the dashboard show p50 instead of the average?
Agent task durations have a long tail. One task blocked over a weekend drags the average far from anything typical. The median doesn't move, and max is right next to it for finding the outlier.

Which states can appear?
Not started, ongoing, blocked, needs input, completed, rejected, and scheduled for recurring or one-time scheduled tasks.

Try it

The change is in agentrq/agentrq#756, and the Task Timeline feature page has the short tour. Open any task that has changed status since the update and look under the description.

Question for you: if you run agents against a task queue, how do you tell "the agent was slow" from "I was slow"? Do you track human wait time separately, or does it all go into one latency number?

Originally published on the AgentRQ blog.

Single Responsibility for AI Agents: One Workspace, One Job

Mustafa Turan — Mon, 28 Sep 2026 04:29:21 +0000

You would never ship a God class that handles billing, email templates, database migrations and the marketing site. So why do so many of us run exactly that as an AI agent?

I did, for months. One agent, one workspace, every repository, every note I had ever written, and a mission description trying to cover a whole company. It was never bad. It was never great at anything either. It wrote landing page copy in the tone of a commit message. It suggested a database migration in the middle of a blog post. It applied a rule from one project to another where that rule was flat-out wrong.

So I refactored it the way I would refactor code: one workspace, one job. This post covers what that means in practice, the two reasons it works, how isolated agents still collaborate (pub/sub, not DMs), and the places where I think you should disagree with me.

TL;DR

An AI agent's memory is only useful if every note in it is true for every task it runs. Mixing jobs breaks that.
Everything an agent loads at the start of a task, it pays for on every turn. A narrow job means a small starting context.
Isolated workspaces coordinate through events (publish/subscribe) and one supervisor agent, never agent-to-agent messages.
Split where the knowledge diverges, not where the task names differ.

What is an isolated, single-purpose AI agent workspace?

I build AgentRQ, so that is the vocabulary I will use, but the idea is tool-agnostic. A workspace is the unit an agent connects to. It holds:

a mission the agent reads when it starts a task,
a task board with the history of every job,
a memory the agent reads and writes (loadMemory / saveMemory over MCP),
a set of skills it can search and load.

"Single-purpose" is just a discipline on top: one workspace, one definition of done. Not "engineering". Something closer to "the static marketing site and its SEO content." If you can't describe success in one sentence, the scope is too wide.

Today I run a handful: static site, core app, QA, support, social, outreach. They don't know about each other. That is the point.

Why does a shared workspace make AI agent memory go bad?

This is the part I underestimated most.

Agent memory rots in a specific way when jobs share it: a lesson that is true in one context gets applied in another where it is false.

# app repo:     "Always run the migration before deploying."   ✅ gospel
# static site:  "Always run the migration before deploying."   ❌ nonsense

# static site:  "The Markdown converter has no italics; use bold."  ✅ vital
# app repo:     "The Markdown converter has no italics; use bold."  🤷 noise

Put both in one pile and the agent has to guess which rules apply, on every task. Sometimes it guesses wrong, confidently. It's the agent equivalent of a global mutable config shared between services.

In a single-purpose workspace, every note is about the same system. The workspace that builds our site has a memory index of about forty entries, and every one of them is about that site: the converter has no italics or blockquotes, headings render as plain text, the CSS hash changes on every build and that diff churn is expected, slugs should be long and descriptive. None of those would survive contact with another project. Here, all of them are simply true.

Two side effects I didn't expect:

The agent writes memory freely. I don't have to curate defensively, wondering whether a note will leak into the wrong context. The agent writes down whatever would have saved it a detour, and the next run skips the detour. Learning compounds instead of colliding.
I can actually review it. Opening one workspace's memory is reading the operating manual for one job. I can spot a wrong note in a minute. A mixed memory is a junk drawer, and nobody audits a junk drawer.

How much context does an AI agent really need to start a task?

Only what the job needs, and the difference adds up.

Before an agent does any work, the mission, the memory index, the skill descriptions and the instructions all go into its context window. In a stateless tool-calling loop, that prefix is re-sent on every turn.

A do-everything workspace has a do-everything prefix. The mission explains five businesses. The memory index lists notes for all of them. The skill list offers a release playbook to an agent writing a tweet. Most of it is noise for the task at hand.

A single-purpose workspace starts smaller because there is less to say. I haven't benchmarked the exact saving (it depends entirely on how big your notes get and how long your tasks run), so I won't invent a number. The shape is simple arithmetic, though:

cost ≈ starting_context × turns + work

Shrink the first term and you save on every turn of every task.

Tokens are the smaller half. The bigger half is attention: an agent whose window is full of relevant context makes better decisions than one that has to ignore half of what it was handed. I pair this with Clear Context, which starts every task on a clean window, for the same reason.

How do isolated AI agents collaborate without sharing context?

The obvious objection: a feature has to be built, tested, released, written up and announced. No single workspace owns all of that.

The workspaces are isolated from each other's context, not from each other's work. They coordinate in two ways, and neither involves one agent reading another's memory.

1. A supervisor agent that sees everything

One supervisor agent connects to an account-wide Supervisor MCP instead of a single workspace. It can see every workspace, task and status; create tasks anywhere; and move a task that landed in the wrong place.

When I want a feature shipped end to end, I brief the supervisor once. It hands the core app its half, the static site its half, and outreach its half, each written for that workspace. The workers stay narrow; the supervisor is the one place allowed to be broad. And it has a single job too: dispatching, not doing.

2. Events, not direct messages

For routine hand-offs I don't want a supervisor in the middle. The workspaces talk through events, which is plain publish/subscribe:

A workspace finishes something and publishes a named event with a short payload.
AgentRQ finds every trigger subscribed to that name.
Each subscribed workspace gets a new task, with the payload in the task body.

The publisher doesn't know who is listening. The listeners don't know who published. The event name is the only contract.

These are the events my workspaces actually run on:

Event	Published when	Who picks it up
`code_changed`	Core app merges a change	QA runs its checks
`qa_failed`	QA finds a regression	Core app gets a fix task, failure attached
`bug_fixed`	Core app lands the fix	QA re-checks, Support tells the reporter
`feature_released`	A release goes out	Static site drafts a post, updates feature pages
`blog_published`	A post goes live	Social turns it into an X thread
`x_thread_created`	The thread is posted	Outreach adds it to follow-ups

Every name is past tense, on purpose. An event reports a fact any workspace can react to in its own way. fix_the_bug would be a command aimed at one agent, which is just a direct message wearing an event's name.

A trigger can also name the event to fire when its task completes, so the chain wires itself. Here is the release part of it as a workflow called release_cycle, spanning five workspaces. Note the fan-out on bug_fixed: Support notifies reporters while Core App cuts the release, in parallel.

I ran it once on a local dev build to check it behaves like the table says. I created exactly one task, a Core App merge that published code_changed. Every task after that was created by an event. Each workspace did its part over its own connection, knowing only its own mission:

Outreach isn't even in that workflow. It subscribes to x_thread_created on its own. The chain grows at the edges without anyone rewiring the middle.

Why not just let agents message each other?

Same reason you put a queue between microservices instead of having every service call every other one:

Coupling. An agent that can DM any other agent has to know who they all are and what each does. That is exactly the cross-domain context I kept out of its window.
Combinatorics. Point-to-point links grow as n(n-1)/2. Five workspaces is already 10 conversations to keep straight, each a place for a request to get lost or answered twice. With events, adding a sixth workspace is one new trigger.
Observability. Every hand-off is a task with a title, a body describing what happened upstream, and a status on the board. When a chain breaks, I'm reading tasks, not reconstructing a group chat between bots.

What does isolating AI agents actually unlock?

Agents get good at one job and stay good. The workspace that runs our site has closed more than ninety tasks, and lessons from the first ones are still in its memory, still true, still read before every new task.
Delegation without re-explaining. I send a one-paragraph brief from my phone. The workspace already knows the tone, the build steps, the formatting quirks and what I rejected last time. That's the difference between delegating a task and babysitting one.
A small blast radius. A bad note or a confused agent can only damage one job. When outreach learns something wrong, the release process doesn't notice.
Cheap agent swaps. The knowledge lives in the workspace, not in one vendor's config file. Point a different coding agent at the workspace and it inherits the mission, memory and skills on day one.

The pitfalls I actually hit

Going too narrow. After the first split I split everything: blog posts, glossary terms, feature pages, each in its own workspace. Same repo, same build, same quirks, and I was teaching three agents the same lessons. The rule now: split where the knowledge diverges, not where the task names do. If two jobs would write the same notes, they belong together.

Genuinely shared knowledge. Some rules are universal: how PRs are described, which branch never gets a direct push. Copying them into every workspace is the same rot, spread thinner. Keep memory for what's local and put what's universal in something shared. In AgentRQ that's skills shared across workspaces: fix a playbook once, fixed everywhere.

Work that crosses the line. A launch needs code in the app and a post on the site. I don't create a third workspace; I split it into two tasks, via the supervisor or a feature_released event. A task that lands in the wrong workspace gets moved, with its history.

Memory still goes stale. Isolation keeps memory relevant, not current. Tools get upgraded, a limitation gets fixed, and the note warning about it becomes a lie. Tell the agent to correct or delete a note when it finds one that no longer holds.

Setup cost. A new workspace needs a mission, a connected agent and a few tasks before its memory is worth anything. Isolation pays back on work that repeats, not on one-offs.

Where you should push back

"Context windows are huge now, just give it everything." Windows have grown, and strong models ignore a lot of noise. But every token is still billed on every turn, and ignoring noise is a skill models have, not one they are perfect at. If your contexts are small and cost isn't a concern, this argument carries real weight.

"A generalist sees connections a specialist misses." The strongest objection, and true. My narrow workspaces will never notice on their own that a new feature deserves a post. The supervisor and events cover the connections I already know about, but a dispatcher over narrow workers isn't one mind holding everything. If cross-domain insight is your main value, a generalist may serve you better.

"Just use retrieval over one big memory." Works when retrieval is good; fails quietly when it isn't. The wrong note ranks high and the agent acts on it. Isolation is blunter, but it fails loudly: you can always see which workspace you are in.

"Overkill for small projects." Often, yes. One repo and one kind of work? One workspace is the single-purpose workspace.

"Teams need shared context, not silos." For teams, boundaries should follow ownership and on-call lines, not one person's mental model. What I describe is shaped for one person running many jobs.

FAQ

What is a single-purpose AI agent workspace?
A workspace scoped to one job with one definition of done, holding its own mission, memory, skills and task history, so an agent working in it only ever loads context that is relevant to that job.

Does isolating AI agents reduce token usage?
Usually. The mission, memory index and skill list are loaded at the start of every task and re-sent on every turn, so a narrower workspace means a smaller fixed cost per turn. The exact saving depends on your notes and task length.

How do isolated AI agents hand off work?
Through publish/subscribe events (a workspace publishes a past-tense event like bug_fixed; subscribed workspaces receive a new task) or through a supervisor agent with account-wide visibility that creates tasks in each workspace.

When should I keep one workspace instead of splitting?
When every note in your agent's memory is true for every task it runs. If you catch yourself writing "except in the other project" into a note, that workspace probably wants to become two.

Try it on one job

None of this is a law. It's the setup that fits one person running many unrelated jobs and wanting to delegate and walk away. I know people who run one giant workspace very productively, people who spin up a workspace per feature and throw it away on ship, and teams who isolate by customer instead of function.

So take the question, not my answer: is every note in your agent's memory true for every task it will run? If not, split one job out, give it a week of tasks, and read its memory at the end.

How do you scope your agents: one generalist, many specialists, or something else? I'd like to hear what's working for you in the comments.

Originally published on the AgentRQ blog. AgentRQ is a human-in-the-loop task manager for AI agents: agentrq.com.

Zero Dependency Open Source

Mustafa Turan — Thu, 02 May 2019 07:29:01 +0000

Writing a zero-dependency open-source library could be the way to bring an immortal contribution to the developer communities. Adding dependencies to your open-source will bring many update/upgrade work while your busy life goes on. And you/community may give-up one day to update those dependencies because of several reasons. Even the zero-dependency library might need language version updates. So, the real intention is keeping as minimum dependency as possible.

Instead of putting dependencies, put interfaces to the library and let the library users to use their own choice of libraries by implementing your interface. And share sample implementations with a dependent library as an example instead of directly adding implementation. (What is being defined is also a part of hexagonal-architecture pattern for software design which makes the library optioned without implementation choices.)

4 steps to provide zero-dependency library:

Implement your library functionality
When you need an external dependency(external library from another author), create an interface instead of adding the dependency
Document a sample implementation with/without dependency (but do not implement)
Let the library user decide what to use & leave the interface implementation to the library user.

This could be the way to bring an immortal contribution to the developer communities. Since there will be no dependency, the library can be used for new projects/libraries with different implementation details. Even after years, new implementations would be possible without updating the library...

Before taking action, it is highly recommended also reading DHH's Rails is Omakase post. More ideas are highly welcome. Let's discuss.

Decoupled Package Communication in Go

Mustafa Turan — Sun, 28 Apr 2019 23:14:24 +0000

Go is very powerful language for software development with its simplicity, concurrency, first-class functions and tools.

In Go, usually, a package is responsible only for one thing. Applications grows with several packages with their own responsibilities. When the number of packages in the project and responsibilities of the project increase, it is possible to mess up on communication with other packages. (In here, the communication means calling functions on different packages/modules on the flow with/without waiting result. Like incrementing counter metric when an order received/full-filled)

One of the known ways of decoupling on communication is the event driven software designs. Usually, using an external event/message-bus server is the way distributing the responsibility to internal/external services. But this also brings another external component to your stack. And each stack comes with its own problems.

For small services, packages/libraries, and embedded systems adding an external bus could be unnecessary addition. To overcome this problem, adding an internal message-bus package to your package may help. And when things getting bigger, it is possible to communicate with this internal message-bus to external message-bus services.

Assume that, a project needs to do several things on user registration like; incrementing counters, sending email, logging, and/or sending webhook to external service; instead of directly calling each of the functionalities directly, a message-bus can help to execute multiple functionalities asynchronously without knowing the caller.

Decoupled packages help us to write cleaner code, focus on only one thing at a time. With bus Go package, you can get benefit of real message bus system and write decoupled packages easily. The bus package allows any handler to listen any events, without knowing who generates the event. Thus, packages can communicate without depending on each other. Moreover, it is very easy to substitute a consumer function. As long as the new function understands the Event struct that are being sent and received, the other functions will never know.

Get Started With `Bus` Go Package in 4 Steps

Configure

The bus package requires a unique id generator to assign ids to events. You can write your own function to generate unique ids or use a package that provides unique id generation functionality. Here is a sample configuration using monoton id generator:

import (
    "github.com/mustafaturan/bus"
    "github.com/mustafaturan/monoton"
    "github.com/mustafaturan/monoton/sequencer"
)

func init() {
    // configure id generator (it doesn't have to be monoton)
    node        := uint(1)
    initialTime := uint(0)
    monoton.Configure(sequencer.NewMillisecond(), node, initialTime)

    // configure bus
    if err := bus.Configure(bus.Config{Next: monoton.Next}); err != nil {
        panic("whoops")
    }
    // ...
}

Register Event Topics

To emit events to the topics, topic names need to be registered first:

func init() {
    // ...
    // register topics
    bus.RegisterTopics("order.received", "order.fulfilled")
    // ...
}

Register Event Handlers

To receive topic events you need to register handlers; A handler basically requires two values which are a Handle function and topic Matcher regex pattern.

handler := bus.Handler{
    Handle: func(e *Event){ 
        // fmt.Printf("Event: %+v %+v\n", e, e.Topic)
        // do something
        // NOTE: Highly recommended to process the event in an async way
    },
    Matcher: ".*", // regex pattern that matches all topics
}
bus.RegisterHandler("a unique key for the handler", &handler)

Emitting Events

The bus package provides a generic event struct to standardize what an event is for all of its handlers. Before delivering an event, it is good to know what an event is for the bus package. If this is your fist moments with the library, it is highly recommended to check the data structure of the Event struct.

txID  := "some-transaction-id-if-exists" // if it is blank, bus will generate one
topic := "order.received"                // event topic name (must be registered before)
order := make(map[string]string)         // interface{} data for event

order["orderID"]     = "123456"
order["orderAmount"] = "112.20"
order["currency"]    = "USD"

bus.Emit(topic, order, txID) // emit the event for the topic

Congratulations!!! You emitted your first event with the bus package. Now, the all matched handlers will receive the same event. Please try yourself and share your experience as comment.

Also a sample project using bus package can be found on bus-sample-project Github.

mustafaturan / bus

🔊Minimalist message bus implementation for internal communication with zero-allocation magic on Emit

🔊 Bus

Bus is a minimalist event/message bus implementation for internal communication It is heavily inspired from my event_bus package for Elixir language.

API

The method names and arities/args are stable now. No change should be expected on the package for the version 3.x.x except any bug fixes.

Installation

Via go packages: go get github.com/mustafaturan/bus/v3

Usage

Configure

The package requires a unique id generator to assign ids to events. You can write your own function to generate unique ids or use a package that provides unique id generation functionality.

The bus package respect to software design choice of the packages/projects. It supports both singleton and dependency injection to init a bus instance.

Hint: Check the demo project for the singleton configuration.

Here is a sample initilization using monoton id generator:

import (
    "github.com/mustafaturan/bus/v3"
    "github.com/mustafaturan/monoton/v2"
    "github.com/mustafaturan/monoton/v2/sequencer"
)
func NewBus() *bus.Bus {
    // configure id generator (it doesn't have

…

View on GitHub

Persisting event data to Postgres using GenStage and EventBus

Mustafa Turan — Tue, 31 Jul 2018 08:10:52 +0000

One of the ways to consume EventBus events is implementing GenStage consumers. GenStage handles backpressure easily with configurable workers. event_bus_postgres library uses GenStage to persist event_bus events to postgres DB with batch insert.

How it works

+-----+
|     |                                         GEN STAGE
|     |        EVENTBUS      +------------------------------------------+
|     |        CONSUMER      |                   +---+                  |
|     |        +-----+       |                   |   |                  |
|     |        |     |       |                   |   |          +---+   |
|     |        |  E  |       |                   |   |          |   |   |
|     |        |  v  |       |                   |   |          |   |   |
|     |        |  e  |       |                   |   |          |   |   |
|  E  |        |  n  |       |                   | E |          |   |   |
|  l  |        |  t  |       |  +-------+        | v |          |   |   |
|  i  | topic  |  B  |  topic   |       |        | e |          |   |
|  x  |   +    |  u  |    +     |   Q   |        | n |          | B |       +--+
|  i  |event_id|  s  | event_id |   u   |   ask  | t |    ask   | u |       |  |
|  r  |------->|  .  |--------->|   e   |<-------|   | <--------| c | BATCH |  |
|     |        |  P  |          |   u   |------->| M | -------->| k |------>|DB|
|  E  |        |  o  |          |   e   |   pull | a |    pull  | e | INSERT|  |
|  v  |        |  s  |          |       |        | p |          | t |       |  |
|  e  |        |  t  |       |  +-------+        | p |          |   |   |   +--+
|  n  |        |  g  |       |  GENSTAGE         | e |          |   |   |
|  t  |        |  r  |       |  PRODUCER         | r |          |   |   |
|  B  |        |  e  |       |                   |   |          |   |   |
|  u  |        |  s  |       |                   |   |          |   |   |
|  s  |        +-----+       |                   |   |          |   |   |
|     |<-----------------------------------------|   |          +---+   |
|     |                      |    fetch_event/1  |   |         CONSUMER |
|     |                      |                   |   |                  |
+-----+                      |                   +---+                  |
                             |                  CONSUMER                |
                             |                  PRODUCER                |
                             +------------------------------------------+

Components

EventBus
Message bus for Elixir; it publishes event_id and topic data to topic subscribers.

EventBus.Postgres
Message bus event consumer; it pushes event_id and topic to the EventBus.Postgres.Queue

Queue
GenStage producer; it is a simple queue implementaion

EventMapper
GenStage producer-consumer; it pulls/dequeues from EventBus.Postgres.Queue, and fetch original event from EventBus and then convert data into Ecto model.

Bucket
GenStage consumer; it pulls/dequeues from EventBus.Postgres.EventMapper and batch insert data to Postgres DB.

Source code: https://github.com/otobus/event_bus_postgres

Decoupled Modules with Elixir EventBus

Mustafa Turan — Mon, 23 Jul 2018 07:48:41 +0000

Elixir EventBus is a library that allows different modules to communicate with each other without knowing about each other. A module/function can create an Event struct, and deliver to the EventBus without knowing which modules will consume.

Modules can also listen to events on the EventBus, without knowing who sent the events. Thus, modules can communicate without depending on each other. Moreover, it is very easy to substitute a consumer module. As long as the new module understands the Event struct that is being sent and received, the other modules will never know.

Get started with decoupled modules in 4 steps

Decoupled modules help us to write clear code, focus on only one thing at a time. With EventBus library, you can get benefit of real event bus system and write decoupled modules easily.

Registering event topics

On your app init, or anytime before delivering the events we need to register our topics. For example, when we receive a payment, we will create checkout_completed event.

EventBus.register_topic(:checkout_completed)
EventBus.register_topic(:checkout_failed)

Delivering events

EventBus.EventSource module provides notify helper to deliver events without modifying your current code.

defmodule Order do
  ...
  use EventBus.EventSource
  ...
  def checkout(params) do
    event_params = %{topic: :checkout_completed, error_topic: :checkout_failed}
    EventSource.notify(event_params) do
      ... # process the payment as usual in here and if errors then return {:error, _} tuple
    end
  end
end

Subscribing consumers to topics

Assume that we have several operations waiting on success and failure conditions. Let's subscribe the consumers to the event topics.

EventBus.subscribe({StockUpdateService, ["^checkout_completed$", "^new_stock_arrived$", ...]})
EventBus.subscribe({CargoService, ["^checkout_completed$, "^cargo_dispatched$", "^new_stock_arrived$", ...]})
EventBus.subscribe({EmailService, ["^user_registered$", "^checkout_completed$", ...]})
EventBus.subscribe({EventBus.Logger, [".*"]})

Consuming events

EventBus consumers are just modules so they can be implemented by any kind of consumer strategy including GenStage(event_bus_postgres as sample), pooling, DynamicSupervisors, global consumers, spawn et al. So, depending on your use case, implement your consumers with the best suitable strategy. (But any kind of blocker strategies are not recommended!)

defmodule CargoService do
  use GenServer
  ...
  def process({topic, id}) do
    GenServer.cast(__MODULE__, event_shadow)
  end

  def handle_cast({topic, id}, state) do
    payment_data = EventBus.fetch_event_data({topic, id})
    # do sth with payment_data
    ...
    # mark event as completed for this consumer
    EventBus.mark_as_completed({CargoService, topic, id})
    {:noreply, state}
  end
end

Here is another consumer that needs all event structure and consumes with spawning:

defmodule StockUpdateService do
  ...
  def process({topic, id}) do
    spawn(fn ->     
      event = EventBus.fetch_event({topic, id})
      # do sth with event.data and/or any other event attributes
      ...
      # mark event as completed for this consumer
      EventBus.mark_as_completed({StockUpdateService, topic, id})
    end)
  end
end

About the EventBus library

EventBus library is a traceable, extendible, fast, and memory friendly pure Elixir implementation without any external dependency in the pocket.

Traceable

EventBus library comes with good optional attributes to provide traceability. When a consumer receive the topic and event_id, it can fetch structure with fetch_event/1 function. And if you use EventBus.EventSource helper, the optional fields are set automatically for you. Here is the structure of an Event model:

%EventBus.Model.Event{
  id: String.t | integer(), # required
  transaction_id: String.t | integer(), # optional
  topic: atom(), # required
  data: any() # required,
  initialized_at: integer(), # optional
  occurred_at: integer(), # optional
  source: String.t(), # optional
  ttl: integer() # optional
}

Extendible

EventBus library allows subscribing events with regex patterns, which allows consumers to subscribe new topics automatically. With this feature, it allows extending the system asynchronously with generic consumers like event_bus_logger, generic Postgresql event store, event_bus_metrics UI, and so on.

Fast by design

EventBus library uses builtin memory store ETS effectively to get benefits of concurrent reads and writes. It doesn't block majority of the read operations, and allows concurrent reads to fetch Event data.

It applies queueing theory to handle inputs. And almost all implementation data accesses have O(1) complexity.

Memory friendly

EventBus library delivers only topic and event_id to the consumers and keeps the original event data in the topic's Event table. So, only when consumers are able to process the event, then they fetch the event data.

Distributed?

Even though the main intention to create this library is to use for internal module communications, it is possible to deliver events across nodes. One of the ways to delivery is sending message to connected other nodes as usual Elixir/Erlang way:

for node <- Node.list() do
  Node.spawn(node, EventBus, :register_topic, [:checkout_completed])
  Node.spawn(node, EventBus, :notify, [%{EventBus.Model.Event{..}}])
end

Note: EventBus library is not in the same class distributed solutions like Apache Kafka, RabbitMQ, or Redis Streams.

Original story on Medium: https://medium.com/elixirlabs/decoupled-modules-with-elixir-eventbus-a709b1479411

The source code of EventBus library: https://github.com/otobus/event_bus

When to give a star to an open source library?

Mustafa Turan — Tue, 17 Jul 2018 04:23:00 +0000

Giving a star to an open source library means to a lot to the developers and consumers of the library. Because this will give the developers a positive impact to make the library better. It is definitely a way to tell gently to the developers, there are people out there who use that library.

As a consumer of the library

If you are using an open source library, go ahead and find its Github/Gitlab (or any version control source) and give it a star. If you need to use a high-quality generic library, you should help to bring new people to the library. Starring will bring quality and aliveness to the library. One of the people that you bring, might be the next contributor to the library.

To support the work or idea

You find an open source library in the following interests:

Like the idea
Plan to use it in your current or next project
Like the software design of the library
A topic of interests like distributed systems, data structures, useful links

Don't forget that any positive starring activity will bring more people to like the library with the social impact. This positive impact will also bring more contributors to the library. And will prevent the library to get out-dated.

These are only my ideas while starring a library, please do not hesitate to share yours. I will be happy to include in the story including your name.

DEV Community: Mustafa Turan

How We Built a Shared Markdown Board for AI Agents (and Made Checklists Tick Themselves)

What problem are we solving?

What is a Pano doc?

Why can't agents search the Pano?

How does an assigned checklist item follow its task?

Step 1: assigning writes a link into the markdown

Step 2: a status change triggers a server-side rewrite

Step 3: the write is a sync, not a save

Step 4: open boards update live

How do two agents avoid overwriting each other?

Every doc has a version

The check happens in the UPDATE itself

A conflict tells the agent exactly what to do

edit: change a line without resending the doc

What humans see on a conflict

How do @mentions turn into tasks?

What stops the board from filling up forever?

What are the rules for files?

What does this unlock?

FAQ

How to Enable Claude Code Channels for Team and Enterprise Plans (Step by Step)

TL;DR

What are Claude Code Channels, and why are they off for my org?

Who can enable Channels?

Step 1: Open Organization settings

Step 2: Go to Products → Claude Code and find Channels

Step 3: Confirm it says "Set by admin"

Step 4: Connect a channel (AgentRQ, Telegram or Discord)

Option A: AgentRQ

Option B: Telegram

Option C: Discord

Can I enable Channels with managed settings instead?

How do I restrict which channel plugins can run?

What should admins think about before turning it on?

FAQ

Use Claude right inside your Chrome and let it play with WebMCP tools

What problem does WebMCP leave open?

Part 1: The WebMCP bridge

Challenge 1: How do you see a page's tools without becoming a tool provider?

Challenge 2: How do you talk to page code without the page listening in?

Challenge 3: How does a server reach a browser behind NAT?

Challenge 4: Which tab runs the call?

Challenge 5: How do you keep remote tools from eating the agent's context window?

Challenge 6: How do you let a remote agent act as you without handing it your credentials?

Part 2: Claude Code's terminal, inside the extension

Challenge 7: Why not just bundle the web app into the extension?

Challenge 8: How do you replay a terminal that redraws itself 100 times a second?

Challenge 9: How do you handle backpressure without corrupting the stream?

Challenge 10: Why is input never batched?

Challenge 11: Why did terminals sometimes go blank?

What did we trade away?

FAQ

Try it

Stop Overwriting Your AI Agent's Task Status: Why We Keep an Immutable State History

Why is overwriting a status the wrong model for agent work?

What does "immutable history" mean here?

Why does immutability matter so much for agents?

Why are the states an enum instead of free-form strings?

Why is there only one writer?

Why is "needs input" a state the task can never be in?

What does it look like?

How does the dashboard tell the story across every task?

What does it unlock?

What are the trade-offs?

FAQ

Try it

Single Responsibility for AI Agents: One Workspace, One Job

What is an isolated, single-purpose AI agent workspace?

Why does a shared workspace make AI agent memory go bad?

How much context does an AI agent really need to start a task?

How do isolated AI agents collaborate without sharing context?

1. A supervisor agent that sees everything

2. Events, not direct messages

Why not just let agents message each other?

What does isolating AI agents actually unlock?

The pitfalls I actually hit

Where you should push back

FAQ

Try it on one job

`edit`: change a line without resending the doc

Get Started With `Bus` Go Package in 4 Steps