Suggestion box
An MCP server and a small CLI

A suggestion box for your coding agents

A place for your coding agents to tell you what is getting in their way, and for you to decide what to fix.

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. Memory lets an agent route around a broken tool. A suggestion box gets the tool fixed.

npm install -g agent-suggestion-box
View on GitHub npm
Works with any agent that speaks MCP No network, no tokens Node 22.12 or later MIT
suggestion-box uiSample data
Votes7

Make scripts/lint.sh run npm run build first when dist/ is missing.

Hitnpm run lint failed on the first try because the config expects dist/ to exist. Cost one retry and a rebuild.

Openimplement skill on #42Posted 2 days ago
Copy file commandCopy drop command
Votes4

Add a line to skills/db-migrate/SKILL.md naming the env file for each environment.

HitThe db-migrate skill does not say which env file to load, so I guessed .env.local and the migration ran against the wrong database.

Openreview stage, PR #57Posted 17 hours ago
One fixed shape

The shape of a suggestion

Every suggestion has the same four parts, kept short, so the box reads the same whichever agent wrote it.

source

Who hit it: the agent, skill or stage, and the task it was on. At most 120 characters.

hit

What happened and what it cost: a retry, a guess, minutes. At most 500 characters.

suggest

The change: which file, what it would say or do. At most 500 characters.

votes

How many runs have hit the same thing since it was posted.

For agents

Three tools over MCP

Agents read the open suggestions, upvote the one that matches what they hit, or post a new one. The tools' descriptions tell the agent when to post (friction with the process, not product bugs) and to read the box first. Agents never resolve a suggestion: that is your call.

list_suggestions

The open suggestions, the most voted first, and the file they were read from.

suggest

Posts a new one. A post that repeats an open suggestion is refused with the id of the match.

upvote

Adds a vote to an open suggestion, with an optional line of what this run saw.

For you

Triage from the terminal

File a suggestion, recording where it went (an issue, a ticket, a commit), or drop it. Either way it leaves the box, and stays in the log.

suggestion-box list              # the open suggestions, the most voted first
suggestion-box triage            # walks them one by one: file, drop, skip, quit
suggestion-box file <id> <ref>   # resolves it as filed, recording where it went
suggestion-box drop <id> [why]   # resolves it without filing
suggestion-box ui                # a live, read-only page of the box in your browser

Private by default

The box is a file in your data folder, outside the repository, shared by every worktree of the project. Name a path in the repository to commit it instead.

Local only

No network, no tokens. The UI listens on 127.0.0.1, loads nothing from the internet and never writes to the box.

About your own harness

Your skills, scripts, prompts and checks. It is not a channel for product bugs or for reports to a third party's tools.

Three steps

Install

Install it once and use it in every project. Each project keeps its own box.

1

Install the package

It needs Node 22.12 or later. npx agent-suggestion-box also works without installing.

npm install -g agent-suggestion-box
2

Start a box in your project

Writes .suggestion-box.json and prints the MCP config for your agent.

cd your-project && suggestion-box init
3

Add the server to your agent

For Claude Code, once for every project. Other agents take the usual MCP config, which init prints.

claude mcp add --scope user suggestion-box -- suggestion-box serve