AgentsRoom MCP
- Desktop app
- All plans
What it does
AgentsRoom exposes itself to the agents it runs, through the Model Context Protocol. Every agent launched in a project gets a set of local MCP servers that let it read and act on the workspace: the backlog, the saved dev commands, the prompt and skills libraries, the project memory, the agent roster and its mail, the saved SSH and database connections, the app settings, and the embedded browser for QA agents. Every one of these actions keeps its manual path in the UI; MCP adds the option to have an agent do it. The servers are small local processes, talking to the desktop on the loopback interface with a token regenerated at every boot. Nothing goes through a cloud.
Video (1:18): AgentsRoom MCP, shown in the real app. A Claude Code agent is asked to fix a checkout bug and track it on the task board: it files its own card in To do, fixes the bug, then moves the card straight to Done with a one-line summary, without anyone touching the board. In the app, the video tutorial icon of the Backlog header (right after the Board / Epics switch) opens a Video tutorials menu where it is listed as Let your agent update the board (since 2026-11-12).
Where to find it
- Nothing to install: the servers are declared to each CLI when an agent starts, in the format that CLI reads (
.mcp.jsonfor Claude Code, a generatedCODEX_HOMEfor Codex,.cursor/mcp.jsonfor Cursor, per-CLI project configs for the others). - Inside a session, the agent sees them as
AgentsRoom-MCP(the main server),AgentsRoom-Browser(QA agents only),AgentsRoom-Test-RunnerandAgentsRoom-QA-Tester. Ask an agent to callcapabilities_getto list what it has. - Consent prompts appear in the calling agent's panel (spawning another agent, driving a test tool) and can be relaxed in Settings > Agent behavior and per project.
- An agent started in a git worktree (a ticket with its own branch, or an agent pinned to a worktree) gets the same tools as one started at the project root. Claude Code and Copilot only read the tool declaration of the folder they start in, so since 2026-09-22 a worktree launch hands them the AgentsRoom servers with its launch options; the other CLIs were already covered. See Git Worktrees.
- An agent offloaded to a remote SSH host gets the same tools installed on that host before each launch (Claude Code and Codex only, the host needs Node.js and a plain SSH connection), so a remote agent uses the backlog, memory, skills, prompts, dev commands and agent mail like a local one. See Remote SSH Offload.
How to use it
- Talk to the agent in plain language: "log this as a ticket", "start the dev server", "save this prompt", "message the QA agent", "what is my quota". The agent picks the tool.
- Reads (
*_list,*_get, screenshots) never ask for confirmation. Writes follow an etiquette: an explicit request is acted on, an agent's own initiative is proposed first. Deletions require a request naming the item. - Some writes are refused by design and the refusal is returned to the agent with its reason: an agent never edits its own configuration, never closes itself, never edits a team definition while a run of that team is live, and never receives a password or secret value.
Tool families, in user terms:
- Capabilities:
capabilities_getdescribes the connector itself (versions, tool catalogue by family with read / write / destructive marks, what loaded or not and why, the teams connection contract). The call to make when a tool seems missing. - Backlog:
backlog_list/_get/_create/_update/_delete/_reorder/_start_next,backlog_comments(read a public ticket's reporter thread) andbacklog_comment/backlog_notify_done(answer that reporter),backlog_submit_for_review/backlog_review(a ticket with a reviewer closes only through review),backlog_link/_unlink(dependencies: a blocked ticket waits by itself),backlog_columns_list/backlog_column_save/backlog_column_delete(the board's columns and every column's prompt, mode and agent),backlog_publish_mockup.backlog_update({ descriptionAppend })adds a section to a ticket's body without rewriting it and answers with the room left; once the description is full, the section is filed in the ticket's Comments instead of being refused (appendedTo: "comments"). Progress notes go tobacklog_internal_comment, the ticket's activity log. - Terminal commands:
commands_list/_get/_create/_run, project and account scopes; the way an agent starts a dev server instead of a background shell.commands_outputreads the tail of what a running tab has printed (a saved command, a tab opened throughcommands_propose, or an SSH tab opened withssh_connect), so the agent follows a build instead of launching it twice; it is refused for a command whose text references a{{secret:NAME}}.commands_stopends what the agent started: Ctrl-C in place (the tab stays,commands_runreruns in it) or kill and close the tab, so agents clean up their own terminals.commands_proposeis the other side of it: a line the agent's own sandbox refused, handed to you as a card to run or refuse (see Command Proposal). - Libraries and memory:
prompts_*,skills_*(upsert by name;skills_gettakes a skill id or its name, case, spaces and punctuation ignored, so a skill named in the boot prompt needs no lookup),memory_*. - Agents:
agents_list/_get/_save(saved agent configuration),agents_spawn/agents_close(a throwaway colleague, confirmed by you),agents_delete(delete saved agents, here or in every open project, by id or exact name, confirmed by you on one card for the whole batch),agents_recover(coordinator only: interrupt a stuck teammate's turn or restart its console on its previous conversation, with a notice to you; or, withaction: "handover", ask you on a « Hand over and restart » card to let a teammate write its handover and start over on a fresh conversation, which runs only if you approve),agents_restart(the calling agent starts its OWN console over on a fresh conversation, with the first message it wrote, once its turn ends: what/clearplus a typed message would do, for context checkpoint routines; see the question below),agents_restart_receipt(AgentsRoom's own record of that restart, read by the new conversation: which restart started it, with the metadata the previous one attached),team_finalize_run/team_cancel_run, and Agent Mail:agents_list_live,agents_send,agents_message_status,agents_read_inbox(the whole mailbox, or one message withmessageId, which earns its read receipt on its own),agents_reply,agents_ack,agents_report_status. - Delegation ledger (Agent Mail family):
assignments_createhands work to one agent of the project and records it,assignments_listgives each delegation's state and the delegator's next step computed by fixed rules (also served to scripts at/v1/assignmentsof the local status API),assignments_minelists what the caller owes,assignment_updatemoves one (accepted, declined, blocked, submitted with a result, verified, returned, closed, a follow-up). See Delegation ledger. - Agent catalog and custom agents (every agent):
agents_catalog_search(built-in roles, The Agency, community agents and your own agents, private ones included;suggest: trueuses the AI pick and its monthly allowance),agents_create_custom(a new agent in My agents, private, counts against the plan's personal-agent limit) andagents_publish_custom(sends it to the moderation queue; a near duplicate of a public agent comes back as a question). Creation and publication only after your explicit yes. - Personal assistant only (hidden from coding agents):
assistant_journal,assistant_attach/assistant_image(keep an image in the private memory, look at one), and the team toolsassistants_list/assistants_create/assistants_delegate/assistants_message(the assistant and its specialists hand requests over and exchange short, rate-limited messages; see Assistant specialists), andagents_questions_list/agents_question_answer(the main assistant reads the questions agents are waiting on, AgentsRoom cards and Claude Code's own question dialog, and passes on the user's own answer; see Structured questions). These two are also listed to a project's coordinator (the project assistant, or any saved agent with Coordinator on), for the agents of its own project only. - Teams:
teams_list/_get/_save(withdryRun) /_delete. A big team no longer has to be read or resent whole:teams_getandteams_saveacceptview: "structure"(every node and edge, prompts replaced by their size and a preview),teams_get({ node })returns one node in full with its edges, andteams_savetakes incremental operations (nodePatches,addNodes/removeNodes,addEdges/removeEdges/edgePatches) that touch only what they name. A step's check command carries its two delays there too (checkIdleTimeoutSec, default 120, andcheckMaxTimeoutSec, default 3600). Inside a run, the run-scoped team server'steam_complete_stepacceptsneedsInput: trueamong its flags: the run pauses on that step and shows the summary to you as a question instead of moving on. Triggers:triggers_list/_get/_save/_run/_delete. Ideas: theideas_*family of the Idea Radar. - Connections:
ssh_list/ssh_exec/ssh_transfer/ssh_connect/ssh_connection_new/ssh_folders_get/ssh_folders_apply, which cover SSH servers, AWS SSM instances and Windows hosts over WinRM (kind: "winrm":ssh_execruns one PowerShell line, read-only for agents unless the owner allowed writes, every write confirmed by you in the agent's pane),db_list/db_schema/db_query(read-only) /db_connection_new/db_folders_get/db_folders_apply(folders of the lists, display only),kube_list/kube_status/kube_kubectl(saved Kubernetes clusters: reads run, writes need a writable cluster and your approval in the agent's pane),secrets_list(names only). - Keep the computer awake:
keep_awake_status(is the machine held awake, and why),keep_awake_start(hold it even with nothing running, forminutesor until stopped, optionally with the screen on),keep_awake_stop. Same hold as the cup icon in the status bar; see Keep the Machine Awake. - Quota rules:
quota_rules_list/_save/_delete, the rules of Usage > Quota management (block, redirect or adjust a launch, run a trigger, switch running agents when a gauge reaches a threshold), one rule at a time, checked and applied live. - Settings:
settings_list/settings_get/settings_setat three scopes:global(the machine's app settings),project(this project's overrides, with the inherited and effective value shown,nullremoves an override) andagent(one saved agent's configuration, by id or exact name). - Workspaces:
workspace_create, which opens a new workspace of the account from a name and a mission, with no directory to pick. The zone is named as it appears in the sidebar; an unknown name is refused rather than filed at the root. - Project setup:
projects_openadds a directory that already exists on this computer as a project, like Projects home > + > Open project (a path that is already a project is selected, not added twice;~/paths work; counts against your plan's project limit).projects_renamechanges a project's display name, like the sidebar rename (never its directory).projects_folders_getshows the folder tree with every project's id, path and folder;projects_folders_applycreates folders (nested if needed) and files projects into them in one batch, all or nothing, like dragging projects in the sidebar. An agent can also register a folder that already exists on one of your saved SSH servers as a project, like New project > Remote, without cloning it again (projects_openwith the server's connection id): the server is asked whether the folder exists first, and a folder already registered is selected, never added twice. Everything is saved and synced to your account. A project or folder named ambiguously (two clones of one repository, two projects with the same name) is refused with the candidates, never guessed. - Product knowledge:
product_help_index/product_help_get/product_help_search, the feature-by-feature knowledge base shipped with the app. Any agent can read it, not only the in-app assistant. - Git:
git_set_commit_messagepre-fills the commit box of the calling agent's pill in the Changes tab with its final commit line, following your commit format rules. It commits nothing and runs no git command: the click stays yours. One write per commit cycle: the tool only fills an empty box (a later call answersalreadySetand changes nothing), and committing clears it. When a later turn changes what the work is (a feature removed, the first change reverted), the agent can replace its own message withreplace: true. A message you typed by hand in that box is kept and the tool answerskeptUserDraft; it is refused when Agents write their own commit message is off. - Phone:
notify_usersends the calling agent's own message to your phone as a push (plus a desktop notification), for an agent working without you that needs a decision, such as a scheduled run keeping your board moving. The title is always the agent and the project; the agent only writes the body (300 characters). One message per agent per minute. It follows your phone notification levels: an agent set to Off reaches only the desktop, and the answer tells it so. See Agent Notifications. - Showing a page:
view_presentlets the calling agent show you a page it wrote (an HTML dashboard, a chart, a report; also an image, SVG, PDF, Markdown or CSV file), whatever its CLI, with no hosted service: the file stays on your machine. It is where an agent's reports, audits and studies go by default; a notebook page is written only when you ask for a note (Structured Notes). It appears as a block above that agent's composer and never takes your screen. Click the block: the Documents tab of the right panel comes to the front and the page opens. The cross removes the block, the document stays in Documents, whose tab shows how many there are. If you are not looking at that agent, you also get a desktop notification, whose click lands on the page, and a phone push that opens it on the phone. - Team Chat bridge:
chat_list_threads,chat_readandchat_send, listed only to the one saved agent per project you gave Team Chat bridge (Edit agent > Capabilities, off by default). See Team Chat. - Fast replies:
fast_replysends the calling agent's short answer (500 characters) to a quick question of the user: a bubble above its input box, the title bar Replies list and, per the user's channel, the phone or the developer inbox Mail tab. Required when the user's message ends with the fast reply marker (the lightning button left of Send). Answersdisabledwhen the user turned it off. See Fast replies. - Clock:
clock_getanswers the current local date and time of your computer, its IANA time zone (Europe/Paris,America/New_York) and its UTC offset, plus the same instant in UTC. A model has no clock, and the shell an agent runs commands in may be set to another zone (often UTC), so (if an agent wrote times in UTC, hours away from yours) once the tool is on, the startup instructions tell every agent to call it before writing any date or time (logs, reports, notes, tickets) and to write your local time with its offset unless you asked for UTC. Computed on your machine with no network call, on macOS, Windows and Linux alike. Off by default: turn it on in Settings > AgentsRoom tools, Desktop family,clock_get(or for one folder, project or agent only). Once on, the startup line comes with it; off, neither the tool nor the line reaches the agent. - Account and support:
usage_overview(quota per provider and account, anonymous),projects_list(every project of the account, the ones open on this desktop first, each flaggedopenHere) plus aprojectargument on the read tools to look into a sibling project (a name carried by several projects is refused with the candidates, except when only one of them is open on this desktop: that one is used),report_issueto file a bug about AgentsRoom itself on the AgentsRoom public board. - What changed in AgentsRoom:
product_changelog(the public changelog, release by release, next to the version you run and whether an update is out;sinceVersionkeeps only what is newer),product_board_list(the AgentsRoom team's public feature/bug board: type, status, votes, the release that carries a fix;mine: truelists your own reports when you are signed in,updatedSincewhat moved since a date) andproduct_board_get(one ticket with its public thread, and whether the version you run already has the fix). Read-only and public: nothing about your project is sent, and reading a ticket never marks a reply as read. - Browser (QA agents):
browser_navigate/_click/_type/_screenshot/_evaluate/_get_logs/_get_state/_wait_for/_go_back/_go_forward/_reload.
Settings
mcpTransport(global, Settings > Agent behavior > Shared AgentsRoom tool server: Shared / Per agent; project override in Project settings > AI providers, with Inherit; default Shared; machine-local, not synced with the account): how agents reach these tools. Shared (since 2026-10-19): ONE background process of the computer serves every agent console over HTTP on 127.0.0.1, instead of four or five Node.js processes started by each agent CLI; each console proves who it is with its own session token. Used by Claude Code, Copilot, Codex, OpenCode and Grok (Grok on macOS and Linux); every other CLI keeps its own processes. Per agent: the historical way, every CLI starts its own copy of each server. Applies to agents launched afterwards. The row shows whether the shared server is running, its sessions and its memory. Also settable withsettings_set { key: "mcpTransport" }at global or project scope.preserveMcpJson(project only, Project settings > AI providers > Leave this project's .mcp.json untouched; off by default; stored with the account, so every computer follows): for a repository that declares its own MCP servers in a committed.mcp.json. On: AgentsRoom adds nothing to that file, takes back out the entries it had added (only its ownAgentsRoom-*/agentsroom-teamnames; a file it cannot parse is left as it is), and no longer adds.mcp.jsonto the project's.gitignore. Claude Code and Copilot agents still get every AgentsRoom tool, team runs included, through their launch command instead; the servers your.mcp.jsondeclares load as usual (Claude Code asks you once to approve them). Restart running agents to apply. Also settable withsettings_set { scope: "project", key: "preserveMcpJson" }.askBeforeAgentSpawn(global, Settings > Agent behavior, "Ask before an agent creates an agent"; project override; per-agent exemption): confirm before an agent creates another agent. On by default; the cap on live throwaway agents per project applies either way. On the Create an agent? card, Don't ask again when "<agent name>" creates agents exempts the agent that asks, not the one being created; Stop asking for this project writes the project override.focusBackgroundAgents(global, Settings > Agent behavior > Bring agents started in the background to the front; project override in Project settings > Agents; on by default): when a team run moves to its next step, the app shows that step's console. Off: you stay on the agent you are working with, the step's agent still starts and shows in the sidebar. Whatever this setting, the app never switches agents while you are typing (a key pressed in the last 10 seconds, or an unsent draft in the focused field). One exception when it is off: a Relay step that restarts its console on another provider, model or account still comes to the front once you stop typing, because the console on screen performs that restart. Agents created byagents_spawnorbacklog_start_nextnever take the focus.focusAgentCommandTabs(global, Settings > Agent behavior > Bring dev command tabs started by agents to the front; project override in Project settings > Agents; on by default): same rule for the terminal tab of a command an agent starts withcommands_run. Off: the tab appears in the bottom bar with the agent's avatar and the app does not switch to it. Never switches while you are typing. See Dev Terminals.maxLiveThrowawayAgents(global, Settings > Agent behavior > Max throwaway agents per project; project override in Project settings > Capabilities & permissions): how many throwaway agents (created by an agent, the quick agent or a backlog ticket) can run at once in a project. From 1 to 32, 8 by default. Beyond it,agents_spawnis refused with a message that names this setting. It is the guard against an agent that keeps creating agents; raise it for orchestration workflows (a coordinator with an implementer and a reviewer per ticket). Also settable withsettings_set { key: "maxLiveThrowawayAgents" }at global or project scope.askBeforeTestTools(global, project override, per-agent exemption): confirm before an agent drives the browser, the Electron inspector or the QA test runner.interAgentMessaging(global): allow agents to write to each other through Agent Mail.agentCommitMessage(global, Settings > Git; project override in Project settings > Git; per-agent pin): Agents write their own commit message. On by default: the agent posts its commit line throughgit_set_commit_messageand the commit box stops guessing one from the session title (a backlog ticket title still prefills it). Off: classic prefill and the tool is refused.analyticsOptedOut(read-only): whatreport_issuechecks before attaching app version and OS to a ticket.mcpToolToggles(global, Settings > AgentsRoom tools; folder, project and agent overrides) andmcpToolDescriptions(global): which AgentsRoom tool families or single tools the agents get, and your own wording of tool descriptions. A switched-off tool is not listed to the agent at all. Details in AgentsRoom tools settings.
Agent tools (MCP)
This fiche is the tool list itself; see the families above. Only the names listed exist. agents_context (since 2026-11-16, reported by Tu) answers the caller's real context fill as its header gauge shows it (tokens, window, percent, the user's target ceiling), or a teammate's of the same checkout with to, and unknown with a reason when the CLI gives no reliable figure: see Claude Code Token Usage.
Completed command tabs
Agents can use commands_close to close completed dev-command terminal tabs after reading their output. It refuses running commands, queued launches and unknown execution states. commands_list distinguishes execution from open shells: completedPtyIds lists idle tabs, while runningPtyIds lists busy or unknown tabs. commands_run reuses a finished tab, so no manual cleanup is needed before rerunning. If another instance is still executing, the duplicate guard remains.
Providers
All providers except Aider, which has no MCP support. Each CLI receives the servers in its own configuration format, written at launch. With Shared AgentsRoom tool server on (the default), Claude Code, Copilot, Codex, OpenCode and Grok (macOS, Linux) reach them through the shared host of the computer, each with its own session token; the other CLIs, Grok on Windows and remote SSH hosts keep their own processes. Codex runs from a generated home so its user-level config is untouched; Cursor needs the servers approved on the command line, which AgentsRoom does. The servers are run with the node found on the agents' PATH. Since 2026-09-28, when that node is missing or too old to run them (none of the agent CLIs needs Node.js, so many machines have none), AgentsRoom runs them on the Node.js engine built into the app instead: nothing to install, and machines where node works are left exactly as before. Remote SSH hosts still need their own Node.js. Some CLIs register the tools under a prefixed name (server name plus tool name); the agent's boot prompt tells it to call the exact name its tool list shows, and after a "tool not found" answer to retry once with the name that answer lists, then stop instead of looping. oh-my-pi on a Cursor model (Composer) is told to call the full prefixed name directly, since that is the only one it can reach. Master (development) agents do not receive the Browser server: browser testing is delegated to a QA agent through the QA test runner tool, which every agent may call after asking you.
Mobile
Not applicable: the servers run on the machine that hosts the agents. The phone drives agents through the desktop and sees the results (tickets, commands, messages) in its own screens.
One exception: the questions an agent waits on also appear on the phone, above the composer of the agent that asked: Create an agent? (agents_spawn, with the same provider, model, reasoning-effort and account choices and the same "don't ask again" boxes, tap Runs on to change them), Run this command? (commands_propose) and Allow a test tool?. The first answer wins, on either screen.
Limits
-
The shared tool server is a process of the desktop: it runs while AgentsRoom runs. If it cannot start or keeps crashing, new agents fall back to their own processes by themselves (the Settings row then says it is unavailable) and come back to it once it is up again. Agents already open keep the connection they started with. When the server restarts after a crash it comes back within seconds on the same port, and Claude Code reconnects by itself. Since 2026-10-29, when it stayed away longer than Claude Code keeps retrying (about 15 seconds), or came back on another port, AgentsRoom types
/mcp reconnect allin every open Claude Code console as soon as it is free (no turn running, no dialog, nothing typed by you), which only reconnects the servers that are down (Claude Code 2.1.284 or later). The other CLIs get the AgentsRoom tools back when they are restarted (tooling pill > Restart the agent). A CLI you start yourself in a terminal, outside AgentsRoom, has no session token: it gets the tools only after you exportAGENTSROOM_MCP_SESSIONwith the content ofmcp-host/machine-sessionin the AgentsRoom folder (~/.agentsroom/), and only while the desktop runs; otherwise switch the setting to Per agent. -
Agent consoles keep the shared tool server out of every proxy: with a proxy variable (
HTTP_PROXY,HTTPS_PROXYorALL_PROXY), AgentsRoom adds127.0.0.1to theirNO_PROXY; without one, it setsNO_PROXY=localhost,127.0.0.1,::1, because Codex also follows the proxy of your system settings and a shell profile can export a proxy later. An existingNO_PROXYis only extended. A request handed to a proxy, even a local one such as Clash, Karing or Surge, reaches the tool server from the proxy instead of from the agent's console, and is refused. Side effect: in a console whose only proxy is the system one, Python (requests,pip) no longer picks up that system proxy, since Python reads it only when no proxy variable exists. -
Tools that create or drive a console (
backlog_start_next,agents_spawn,agents_close,agents_delete,agents_restart,agents_recover,commands_run,commands_propose,ssh_connect) need the desktop running; reads of the backlog, memory and libraries work with it closed. -
backlog_start_nextstarts a ticket assigned to a saved agent from any computer of the account, not only the one where the project was created. When the machine has no saved agent for the project, it says so instead of failing silently. -
Cross-project access is read-only except
backlog_create({ project })and the executor re-assignmentbacklog_update({ project, taskId, teamId | agentId }). A ticket filed in another project can be assigned to one of THAT project's teams or saved agents (ids fromteams_list({ project })/agents_list({ project })), checked over there: an id from the current project, or a client-folder team, is refused. Skills and account profiles cannot be passed from one project to another. -
report_issueis rate limited (one per minute, three per hour, ten per day) and refuses without a signed-in email. -
No tool ever returns a credential;
db_queryrefuses writes whatever the connection allows a human. -
An agent cannot lift its own consent gates or its own telemetry switch.
-
The tools need a live sign-in on the desktop for everything stored in your account (backlog, memory, libraries). When that session is signed out or expired, the tools stop calling the server: since 2026-09-19, after one refusal they answer locally "the AgentsRoom desktop session on this machine is signed out or expired. Open the AgentsRoom desktop app and sign in again; no request was sent" until the desktop holds a fresh sign-in. No retry loop, no network traffic in the meantime.
-
Leave this project's .mcp.json untouched covers this computer's checkouts and their worktrees. An agent offloaded to a remote SSH host still gets the AgentsRoom entries written into the remote checkout's
.mcp.json; turn off the SSH connection's agent tools to keep that one untouched too. A.gitignoreline added before the switch was turned on stays: remove it yourself if you do not want it. -
On a remote SSH host, the AgentsRoom tools are installed for Claude Code and Codex only; over a password-authenticated connection with no open terminal tab on that host, they are not installed and the terminal says "password connection with no open session on this host, open a terminal tab on it first". The agent then runs without them.
-
A card that an agent files or moves (
backlog_create,backlog_update) shows on an open task board at its next refresh: when the board opens, and then every 30 seconds while it stays open. Nothing to reload by hand.
Common questions
-
The "Create an agent?" question keeps coming back even though I ticked the box. Why? The box named after an agent only exempts that agent, the one asking. If each task runs in a new agent, the next one asks again. To stop it for every agent, tick Stop asking for this project on the card, or turn off Ask before an agent creates an agent in Settings > Agent behavior. With no answer within 2 minutes, nothing is created.
-
Can my assistant open an existing folder as a project, rename a project or put projects into folders? Yes, on your request: ask it ("open ~/code/my-repo as a project", "rename Project to My Product", "put the client repos in a Clients folder"). It uses
projects_open,projects_renameandprojects_folders_apply, the same paths as the Open project dialog, the sidebar rename and a drag and drop. On its own idea it asks first, because each one changes your sidebar on all your computers. -
Can I switch off the AgentsRoom tools I do not use, to save context or because I run my own memory or backlog? Yes: Settings > AgentsRoom tools. A switched-off family or tool is not even listed to the agent and its instructions leave the startup prompt; a folder, a project or one agent can override each switch, and you can rewrite any tool's description. See AgentsRoom tools settings.
-
AgentsRoom is slow and I see dozens of
nodeprocesses for the MCP servers. Before 2026-10-19 every agent CLI started its own copy of each AgentsRoom server: four or five Node.js processes per console, about 140 MB each time, so 80 consoles meant more than 300 processes and around 11 GB. With Shared AgentsRoom tool server (Settings > Agent behavior, on by default) one process serves them all, about 1 MB per agent session. Restart the agents (or the app) so they pick it up. The agent CLIs themselves are not affected: each one keeps its own memory. -
My own
claudestarted in a terminal lost the AgentsRoom tools. It reads the project's.mcp.json, which now points at the shared tool server, and only consoles opened by AgentsRoom carry a session token. Addexport AGENTSROOM_MCP_SESSION="$(cat ~/.agentsroom/mcp-host/machine-session)"to your shell profile (the tools then work while the desktop runs), or switch Shared AgentsRoom tool server to Per agent. -
My agents lost the AgentsRoom tools behind a proxy (a company proxy, or Clash, Karing, Surge in system proxy mode). An agent CLI sends even local requests to the proxy unless
127.0.0.1is listed inNO_PROXY, and since 2026-10-26 the tool server refuses a request that a proxy relays: it only answers the processes of the agent's own console. Since 2026-10-27 AgentsRoom puts127.0.0.1in theNO_PROXYof every agent console, with or without a proxy variable; restart the agents so they pick it up. If a CLI still cannot reach the tools (your shell profile overwritesNO_PROXYwithout127.0.0.1, for instance), add127.0.0.1to it, or switch Shared AgentsRoom tool server to Per agent: each agent then starts its own processes, as before. -
AgentsRoom rewrites my project's
.mcp.json(or adds it to.gitignore) and breaks the servers my repository declares. Turn on Project settings > AI providers > Leave this project's .mcp.json untouched. AgentsRoom then removes only the entries it had added, never writes the file again, never adds it to.gitignore, and hands the AgentsRoom tools to Claude Code and Copilot through their launch command. Your own servers, including URLs with a query string that changes often, stay exactly as committed. Restart the agents that were running. -
All the AgentsRoom tools of an agent disconnected at once (ECONNRESET on 127.0.0.1) and only came back after
/mcp. The shared tool server restarted and stayed away longer than Claude Code keeps retrying (about 15 seconds): Claude Code then gives up for good, even once the server is back. Since 2026-10-29 the server restarts within 3 seconds, and when an outage still lasts longer AgentsRoom types/mcp reconnect allin each open Claude Code console once it is free. On an older Claude Code (before 2.1.284) or another CLI, type/mcpand reconnect, or restart the agent from its tooling pill. Since 2026-11-06 the server no longer closes a connection that sits idle while the model thinks, which removes one cause of these cuts, and an agent whose tool call was cut receives a message from AgentsRoom once its tools are back, naming the calls that were cut, so it picks its work up again. -
How do I go back to one process per agent? Settings > Agent behavior > Shared AgentsRoom tool server > Per agent (or only for one project, in its Project settings > AI providers). The agents launched afterwards use it.
-
Can an agent that spawned another agent know when it is done? Yes, since 2026-10-16. The agent that called
agents_spawnfollows its own runs withagents_spawned_list(all of them),agents_spawned_get(one) andagents_spawned_wait(blocks until a run is done, stopped on a question, ended or closed; 50 s by default, up to 10 min). Each run shows its state, its timestamps and what the agent reported (its title, its summary, the first line of its last answer). It then closes the run withagents_close, which frees its place under Max throwaway agents per project. An agent only sees the runs it spawned itself, andagents_closerefuses to close a run another agent spawned (only that agent or you can). Closed runs stay readable until the desktop restarts. -
Can I see which agent spawned which in the sidebar? Yes, since 2026-10-27, on the desktop and in the mobile app's agent list. An agent created by another agent (
agents_spawn), and a QA Bot started byrun_qa_test, sits right under the agent that launched it, shifted right with a branch line, and its own sub-agents one level deeper (up to three levels). In the Activity sort the whole family stays together and is filed in the section of its most urgent member: a worker that waits on you brings its orchestrator into Needs input with it. Pinning the top agent pins its family. In the Group sort, a child sits under its parent when both are in the same group. A fork is not a child: it is an independent agent and sorts on its own. -
A new agent or a team run keeps pulling me away from the agent I am typing in. Can I stop that? Since 2026-10-12 the app never switches agents while you are typing. To never be moved by a team run at all, turn off Bring agents started in the background to the front (Settings > Agent behavior, or per project in Project settings > Agents): its agents then start in the background and you open them from the sidebar. Agents created by another agent (
agents_spawn) or bybacklog_start_nextalready start in the background. -
Do I have to configure MCP servers? No. They are added to each agent at launch, in the format its CLI reads, without modifying your own MCP configuration.
-
My agent says it has no AgentsRoom tools. Ask it to call
capabilities_getwith topicruntime: it says which modules loaded and whether the desktop bridge is reachable. Aider has no MCP at all. -
On 1.185.0 no agent of mine had any AgentsRoom tool. A release accident: the tool server could not start at all, so every agent opened without it. Fixed in 1.185.1, and the build now refuses to publish a tool server that does not load, so the whole set can no longer disappear for everyone at once. Update the desktop.
-
Every AgentsRoom server shows "Failed to connect" or "Connection closed" and I do not have Node.js. Fixed on 2026-09-28: when
nodeis absent or unusable on the agents' PATH, the servers now run on the engine bundled with AgentsRoom. Update the desktop and restart the agents; no need to install Node.js. -
My oh-my-pi agent on a Cursor model loops on "tool not found". Fixed on 2026-09-28: the boot prompt now tells it to call the full tool name oh-my-pi exposes on Cursor models and to stop after one retry. Update the desktop and restart the agent.
-
My agent works in a git worktree and has none of the tools. Fixed on 2026-09-22 for Claude Code and Copilot, which only read the tool declaration of the folder they start in. Update the desktop; nothing to configure and nothing new is written into the worktree.
-
Every tool answers that the desktop session is signed out or expired. Your sign-in with agentsroom.dev has lapsed; the desktop shows the Session expired banner ("Sign in again to reconnect the app to your account."). Click Sign in in the desktop: the very next tool call goes through, nothing to restart on the agent's side. Until then the tools refuse locally instead of retrying against the server.
-
Can an agent change my settings? Yes, when you ask:
settings_setat global, project or agent scope, with validation. It cannot change its own agent configuration, its own consent gates or the telemetry switch. -
Why did the agent ask permission before spawning a colleague? That is the spawn gate. Turn it off in Settings > Agent behavior, or per project or per agent, for orchestration workflows.
-
Can a teammate's message interrupt an agent while it saves its context and restarts? Not once the agent has said it is handing off. Its routine calls
agents_restart_preparewhen the checkpoint begins (agents_restartdoes the same at the end): Agent Mail notices and scheduled prompts then stay out of that console. The messages stay stored and unread, keeping their id, thread and date. The new conversation takes up its checkpoint first, is told how many are unread, and gets the notices after its first turn. If the handoff is cancelled (cancel: true), or the restart is dropped, they go to the current conversation instead. The hold lifts by itself after 15 minutes, senders seehandingOffinagents_list_live, and your own messages are never held. -
Can an agent clear its own context and carry on without me typing
/clear? Yes, since 2026-10-02:agents_restart({ prompt }). Built for context checkpoint (handoff) routines: the agent saves its state to a file, calls the tool as the last step of its turn, and once that turn has ended its console restarts in the same tab on a new conversation whose first message is the prompt it wrote ("Read .handoff/latest.md and continue"). Same agent, CLI, model, account and permissions; nothing it did not write down survives. It only ever restarts the caller, never a colleague, and asks for no confirmation. To stop a routine that loops, it allows one restart every 2 minutes and 6 per hour per agent. It is refused for a step of a running Agent Team, for a QA run, and while the project's terminals are shown in another window (detached terminals or the project's own window); a restart whose turn has not ended 30 minutes later is dropped. Works with every CLI that has MCP. Since 2026-10-23 the call can also carry a smallmetadataobject (a handoff id, for example) and answers arestartId: AgentsRoom keeps its own receipt of the restart (old and new console, timestamps, status scheduled, started or failed), and the new conversation reads it withagents_restart_receipt, so a handoff routine adopts the right checkpoint without putting its id in the prompt or parsing each CLI's transcripts. Receipts stay in the desktop's memory until it quits. -
Can I set how hard a requested colleague thinks? Yes: the Create an agent? card has a reasoning-effort row in its Runs on block, next to the model. It only shows for the CLIs that have an effort lever, its tiers follow the selected model, and Default leaves the CLI on its own choice. The same row exists on the phone's card; the desktop must be up to date for the pick to apply.
-
An agent asked for a colleague while I was on my phone, and the request expired. Before 2026-09-26 the confirmation only showed in the agent's tab on the desktop, and a request nobody answers within 2 minutes creates nothing. Update the desktop and the mobile app: the Create an agent? card now shows on the phone too, in that agent's screen, like Run this command? and Allow a test tool?. If the computer goes to sleep while the card waits, the request is withdrawn (since 2026-11-09): the asking agent gets a clear answer saying the request was interrupted by sleep or expired, and is told to check
agents_spawned_listinstead of retrying on its own. -
An agent says "this project already has 8 throwaway agents running". That is the runaway guard of
agents_spawn, not a plan limit. Close a finished throwaway agent, or raise Max throwaway agents per project (1 to 32) in Settings > Agent behavior, or for one project in Project settings > Capabilities & permissions. -
Can agents use my SSH servers and databases? Yes, by reference:
ssh_execruns one command and returns the output,db_queryruns one read-only statement; the desktop injects the credential, the agent never sees it. -
Can an agent report a bug in AgentsRoom? Yes,
report_issuefiles it on the AgentsRoom public board, with a five-line diagnostic block unless you opted out of data sharing. With sharing off, agents are told before they draft (in the board list they check first) to keep the report text only: no screenshots and nothing from your work. -
Can my agents keep up with what changes in AgentsRoom? Yes, since 2026-10-20: ask an agent "what's new in AgentsRoom since my version?" or "is my bug fixed?". It reads the public changelog (
product_changelog) and the AgentsRoom feature/bug board (product_board_list/product_board_get), including your own reports and the version that carries each fix. Nothing is pushed into your agents: they read it when you ask, or when a routine you set up (a trigger, a start-of-session instruction) asks them to. -
The commit box already holds a message I did not type. The agent posted it through
git_set_commit_messageat the end of its turn; only its own pill is affected and nothing was committed. It stays until you commit: later calls from the agent only replace it when the work itself changed (a feature added, removed or reverted), so edit it by hand if it needs a fix, or turn off Agents write their own commit message in Settings > Git to go back to the classic prefill. A message you typed by hand is never replaced. -
My agent refuses to edit and cites a rule that needs tools I cannot find (for example
changes_list,changes_read,changes_editorALL_TOOLS). AgentsRoom has no such tools and never sends such a rule: it came from outside the app, usually a global instruction file of the agent's CLI (for Codex,~/.codex/AGENTS.mdordeveloper_instructionsin~/.codex/config.toml), a plugin, or text the agent read during the conversation. Restarting the tab does not clear it because the tab resumes the same conversation. Remove the rule at its source, then start a new conversation for that agent. Since 2026-10-28 agents are told not to stop over a rule that depends on a tool nobody advertises: they name where they read it and carry on. -
How do I let my agent keep my task board up to date? Ask it in plain words, in its message box: "fix this bug and track it on our task board: add a card, then move it to Done with a one-line summary". The agent files the card itself (
backlog_create), does the work, then moves the card and writes its summary in it (backlog_update). Ask it to go straight from To do to Done: a column that starts an agent (Development) would start a second agent on the card. The card shows on the open board at its next refresh. Video: https://youtu.be/mDeow0uNpyQ -
Is there a video that shows it? Yes, an agent keeping the task board up to date by itself, in the real app: https://youtu.be/mDeow0uNpyQ
Related
- Backlog Task Board: the board the
backlog_*tools drive. - Dev Terminals: the saved commands behind
commands_*. - Agent Messaging: Agent Mail in user terms.
- Agent Delegation: the QA test runner and the QA agent.
- SSH Connections and Database Connections: the connections exposed by reference.
- Multi-Provider Support: how each CLI receives the servers.
- Workspaces: what
workspace_createopens. - AgentsRoom Help: the assistant built on the
product_help_*tools. - AI Commit Messages: the commit box that
git_set_commit_messagepre-fills. - Agent Teams: the graph the
teams_*tools edit and the run-scoped team server. - Windows Connections (WinRM): the WinRM hosts reachable through
ssh_exec. - MCP Servers: your own MCP servers, handed to agents next to these.
- Remote SSH Offload: the same tools installed on the SSH host an agent is offloaded to.
- Git Worktrees: the isolated checkout an agent now keeps its tools in.