conus MCP server
Commit Nov 9, 2026An autonomous task manager that allows AI agents to create, track, and manage their own tasks through MCP and automated hooks.
Also known as Pandusss/conus
- Stars
- 6
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is conus MCP?
conus is an autonomous task manager that allows AI agents to create, track, and manage their own tasks through MCP and automated hooks.
Summary generated from the project's README
About conus MCP server
Managing complex development workflows by allowing AI agents to maintain their own task boards is what Conus enables. It provides an autonomous system where agents using Claude Code, Codex, or Gemini CLI can create, track, and update high-level tasks like features and bug fixes without manual intervention. The system operates through an MCP server and a local CLI that runs automated hooks to report file changes, commits, and test results.
Developers deploy the central server using Docker and Compose, which manages a Postgres database and can be configured with a domain for HTTPS. To connect agents, you install the conus-cli on the agent machine and run a setup command. The architecture ensures reliability through a local outbox, meaning agents can continue working even if the server is temporarily unavailable. For enhanced oversight, an optional manager powered by an Anthropic API key can review tasks and process correspondence into project proposals.
What you can do with it
- 1Automated task lifecycle managementAn AI agent can independently create, work on, and mark major features or bugs as complete.
- 2Synchronizing agent progress with developersDevelopers can review exactly what was accomplished during an AI session by checking task history and commits.
- 3Converting communications into actionable workYou can provide chat logs from clients or colleagues to automatically generate new project proposals.
- 4Receiving real-time status notificationsA Telegram bot can alert you when an agent is stuck or when a task requires your manual approval.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepandusss/conus is public and reachablegithub.com/pandusss/conus ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/pandusss/conus ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubYou work with Claude Code or Codex as usual and never mention a task manager. The agent creates the main tasks, takes them into work, marks what blocks it, completes them with a result and drops what you abandoned. After a session Conus shows what is in progress and what got done: who changed what, when and in which session, with the commits.
Conus tracks main tasks only: features, notable fixes, important bugs, decisions that lead to separate work. Small edits and the steps of an agent's plan never become tasks; they end up in the result of the main task.
How it works
"The agent keeps the tasks itself" takes three levels, each with its own mechanism:
| Level | Meaning | Mechanism |
|---|---|---|
| 1. Access | the agent can call the operations | an MCP server and a REST API |
| 2. Understanding | the agent knows when to call them | a protocol delivered by hooks, a skill and instructions |
| 3. Reliability | the board does not depend on the model's memory | hooks on tool use and on stop, server-side reconciliation, a local outbox |
flowchart LR
A[Claude Code / Codex / Gemini CLI] -- MCP over stdio --> B[conus mcp]
A -- hooks --> C[conus hook]
B -- HTTPS --> S[(Conus server + Postgres)]
C -- HTTPS, outbox when offline --> S
W[Web app] --> S
On every agent machine conus-cli runs the agent's hooks and the conus mcp bridge. Hooks report facts (edited
files, commits, test runs) and hand the agent a short snapshot of its open tasks at the start of a session and on
every prompt. At the end of a turn the server checks the facts against the board and, when a main task was
clearly left behind, asks the agent to update it. When the server is down, nothing stops: events wait in a local
outbox and the agent keeps working.
Quick start
1. Run the server
You need Docker with Compose v2.
curl -fsSL https://raw.githubusercontent.com/Pandusss/conus/main/deploy/install.sh | sh
The installer puts compose.yml and a generated .env (a random database password, a setup code) into ./conus,
starts the server and prints its address and the setup code. It asks one question: a domain for HTTPS.
- No domain: Conus runs on http://localhost:8080 of this machine. Good for trying it and for agents on the same machine.
- A domain whose A record points at the server, with ports 80 and 443 free: Caddy gets a Let's Encrypt
certificate and Conus is on
https://<domain>. - Your own reverse proxy: answer with no domain, then point the proxy at
127.0.0.1:8080and setCONUS_PUBLIC_URLin.envto the public address.
Open the address, enter the setup code and choose the owner password.
2. Connect your agents
In the web app open Agents → Connect agent, name the agent and copy the two commands. On the agent's machine (Node.js 22 or newer):
npm install -g conus-cli
conus setup https://conus.example.com conus_xxxxxxxx
No access to the npm registry? Every release also carries the package:
npm install -g --allow-remote=all https://github.com/Pandusss/conus/releases/latest/download/conus-cli.tgz (--allow-remote=all lets npm 12 and newer install from a URL; older npm ignores it).
conus setup logs in, then connects every agent it finds: the Conus plugin in Claude Code (through the
claude CLI; without it, it prints the two /plugin commands to run in Claude Code), the MCP server, hooks and
skill in Codex, the MCP server in Gemini CLI. It offers to add a short Conus rule to each agent's global
instructions and finishes with conus doctor. Restart the agents afterwards. In Codex, approve the hooks once
with /hooks.
To install only the Claude Code plugin by hand (after conus login <url> <token>), run in Claude Code:
/plugin install conus --marketplace Pandusss/conus
Any other MCP client: add a stdio server that runs conus mcp, and add the protocol block to the repository with
conus init --agents-md.
That is all: from now on the agents keep the board themselves.
Privacy
Only this leaves an agent's machine:
- paths of changed files, relative to the repository root;
- sha and subject of commits;
- the git remote address (without login or password), the branch, the
HEADsha, the repository folder name and a hash of its path; - the working directory relative to the repository root;
- the agent's model name;
- command lines of test runs (up to 300 characters, simple commands only — never from scripts with a heredoc, and
for PowerShell never with a here-string, backtick line continuation or
-EncodedCommand); - excerpts of the prompt and the answer, up to 2000 characters;
- titles and texts of tasks written by the agent;
- service data: the agent's session id, the names of the Conus tools called, task refs.
File contents and diffs are never sent. Prompt and answer excerpts can be turned off; the server then works from facts only (commits and files):
conus config set send_text false
The token lives in ~/.conus/config.json, readable by its owner only; the server stores only its SHA-256 hash, and
you can revoke it in the web app. The optional judge (see below) sends the turn's facts and excerpts to the
Anthropic API. The optional manager sends task titles, statuses, block reasons and source quotes, and the
correspondence you give it, to the Anthropic API.
To stop tracking in one repository, run conus disable in it (conus enable turns it back on). Folders outside git
are never tracked.
The manager and Telegram
The web app opens on an Overview of every project, the ones that need you first: who works on what right now, what is blocked and why, what waits for your check, what is next, and deadlines. Tasks have a priority and a due date; agents see their project's tasks most important first.
With an Anthropic API key on the server, a manager works on top of the agents:
- every morning it reviews all open tasks, sets priorities (never ones you set yourself) and picks the focus for the day, which agents see at session start;
- give it correspondence with a client, a colleague or an investor (paste it under Proposals, or forward it to the bot) and it files the work as proposals in the right projects, with a priority, a date and the quote it came from.
With a Telegram bot it reaches you: a morning digest, a message when a task waits for your check (accept or send it
back with a button) or an agent is blocked, and a reminder every few hours for as long as something still waits for
you: checks, blockers, deadlines, proposals, the unfinished focus. Reminders are quiet at night, stop until the next
digest with one button, and are set in Settings (every 3 hours by default, or off). /now shows the same list at any
moment. Every task in a message is a link to it in the web app.
Create a bot with @BotFather, put its token in CONUS_TELEGRAM_BOT_TOKEN, restart, then
press Link Telegram in Settings. The bot polls Telegram, so the server needs no public webhook, and it talks only
to the chat you linked.
Configuration
Server (.env next to compose.yml)
| Variable | Default | Meaning |
|---|---|---|
POSTGRES_PASSWORD |
generated | Database password: letters and digits only. Used once, when the database volume is created. |
CONUS_PUBLIC_URL |
http://localhost:8080 |
The address people and agents use. |
COMPOSE_PROFILES=https, CONUS_DOMAIN |
off | The built-in HTTPS with Caddy and Let's Encrypt. |
CONUS_PORT, CONUS_BIND |
8080, 127.0.0.1 |
Where the app listens on the host. |
CONUS_VERSION |
latest |
The image tag, e.g. 0.1.0. |
CONUS_LANG |
en |
en or ru: the language of what the server writes — chat notes, the agents' status line, task history. The web app is in English until you switch it to Russian (the switch is in the sidebar and on the sign-in screen). |
CONUS_SETUP_CODE |
generated | The code for the first visit. Empty: a random one is printed in docker compose logs app. |
ANTHROPIC_API_KEY |
empty | Turns on the judge: an LLM check at the end of a turn and short summaries of tasks the janitor sends to review. Without it the deterministic checks still run. |
CONUS_JUDGE_ENABLED, CONUS_JUDGE_MODEL |
true, claude-haiku-5-5 |
The judge switch and model. |
CONUS_MANAGER_ENABLED, CONUS_MANAGER_MODEL |
true, claude-opus-5-5 |
The manager (daily review, correspondence into proposals) runs when ANTHROPIC_API_KEY is set; this switches it off or picks another model. |
CONUS_TELEGRAM_BOT_TOKEN |
empty | The owner's Telegram bot: digests, notices, forwarded correspondence. The schedule and quiet hours are in Settings. |
Update: run the installer again, or docker compose pull && docker compose up -d in the conus folder.
Back up: docker compose exec db pg_dump -U conus conus > conus.sql.
Forgot the owner password: docker compose exec app node dist/admin.mjs reset-password.
Agent machines
conus setup writes ~/.conus/config.json. CONUS_URL and CONUS_TOKEN override it (handy in CI),
CONUS_CONFIG_DIR moves it. Messages are in English; conus config set lang ru (or CONUS_LANG=ru) switches
them to Russian.
Troubleshooting
- Run
conus doctor: it checks the configuration, the server, the token, thatconusis on PATH, each agent and a test session in the current repository.✓is fine,!is a warning,✗is an error (exit code 1). - Hooks never interrupt the agent and stay silent on errors; they log to
~/.conus/logs/hook.log. ✗ token: the token was revoked or mistyped. Issue a new one in the web app and runconus setupagain.! path: agents startconusfrom hooks; add npm's global bin directory (npm prefix -g) to PATH, for desktop apps too.! codexwith a hint about/hooks: open Codex and approve the hooks.- The server is down: work goes on; events collect in
~/.conus/outboxand are sent on the next successful call.
Contributing
Questions and ideas go to Discussions; bugs to issues; pull requests are welcome, see CONTRIBUTING.md. Report vulnerabilities privately: SECURITY.md.
License
conus MCP questions
Does Conus track every small edit made by an agent?
No, Conus only tracks main tasks such as features, notable fixes, and important bugs. Small edits and plan steps are included in the result of the main task.
What happens if the Conus server is offline?
The agent can continue working uninterrupted; events are stored in a local outbox and sent once the server is back online.
Does Conus send my private file contents to the server?
No, file contents and diffs are never sent. You can also disable sending prompt and answer excerpts via configuration.