The Argus plugin

One install that connects an agent to Argus, both ways:

• It tells Argus what it is doing. When a turn starts, when it finishes (with its last words), and when it needs you — naming what it wants: "needs your permission to use Bash: rm -rf build". The desk tab's light, the bell on your phone and "working / waiting" come from the agent itself instead of from watching its screen.
• It can use Argus. The MCP tools: ask you something and wait for the tap on your phone, ring, see who else is working, relay to another session, start_agent (in its own worktree), read the teams and your prompts. See what that is good for.

What you can ask it

The whole list — what it does by itself, what it does on your tap, what it cannot do and why — is What an agent can do. The plugin's argus skill carries the same table, so the agent knows it without being told.

Say it in your own words to Claude or Codex; it picks the tool from what you asked.

You say	It does	Tool
"open a new desk called pippo"	the tab appears in your browser and switches to it	open_desk
"rename the desk Desk 11 to Pippo"	renamed on the machine and on every open page	rename_desk
"rename the desk appropriately"	the desk the agent is in, with a name it chose	rename_desk without desk
"open a Claude and a Codex in pippo, in ~/work/parser"	two sessions start, their windows land in that desk	start_agent (desk)
"start a Codex reviewer on branch fix-42 with this brief…"	a new session in its own git worktree, prompt sent	start_agent (worktree_branch, prompt)
"start Claude with sonnet, allowed to edit files"	the flags come from the agent's own --help	launchers, start_agent (options)
"work on to-do #3 and mark it done when you have"	marks #3 doing, works on it, marks it done; the To do screen shows "by" its session	todos, todo_set
"add a to-do to check the CI later"	a new line on your list, with the next number	todo_add
"who else is working here?"	every session, its agent, folder, working or waiting	who
"tell the reviewer the diff is ready"	the sentence typed into that session	relay
"ask me before you delete anything"	the question on your phone with buttons; it waits for the tap	ask
"ring me when you're done"	one bell, with what happened	ring
"how is the team doing?"	round, whose turn, the last check	teams
(in a team, by itself) "what is my task?" / "I'm done"	reads its task; reports its turn with a summary and a verdict	team_task, team_done
"make me a team that speeds up the parser, with a reviewer"	writes the team, checks it, writes it as team.yaml and rings you — you start it	team_check, team_propose
"use my Referee prompt"	your prompt library, read from Argus	prompts
"make me a worktree on branch x"	a second checkout, inside the folders Argus serves	worktree

And without being asked, through the hooks: it tells Argus when a turn starts, when it ends (with its last words) and when it is waiting for you (naming what it wants to run) — the lights on the desk tabs and the bells come from there.

In a team the plugin does three more things, so an agent takes part without being taught the protocol in every prompt: the argus-team skill (the protocol in one page: read your task, do one turn, report it, stop), the tools team_task and team_done, and the Stop guard — an agent that tries to stop with its turn unreported is sent back to report it, twice at most. See Teams.

Designing a team is the other skill, argus-team-author: the team language (Mermaid and YAML), the rules Argus checks and what makes a good team, with examples — so "make me a team that…" works without pasting the documentation. With team_check and team_propose the agent writes it, checks it and leaves it for you to start. See Asking an agent to design one.

With your OK — the tool request: what its key cannot do (start a team in a desk, continue or stop one, end or rename a session, start an agent with no questions, remove a worktree, delete a to-do) it asks for; you get Do it / No, and on Do it Argus does it. "Start the team Kraken paper in the desk Trading" works this way.

What it cannot do, on purpose: answer a question meant for you, remove a desk or anything in it, delete files through Argus. And by itself — without your tap on a request — start an agent that asks nobody anything, or start, pause or stop a team.

Argus must be running on the same machine; the plugin finds it through ~/.config/argus/config.yaml, as argus-say does.

Installing it

From Argus, with a press. Settings → Interruptions has a row per agent on the machine: The Argus plugin in Claude Code — not installed [Install], or 0.1.3 — 0.1.5 is out [Update]. The button runs the agent's own plugin commands for you. When the agent has no marketplace called argus yet, it uses your Argus checkout as the marketplace, so the plugin always matches the server that offers it: pull Argus, press Update, and the two move together.

