Lets AI coding agents claim tasks atomically, share memory, and record cost and audit history through MCP, CLI and REST.
Also known as roboticforce/sugar, sugarai
- Stars
- 101
- Tools
- —
- Downloads, 30 days
- 1,109
- Latest version
- 3.4.2
- Last commit
- Nov 10, 2026
- License
- —
What is Sugar MCP?
Sugar lets AI coding agents claim tasks atomically, share memory, and record cost and audit history through MCP, CLI and REST.
Summary generated from the project's README
About Sugar MCP server
Coordinating multiple coding agents across different environments is what Sugar enables for developers using tools like Claude Code, Cursor, or Goose. It acts as a central mission control that provides a durable work queue, preventing different agents from claiming the same task simultaneously. By sitting between your coding harnesses and your repository, it ensures that every action is recorded in an append-only event spine for complete visibility.
Users interact with the system through a local-first setup that requires no accounts, utilizing a web dashboard, a native macOS app, or a CLI. It manages task lifecycles using atomic claims and leases, which automatically requeue tasks if a worker crashes. The system also provides shared memory through local embeddings, allowing agents to recall previous decisions and project context via MCP tools like search_memory and store_learning. This setup allows teams to track tool usage, reported costs, and detailed audit histories without sending data to a vendor cloud.
What you can do with it
- 1Preventing duplicate task executionAn AI client can claim a task from the durable queue to ensure no other agent picks up the same work.
- 2Maintaining long-term agent memoryDevelopers can provide agents with project-specific context and past decisions through semantic search.
- 3Monitoring a live agent fleetA developer can watch real-time tool calls and lease countdowns for all active agents in a single view.
Written from the project's README. Every use case is checked against a quote from it.
How to install Sugar MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Sugar MCP in Claude Code
$ claude mcp add sugar -- uvx sugaraiInstall Sugar MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"sugar": {
"command": "uvx",
"args": [
"sugarai"
]
}
}
}Install Sugar MCP in VS Code
.vscode/mcp.json
{
"servers": {
"sugar": {
"type": "stdio",
"command": "uvx",
"args": [
"sugarai"
]
}
}
}Install Sugar MCP in VS Code CLI
$ code --add-mcp '{"name":"sugar","type":"stdio","command":"uvx","args":["sugarai"]}'Install Sugar MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"sugar": {
"command": "uvx",
"args": [
"sugarai"
]
}
}
}Install Sugar MCP in Codex
$ codex mcp add sugar -- uvx sugaraiInstall Sugar MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.sugar] command = "uvx" args = ["sugarai"]
Install Sugar MCP in Gemini CLI
$ gemini mcp add -s user sugar uvx -- sugaraiInstall Sugar MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"sugar": {
"command": "uvx",
"args": [
"sugarai"
]
}
}
}Configuration
ANTHROPIC_API_KEYAnthropic API key for Claude model access
GITHUB_TOKENGitHub token for repository access
SUGAR_DEFAULT_REPODefault repository in owner/repo format
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachableroboticforce/sugar is public and reachablegithub.com/roboticforce/sugar ↗Pass
- Package names this repository as its sourcesugarai names roboticforce/sugar as sourcepypi.org/project/sugarai/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for sugaraipypi.org/project/sugarai/ ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-10github.com/roboticforce/sugar ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from sugaraiPass
- No critical advisory in the package or its dependencies37 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- 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 GitHubSugar
Mission control for your agent fleet.
One durable board for Claude Code, Codex, Cursor, Goose, OpenCode, DSH — and any harness that can claim a task. Atomic claims, live agent activity, cost attribution and tamper-evident history. Local-first, no account.
Quick start · See it work · Why Sugar · Works with · Docs · Team edition
Your agents can't see each other
You run four agents across three harnesses on one repo. Then:
- Two agents pick up the same task and overwrite each other's work.
- A crashed run keeps a task "claimed" forever; the queue quietly stalls.
- "What happened yesterday?" lives in six terminal tabs and a scrollback buffer.
- You can't answer who did what, with which harness, for which task — and what did it cost?
- Your agent starts every session with amnesia: last week's decisions, conventions and dead ends are gone.
A prettier kanban board doesn't fix this. The missing layer is underneath: a durable queue, atomic claims and leases, provenance for every actor, and a history you can replay and export. That's what Sugar is.
One board. Any harness. Full history.
Sugar is local-first infrastructure for a fleet of coding agents. Every harness gets the same durable work queue and the same memory. Every claim, transition and tool call lands in an append-only event spine. You watch the fleet in a web dashboard or a native macOS app — on your machine, in your files, with no account.
Your agents keep their own subscriptions and workflows. Sugar doesn't replace Claude Code or Codex; it sits between them and your repo.
Coordinate — a queue agents can't double-claim
- Durable SQLite queue with priorities, dependencies, attempts, hold/release and retries.
- Atomic claim + lease + heartbeat. If a worker dies, the lease expires and a reaper requeues the task.
- The same verbs from the CLI (
sugar add,sugar list,sugar run), MCP tools, REST API and dashboard. - Keep your existing board: serve Sugar's queue, or mirror a Hermes Kanban board with
--board kanban(Sugar reads it; Hermes keeps its write path).
See — Mission Control for the fleet
- Web dashboard and native macOS app, both on the same REST + SSE contract.
- Live floor: every working agent with its current action, elapsed/lease countdowns and lease health.
- Streaming console: tool calls, run starts/ends and usage events as they happen.
- Trends: throughput, failures, cycle time and reported spend over time, by agent, harness or project.
- Activity feed, search, filters and direct task links across all of it.
Prove — history with receipts
- Append-only event spine (
~/.sugar/events.db, retention configurable) records every task transition and every harness event: actor, harness, machine, session, task, project, run and trace id. - Usage and cost attribution (
sugar usage,/api/usage): tokens and cost as your harness reports them — no invented pricing table. - Tamper-evident audit exports (
sugar audit export/sugar audit verify): canonical JSONL plus a SHA-256 manifest and optional HMAC signature. Export before retention prunes, keep the evidence. - Claims are recorded in the same transaction as the work item, so "who is holding this task?" is a query, not a guess.
Connect — one board, many harnesses
- MCP servers for tasks and memory: Claude Code, Codex, Cursor, Goose, OpenCode and any MCP client can read context, claim work and complete it.
- REST + SSE for custom scripts, bots and CI.
- CLI for everything a human needs, including
sugar emitfor harnesses that stream their own telemetry. - TaskStore port + conformance suite: SQLite today; the contract is backend-agnostic.
Remember — your context, not the vendor's
- Project memory (
.sugar/memory.db) and global memory (~/.sugar/memory.db), with seven memory types: decisions, preferences, file context, error patterns, research, outcomes and guidelines. - Semantic search via local embeddings (
sugarai[memory]), with FTS5 keyword fallback. No external API calls. - Agents read and write memory directly through MCP:
search_memory,store_learning,recall,get_project_context,list_recent_memories.
Quick start
# Install once, use in any project
pipx install 'sugarai[all]'
cd ~/dev/my-app
sugar init
# Give the fleet work
sugar add "Fix the auth timeout" --type bug_fix --urgent
sugar add "Add profile settings" --type feature
# Watch it, or let Sugar run it
sugar dashboard --open
sugar run
Your agent gets memory and the board over MCP:
claude mcp add sugar -- sugar mcp memory
claude mcp add sugar-tasks -- sugar mcp tasks
# Other clients
sugar opencode setup # OpenCode, one command
goose configure # Goose: Add Extension -> Command-line -> sugar mcp memory
See your fleet work
The dashboard and app are only half the story — the Live view is the part that makes a fleet feel real. Harnesses stream their tool calls with one line each:
sugar emit --kind tool.invoked --task-id "$TASK_ID" \
--message "running pytest tests/test_api.py" --payload file=src/api.py
No harness wired up yet? The repo ships a simulator for demos:
git clone https://github.com/roboticforce/sugar.git && cd sugar
python scripts/demo_dashboard.py --serve --open # demo queue + dashboard
python scripts/simulate_agent_activity.py # live agents in a second shell
Trends need history; seed a throwaway spine and open the Trends view:
python scripts/seed_demo_trends.py --db /tmp/sugar-dashboard-demo/.sugar/events.db --reset
Full walkthrough: Mission Control · Telemetry · Trends
Works with your harnesses
Any harness that can run a CLI or speak MCP can use the board and the memory. The built-in runner
(sugar run) drives Claude Code through the Agent SDK today; the other harnesses keep doing their own thing
while Sugar coordinates them.
| Harness | Board (MCP / CLI / REST) | Shared memory | Notes |
|---|---|---|---|
| Claude Code | Yes | Yes | Built-in runner; plugin + Skills; full support |
| Codex | Yes | Yes | Via MCP/CLI; no runner coupling |
| Cursor | Yes | Yes | Via MCP |
| Goose | Yes | Yes | Via MCP extension |
| OpenCode | Yes | Yes | sugar opencode setup |
| Aider | Yes | Yes | Via CLI/MCP |
| Hermes Kanban | Yes | — | Mirror a board with --board kanban; Hermes owns writes |
| Custom scripts / bots | Yes | Yes | REST + SSE, or MCP |
Team edition (self-hosted)
The default dashboard binds loopback and needs no auth. For a team, run one board on a shared machine with scoped tokens — reads and writes, nothing in a vendor cloud:
cat ~/.sugar/board-tokens # name:scope:secret (scope: read | write; file must be 0600)
sugar dashboard --bind 0.0.0.0 --allow-remote --token-file ~/.sugar/board-tokens
The browser exchanges a one-time token for a SameSite=Strict cookie; API/SSE accept Authorization: Bearer.
Remote binds are refused without both --allow-remote and a token source, the foreign-Origin write guard
stays on, and TLS is expected from a reverse proxy. See Board Server for the threat
model and Caddy/nginx setup.
What teams get today: one live board, provenance, cost attribution, and audit exports. Approval policies, RBAC/SSO, quotas and a hosted relay are on the roadmap — tell us what your team needs.
Why Sugar
- Harness-neutral by design. You don't have to pick a winner. Claude Code, Codex, Cursor, Goose, OpenCode, DSH and your own scripts share one queue and one history.
- Local-first, not cloud-first. Task state, memory and the event spine are SQLite files on your disk. No account, no repo upload, no vendor in the loop. Remote mode is opt-in and self-hosted.
- Evidence beats dashboards. Any tool can show you a board. Sugar records the claim, the lease, the actor, the harness, the transitions and the spend — then lets you export and verify it.
- Durable, not demo-grade. Atomic claims, lease heartbeats, crash reaping, dependency gating and retries are tested against a backend-agnostic conformance suite.
- Open and inspectable. Dual-licensed AGPL-3.0 + commercial; the REST/SSE contract, event schema and adapter playbook are documented and versioned.
What Sugar is not: not a model vendor, not an agent runtime or cloud coding agent, not a code host, and not another kanban UI. It's the neutral layer underneath the harnesses you already chose.
Is this just a kanban board for agents? No. A board shows status; Sugar owns the queue, the claim/lease transaction, dependency gating, provenance and an append-only history. It can mirror a Hermes Kanban board, but it doesn't depend on one.
How is this different from Claude Code Agent Teams or a single-harness orchestrator? Those make one harness better at running its own agents. Sugar coordinates across harnesses and keeps the durable record. You can run Claude Code Agent Teams and still put their work on the same board as Codex.
Does Sugar send my code or data anywhere?
No. State is local SQLite by default; the dashboard binds loopback. Telemetry is what your harness explicitly
emits (sugar emit / POST /api/events), and audit exports are files you write yourself.
Do I need to change how my agents work? No. Add the MCP servers (tasks + memory) or use the CLI/REST API. The built-in runner is optional.
Is it production-ready? The 3.10 line is an early release: used daily, with a large test suite and CI across Linux/macOS/Windows, but expect rough edges. Start with a demo board or a side project, then move your real queue over.
Install
Recommended: pipx — one install, available everywhere:
pipx install 'sugarai[all]' # dashboard, memory search, MCP, GitHub, OpenCode
pipx upgrade sugarai
pip install 'sugarai[all]' # inside a venv
uv pip install 'sugarai[all]' # uv
pipx install sugarai # core only (keyword memory, no dashboard)
pipx install 'sugarai[dashboard]' # web dashboard + macOS app backend
pipx install 'sugarai[memory]' # semantic memory (local embeddings)
Native macOS app: latest release — or build it:
cd apps/macos && ./build-app.sh && open dist/SugarDash.app
Requirements: Python 3.11+, macOS 14+ for the app, and a CLI/MCP-capable coding agent if you want agents to claim work.
Also in the box
- Discovery — turn GitHub issues, error logs and code analysis into queue items.
- Autonomous runner —
sugar runclaims, executes, tests, commits and moves on;--ralphiterates until tests pass. - Orchestration — decompose a large task into a research → plan → implement → review workflow.
- Quality gates and hooks — pre/post-execution checks, file protection and command guardrails.
- Agent Skills —
sugar-memory,sugar-task-planner,sugar-quality-guardian,sugar-orchestrator, with evaluation data inskills/. - Claude Code plugin — slash commands and hooks via
.claude-plugin/. - Task types, learning and memory types — the boring machinery that makes repeated runs better.
Documentation
- Mission Control — dashboard, macOS app, event spine
- Local Dashboard API — frozen REST/SSE contract
- Trends · Telemetry · Usage & cost · Audit exports
- Board Server — team/remote access and TLS
- Storage Port · Adapters — backends and harness playbook
- Memory System · CLI Reference · Quick Start
- Agent Teams: market & validation · Business strategy
Status and roadmap
Sugar is an early 3.10 release. The stable parts: the task store contract, the event spine schema, the REST/SSE contract and the audit format. The moving parts: live telemetry wiring, remote/mobile access, approval policies and additional runners.
Next up, roughly in order: zero-config harness hooks (so Live lights up without manual sugar emit), pairing and
a mobile-friendly Mission Control, permission modes with ledger-recorded approvals, then a Postgres backend.
Ideas and bug reports are welcome — open an issue.
Contributing
git clone https://github.com/roboticforce/sugar.git
cd sugar && git checkout develop
uv pip install -e ".[dev,test,github,mcp]"
pytest tests/ -v
See CONTRIBUTING. PRs target develop; releases go to main.
License
Dual license: AGPL-3.0 + commercial.
- AGPL-3.0 — free for open source and personal use.
- Commercial license — for proprietary use. Contact RoboticForce or see LICENSE.
Sugar is provided "AS IS" without warranty. Review all AI-generated code before use.
Sugar MCP questions
How do I add Sugar MCP to Claude Code?
Run claude mcp add sugar -- uvx sugarai in your terminal. Add --scope user to make it available in every project.
How do I add Sugar MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Is Sugar just a kanban board for agents?
No. A board shows status; Sugar owns the queue, the claim/lease transaction, dependency gating, provenance and an append-only history. It can mirror a Hermes Kanban board, but it doesn't depend on one.
Does Sugar send my code or data anywhere?
No. State is local SQLite by default and the dashboard binds to loopback; telemetry is only what your harness explicitly emits.
Do I need to change how my agents work to use Sugar?
No. You add the MCP servers for tasks and memory, or use the CLI/REST API; the built-in runner is optional.
Which harnesses does Sugar work with?
Claude Code, Codex, Cursor, Goose, OpenCode, Aider and custom scripts or bots can all share the board and memory.
Is Sugar production-ready?
It is an early release used daily with a large test suite and cross-platform CI, but expect rough edges; start with a demo board before moving a real queue over.