Skip to content
Back to search

agentrq

MarketplaceWorks with Claude CodeGitHub

Task manager for AI agents. Orchestrate multiple agents, trigger agentic flows with events on your desired language.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/agentrq/agentrq with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/agentrq/agentrq'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agentrq--agentrq/badge.svg)](/listings/agentrq--agentrq)

HTML

<a href="/listings/agentrq--agentrq"><img src="/api/listings/agentrq--agentrq/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- **Go** 1.27.1+ - **Node.js** 18+ (with npm) - **OpenSSL** if `make dev` needs to generate a local JWT secret - **Google Cloud Console**: An OAuth2 Client ID and Secret.

Configuration

1. Edit `backend/cmd/server/_config/base.yaml` (or `development.yaml`). 2. Fill in your Google OAuth2 credentials:

auth:
  google:
    clientId: "your-google-client-id"
    clientSecret: "your-google-client-secret"

3. Set `AGENTRQ_AUTH_JWT_SECRET` to a stable random value (at least 32 characters) when starting the backend directly. In the default development mode, `make dev` generates and reuses a local value if the variable is absent.

Running Locally

Use the provided `Makefile` to start the full stack:

# 1. Install all dependencies
make install

# 2. Start both Frontend and Backend
make dev

The frontend will be available at `http://localhost:5173`. For the desktop app, run `make desktop-dev` in another terminal — see the [Desktop Guide](docs/DESKTOP.md).

Self-Hosting (Docker)

For running the production or development stack using the pre-built Docker image, see the [Self-Hosting Setup Guide](SETUP.md).

> [!NOTE] > **Agents / AI Assistants:** If you need to set up, configure, run, or diagnose a local self-hosted instance of AgentRQ using Docker, refer to [SETUP.md](SETUP.md) for step-by-step instructions, Docker run commands, and environment variable configurations.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 40 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "agentrq",
  3. "description": "Task manager for AI agents. Orchestrate multiple agents, trigger agentic flows with events on your desired language.",
  4. "owner": {
  5. "name": "AgentRQ",
  6. "email": "hi@agentrq.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "agentrq",
  11. "source": "./plugins/claude/agentrq",
  12. "description": "Human-in-the-loop agent orchestration for managing multiple agents with specialized tasks.",
  13. "author": {
  14. "name": "Mustafa Turan",
  15. "email": "dev@agentrq.com",
  16. "url": "https://github.com/mustafaturan"
  17. }
  18. },
  19. {
  20. "name": "agentrq-custom-supervisor",
  21. "source": "./plugins/claude/agentrq-custom-supervisor",
  22. "description": "Human-in-the-loop agent orchestration for a self-hosted AgentRQ server: the supervisor plugin, pointed at your own server's URL.",
  23. "author": {
  24. "name": "Mustafa Turan",
  25. "email": "dev@agentrq.com",
  26. "url": "https://github.com/mustafaturan"
  27. }
  28. },
  29. {
  30. "name": "agentrq-workspace",
  31. "source": "./plugins/claude/agentrq-workspace",
  32. "description": "Human-in-the-loop task manager for AI agents",
  33. "author": {
  34. "name": "Mustafa Turan",
  35. "email": "dev@agentrq.com",
  36. "url": "https://github.com/mustafaturan"
  37. }
  38. }
  39. ]
  40. }
