{"id":50988356,"url":"https://github.com/agentrq/agentrq","last_synced_at":"2026-07-07T22:00:51.533Z","repository":{"id":354801344,"uuid":"1190390511","full_name":"agentrq/agentrq","owner":"agentrq","description":"AgentRQ: Human-in-loop realtime conversational task manager for AI Agents.","archived":false,"fork":false,"pushed_at":"2026-07-03T20:51:34.000Z","size":2118,"stargazers_count":951,"open_issues_count":18,"forks_count":74,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-07-03T22:26:00.859Z","etag":null,"topics":["acp-client","acp-gateway","agentic-ai","agentic-workflow","agents","mcp","mcp-server","supervisor","task","task-manager","task-scheduler","todo"],"latest_commit_sha":null,"homepage":"https://agentrq.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentrq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-24T08:35:45.000Z","updated_at":"2026-07-03T20:51:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agentrq/agentrq","commit_stats":null,"previous_names":["agentrq/agentrq"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/agentrq/agentrq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentrq%2Fagentrq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentrq%2Fagentrq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentrq%2Fagentrq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentrq%2Fagentrq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentrq","download_url":"https://codeload.github.com/agentrq/agentrq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentrq%2Fagentrq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35243953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acp-client","acp-gateway","agentic-ai","agentic-workflow","agents","mcp","mcp-server","supervisor","task","task-manager","task-scheduler","todo"],"created_at":"2026-06-19T23:00:32.335Z","updated_at":"2026-07-07T22:00:51.525Z","avatar_url":"https://github.com/agentrq.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# AgentRQ ── Agent-Human Collaboration Platform\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.zh-CN.md\"\u003e简体中文\u003c/a\u003e\n  \u003cbr /\u003e\n  \u003cbr /\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=GBAoSpuCzrU\"\u003eWatch on YouTube in HD\u003c/a\u003e\n  \u003cbr /\u003e\n  \u003cbr /\u003e\n  \u003ca href=\"https://discord.gg/xFSMaEA2b2\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge\u0026logo=discord\u0026logoColor=white\" alt=\"Discord\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nAgentRQ 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.\n\n## 🚀 Overview\n\nThink 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. \n\nBecause 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.\n\n## 🏛 Architecture\n\nAgentRQ follows a decoupled service-oriented architecture:\n\n### Backend (Go / Fiber)\n- **API Server**: Fiber-based REST API for workspace and task management.\n- **MCP Server**: Integrated `mcp-go` SSE server that exposes tools and resources to AI models.\n- **CoreMCP (Supervisor)**: A global MCP server that allows agents to manage all workspaces, tasks, and statistics across the entire platform.\n- **Data Layer**: GORM with SQLite for persistent, user-scoped storage.\n- **Authentication**: Google OAuth2 integration with JWT-based session management.\n- **Event Bus**: Internal pub/sub system for real-time SSE notifications.\n\n### Frontend (Vue.js 3 / Vite)\n- **Modern UI**: Tailored with Vue 3, Pinia, and Tailwind CSS.\n- **Glassmorphism**: A sleek, premium design language with smooth transitions and real-time updates.\n- **Reactive State**: Synchronized with the backend via SSE events.\n\n## 🛠 Getting Started\n\n### Prerequisites\n- **Go** 1.21+\n- **Node.js** 18+ (with npm)\n- **Google Cloud Console**: An OAuth2 Client ID and Secret.\n\n### Configuration\n1. Create a `_config/base.yaml` (or `development.yaml`) in the `backend` directory.\n2. Fill in your Google OAuth2 credentials:\n\n```yaml\nauth:\n  google:\n    client_id: \"your-google-client-id\"\n    client_secret: \"your-google-client-secret\"\n```\n\n### Running Locally\nUse the provided `Makefile` to start the full stack:\n\n```bash\n# 1. Install all dependencies\nmake install\n\n# 2. Start both Frontend and Backend\nmake dev\n```\n\nThe frontend will be available at `http://localhost:5173`.\n\n### Self-Hosting (Docker)\nFor running the production or development stack using the pre-built Docker image, see the [Self-Hosting Setup Guide](SETUP.md).\n\n\u003e [!NOTE]\n\u003e **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.\n\n## 🤖 Claude Code \u0026 AI Integration\n\nAgentRQ 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.\n\nEach 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/`.\n\n### Step 1 — `.mcp.json`\n\nCreate 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`).\n\n```json\n{\n  \"mcpServers\": {\n    \"agentrq-WORKSPACE_ID\": {\n      \"type\": \"http\",\n      \"url\": \"YOUR_MCP_URL\"\n    }\n  }\n}\n```\n\n### Step 2 — `.claude/settings.local.json`\n\nAdd a `.claude/settings.local.json` file in the same project directory to pre-approve the AgentRQ tools and avoid permission prompts on every action:\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"mcp__agentrq-WORKSPACE_ID__updateTaskStatus\",\n      \"mcp__agentrq-WORKSPACE_ID__getWorkspace\",\n      \"mcp__agentrq-WORKSPACE_ID__reply\",\n      \"mcp__agentrq-WORKSPACE_ID__createTask\",\n      \"mcp__agentrq-WORKSPACE_ID__downloadAttachment\",\n      \"mcp__agentrq-WORKSPACE_ID__getTask\"\n    ]\n  },\n  \"enableAllProjectMcpServers\": true,\n  \"enabledMcpjsonServers\": [\"agentrq-WORKSPACE_ID\"]\n}\n```\n\n### Step 3 — Start Claude\n\nOnce both files are in place, launch Claude Code from that project directory:\n\n```bash\nclaude --dangerously-load-development-channels server:agentrq-WORKSPACE_ID\n```\n\n\u003e **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.\n\n### Available MCP Tools\nWhen connected, the AI agent has access to:\n- `createTask`: Assign a task to the human user (supports optional `cron_schedule` for recurring tasks).\n- `updateTaskStatus`: Move tasks through `notstarted`, `ongoing`, `blocked`, and `completed`.\n- `reply`: Send messages back to the AgentRQ dashboard in real-time.\n- `getWorkspace`: Fetch the workspace name, mission description, and task statistics.\n- `getTask`: Fetch a task — with no `taskId` it dequeues the next \"not started\" task assigned to the agent; with a `taskId` it returns that task. Pass `includeConversation: true` to also include the chat history (cursor-based pagination).\n- `downloadAttachment`: Retrieve an attachment by its ID.\n- **Real-time Notifications**: Agents receive notifications via the `notifications/claude/channel` protocol whenever a human interacts with their tasks.\n\n## 🌉 ACP Gateway (Bridge for ACP Agents)\n\nWhile Claude Code has native support for `claude/notifications`, other agents like **Gemini CLI** require a bridge to receive real-time task notifications from AgentRQ. The `@agentrq/acp-gateway` bridges the [Agent Client Protocol (ACP)](https://agentclientprotocol.com) with MCP to enable this.\n\n### Installation\n\n```bash\nnpm install -g @agentrq/acp-gateway\n```\n\n### Usage\n\n1. Ensure you have a [`.mcp.json`](#step-1--mcpjson) in your project root.\n2. Run the gateway followed by your agent's ACP command:\n\n```bash\n# Using Gemini CLI\nacp-gateway -- gemini --acp\n```\n\nThe gateway will automatically:\n- Connect to your AgentRQ workspace via the URL in `.mcp.json`.\n- Spawn the agent subprocess and bridge standard I/O.\n- Forward task assignments, messages, and permission requests in real-time.\n\n## 🌌 Codex Gateway (Bridge for OpenAI Codex)\n\nSimilar to the ACP Gateway, the `@agentrq/codex-gateway` connects [OpenAI Codex](https://github.com/openai/codex) to AgentRQ workspaces by bridging the Model Context Protocol (MCP) with the Codex app-server protocol.\n\n### Installation\n\n```bash\nnpm install -g @agentrq/codex-gateway@latest\n```\n\n### Setup\n\n**1. Configure agentrq MCP server for Codex (project-level)**\n\nCodex reads project-level MCP server config from `.codex/config.toml`. Create this file so the Codex agent can use agentrq tools directly during task execution (replace `\u003cWORKSPACEID\u003e` and `\u003cTOKEN\u003e` with your values from the agentrq dashboard):\n\n```bash\nmkdir -p .codex\ncat \u003e\u003e .codex/config.toml \u003c\u003c 'EOF'\n\n[mcp_servers.agentrq-workspace]\nurl = \"https://\u003cWORKSPACEID\u003e.mcp.agentrq.com/?token=\u003cTOKEN\u003e\"\n\n[mcp_servers.agentrq-\u003cID\u003e.tools.updateTaskStatus]\napproval_mode = \"approve\"\n\n[mcp_servers.agentrq-\u003cID\u003e.tools.getWorkspace]\napproval_mode = \"approve\"\n\n[mcp_servers.agentrq-\u003cID\u003e.tools.reply]\napproval_mode = \"approve\"\n\n[mcp_servers.agentrq-\u003cID\u003e.tools.createTask]\napproval_mode = \"approve\"\n\n[mcp_servers.agentrq-\u003cID\u003e.tools.downloadAttachment]\napproval_mode = \"approve\"\n\n[mcp_servers.agentrq-\u003cID\u003e.tools.getTask]\napproval_mode = \"approve\"\nEOF\n```\n\n**2. Configure the gateway's agentrq connection**\n\nCreate a `.mcp.json` in your project root so `codex-gateway` can connect to the same agentrq workspace:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentrq\": {\n      \"type\": \"http\",\n      \"url\": \"https://\u003cWORKSPACEID\u003e.mcp.agentrq.com/mcp?token=\u003cTOKEN\u003e\"\n    }\n  }\n}\n```\n\n\u003e **Note:** `.mcp.json` is used by `codex-gateway` to receive tasks. `.codex/config.toml` is used by the Codex agent itself to call agentrq tools (e.g. `reply`, `updateTaskStatus`) during execution.\n\n### Usage\n\nRun `codex-gateway` from your agentrq workspace root (the directory containing `.mcp.json`):\n\n```bash\n# Default: runs `codex app-server`\ncodex-gateway\n\n# Custom codex command\ncodex-gateway -- codex app-server\n```\n\n## 👑 Supervisor (CoreMCP)\n\nWhile 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.\n\nThe 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.\n\n### Why use the Supervisor?\n- **Multi-Workspace Management**: List, create, and update workspaces.\n- **Global Task View**: Fetch tasks from all workspaces in a single call (`listAllTasks`).\n- **Administrative Control**: Manage task assignments, status, and priorities globally.\n- **Unified Statistics**: Access detailed statistics and health metrics for any workspace.\n\n### Available Supervisor Tools\nThe Supervisor provides a comprehensive suite of tools for global management, requiring `workspaceId` parameters where applicable:\n\n**Workspace Management**\n- `listWorkspaces`: Overview of all active and archived workspaces.\n- `createWorkspace`: Bootstrap new project environments.\n- `getWorkspace`: Retrieve details of a specific workspace by ID.\n- `updateWorkspace`: Modify workspace settings and metadata.\n- `getWorkspaceStats`: Retrieve high-level analytics and performance data for a workspace.\n\n**Task Management**\n- `listAllTasks`: Search and filter tasks across the entire platform.\n- `listTasks`: List tasks within a specific workspace.\n- `createTask`: Create a new task in a specific workspace.\n- `getTask`: Retrieve details of a specific task.\n- `updateTaskStatus`: Change a task's status.\n- `updateTaskOrder`: Reorder a task in the list.\n- `updateTaskAssignee`: Change the assignee of a task.\n- `updateTaskAllowAll`: Toggle `allow_all_commands` permission for a task.\n- `updateScheduledTask`: Modify a scheduled/cron task.\n\n**Communication \u0026 Files**\n- `replyToTask`: Post a message to a task's chat thread.\n- `respondToTask`: Submit an allow/deny verdict for a permission request.\n- `getAttachment`: Retrieve data as base64 and metadata for a specific attachment.\n\n### Connecting to Supervisor (Claude Code)\nSince the Supervisor uses OAuth2, you can connect it using the following configuration in your `~/.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentrq\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.agentrq.com/mcp\"\n    }\n  }\n}\n```\n\nWhen you first run Claude with this server, it will provide a link to authenticate via your browser.\n\n## 🧩 Official Extensions\n\nAgentRQ 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.\n\n### 🍊 Claude Code\nThe AgentRQ plugin for Claude Code is distributed via our official marketplace. It provides built-in skills and pre-configured MCP access.\n\n**Installation:**\n```bash\n/plugin marketplace add https://github.com/agentrq/agentrq-claude-extension\n/plugin install agentrq@agentrq\n```\n\n### ♊ Gemini CLI\nThe Gemini CLI extension allows you to manage AgentRQ workspaces and tasks directly from your terminal using Google's Gemini models.\n\n\u003e **Tip:** To enable real-time task notifications with Gemini, use the [ACP Gateway](#-acp-gateway-bridge-for-acp-agents).\n\n**Installation:**\n```bash\ngemini extensions install https://github.com/agentrq/agentrq-gemini-extension\n```\n\n## 🔌 Integrations\n\n### Slack Integration\nAgentRQ supports multi-tenant Slack integration for real-time task creation, thread replies sync, and agent permission requests:\n- [Slack Integration Setup \u0026 Usage Guide](integrations/slack/README.md)\n\n## 🤝 Credits\n\n- [AgentRQ](https://agentrq.com) — The official Agent-Human collaboration platform.\n- [HasMCP](https://hasmcp.com) — Bridge the Gap Between APIs and Agents.\n\n## 📝 License\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentrq%2Fagentrq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentrq%2Fagentrq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentrq%2Fagentrq/lists"}