agent-suggestion-box
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
agent-suggestion-box
Status: v0.1. The three MCP tools, the CLI, the file store and the read-only UI work and are tested. It is young, so expect changes before 1.0. The settled decisions are in
docs/adr/.
A place for your coding agents to tell you what is getting in their way, and for you to decide what to fix. The short tour is at kaiosilveira.github.io/agent-suggestion-box.
Agents run into the same friction run after run: a script that fails on the first try, a skill that leaves them guessing, a check that flakes, a helper that is missing. Memory lets an agent route around a broken tool; a suggestion box gets the tool fixed. (Thoughtworks Technology Radar, vol. 35, "Agent suggestion box", Assess; see also "Feedback flywheel".)
agent-suggestion-box is an MCP server and a small CLI:
Agents read the open suggestions, upvote the one that matches what they hit, or post a new one, in a fixed shape.
You triage the box from the terminal: file a suggestion (record where it went: an issue, a ticket, a commit), or drop it. Either way it leaves the box.
The box is a file private to you, outside your repository, shared by its worktrees. Stores are pluggable, so it can live elsewhere later.
It works with any agent that speaks MCP (Claude Code, Codex, OpenCode, Cursor…), and it is about your own harness: your skills, scripts, prompts and checks. It is not a channel for reporting bugs to a third party's MCP server.
Install
It needs Node 22.12 or later. Install it once and use it in every project:
npm install -g agent-suggestion-box
cd your-project && suggestion-box init
claude mcp add --scope user suggestion-box -- suggestion-box serve # Claude Code, for every projectOr run it without installing: npx agent-suggestion-box <command>. Other agents take the usual MCP config, which init
prints; see examples/claude-code.md for Claude Code.
Each project keeps its own box. The server finds the project it was started in: --root <dir>, else SUGGESTION_BOX_ROOT,
else the nearest .suggestion-box.json or .git above it. Every git worktree of a repository shares the main worktree's
box.
Related MCP server: ai-agent-channel
The shape of a suggestion
Every suggestion has the same four parts, kept short:
Field | What it holds |
| who hit it: the agent, skill or stage, and the task it was on ( |
| what happened and what it cost: a retry, a guess, minutes; at most 500 characters |
| the change: which file, what it would say or do; at most 500 characters |
| how many runs have hit the same thing since it was posted |
For agents: the MCP tools
Tool | Does |
| the open suggestions, the most voted first, and the file they were read from |
| posts a new one ( |
| adds a vote to an open suggestion, with an optional line of what this run saw |
Agents never resolve suggestions: that is the human's call. The tools' descriptions tell the agent when to post (friction with
the process, not product bugs) and to read the box before posting. Set SUGGESTION_BOX_SOURCE in the server's environment
to name the source when the agent leaves it out (a loop, a stage, a CI job).
For you: the CLI
suggestion-box init # writes .suggestion-box.json and prints the MCP config to add to your agent
suggestion-box serve # the MCP server over stdio (what your agent starts)
suggestion-box list [--json] # the open suggestions, the most voted first
suggestion-box ui # a live page of the box in your browser (127.0.0.1:4848)
suggestion-box triage # walks them one by one: [f]ile, [d]rop, [s]kip, [q]uit
suggestion-box file <id> <ref> # resolves it as filed, recording where it went (an issue URL, a ticket, a commit)
suggestion-box drop <id> [why] # resolves it without filingEvery command takes --root <dir> to name the project instead of finding it from the current directory.
The UI
suggestion-box ui opens a page of the box: what is open, the most voted first, and what was filed (with where it went) or
dropped (with why). It updates as agents post, searches every field, and works in light and dark. It is read-only: each
open suggestion has buttons that copy its file and drop commands for the terminal.
It listens on 127.0.0.1 only and loads nothing from the internet. --port <n> picks the port, --no-open only prints the
address. See ADR 7.
Stores
Store | The box is | A vote is | Resolved is | Status |
| a | an event line | an event line | v0.1 |
Every store implements one port (src/store/store.ts) and passes one contract suite (src/store/contract.ts), so a
new store (GitHub, Slack, a database…) plugs in without touching the domain, the MCP server or the CLI. See
docs/adr/0005.
Configuration
.suggestion-box.json at the repository's root:
{
"store": "file",
"file": { "path": ".suggestion-box/suggestions.jsonl" }
}Both fields are optional. With no file.path, the box is private to you, outside the repository:
<data folder>/suggestion-box/<project>-<hash>/suggestions.jsonl, the data folder being XDG_DATA_HOME, else
~/Library/Application Support (macOS), %LOCALAPPDATA% (Windows) or ~/.local/share. Every worktree of the repository shares
it, and list_suggestions names the file it read. Name a path in the repository to commit the box instead; init then adds a
union merge rule for it. No network, no tokens. See docs/adr/0009.
Set SUGGESTION_BOX_FILE to put the file elsewhere on one machine (absolute, or against the project root); it wins over the config.
Layout
agent-suggestion-box/
├── src/
│ ├── domain/
│ │ ├── suggestion.ts # the Suggestion and its rules (shape, limits, open/filed/dropped)
│ │ └── duplicate.ts # the cheap duplicate check `suggest` runs before posting
│ ├── store/
│ │ ├── store.ts # the port: list, post, upvote, resolve
│ │ ├── contract.ts # one suite every store passes (called from each store's tests)
│ │ ├── file-store.ts # an append-only JSONL log of events
│ │ ├── open.ts # the store the config names
│ │ └── ulid.ts # suggestion ids
│ ├── mcp/
│ │ └── server.ts # the three tools, over stdio
│ ├── cli/
│ │ ├── main.ts # the suggestion-box binary
│ │ └── run.ts # init, serve, list, ui, triage, file, drop
│ ├── ui/
│ │ ├── server.ts # the read-only page and /api/suggestions, on 127.0.0.1
│ │ └── page.ts # the page: markup, styles and script inline
│ ├── config.ts # finds the project, reads .suggestion-box.json and places the box
│ ├── format.ts # how a suggestion reads in a terminal and to an agent
│ └── version.ts # the package's version, read from package.json
├── docs/
│ ├── design.md # the model, the port, the store, the MCP server
│ └── adr/ # one page per lasting decision, Nygard's format
├── examples/
│ └── claude-code.md # the MCP config and a line for CLAUDE.md or a skill
├── site/
│ └── index.html # the project's page, deployed to GitHub Pages by .github/workflows/pages.yml
├── CONTRIBUTING.md # the setup, how changes are made, how to add a store
├── package.json
├── tsconfig.json # tsconfig.build.json leaves the tests out of dist/
└── README.mdEach module's tests sit next to it as *.test.ts.
Roadmap
v0.1: the three tools, the CLI, the
filestore, the read-onlyui.v0.2:
triage --agent, a model that groups duplicates and drafts the issue (the radar's second, deduplicating agent).Later: more stores (GitHub, Slack);
stats(what got fixed, votes before it was).
Development
npm install
npm test # vitest
npm run typecheck
npm run build # to dist/
npm run dev -- list # run the CLI from source
npm link # put this checkout's suggestion-box on your PATH, as a global install wouldSee CONTRIBUTING.md for how changes are made and how to add a store.
Licence
MIT.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Comment on AI-generated webpages; feedback flows back to your coding agent. Free, MIT, local-first.
One shared project for a team's coding agents: decisions, a task board and handoffs.
Team knowledge base for snippets, API calls and docs. Agents search and file items; humans review.
A shared backlog for the out-of-scope work your coding agents find.
Related MCP Servers
- AlicenseAqualityDmaintenanceLocal-first project memory for AI coding agents. Records failed attempts, fragile files, and decisions per repo, and warns the agent via hooks before it repeats a recorded mistake.669 npmMIT
- AlicenseAqualityBmaintenanceLets separate coding-agent sessions coordinate through a shared, role-addressed mailbox instead of a human relaying every message, over a single local SQLite file or a hosted server with many isolated channels. Messages can be sent as tracked obligations that stay open until one side resolves and the other confirms, alongside threads, full-text search, work statuses, and an append-only versioned pin system where protected changes require recorded agreement from every declared role.41MIT

miloopsofficial
AlicenseNot gradedqualityBmaintenanceTurns a local repo into a command center where AI coding agents run missions as decision tickets, surface every question into one inbox for the human to answer, and record decisions, rationale, and live token spend. Missions stay as plain markdown files on your machine, and any MCP-capable coding agent (Claude Code, Codex) can connect and work them.2MIT- AlicenseBqualityBmaintenanceLocal harness for Codex, Claude Code, opencode and other coding agents: agents record pitfalls and design decisions as Markdown files reviewed in the same PR as the code, and route only task-related records to the next agent.516GPL 3.0