README.md · README · 696 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # AgentRQ ── Agent-Human Collaboration Platform
  2. <p align="center">
  3. <a href="README.zh-CN.md">简体中文</a>
  4. <br />
  5. <br />
  6. <a href="https://chromewebstore.google.com/detail/agentrq/iadkenmjgjoilnioldgchgjpdnbaghbj">
  7. <img src="https://img.shields.io/badge/Chrome%20Web%20Store-Add%20to%20Chrome-4285F4?style=for-the-badge&logo=googlechrome&logoColor=white" alt="Chrome Web Store" />
  8. </a>
  9. </p>
  10. AgentRQ is a modern, high-performance platform designed for seamless collaboration between human operators and AI agents. It leverages the **Model Context Protocol (MCP)** to allow AI models (like Claude) to interact directly with your workspace's task management system.
  11. ## 🚀 Overview
  12. Think of AgentRQ as a shared workspace where humans and AI agents work together seamlessly. You can break down complex goals into manageable tasks, and delegate work directly to your AI agents.
  13. Because agents "see" the workspace state via MCP, they can autonomously pull their assigned tasks, update statuses, request permissions for sensitive actions, and communicate with you—all synchronized instantly across the platform in real-time.
  14. <p align="center">
  15. <img src="docs/assets/readme/task-board.svg" width="1200" alt="AgentRQ task board: you add five tasks and five agents, claude, codex, agy, hermes and openclaw, each pick up their own. Cards move from Not Started to Ongoing; codex asks a question and its card turns Blocked until you click Allow; then every card lands in Done and the agents celebrate." />
  16. </p>
  17. ## ✨ Features
  18. Animated sketches of the main features.
  19. <table>
  20. <tr>
  21. <td colspan="2" valign="middle">
  22. ### Visual Task Board
  23. Every task Claude creates appears instantly on your board. See what it's working on, what it needs, and what it just finished — all from a clean, fast dashboard you can open on any device, as a list or a Kanban.
  24. </td>
  25. </tr>
  26. <tr>
  27. <td colspan="2" valign="middle">
  28. ### Task Scheduling
  29. Give any task a launch date, or a recurring cadence — every 15 minutes, hourly, daily, weekly, custom days. A background poller ticks every minute and spawns the task the instant it's due, no server or agent needing to stay awake and wait.
  30. <img src="docs/assets/readme/task-scheduling.svg" width="1200" alt="AgentRQ task scheduling: you give a task a cadence, every 15 minutes, and click Save. A poller ticks every minute while five agents, claude, codex, agy, hermes and openclaw, sleep; when a scheduled task comes due its row flashes and a run flies down to its agent, which wakes, works and finishes, and the next run rolls forward." />
  31. </td>
  32. </tr>
  33. <tr>
  34. <td width="50%" valign="middle">
  35. ### Events
  36. Events are named signals — `qa_passed`, `deploy_finished`, `blog_published` — that any task can fire when it completes. Wire one to a workspace and that workspace gets a new task automatically, no polling and no glue code. Outside services fire them too: point a GitHub webhook, or any `curl`, at a hook URL, and a failed CI run becomes a task. [How hooks work →](docs/HOOKS.md)
  37. </td>
  38. <td width="50%" valign="middle">
  39. ### Workflows
  40. A Workflow is Events and workspaces arranged on a graph. Drag a workspace onto an event to subscribe it; drag an event onto a workspace to emit it on completion. No decision-tree DSL, no YAML — just the shape of your release process, visible.
  41. </td>
  42. </tr>
  43. <tr>
  44. <td colspan="2"><img src="docs/assets/readme/events-workflows.svg" width="1200" alt="AgentRQ workflows: you drag the release workspace onto the deploy_finished event. claude finishes the qa task, so qa_passed fires and a pulse runs into deploy, which gets a new task; codex deploys, deploy_finished fires and release gets its task; hermes writes the release notes and claude, codex and hermes celebrate." /></td>
  45. </tr>
  46. <tr>
  47. <td colspan="2" valign="middle">
  48. ### Tool Call History
  49. The task detail view's History tab lays out a lane-grouped timeline of every tool call and message in a run — Input, Agent, and Tools. Search it, click into any entry, and see exactly what ran, what it returned, and whether it was allowed or denied.
  50. <img src="docs/assets/readme/tool-call-history.svg" width="1200" alt="AgentRQ tool call history: a task's Trajectory view lays out the run on three lanes, Input, Agent and Tools. claude reads, greps and edits; a Bash call waits for you and you deny it, so it turns red; claude tries another way and npm test passes. You open that call to see what ran and what it returned, then search for bash and only the two Bash calls stay lit, while the agents celebrate." />
  51. </td>
  52. </tr>
  53. <tr>
  54. <td colspan="2" valign="middle">
  55. ### YOLO Mode
  56. Flip **YOLO** on a task and every permission request its agent sends from then on is allowed automatically: no waiting on you, and each call is still recorded in the task's history as auto-allowed. Turn it off and approvals come back. A workspace can turn it on for every task its agent creates, and an event trigger or a workflow step can create its tasks with it on.
  57. <img src="docs/assets/readme/yolo-mode.svg" width="1200" alt="AgentRQ YOLO mode: claude asks to run go test and waits, so you flip the task's YOLO toggle instead of answering. That call and every one after it is auto-allowed, edits and test runs land in the Trajectory view without a single wait, and 48 tests pass. You open the last call to see it was auto-allowed, turn YOLO off again, and the agents celebrate." />
  58. </td>
  59. </tr>
  60. <tr>
  61. <td colspan="2" valign="middle">
  62. ### Task Timeline
  63. Under every task, a timeline shows each status it has been in and for how long: a dot per change, with the time spent on the line to the next, stretches waiting on you in yellow and blocked ones in red. Above it, the totals say which agent worked on it and for how long, how long it was blocked or waited for your input, and how long it took from start to close. Every status change is recorded with the task itself, so nothing moves without leaving a dot.
  64. <img src="docs/assets/readme/task-timeline.svg" width="1200" alt="AgentRQ task timeline: under a task, a dot lands for every status it enters, with the time spent on the line to the next. claude picks up Migrate users table, waits on you to allow a command (a yellow needs-input stretch), later is blocked until you reply (a red stretch), and completes it; the totals read claude-code worked 14m, blocked 3m, needs input 2m, start to close 19m, and claude celebrates." />
  65. </td>
  66. </tr>
  67. <tr>
  68. <td colspan="2" valign="middle">
  69. ### Speech-to-Text
  70. Click the mic on any task description or reply and dictate it instead. Transcription runs on an in-browser Whisper model — your voice is processed on-device and never uploaded anywhere.
  71. <img src="docs/assets/readme/speech-to-text.svg" width="1200" alt="AgentRQ speech-to-text: you click the mic on the New Task form and say 'Add a dark mode toggle to settings'. The first time, a Whisper model downloads into the browser; it turns your voice into text on the device, uploading nothing, and the text lands in the description. agy takes the task, asks a question, you dictate the reply, agy finishes and the agents celebrate." />
  72. </td>
  73. </tr>
  74. <tr>
  75. <td colspan="2" valign="middle">
  76. ### Message Send Delay
  77. Give a workspace a countdown — 3s, 5s, 10s, 15s, 30s or 60s — and every chat message waits that long in the thread before it reaches the agent. **Send Now** delivers it early, **Cancel** pulls it back unsent and puts the exact text and attachments back in your composer. Off by default, per workspace.
  78. <img src="docs/assets/readme/message-send-delay.svg" width="1200" alt="AgentRQ message send delay: you type 'deploy to prod' and send it, and it waits in the thread with a 5 second countdown and Cancel and Send Now buttons while codex has not seen it yet. At 3 you click Cancel and the text comes back to the composer; you change it to 'deploy to staging', send it, and click Send Now, so codex gets it, deploys, and the agents celebrate." />
  79. </td>
  80. </tr>
  81. <tr>
  82. <td colspan="2" valign="middle">
  83. ### Search & Keyboard Shortcuts
  84. <kbd>⌘K</kbd> (<kbd>Ctrl+K</kbd> off macOS) opens a task finder that matches any word in a title or description, straight from the copy your device already saved — so it answers offline, and tells you how far it looked. Everything else is a bare letter: <kbd>N</kbd> for a new task, <kbd>W</kbd> and <kbd>M</kbd> to jump to a workspace or a machine, <kbd>P</kbd> for the Pano, <kbd>C</kbd> and <kbd>T</kbd> to flip between a task's chat and its trajectory, <kbd>?</kbd> for the list. Nothing to configure, and nothing to memorise.
  85. <img src="docs/assets/readme/search-keyboard-shortcuts.svg" width="1200" alt="AgentRQ search and keyboard shortcuts: claude has a question on a task you cannot see in a busy workspace, so you press ⌘K and type 'migration'. The finder narrows the tasks saved on this device to 'Run the users migration' without asking the server; Enter opens it and C flips to the chat, where you answer and claude finishes. Then W, P and ? bring up the workspace switcher, the Pano and the keyboard shortcuts sheet while the agents celebrate." />
  86. </td>
  87. </tr>
  88. <tr>
  89. <td colspan="2" valign="middle">
  90. ### Machines
  91. Install `agentrqd` on a computer you own, enrol it once with a single-use code typed on the machine itself, and it becomes somewhere agents can run — in your repositories, with your toolchain. Pick a workspace and what to run, and it starts in that workspace's folder on that machine. Each machine's page shows what it has left: CPU, memory, uptime, load and free space per filesystem.
  92. <img src="docs/assets/readme/machines.svg" width="1200" alt="AgentRQ machines: you click Add machine and get a single-use code, and typing it on your own computer enrols it, so dev-box comes online. You pick the agentrq-web workspace and Start agent, and claude starts in that workspace's folder on the machine, straight into its terminal. Back on the machine page one session is running, and Machine Info shows CPU, memory and load climb while claude works and fall when it is done, and claude celebrates." />
  93. </td>
  94. </tr>
  95. <tr>
  96. <td colspan="2" valign="middle">
  97. ### Live Terminals
  98. Open a running session from any browser and you are at the prompt. Keystrokes go straight through as the bytes your keys produced — <kbd>Esc</kbd> and <kbd>Ctrl-C</kbd> included — resizing reflows the program on the far end, and the session keeps running whether or not anybody is watching. Drop the network and the screen is still there when you come back.
  99. <img src="docs/assets/readme/live-terminals.svg" width="1200" alt="AgentRQ live terminals: on the machine page you open claude's running session and you are at its prompt in the browser. You answer y, then press Esc when claude takes a wrong turn and type a new instruction, every key going down the wire to the machine. The network drops and you close the tab, but on the machine claude keeps working; when you come back the screen is restored and has moved on, claude finishes, hermes opens the same session, and the agents celebrate." />
  100. </td>
  101. </tr>
  102. <tr>
  103. <td colspan="2" valign="middle">
  104. ### Skills
  105. Give a workspace's agents the playbooks your team already follows. A skill is a `SKILL.md` plus the files it points to, in the same format Claude Code uses. Paste a public GitHub link, such as [obra/superpowers](https://github.com/obra/superpowers), and every skill in it is imported. Write your own, or let an agent save one. Skills belong to your account: turn each one on in the workspaces that need it, and they all read the same copy, so an edit reaches every one of them. Every agent that connects to the workspace is told to search its skills at the start of a task and load the ones that match, over MCP, whatever harness it runs in. [How skills work →](docs/SKILLS.md)
  106. <img src="docs/assets/readme/skills.svg" width="1200" alt="AgentRQ skills: you paste a GitHub link and import three skills, tdd, code-review and release, then turn them on in the api, web and docs workspaces. Each agent, claude, codex and agy, gets a task, finds the skill that matches and loads it; you edit code-review and the one copy updates in every workspace, and the agents finish and celebrate." />
  107. </td>
  108. </tr>
  109. <tr>
  110. <td colspan="2" valign="middle">
  111. ### Pano
  112. A board of markdown docs that every workspace of your account shares. An agent posts a plan, a report or a chart, and hands its id to the agents in other workspaces that need it. They read it, comment on it and attach files. You see every doc as a post-it, edit it, comment on it, or write your own and turn it into a task. Each doc lives 30 days from its last save unless the agent asks for longer. [How the Pano works →](docs/PANO.md)
  113. <img src="docs/assets/readme/pano.svg" width="1200" alt="AgentRQ Pano: claude posts a Release plan on the board every workspace shares, with a checklist assigned to agy, codex and openclaw, and hands its id to them. They read it and comment, and each item ticks itself as its task finishes until it reads 3 of 3 done; then you write a note of your own, turn it into a task for hermes, and everyone celebrates." />
  114. </td>
  115. </tr>
  116. <tr>
  117. <td colspan="2" valign="middle">
  118. ### Isolated Workspaces
  119. Each workspace is its own world: one project or mission, with its own MCP server address and token, its own task queue, memory and settings — which commands are auto-allowed, how long a message waits before it is sent — and its own folder on every machine that runs it. An agent connects with one workspace's token and sees that workspace alone: its tasks, its memory, its permission requests. Nothing crosses between workspaces by accident; when work should cross, it does so on purpose, through a Pano doc, an event, or the supervisor workspace.
  120. <img src="docs/assets/readme/isolated-workspaces.svg" width="1200" alt="AgentRQ isolated workspaces: api, web and docs each have their own MCP server and token, folder, tasks, memory and settings. claude, codex and agy connect with their own workspace's token and take only its tasks; codex saves a memory and it lands in web alone, and codex sees web and nothing else. agy asks to push in docs and you allow it there, then all six tasks are done and the agents celebrate." />
  121. </td>
  122. </tr>
  123. <tr>
  124. <td colspan="2" valign="middle">
  125. ### Workspace Forks
  126. Fork a workspace to have a second agent take some of its tasks in parallel. Right-click it in the sidebar to fork it, or choose **Spin up** on a task, which forks the workspace, moves the task in and launches an agent in one step. The fork has its own queue and agent. It shares the parent's memory, skills and settings, and runs in its own git worktree or copy of the parent's folder. When its tasks are done, merge it back: its agent is stopped and every task returns to the parent with its thread. [How forks work →](docs/FORKS.md)
  127. <img src="docs/assets/readme/workspace-forks.svg" width="1200" alt="AgentRQ workspace forks: claude has six tasks in the api workspace, so you fork it into api-fork and move three tasks there. codex works the fork while claude works api, both sharing the same memory, skills and settings; when the fork's tasks are done you merge it back, its three tasks return to api with their threads, and the agents celebrate." />
  128. </td>
  129. </tr>
  130. </table>
  131. See the full list at [agentrq.com/features](https://agentrq.com/features).
  132. ## 🏛 Architecture
  133. AgentRQ follows a decoupled service-oriented architecture:
  134. ### Backend (Go / Fiber)
  135. - **API Server**: Fiber-based REST API for workspace and task management.
  136. - **MCP Server**: Integrated `mcp-go` SSE server that exposes tools and resources to AI models.
  137. - **CoreMCP (Supervisor)**: A global MCP server that allows agents to manage all workspaces, tasks, and statistics across the entire platform.
  138. - **Data Layer**: GORM with SQLite for persistent, user-scoped storage.
  139. - **Authentication**: Google OAuth2 integration with JWT-based session management.
  140. - **Event Bus**: Internal pub/sub system for real-time SSE notifications.
  141. ### Frontend (Vue.js 3 / Vite)
  142. - **Modern UI**: Tailored with Vue 3, Pinia, and Tailwind CSS.
  143. - **Glassmorphism**: A sleek, premium design language with smooth transitions and real-time updates.
  144. - **Reactive State**: Synchronized with the backend via SSE events.
  145. ### Desktop (Electron)
  146. - **Same application, native shell**: the desktop app renders the *same* Vue components as the browser, so the two never diverge.
  147. - **Native notifications**: agent activity reaches you while the window is in the background, with a dock or taskbar badge.
  148. - **Tray, global shortcut, deep links**: `Cmd/Ctrl+Shift+N` from anywhere, and `agentrq://` URLs that open the app at a specific task.
  149. - **Auto-updating**: checks in the background and installs on restart.
  150. ## 💻 Desktop App
  151. AgentRQ has a desktop app for macOS, Windows and Linux. It is a client — it
  152. connects to whichever AgentRQ server you run.
  153. On macOS and Linux, one command installs it — and updates it later:
  154. ```sh
  155. curl -fsSL https://agentrq.com/install.sh | sh -s -- --quit
  156. ```
  157. Or **[download the latest release →](https://github.com/agentrq/agentrq/releases/latest)**
  158. | Platform | Download |
  159. |---|---|
  160. | macOS | `.dmg` — Apple silicon and Intel |
  161. | Windows | `.exe` installer — x64 and arm64 |
  162. | Linux | `.AppImage` or `.deb` — x64 and arm64 |
  163. | Tauri build (preview) | `.dmg`, `.exe`, `.AppImage`, or `.deb` (`AgentRQ-Tauri-` assets, or `install.sh --tauri`) — see [Preview: Tauri build](docs/DESKTOP.md#preview-tauri-build) |
  164. Builds are currently **unsigned**, so a hand-downloaded build warns on first
  165. launch on macOS and Windows, and macOS cannot auto-update until signing
  166. certificates are in place — the install command above is the way around both.
  167. Connecting to a server and troubleshooting are covered in the
  168. [Desktop Guide](docs/DESKTOP.md).
  169. ## Extending the desktop app
  170. Extensions add pages, actions, keyboard shortcuts and scheduled work. They are
  171. ordinary Node modules, discovered from GitHub repositories carrying the
  172. `agentrq-extension` topic, and installed from the desktop app.
  173. **Extensions are desktop-only, and deliberately so.** An extension is code
  174. somebody else wrote, running with the privileges of the process it is in. On a
  175. self-hosted server that would mean a stranger's code next to your database and
  176. your other users; on the desktop it runs on the machine of the person who chose
  177. to install it. The server never loads extension code.
  178. What AgentRQ does enforce is everything it owns: which surfaces an extension can
  179. contribute to, and which MCP tools it may call against which workspaces — the
  180. extension never holds a credential, it asks, and the app attaches the token on
  181. the way out. That is a real boundary around your AgentRQ data. It is not a
  182. sandbox around your machine, and the install screen says so on every install.
  183. Three worked examples live in [`examples/extensions/`](examples/extensions/),
  184. from one that asks for no permissions at all to one that runs a daily digest
  185. across every workspace. See the [Extensions Guide](docs/EXTENSIONS.md).
  186. ## 🧭 Chrome Extension
  187. **[Add AgentRQ to Chrome →](https://chromewebstore.google.com/detail/agentrq/iadkenmjgjoilnioldgchgjpdnbaghbj)**
  188. AgentRQ lives in your browser's toolbar: open your workspaces in a popup, or full
  189. size in a tab.
  190. - **Bridge any WebMCP site into your agents.** When a website offers tools
  191. through [WebMCP](https://github.com/webmachinelearning/webmcp), the toolbar
  192. icon lights up; share the site with a workspace and its agents can call those
  193. tools in your own signed-in Chrome. A tool the site does not mark read-only
  194. waits for your approval in the task first.
  195. - **Your agents' terminals, right inside your browser.** Open the live terminal
  196. of a Claude Code, Codex or Antigravity session running on one of your
  197. [machines](#machines) and work in it without leaving the tab you are in.
  198. Installing from source and self-hosted servers are covered in the
  199. [extension's README](plugins/chrome/README.md).
  200. ## Driving AgentRQ from a browser agent
  201. If your browser supports [WebMCP](https://github.com/webmachinelearning/webmcp),
  202. an AI agent you talk to there can use AgentRQ directly — list your workspaces,
  203. open a task, reply in it, build a workflow. Everything the interface can do is
  204. offered as a tool, including asking which page you are on, so "reply to this
  205. task" resolves to the task you have open.
  206. The tools run in the page as you, with your session, so an agent gets exactly
  207. your permissions and nothing more, and they are withdrawn when you sign out.
  208. Nothing to install or configure; a browser without WebMCP simply sees no tools.
  209. See the [WebMCP Guide](docs/WEBMCP.md).
  210. ## Driving AgentRQ from the command line
  211. Inside a workspace directory — one with the `.mcp.json` an agent works from —
  212. the same capabilities are a shell command away:
  213. ```bash
  214. npx -y @agentrq/agentrq-ws@latest help
  215. ```
  216. It reads that `.mcp.json`, so there is nothing to configure, and it covers every
  217. workspace tool: read and create tasks, reply, publish events, read and write the
  218. workspace memory, ask a human a question. Attachments are plain file paths in
  219. both directions — `--attach ./run.log` to send one, and a download writes the
  220. file and prints where it went. See
  221. [cli/agentrq-ws](cli/agentrq-ws/README.md).
  222. ### 🖥️ Your own machines
  223. Install `agentrqd` on a computer, enrol it once, and you can start an agent for
  224. a workspace on it from the control panel — then watch its terminal and type into
  225. it, `Esc` included. The machines page shows what each box has left: memory, CPU
  226. and free space per filesystem, so you can tell whether it can take another
  227. agent.
  228. On Linux and macOS:
  229. ```bash
  230. curl -fsSL https://agentrq.com/install-agentrqd.sh | sh
  231. ```
  232. On Windows (PowerShell):
  233. ```powershell
  234. irm https://agentrq.com/install-agentrqd.ps1 | iex
  235. ```
  236. Either one picks the right build, **verifies it against the checksums
  237. published with the release**, and puts it on your `PATH`; running it again
  238. updates in place. It installs only — enrolling stays a separate, deliberate
  239. step, and it never runs as root or Administrator. Manual installs are on the
  240. [releases page](https://github.com/agentrq/agentrq/releases/latest)
  241. — one static binary for Linux, macOS and Windows.
  242. Then **Machines → Add machine** gives you a code to enrol it with.
  243. Enrolling a machine is a real grant, and the [Daemon
  244. Guide](docs/DAEMON.md) says so plainly: it lets anyone who can authenticate as
  245. that account run commands on the machine as the user who started the daemon.
  246. Read it before you enrol anything. It also covers the local kill switch, which
  247. works without the server's cooperation, and what the audit trail records —
  248. starts, kills and attaches, never keystrokes.
  249. ### ⌨️ Agent slash commands
  250. Agents connected through the ACP gateway advertise commands of their own —
  251. `/init`, `/compact`, `/review`, whatever they ship with. Type `/` in a task and
  252. they appear above the reply box, filtered as you type and chosen with the
  253. keyboard or the mouse. The list comes from the agent and follows it live, so it
  254. changes as the agent's context does. An agent that advertises none gets no menu
  255. and nothing changes. See the [Slash Commands Guide](docs/SLASH_COMMANDS.md).
  256. ### 🧠 Choosing the agent's model
  257. Where an agent offers a choice of model, you can make it from the interface —
  258. on a workspace card, and on the form where a task is written, so the model is
  259. settled before the work starts rather than after. Choosing shows the new model
  260. straight away but marks it as asked-for until the agent itself confirms; if it
  261. refuses, or never answers, the interface goes back to what is actually running
  262. and says so.
  263. The choice appears only where it would do something. An agent that reports no
  264. models — Claude Code connected directly, among others — shows none, and neither
  265. does an ACP gateway older than the release that learned to switch on request:
  266. it says which model it is on without claiming it can change it. Nothing to
  267. configure either way.
  268. To run it from source:
  269. ```bash
  270. make install # dependencies for the whole repo
  271. make desktop-dev # run the desktop app against a local server
  272. make desktop # build installers into desktop/release/
  273. ```
  274. ## 🛠 Getting Started
  275. ### Prerequisites
  276. - **Go** 1.27.1+
  277. - **Node.js** 18+ (with npm)
  278. - **OpenSSL** if `make dev` needs to generate a local JWT secret
  279. - **Google Cloud Console**: An OAuth2 Client ID and Secret.
  280. ### Configuration
  281. 1. Edit `backend/cmd/server/_config/base.yaml` (or `development.yaml`).
  282. 2. Fill in your Google OAuth2 credentials:
  283. ```yaml
  284. auth:
  285. google:
  286. clientId: "your-google-client-id"
  287. clientSecret: "your-google-client-secret"
  288. ```
  289. 3. Set `AGENTRQ_AUTH_JWT_SECRET` to a stable random value (at least 32 characters) when starting the backend directly. In the default development mode, `make dev` generates and reuses a local value if the variable is absent.
  290. ### Running Locally
  291. Use the provided `Makefile` to start the full stack:
  292. ```bash
  293. # 1. Install all dependencies
  294. make install
  295. # 2. Start both Frontend and Backend
  296. make dev
  297. ```
  298. The frontend will be available at `http://localhost:5173`. For the desktop app,
  299. run `make desktop-dev` in another terminal — see the [Desktop Guide](docs/DESKTOP.md).
  300. ### Self-Hosting (Docker)
  301. For running the production or development stack using the pre-built Docker image, see the [Self-Hosting Setup Guide](SETUP.md).
  302. > [!NOTE]
  303. > **Agents / AI Assistants:** If you need to set up, configure, run, or diagnose a local self-hosted instance of AgentRQ using Docker, refer to [SETUP.md](SETUP.md) for step-by-step instructions, Docker run commands, and environment variable configurations.
  304. ## 🤖 Claude Code & AI Integration
  305. AgentRQ is designed for seamless integration as a **Claude Channel**. This allows your AI agents to see tasks assigned to them and respond directly within your Claude session.
  306. Each workspace has its own MCP URL and token (visible in the workspace setup modal). In production, these follow the pattern `https://WORKSPACE_ID.mcp.agentrq.com/`.
  307. ### Step 1 — `.mcp.json`
  308. Create a `.mcp.json` file in your local project directory (the leading dot is required). Each project gets its own file so Claude instances stay isolated per workspace. Replace `YOUR_MCP_URL` below with the full URL shown in the setup modal (e.g. `https://WORKSPACE_ID.mcp.agentrq.com/?token=TOKEN`).
  309. ```json
  310. {
  311. "mcpServers": {
  312. "agentrq-WORKSPACE_ID": {
  313. "type": "http",
  314. "url": "YOUR_MCP_URL"
  315. }
  316. }
  317. }
  318. ```
  319. ### Step 2 — `.claude/settings.local.json`
  320. Add a `.claude/settings.local.json` file in the same project directory to pre-approve the AgentRQ tools and avoid permission prompts on every action. The wildcard covers every tool the workspace exposes, including any added later:
  321. ```json
  322. {
  323. "permissions": {
  324. "allow": ["mcp__agentrq-WORKSPACE_ID__*"]
  325. },
  326. "enableAllProjectMcpServers": true,
  327. "enabledMcpjsonServers": ["agentrq-WORKSPACE_ID"]
  328. }
  329. ```
  330. ### Step 3 — Start Claude
  331. Once both files are in place, launch Claude Code from that project directory:
  332. ```bash
  333. claude --dangerously-load-development-channels server:agentrq-WORKSPACE_ID
  334. ```
  335. > **Tip:** The workspace ID, full MCP URL (with token), and ready-to-paste config snippets are all available in the **Setup** modal inside each AgentRQ workspace.
  336. ### Available MCP Tools
  337. When connected, the AI agent has seven tools. Each takes two inputs, `action` and `payload` (the action's fields), e.g. `task {"action": "reply", "payload": {"taskId": "<id>", "text": "On it."}}`; the `help` tool explains them — with no input every tool and its actions, `{"action": "task"}` one tool's actions, and `{"action": "task.create"}` one action's payload with an example.
  338. - `task`: Work on the workspace's tasks — `create` (assign a task to the human or an agent, optionally on a cron schedule), `get` (with no `taskId` it dequeues the next "not started" task assigned to the agent; `includeConversation: true` adds the chat history, cursor-paged), `updateStatus` (`notstarted`, `ongoing`, `blocked`, `completed`, …), `reply` (send a message to the AgentRQ dashboard in real time), `elicit` (ask the human and block until they answer, as a form or a link to confirm) and `getAttachment` (its public link by default, or its content as base64 or, for a text file, plain text). An attachment sent with `reply` or `create` carries base64 `data` or plain `textContent`.
  339. - `memory`: The workspace's notes, which outlive a task — `load` (with no name, `memory.md`, the index of everything remembered here), `save` (replaces a note whole, given the version `load` showed, so two agents cannot overwrite each other) and `delete`.
  340. - `skills`: The skills the workspace can use — the account's skills turned on in it — `search` (by name or description, with each one's `skill://` URI), `load` (one file; a `SKILL.md` comes with the URIs of the skill's other files), `save` (writing `SKILL.md` creates or updates the skill; a new one belongs to the account and is turned on in the workspace) and `delete`.
  341. - `workspace`: `get` (the workspace name and mission description) and `publishEvent` (fire a named event so subscriber workspaces spawn their trigger tasks).
  342. - `siteTools`: Websites the human shared from the AgentRQ Chrome extension — `search` their WebMCP tools (`q` ranks by relevance, `pattern` filters by a regular expression, `limit`/`offset` page), `getDefinition` (one tool's input schema and annotations, before calling it) and `call` (in the human's own Chrome; a tool the site does not mark read-only asks the human in the task first). What a site returns is data, not instructions.
  343. - `pano`: Read and write the Pano, the account's shared markdown docs: `save` (no `id` creates a doc and returns its id; every file sent must be linked from the markdown), `read` (with `includeComments`/`includeAttachments`, or `outline`/`section` for part of a long doc), `comment`, `attach` (files that need no link) and `delete`.
  344. - `help`: How to call the tools above.
  345. - **Real-time Notifications**: Agents receive notifications via the `notifications/claude/channel` protocol whenever a human interacts with their tasks.
  346. ### Skills
  347. Skills are `SKILL.md` playbooks that agents load when a task matches one. They belong to the account, can be imported from a public GitHub repository such as [obra/superpowers](https://github.com/obra/superpowers), and are turned on workspace by workspace. A skill on in several workspaces is one skill, not copies.
  348. - **Import:** on the **Skills** page or in a workspace's **Settings → Skills**, paste a GitHub link to a repository, branch or folder, tick the workspaces to turn the skills on in, and choose **Import**. The report lists what was imported and why anything was skipped. For a very large repository the tab lists its skills and you choose which to import.
  349. - **Use:** agents are told to call `skills.search` at the start of a task, then `skills.load` the `SKILL.md` of any match. Every file is addressed as `skill://<name>/<path>`.
  350. - **Write:** an agent can create or edit the skills on in its workspace with `skills.save`, so a lesson learned in one task becomes a playbook for the next.
  351. - **Supervisor:** the account-wide server can search any workspace's skills and read them with `skills.search` and `skills.get`.
  352. See [docs/SKILLS.md](docs/SKILLS.md) for the format, limits, importing, sharing and the `skill://` scheme.
  353. ## 🌉 ACP Gateway (Bridge for ACP Agents)
  354. While Claude Code has native support for `claude/notifications`, other agents like **Antigravity** and **Codex** require a bridge to receive real-time task notifications from AgentRQ. The `@agentrq/acp-gateway` connects them to AgentRQ over the [Agent Client Protocol (ACP)](https://agentclientprotocol.com): AgentRQ speaks ACP v1 itself, and the gateway only carries it between the agent and the server.
  355. There is nothing to install — `npx` fetches the gateway, and the gateway fetches
  356. the agent you name.
  357. ### Usage
  358. 1. Ensure you have a [`.mcp.json`](#step-1--mcpjson) in your project root.
  359. 2. Log in to your agent once, then start the gateway from the same directory as
  360. `.mcp.json`:
  361. ```bash
  362. # Using Antigravity
  363. npx -y @agentrq/acp-gateway@latest --login --agent antigravity-acp
  364. npx -y @agentrq/acp-gateway@latest --agent antigravity-acp
  365. ```
  366. ```bash
  367. # Using Codex
  368. npx -y @agentrq/acp-gateway@latest --login --agent codex-acp
  369. npx -y @agentrq/acp-gateway@latest --agent codex-acp
  370. ```
  371. Sign out again with `--logout` in place of `--login`.
  372. The gateway will automatically:
  373. - Connect to your AgentRQ workspace via the URL in `.mcp.json`.
  374. - Spawn the agent subprocess and bridge standard I/O.
  375. - Forward task assignments, messages, and permission requests in real-time.
  376. ### ACP v1
  377. The gateway needs Node 22 or newer. Every server serves ACP v1 (see
  378. [Native ACP](docs/SETUP_PRODUCTION.md#native-acp)); the gateway no longer talks
  379. to AgentRQ over MCP.
  380. ## 🌌 Codex (via the ACP Gateway)
  381. [OpenAI Codex](https://github.com/openai/codex) connects through the same
  382. [ACP Gateway](#-acp-gateway-bridge-for-acp-agents) as every other agent. The
  383. gateway resolves `codex-acp` from the [ACP registry](https://github.com/agentclientprotocol/registry)
  384. and runs it for you, so there is nothing to install and nothing to configure
  385. beyond the `.mcp.json` the gateway reads.
  386. > Earlier releases used a separate `@agentrq/codex-gateway` package and a
  387. > `.codex/config.toml`. Neither is needed now.
  388. ### Setup
  389. 1. Ensure you have a [`.mcp.json`](#step-1--mcpjson) in your project root.
  390. 2. Log in — Codex will not open a session until you have. The first run fetches
  391. the agent, then hands you its login:
  392. ```bash
  393. npx -y @agentrq/acp-gateway@latest --login --agent codex-acp
  394. ```
  395. 3. Start the bridge. Run it from the same directory as `.mcp.json`:
  396. ```bash
  397. npx -y @agentrq/acp-gateway@latest --agent codex-acp
  398. ```
  399. Sign out again with `--logout` in place of `--login`. The registry publishes
  400. Codex as an npm package, so npx fetches it on first use and keeps it current.
  401. ## 👑 Supervisor (CoreMCP)
  402. While individual workspaces provide a scoped view for specific projects, the **Supervisor (CoreMCP)** is a global MCP server that grants an agent bird's-eye view and management capabilities across your entire AgentRQ account.
  403. The Supervisor is accessible at `https://mcp.agentrq.com/mcp`. It uses **OAuth2** for secure authentication, allowing modern AI tools (like Claude Code) to connect securely.
  404. ### Why use the Supervisor?
  405. - **Multi-Workspace Management**: List, create, and update workspaces.
  406. - **Global Task View**: Fetch tasks from all workspaces in a single call (`task.listAll`).
  407. - **Administrative Control**: Manage task assignments, status, and priorities globally.
  408. - **Unified Statistics**: Access detailed statistics and health metrics for any workspace.
  409. ### Available Supervisor Tools
  410. The Supervisor has nine tools. Each takes two inputs, `action` and `payload` (the action's fields), most actions naming a `workspaceId`; the `help` tool prints any action's payload with an example (`{"action": "events.createTrigger"}`).
  411. - `workspace`: `list` (active and archived workspaces), `create`, `get`, `update` (settings and metadata), `stats` (analytics over 7 or 30 days), `fork` (so a second agent can work some of its tasks in parallel) and `mergeFork` (back into its parent once its tasks are done).
  412. - `task`: Every workspace's tasks — `listAll` (search and filter across the platform), `list` (one workspace), `create`, `get` (tool calls only with `includeToolCalls`; `messagesSince` keeps the newer messages), `messages` (just the conversation, oldest first, with the task's status), `changes` (only the tasks whose status or conversation changed after `since`, a short line each, with `now` for the next call: the efficient way to follow up), `updateStatus`, `updateSortingOrder`, `updateAssignee`, `updateAllowAll` (`allow_all_commands`), `updateSchedule` (a scheduled/cron task; these, `create` and `reply` answer only the task's id, title, status and assignee, `verbose: true` the whole task), `delete` (with its messages and attachments — the way to retire a schedule rather than leave it running), `reply` (post to a task's thread), `respond` (allow/deny a permission request) and `getAttachment` (its public link by default, or its content as base64 or plain text, with its metadata).
  413. - `memory`: A workspace's memory, read-only — `list` (name, size and when each changed) and `get` (one in full; `MEMORY.md` is the index the others hang off).
  414. - `skills`: The account's skills as a workspace sees them, read-only — `search` (with whether each is on there, `limit`/`offset` paging and a `total`; content is not included) and `get` (one file by its `skill://<name>/<path>` URI).
  415. - `events`: Named signals a workspace publishes, and the triggers that create a task somewhere when one fires. Publishing stays agent-side (`workspace.publishEvent` on the per-workspace server) — the supervisor builds the wiring, the workers fire it. `list`, `create`, `get`, `update`, `delete` define the signals; `createTrigger`, `listTriggers`, `getTrigger`, `updateTrigger`, `deleteTrigger` decide what each one causes; `listTasks` shows the tasks an event has spawned.
  416. - `workflows`: The graph those pieces add up to: a start event, and the steps that react to it and to each other. `list`, `create`, `get`, `update`, `delete` the graph itself; `createStep`, `listSteps`, `deleteStep` its nodes; `getText` and `replaceFromText` the whole graph as the indented document the UI's text mode edits — the declarative way to write one; `listTasks` the tasks it has spawned.
  417. - `machines`: `createEnrolmentCode` (a one-time code for enrolling a new machine with `agentrqd`, shown once and expiring shortly — there is no remote enrolment, so it hands back a ready-to-run command), `list` (whether each machine is enabled and online and how many agents it runs), `launchAgent` (start a workspace's agent, `claude-code` or `acp-gateway`, with the same checks as the launch button in the app) and `stopAgent`.
  418. - `pano`: Read and write the account's shared markdown docs, as the supervisor workspace, with the same actions as the workspace tool.
  419. - `help`: How to call the tools above.
  420. ### Supervisor Resources & Prompts
  421. Beyond tools, the Supervisor also exposes MCP **resources** — read-only reference material an agent can pull into its own context — and MCP **prompts** — ready-made templates for the workflows a "single brain overseeing many workspaces" is for.
  422. Resources:
  423. - `agentrq://guides/new-workspace`: how to set up a new workspace end-to-end.
  424. - `agentrq://guides/agentrqd-setup`: how to install `agentrqd` and enrol a new machine, with the enrol command templated to this server.
  425. - `agentrq://workspaces/{workspaceId}/tasks/{taskId}`: a task's status, `updatedAt`, `awaitingReply` and its last five text messages, without tool calls.
  426. - `agentrq://workspaces/{workspaceId}/tasks` and `agentrq://tasks/delegated-by/{workspaceId}`: the newest 50 tasks of a workspace, or of those a workspace delegated through `task.create`, as `task.list` returns them.
  427. A client on protocol revision 2026-07-28 can follow the three task resources with `subscriptions/listen`, on the caller's own workspaces, at most 100 per listen. It gets `notifications/resources/updated` when a task's status changes, a message arrives, or its agent asks a question or a permission, instead of polling.
  428. Prompts:
  429. - `new-workspace`: scaffold a new workspace for a stated purpose.
  430. - `setup-agentrqd`: mint an enrolment code and hand back the exact commands to run on a new machine.
  431. - `workspace-status`: a status report across every workspace at once.
  432. ### Connecting to Supervisor (Claude Code)
  433. Since the Supervisor uses OAuth2, you can connect it using the following configuration in your `~/.mcp.json`:
  434. ```json
  435. {
  436. "mcpServers": {
  437. "agentrq": {
  438. "type": "http",
  439. "url": "https://mcp.agentrq.com/mcp"
  440. }
  441. }
  442. }
  443. ```
  444. When you first run Claude with this server, it will provide a link to authenticate via your browser.
  445. ## 🧩 Official Extensions
  446. AgentRQ provides official extensions for major AI agent CLI tools to simplify setup and integration with its supervisor MCP. The sub agents MCPs should use their own workspace specific MCP server URLs.
  447. ### 🍊 Claude Code
  448. Plugins for Claude Code are published from this repository's own marketplace, each with a skill and pre-configured MCP access:
  449. - [`agentrq`](plugins/claude/agentrq/README.md) — the **supervisor**, talking to the account-level MCP server so one agent can orchestrate work across every workspace you own.
  450. - [`agentrq-custom-supervisor`](plugins/claude/agentrq-custom-supervisor/README.md) — the same supervisor for a **self-hosted** server; it asks for the server's supervisor MCP URL.
  451. - [`agentrq-workspace`](plugins/claude/agentrq-workspace/README.md) — the **workspace agent**, connected to a single workspace's MCP server to work its queue.
  452. **Installation:**
  453. ```bash
  454. /plugin marketplace add https://github.com/agentrq/agentrq
  455. /plugin install agentrq@agentrq
  456. /plugin install agentrq-workspace@agentrq
  457. ```
  458. > Previously these lived in a separate `agentrq-claude-extension` repository. The marketplace URL is now this repository; if you added the old one, re-add the marketplace at the URL above.
  459. ### 🖱️ Cursor
  460. Plugins for Cursor are published from this repository too, with the same skills and MCP access as the Claude Code ones:
  461. - [`agentrq`](plugins/cursor/agentrq/README.md) — the **supervisor**, connected to `https://mcp.agentrq.com/mcp`; it signs in with OAuth and asks nothing at install.
  462. - [`agentrq-workspace`](plugins/cursor/agentrq-workspace/README.md) — the **workspace agent**; its MCP URL is a plugin variable set under **Plugins → Configure** in the Cursor dashboard.
  463. **Installation:** open **Customize** in Cursor's sidebar, find **AgentRQ** and select **Install**.
  464. ### ♊ Gemini CLI
  465. The Gemini CLI extension allows you to manage AgentRQ workspaces and tasks directly from your terminal using Google's Gemini models.
  466. > **Tip:** To enable real-time task notifications with Gemini, use the [ACP Gateway](#-acp-gateway-bridge-for-acp-agents).
  467. **Installation:**
  468. ```bash
  469. gemini extensions install https://github.com/agentrq/agentrq
  470. ```
  471. > Previously this lived in a separate `agentrq-gemini-extension` repository. It now ships from [`plugins/gemini`](plugins/gemini/README.md) in this one; if you installed the old one, uninstall it and install again from the URL above.
  472. ### 🐋 DeepSeek Harness
  473. The [`@agentrq/dsh-plugin-agentrq`](plugins/deepseek-harness/README.md) bundle brings AgentRQ into [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). It bridges the workspace's tools to the model as `mcp__agentrq__*` and holds a supervised workspace session, so tasks assigned to the agent and the human's replies arrive over the MCP channel and land in the live session — no polling, and no leaving the harness to work the queue.
  474. **Installation:**
  475. ```bash
  476. npx @deepseek-ai/dsh plugin --profile agentrq-<workspace> add @agentrq/dsh-plugin-agentrq
  477. # pin this workspace's MCP URL in ~/.dsh/profiles/agentrq-<workspace>/cordis.patch.yml
  478. npx @deepseek-ai/dsh --profile agentrq-<workspace>
  479. ```
  480. Copy the filled-in commands and config block from **Workspace Settings → Setup → DeepSeek Harness**. A dsh profile serves one workspace and carries its own endpoint, so run one profile per workspace and switching workspaces is switching profiles. Delivery, startup catch-up, and reconnect behavior are configurable; see the [plugin README](plugins/deepseek-harness/README.md).
  481. ## 🔌 Integrations
  482. ### Slack Integration
  483. AgentRQ supports multi-tenant Slack integration for real-time task creation, thread replies sync, and agent permission requests:
  484. - [Slack Integration Setup & Usage Guide](integrations/slack/README.md)
  485. ## 🙌 Contributing
  486. Bug reports go in a [GitHub issue](https://github.com/agentrq/agentrq/issues/new) and feature or architecture ideas go in a short written proposal — see [CONTRIBUTING.md](CONTRIBUTING.md).
  487. ## 🤝 Credits
  488. - [AgentRQ](https://agentrq.com) — The official Agent-Human collaboration platform.
  489. - [HasMCP](https://hasmcp.com) — Bridge the Gap Between APIs and Agents.
  490. ## 📝 License
  491. AgentRQ is dual-licensed:
  492. - **Open source:** [AGPL-3.0-only](LICENSE).
  493. - **Commercial:** a binary-only [commercial licence](LICENSE-COMMERCIAL) from Contextual, Inc., for proprietary use without the AGPL's obligations. Contact [hi@agentrq.com](mailto:hi@agentrq.com).
  494. The [`agentrqd`](daemon) machine daemon, the desktop and `agentrqd` [install scripts](installers), and the separately published packages — the [`agentrq-ws`](cli/agentrq-ws) command-line client and the plugins under [`plugins/`](plugins) — keep their own Apache-2.0 licence.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.