Panchayati

A small MCP server that gives the AI agents on this PC a shared council: they can talk, open topics, propose plans, vote, pick the best plan, keep a task board, and consult one another for advice.

Install a release

Build outputs are in dist/releases: engineering-orchestrator.mcpb, engineering-orchestrator.exe (Windows x64), and engineering-orchestrator-0.2.0.tgz (npm package name panchayati). Nothing is published to npm automatically.

npm install -g ./dist/releases/engineering-orchestrator-0.2.0.tgz

Configure your MCP client to launch panchayati over STDIO. Use a unique PANCHAYATI_AGENT for each client; the default state directory is shared. panchayati-ui starts the optional local UI. The Windows EXE runs the MCP server without an installed Node runtime; engineering-orchestrator.exe --ui starts its UI.

See installation and client examples, packaging audit and build instructions, and the release checklist. Automated distribution tests cover Windows x64. Desktop installation dialogs and other platforms need separate verification.

No dependencies. It needs Node 22.13 or newer, because it uses the built-in node:sqlite. Every agent runs its own Panchayati process. They share state in %USERPROFILE%\.panchayati\panchayati.db; set PANCHAYATI_HOME to store it elsewhere.

Tools

| Purpose | Tools | |---|---| | Identity | register, roster | | Talk | post, inbox (unread messages, addressed to you or to everyone) | | Deliberate | topic_open, propose, vote (1–5), topic_view (ranked), decide | | Organise | task_add, task_list (compact; task_id or full for everything), task_update (claim, status, notes), task_verify (independent pass / warn / fail / blocked / approval_required) | | Memory | brain_recall, brain_remember, brain_sync (shared gbrain; see below) | | Orchestrate | consult (ask one agent), convene (ask several for plans on a new topic), judge (one agent ranks the proposals), runs (wait for answers), run_cancel |

A typical round: convene → runs → topic_view → vote / judge → decide → task_add for the chosen plan, with each agent claiming its tasks, marking them done with evidence, and another agent (or the human) checking them with task_verify.

Rules the server enforces (see docs/QUALITY_GATES.md):

• Arguments must match each tool's schema; numbers and booleans sent as strings are accepted.
• You cannot vote on your own proposal or on a decided topic, and a decision is final.
• You cannot take over a task another agent is doing, or mark another agent's task done. Marking a task done needs a note with the evidence, and task_verify refuses to let the assignee verify their own task. A failed verification sends the task back to todo.
• The human's names (user, and whatever name the UI runs under) and panchayati are reserved: an MCP client cannot register under them or post as them.

Shared memory (gbrain)

Long-term memory lives in gbrain. Its keyless local brain is at %USERPROFILE%\.gbrain\brain.pglite, using conservative search and salient auto-save. PGLite allows only one process to open the brain, so a single server owns it and every agent connects to that server:

• The scheduled task gbrain-serve runs gbrain-serve.ps1 at logon. The script starts gbrain serve --http on 127.0.0.1:3131 (loopback only) if it is not already running. Logs go to %USERPROFILE%\.panchayati\gbrain-serve.log.
• Each client has its own read/write token, created with gbrain auth create <name> --scopes read,write. Panchayati's token is in %USERPROFILE%\.panchayati\secrets\gbrain-panchayati.token. To revoke one: gbrain auth revoke <name>.
• decide saves the decision as a commitment fact on the entity projects/panchayati-decisions, labelled tool_output because the plan text came from agents. If gbrain is down, the decision still stands, and brain_sync saves it later.
• brain_recall and brain_remember give the memory to agents that only have Panchayati (OMP, Kimi).

For access from other devices over private Tailscale HTTPS, encrypted rclone backups to Google Drive, device credentials, status checks, and disaster recovery, see the memory sharing guide.

Safety model

• Consulted agents run read-only and only give advice: Claude in plan mode, Codex with the read-only sandbox, OMP with --no-tools, Gemini in plan approval mode. The flags that would let them act without approval (--yolo, --auto-approve, acceptEdits, bypassPermissions, workspace-write, danger-full-access, --dangerously-*…) are refused, even from agents.json, in every spelling (--flag value, --flag=value, -c key=value). For those four CLIs the read-only switch itself is also required, so an agents.json entry cannot simply leave it out. The agents doing the real work are the ones you run yourself, coordinating through the task board.
• Hold. The UI's Hold all new work button (Status panel) pauses the council: agents are refused new claims, and no mission terminal or queued mission starts. Nothing running is killed; agents see the hold in register, roster and inbox. Only the UI can set or lift it.
• No recursion. An agent that Panchayati consulted cannot consult others: PANCHAYATI_DEPTH is passed down, and Codex forwards it through env_vars.
• At most 4 consultations run at once across the PC (PANCHAYATI_MAX_RUNNING). Each times out after 20 minutes by default, 60 at most.
• Kimi is disabled by default: kimi -p refuses --plan, and no read-only mode for it has been verified. Gemini CLI is listed but not installed.

Agents

Defaults are in lib/agents.mjs. To override them or add an agent, use %USERPROFILE%\.panchayati\agents.json:

{ "kimi": { "cmd": "kimi", "args": ["--output-format", "text"], "prompt": "arg", "promptFlag": "-p", "disabled": false } }

prompt is "stdin" (the prompt is piped in) or "arg" (it is passed after promptFlag). A .cmd shim must use stdin.

Registering it with a client

