https://github.com/igmagollo/suggestion-box
Feedback registry MCP for coding agents — captures friction, feature requests, and observations with embedding-based dedup, voting, and GitHub issue publishing.
https://github.com/igmagollo/suggestion-box
ai-agents claude-code codex developer-tools feature-requests feedback mcp
Last synced: 2 months ago
JSON representation
Feedback registry MCP for coding agents — captures friction, feature requests, and observations with embedding-based dedup, voting, and GitHub issue publishing.
- Host: GitHub
- URL: https://github.com/igmagollo/suggestion-box
- Owner: igmagollo
- License: mit
- Created: 2026-03-11T01:11:47.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-11T03:15:49.000Z (4 months ago)
- Last Synced: 2026-03-11T07:34:56.655Z (3 months ago)
- Topics: ai-agents, claude-code, codex, developer-tools, feature-requests, feedback, mcp
- Language: TypeScript
- Homepage:
- Size: 73.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# suggestion-box
[](https://github.com/igmagollo/suggestion-box)
A feedback registry MCP for coding agents. Agents proactively report friction, feature requests, and observations as they work. Feedback is deduplicated via embeddings, accumulates votes and impact evidence, and can be published as GitHub issues after human review.
## The problem
When agents and subagents work, they constantly hit friction — tools that fall short, missing features, confusing APIs, insufficient context. That insight evaporates when the session ends. Suggestion-box captures it systematically, creating a feedback loop for improving your agent workspace over time.
## How it works
```
Agent hits friction → submits feedback → similar? auto-votes → human reviews → publishes GitHub issue
```
- **Friction reports** — "I couldn't do X because of Y"
- **Feature requests** — "Tool X should support Y"
- **Observations** — "This pattern is suboptimal"
Each submission includes impact estimates (tokens saved, time saved) for prioritization. Embeddings detect duplicates automatically — if two agents report the same issue, the second becomes a vote instead of a duplicate.
## Demo
Re-record with [VHS](https://github.com/charmbracelet/vhs): `vhs demo/demo.tape`
## Install
No special runtime required — the published package runs on **Node.js** (v18+).
```bash
npx @igmagollo/suggestion-box init .
```
### Homebrew (macOS) — coming soon
Once the tap is published, you'll be able to install with:
```bash
brew install igmagollo/tap/suggestion-box
suggestion-box init .
```
See [docs/homebrew-setup.md](docs/homebrew-setup.md) for tap setup details.
This creates a `.suggestion-box/` data directory (local SQLite + vector DB), configures your coding agents, and updates `.gitignore`. Restart your agent to activate.
## Cross-agent compatibility
`suggestion-box init` configures **Claude Code**, **Codex**, and **OpenCode** automatically. All three share the same `.suggestion-box/` database, so feedback submitted by one agent is visible to all others.
| Agent | Config files created | Notes |
|-------|---------------------|-------|
| **Claude Code** | `.mcp.json` + `.claude/settings.json` | SessionStart hook prompts the agent to use suggestion-box proactively |
| **Codex** | `.codex/config.toml` | Sees the MCP tools; no hook support |
| **OpenCode** | `opencode.json` | Sees the MCP tools; no hook support |
**SessionStart hook**: The `.claude/settings.json` hook fires at the start of every Claude Code session, reminding the agent to submit feedback as it works. Codex and OpenCode don't support session hooks — agents will still have access to the tools, but won't get the proactive prompt unless instructed in their system prompt or rules.
**Shared database**: All agents read and write the same `.suggestion-box/` directory. Dedup, votes, and impact estimates work across agents — if Claude Code reports an issue and Codex hits the same friction later, the second submission becomes a vote on the first.
## MCP Tools
Agents get these tools automatically:
| Tool | Description |
|------|-------------|
| `suggestion_box_submit_feedback` | Submit friction, feature request, or observation. Auto-deduplicates via embeddings. |
| `suggestion_box_upvote_feedback` | Vote on existing feedback with evidence and impact estimates. |
| `suggestion_box_list_feedback` | Browse and filter feedback by category, target, status. |
| `suggestion_box_dismiss_feedback` | Soft-delete feedback that's no longer relevant. |
| `suggestion_box_publish_to_github` | Publish feedback as a GitHub issue via `gh` CLI. |
| `suggestion_box_status` | Overview stats: counts, top voted, total estimated impact. |
## CLI
```bash
suggestion-box serve # Start MCP server (default)
suggestion-box init [dir] # Set up for a project
suggestion-box status # Overview
suggestion-box list [--category X] [--status X] [--target X]
suggestion-box submit # Submit feedback from the CLI
suggestion-box publish [repo] # Publish as GitHub issue
suggestion-box dismiss # Dismiss feedback
suggestion-box purge # Delete dismissed entries
suggestion-box help
```
## Review workflow
```bash
# See what agents have been reporting
suggestion-box list
# Publish the good ones to GitHub
suggestion-box publish owner/repo
# Dismiss the rest
suggestion-box dismiss
```
Or do it conversationally — ask your agent to list feedback, review together, and publish the ones you approve.
## Built with suggestion-box
The issues below were actually filed by AI agents using suggestion-box while developing this project:
- [#84 — Publish flow requires two-step manual intervention](https://github.com/igmagollo/suggestion-box/issues/84) (feature request)
- [#107 — Demo GIF for README](https://github.com/igmagollo/suggestion-box/issues/107) (feature request)
- [#108 — Homebrew formula for CLI distribution](https://github.com/igmagollo/suggestion-box/issues/108) (feature request)
- [#111 — Doctor command for troubleshooting](https://github.com/igmagollo/suggestion-box/issues/111) (feature request)
- [#113 — Configurable feedback categories](https://github.com/igmagollo/suggestion-box/issues/113) (feature request)
- [#116 — README badge showing feedback count](https://github.com/igmagollo/suggestion-box/issues/116) (feature request)
These were all captured automatically during development — no manual issue filing needed. See the full set of agent-filed issues at [#84–#131](https://github.com/igmagollo/suggestion-box/issues?q=is%3Aissue+label%3Asuggestion-box).
## Environment variables
| Variable | Description | Default |
|----------|-------------|---------|
| `SUGGESTION_BOX_DIR` | Data directory path | `.suggestion-box` |
| `SUGGESTION_BOX_MODEL` | Embedding model override | `Xenova/all-MiniLM-L6-v2` |
## How dedup works
Each feedback submission is embedded using a local model (384-dim, runs on CPU, no API key). When new feedback arrives, it's compared against existing open entries. If cosine similarity exceeds 0.85, the submission becomes a vote on the existing entry instead of creating a duplicate. Impact estimates accumulate across votes.
## Runtime compatibility
The published npm package is bundled for **Node.js** — `npx` works out of the box, no bun required. The CLI shebang is `#!/usr/bin/env node` in the published build, and all MCP config generated by `init` uses `npx -y @igmagollo/suggestion-box@latest` as the command.
[Bun](https://bun.sh/) is only needed for **development** (building from source). If you clone the repo to contribute, install bun and run `bun run build`.
## Known limitations
### CLI commands and the MCP server cannot run at the same time
suggestion-box uses an embedded [libSQL](https://github.com/tursodatabase/libsql) database. The libSQL driver acquires an **exclusive file lock** at connect time — before any WAL or busy-timeout pragma can be applied. This is a documented limitation of the driver: it does not support multi-process access.
**In practice:** while the MCP server is running (i.e., your coding agent session is active), CLI commands that need database access (`status`, `list`, `submit`, `dismiss`, `publish`, `triage`, `review`, `purge`) will fail with a lock error and print a helpful message.
**Workaround:** use MCP tools through your agent while the server is active:
| CLI command | MCP tool equivalent |
|-------------|---------------------|
| `status` | `suggestion_box_status` |
| `list` | `suggestion_box_list_feedback` |
| `submit` | `suggestion_box_submit_feedback` |
| `dismiss` | `suggestion_box_dismiss_feedback` |
| `publish` | `suggestion_box_publish_to_github` |
| `triage` | `suggestion_box_triage` |
Or stop the MCP server (end your agent session) first, then use the CLI.
CLI commands that don't touch the database (`init`, `uninit`, `hook`, `serve`, `doctor`, `help`) always work normally.
A future version may add a CLI-to-server communication channel to remove this restriction.
## Badge
Using suggestion-box? Add the badge to your README:
```markdown
[](https://github.com/igmagollo/suggestion-box)
```
## Acknowledgments
Inspired by [memelord](https://github.com/glommer/memelord) — persistent memory with reinforcement learning for coding agents. Suggestion-box follows similar patterns (local Turso DB, embeddings, MCP tools) but focuses on feedback collection rather than memory retention.
## License
MIT