By hand, from the agent. Claude Code:

/plugin marketplace add andreaderuvo/argus
/plugin install argus@argus

Codex (0.160 or later) reads the same plugin:

codex plugin marketplace add andreaderuvo/argus
codex plugin add argus@argus

Codex then asks you once, at its next start, to review the plugin's hooks; until you do, they do not run. Its MCP calls ask for approval the first time, as any tool does.

Gemini CLI gets the tools as an extension (plugin/gemini-extension.json); its hooks come from Settings → Interruptions → Let your agents ring in Argus.

Updating it

You are told when it is time:

• in Argus, once per version, a dialog: which agent has an older plugin, Update (or Update all), and then, in the same dialog, Reload in N waiting for the sessions already open. Later keeps quiet until the next version; Alt+V shows the same at any time;
• in the agent, at the start of each session: the plugin's SessionStart hook asks Argus for the version it offers and, when it is newer, Claude shows "Argus plugin 0.1.5 is available…" at the top of the session. It says nothing when Argus is not there or is up to date.

Each window says when its session is behind. The plugin's hooks tell Argus which plugin version their session runs (at session start, and with every bell), so a terminal window whose agent still runs an older one shows plugin 0.1.4 — reload (Claude: one press types /reload-plugins, only if the session sits at its prompt) or plugin 0.1.4 — restart (Codex, which has no reload and takes the plugin when the session starts again). A session that never said is not guessed about.

After an update, sessions already open still run the old plugin until they reload. Argus offers Reload in N waiting: it types /reload-plugins into the Claude sessions sitting at their prompt — the ones whose last word was done. Never into one that is working, and never into one that is asking you something, where an Enter would answer the question. The others take the new plugin when you reload them by hand or open a new session.

An agent can do it too, through request: update_plugin (agent: claude or codex) is asked first, like any change to an agent's configuration; reload_plugins is never asked, since it only makes the sessions at their prompt run the plugin already installed.

By hand:

/plugin marketplace update argus
/plugin update argus@argus
/reload-plugins

An agent refreshes an installed plugin only when its version changes; the repository's tests keep the version moving with the content (on 2026-10-06 a tool added under the same version never reached anyone who updated). A new tool is there after /reload-plugins, or in a new session.

The plugin or the switch?

Either. Let your agents ring writes the same hooks into the agent's own settings, from Argus; the plugin brings them from the agent's side, with the MCP tools as well, and updates with /plugin update. Settings shows "the Argus plugin" for an agent that has it. Having both does no harm: the two rings of one turn are folded into one.

What it is made of

plugin/ in the repository:

• .claude-plugin/plugin.json — the name and the version;
• hooks/hooks.json — UserPromptSubmit → argus-bell start, Notification and PermissionRequest → argus-bell asking, Stop → argus-stop (the team guard; otherwise it rings as argus-bell done), SessionStart → argus-check (says which plugin version the session runs, and whether a newer is out);
• .mcp.json — the argus-mcp server;
• skills/argus/ (what the agent can do in Argus, and what it requests), skills/argus-team/ (working in a team), skills/argus-team-author/ (writing one — its examples are checked by the tests);
• gemini-extension.json — the MCP tools for Gemini CLI (no hooks, no skills there);
• bin/ — argus-bell, argus-stop, argus-check, argus-mcp, and copies of argus_client.py and argus_mcp.py, kept identical to tools/ by the tests.

Where it finds Argus: ~/.config/argus/config.yaml — its listen port and, when tls_cert is set, https; the hooks sign with the config's token:, the MCP server prefers an agents: key (on loopback, without checking the certificate, which names the public host). Before 0.1.7 the hooks assumed http://127.0.0.1:8090, and an Argus on another port or on https never heard a single ring: update the plugin. The repository root is the marketplace (.claude-plugin/marketplace.json).

One detail that cost a probe: Codex expands ${CLAUDE_PLUGIN_ROOT} in hooks but not in an MCP command, so the MCP command is a small sh -c that uses it when it is there and otherwise finds the copy Codex installed under ~/.codex/plugins/cache/argus/argus/.