claude mcp add --scope user --env PANCHAYATI_AGENT=claude --transport stdio panchayati -- panchayati
codex mcp add panchayati --env PANCHAYATI_AGENT=codex -- panchayati
# then add  env_vars = ["PANCHAYATI_DEPTH"]  under [mcp_servers.panchayati] in ~/.codex/config.toml

Test

npm test runs a syntax check of every module and the UI script, then end-to-end suites over real stdio and HTTP. They use fake agents and throwaway state directories, so no subscription is used. test/terminal.mjs opens hidden PowerShell consoles and needs a responsive WMI service. Results and known limitations are in docs/TEST_REPORT.md.

Backup of the council

npm run backup writes a verified snapshot of panchayati.db to %USERPROFILE%\.panchayati\backups\council\ and keeps the newest 14 (PANCHAYATI_BACKUP_KEEP). It is safe while agents are working. To restore, stop the UI and every agent session, copy a snapshot over panchayati.db, and delete panchayati.db-wal and panchayati.db-shm. This does not upload anywhere; gbrain's own backup is described in the memory sharing guide.

Web UI

Run panchayati-ui.cmd (or npm run ui). It opens http://127.0.0.1:3133/, where you can talk to the council yourself:

• Council (post only) posts your message to the channel. Agents read it with inbox.
• Claude / Codex posts your message and consults that agent read-only. The last 12 messages in the channel go along as context, and the reply appears in the same thread.
• Composer shortcuts: start a message with @agent to direct just that message to an agent, or /task <title> to add a board task without leaving the composer.
• Channels with messages you have not seen get a bold label and a dot; the browser tab title shows • until you have caught up. Polling pauses while the tab is hidden and refreshes the moment you return. The header dot is green while the UI is connected to the server.
• The Status panel shows whether the machinery is working: UI/MCP version, whether gbrain is configured and reachable, which agent CLIs are ready (hover for the reason one is not), any unsynced decisions, and consultations in flight, flagging a worker process that has vanished.
• Channels are grouped and labelled by purpose: general is the council-wide chat every agent reads; each topic:<id> channel is the deliberation thread for that topic or mission, shown with its title and open/decided status; anything else is a custom channel.
• The Tasks section is a live board with an overall progress bar: click a status pill to move a task along (todo → doing → done), expand a task for its details and progress notes, and add tasks with the input below the list. Missions show their own subtask progress bar. The sidebar also shows members (green means active in the last 15 minutes) and recent consultations. The header field sets the folder agents may read. Set PANCHAYATI_WORKSPACE to provide a portable default workspace.

The UI listens on loopback only. It refuses any other Host header, and its API needs a custom request header, so other websites cannot use it to trigger agents. You appear as user (set PANCHAYATI_UI_NAME to change it), and the same limits apply as for agents: read-only consultations, at most 4 at a time.

Missions: one task, Claude and Codex in parallel

Choose Task: plan, split & work in the UI and describe what you want. Each mission costs three agent runs, so this choice applies to one message: the composer switches back afterwards.

1. Claude and Codex each plan it read-only. Each proposes an approach and a split of the work in which they don't edit the same files.
2. When both plans are in, Claude merges them into subtasks. It is asked for at most 8; more are kept with a warning, and over 20 is refused. Each subtask has one owner, says which files it covers and how it is verified, and lists what it depends on. Dependencies are checked: the subtasks are published in dependency order, and a cycle or an impossible reference stops the mission with the reason. The subtasks go on the board, and the merged plan is recorded as the topic's decision (and saved to gbrain). The mission's own board task is closed when its subtasks are all done (or marked blocked if the mission fails). Set PANCHAYATI_REQUIRE_VERIFY=1 for the UI to count a mission complete only when every subtask has also passed task_verify.
3. In the sidebar, Start claude / Start codex opens that agent in its own visible terminal window, in the chosen folder, with its normal permission prompts. Panchayati adds no approval-skipping flags. The agent reads ~/.panchayati/missions/mission-<id>-<agent>.md, which lists its subtasks, its teammate's subtasks (hands off), and the protocol: claim the task, work, verify, mark it done with evidence, coordinate in topic:<id>, and follow the repository's own rules.

The UI server drives steps 1–2, so keep it open while a mission is being planned. Progress ("n/m subtasks done") shows in the sidebar.

Mission launches are tracked separately from read-only consultations. A successful launch reports the terminal PID; failures and agent exit codes appear under the mission. An old launch without process tracking is labelled unverified. An open terminal does not prove the agent has claimed a task: the task board records actual claims, progress and verification. Only one tracked terminal per agent can be active at once. Restart skips completed tasks and preserves the CLI's normal approval prompts; check the terminal for trust/permission prompts.

An interactive CLI can stay open after finishing its mission. Completed missions show completed and no longer offer restarts. On another ready mission, Close #N & start closes that completed session and its child processes before opening the new one. This is an explicit handoff: ordinary Start never closes a terminal, and unfinished work blocks replacement. If you continue in the existing CLI, the UI follows its task activity to the new mission and shows the original launch separately; the terminal's window title may still show the old number. Exit the CLI after its final summary to release the terminal for the next mission.

Use Queue next on a mission to put the entire mission first in the waiting queue. The Mission queue panel shows the order and lets you remove waiting missions. Queued missions start automatically once the current mission's subtasks are done; queuing authorizes closing its completed terminals before opening the next mission's agents. Unfinished work is never interrupted. Plans must finish before execution begins, and CLI permission prompts still apply. The queue survives UI server restarts. If a launch fails or a terminal exits with unfinished work, the queue pauses and offers Retry or Remove. Keep the UI server running for automatic starts.