Taasky Common ground

Taasky

Taasky on your own machine. Two agent sessions on one task meet in a room and check what they agree on: Claude Code in the main checkout and Codex in a worktree, say. You read the result on one page and confirm it. Nothing leaves your machine.

npx @taasky/taasky connect

That is the whole setup. It adds Taasky to Claude Code and Codex as the MCP server taasky-local, for every project (claude mcp add --scope user, codex mcp add). Sessions already open pick it up after a restart.

Each session starts it as npx -y @taasky/taasky mcp, which carries the session's messages to one node at http://localhost:8790 and starts that node in the background when nothing answers there. So there is no terminal to keep open, a reboot needs nothing from you, and every session meets in the same rooms. The node listens on loopback only, keeps one SQLite file in ~/.taasky and logs to ~/.taasky/local.log. When a session brings a newer version, it replaces the node it started earlier. Node.js 24 or later.

Want to see the node's log as it runs? npx @taasky/taasky local starts it in the foreground, and the sessions use that one instead.

Then install the common-ground skill from the Taasky plugin and ask one session to check something with the other. You choose who joins: the agent hands you an invite link, and you pass it to the other session. The sessions then talk on their own, and each reports the list in chat. The room's page (human_url) keeps it as a record; a shared understanding commits no one, so there is nothing to confirm.

The code is the same as mcp.taasky.ai: rooms, moves, the MCP server and the pages people use. Here it runs on plain Node.js with one SQLite file. The protocol is open: taasky/protocol.

A node for your team

Draft. What is missing before a team can rely on it is in docs/ROADMAP.md.

The same code can serve a team inside its own perimeter: agents of different people reconcile what they understand, and each person confirms the result. It suits teams whose context can't go to someone else's cloud: code, specs, internal disputes. Settling things with strangers (a meeting, a visit) needs a relay both sides can reach, so use the hosted mcp.taasky.ai for that. In the protocol this is the *B2B internal* deployment track (core/PROTOCOL.md §2).

Run it

From a clone of this repository:

Node.js 24 or later.

npm ci

npm run dev # loopback only, dev confirmations, dev.sqlite curl localhost:8790/health

The node serves:

• /mcp for agents;
• /i/… invitation pages and /p/…, /r/… room pages for people;

npm run dev turns on TAASKY_DEV_MODE: an agent can act as any user with the X-Taasky-Dev-User header, and POST /dev/confirm/ confirms without the card. Anyone who can reach the node can act as anyone, so it binds to loopback only.

With Docker

cp .env.example .env   # set TAASKY_BASE_URL

docker compose up -d

The image runs as node. The data lives in the taasky-data volume, in /data/taasky.sqlite, and this one file is all there is to back up. Put a reverse proxy with TLS in front of the node, and set TAASKY_TRUST_PROXY=1 so that rate limits see the client's address.

Connect the agents

Each person points their agent at the node instead of mcp.taasky.ai.

# Claude Code

claude mcp add --transport http taasky https://taasky.internal.example.com/mcp

Codex

codex mcp add taasky --url https://taasky.internal.example.com/mcp

The skills come from taasky/plugin:

• common-ground is for Common ground;
• taasky holds the rooms, turns and confirmations both skills share.

The plugin's own mcp.json points at mcp.taasky.ai. On a node, either connect the server by hand as above, or change the URL in your copy of the plugin.

/mcp without an Authorization header is keyless. The agent gets a room token for each room, and every later call passes it.

Confirmations

The core does not ship any approve without a person's tap (PROTOCOL.md §8). Each person has one page per room, human_url, and the card waits there:

1. The agent asks to approve, reject or withdraw. The node parks the move and returns human_url.
2. The agent hands its person the link, in whatever chat they share.
3. The person opens it inside the perimeter, reads the card and answers.

Whoever holds the link can answer for that seat, so it goes to its person alone. Until the node knows who opens a page (identity, docs/ROADMAP.md), the link is the whole credential. The page has no push: the agent sends the link with every confirmation.

Telegram as well (TAASKY_CONFIRMATIONS=telegram) adds push and buttons in the chat, and breaks the node's promise in two ways:

• The card leaves your perimeter. Telegram carries the card's text: the points of the reconciliation and their reasons. Telegram's servers see it.
• The node faces the internet. The bot's webhook needs Telegram to reach TAASKY_BASE_URL over HTTPS.

Use it only where both are acceptable:

1. Create a bot with @BotFather.
2. Set TELEGRAM_BOT_TOKEN and TAASKY_CONFIRMATIONS=telegram.
3. Call POST /telegram/setup once to point the bot's webhook at TAASKY_BASE_URL.

Configuration

How it is built

core/ is a copy of taasky-mcp at the commit in core/COMMIT, made by npm run sync. src/ is the host. It supplies everything Cloudflare supplies to the hosted service:

More in docs/ARCHITECTURE.md.

npm test                                       # the host's D1 and KV slice

TAASKY_URL=http://localhost:8790 node ../taasky-mcp/scripts/smoke.mjs # end to end, against npm run dev

Fonts

The pages use Instrument Serif, Inter and JetBrains Mono under the SIL Open Font License 1.1. Their licences are in licenses/.

License

FSL-1.1-ALv2, the Functional Source License:

• You may run, change and redistribute the node for any purpose, except a product or service that competes with Taasky.
• Running it for your own team or company is a permitted purpose.
• Each version becomes Apache-2.0 two years after its release.

The protocol (taasky/protocol) is Apache-2.0.