{"id":48791434,"url":"https://github.com/igmagollo/suggestion-box","last_synced_at":"2026-04-13T20:04:37.488Z","repository":{"id":343605482,"uuid":"1178384324","full_name":"igmagollo/suggestion-box","owner":"igmagollo","description":"Feedback registry MCP for coding agents — captures friction, feature requests, and observations with embedding-based dedup, voting, and GitHub issue publishing.","archived":false,"fork":false,"pushed_at":"2026-03-11T03:15:49.000Z","size":75,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-11T07:34:56.655Z","etag":null,"topics":["ai-agents","claude-code","codex","developer-tools","feature-requests","feedback","mcp"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/igmagollo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T01:11:47.000Z","updated_at":"2026-03-11T03:00:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/igmagollo/suggestion-box","commit_stats":null,"previous_names":["igmagollo/suggestion-box"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/igmagollo/suggestion-box","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igmagollo%2Fsuggestion-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igmagollo%2Fsuggestion-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igmagollo%2Fsuggestion-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igmagollo%2Fsuggestion-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/igmagollo","download_url":"https://codeload.github.com/igmagollo/suggestion-box/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igmagollo%2Fsuggestion-box/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31768708,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T15:25:13.801Z","status":"ssl_error","status_checked_at":"2026-04-13T15:25:09.162Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","codex","developer-tools","feature-requests","feedback","mcp"],"created_at":"2026-04-13T20:04:36.861Z","updated_at":"2026-04-13T20:04:37.478Z","avatar_url":"https://github.com/igmagollo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# suggestion-box\n\n[![suggestion-box](https://img.shields.io/badge/feedback-suggestion--box-blue)](https://github.com/igmagollo/suggestion-box)\n\nA 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.\n\n## The problem\n\nWhen 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.\n\n## How it works\n\n```\nAgent hits friction → submits feedback → similar? auto-votes → human reviews → publishes GitHub issue\n```\n\n- **Friction reports** — \"I couldn't do X because of Y\"\n- **Feature requests** — \"Tool X should support Y\"\n- **Observations** — \"This pattern is suboptimal\"\n\nEach 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.\n\n## Demo\n\n![suggestion-box demo](demo/demo.gif)\n\nRe-record with [VHS](https://github.com/charmbracelet/vhs): `vhs demo/demo.tape`\n\n## Install\n\nNo special runtime required — the published package runs on **Node.js** (v18+).\n\n```bash\nnpx @igmagollo/suggestion-box init .\n```\n\n### Homebrew (macOS) — coming soon\n\nOnce the tap is published, you'll be able to install with:\n\n```bash\nbrew install igmagollo/tap/suggestion-box\nsuggestion-box init .\n```\n\nSee [docs/homebrew-setup.md](docs/homebrew-setup.md) for tap setup details.\n\nThis creates a `.suggestion-box/` data directory (local SQLite + vector DB), configures your coding agents, and updates `.gitignore`. Restart your agent to activate.\n\n## Cross-agent compatibility\n\n`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.\n\n| Agent | Config files created | Notes |\n|-------|---------------------|-------|\n| **Claude Code** | `.mcp.json` + `.claude/settings.json` | SessionStart hook prompts the agent to use suggestion-box proactively |\n| **Codex** | `.codex/config.toml` | Sees the MCP tools; no hook support |\n| **OpenCode** | `opencode.json` | Sees the MCP tools; no hook support |\n\n**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.\n\n**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.\n\n## MCP Tools\n\nAgents get these tools automatically:\n\n| Tool | Description |\n|------|-------------|\n| `suggestion_box_submit_feedback` | Submit friction, feature request, or observation. Auto-deduplicates via embeddings. |\n| `suggestion_box_upvote_feedback` | Vote on existing feedback with evidence and impact estimates. |\n| `suggestion_box_list_feedback` | Browse and filter feedback by category, target, status. |\n| `suggestion_box_dismiss_feedback` | Soft-delete feedback that's no longer relevant. |\n| `suggestion_box_publish_to_github` | Publish feedback as a GitHub issue via `gh` CLI. |\n| `suggestion_box_status` | Overview stats: counts, top voted, total estimated impact. |\n\n## CLI\n\n```bash\nsuggestion-box serve                # Start MCP server (default)\nsuggestion-box init [dir]           # Set up for a project\nsuggestion-box status               # Overview\nsuggestion-box list [--category X] [--status X] [--target X]\nsuggestion-box submit               # Submit feedback from the CLI\nsuggestion-box publish \u003cid\u003e [repo]  # Publish as GitHub issue\nsuggestion-box dismiss \u003cid\u003e         # Dismiss feedback\nsuggestion-box purge                # Delete dismissed entries\nsuggestion-box help\n```\n\n## Review workflow\n\n```bash\n# See what agents have been reporting\nsuggestion-box list\n\n# Publish the good ones to GitHub\nsuggestion-box publish \u003cid\u003e owner/repo\n\n# Dismiss the rest\nsuggestion-box dismiss \u003cid\u003e\n```\n\nOr do it conversationally — ask your agent to list feedback, review together, and publish the ones you approve.\n\n## Built with suggestion-box\n\nThe issues below were actually filed by AI agents using suggestion-box while developing this project:\n\n- [#84 — Publish flow requires two-step manual intervention](https://github.com/igmagollo/suggestion-box/issues/84) (feature request)\n- [#107 — Demo GIF for README](https://github.com/igmagollo/suggestion-box/issues/107) (feature request)\n- [#108 — Homebrew formula for CLI distribution](https://github.com/igmagollo/suggestion-box/issues/108) (feature request)\n- [#111 — Doctor command for troubleshooting](https://github.com/igmagollo/suggestion-box/issues/111) (feature request)\n- [#113 — Configurable feedback categories](https://github.com/igmagollo/suggestion-box/issues/113) (feature request)\n- [#116 — README badge showing feedback count](https://github.com/igmagollo/suggestion-box/issues/116) (feature request)\n\nThese 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).\n\n## Environment variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SUGGESTION_BOX_DIR` | Data directory path | `.suggestion-box` |\n| `SUGGESTION_BOX_MODEL` | Embedding model override | `Xenova/all-MiniLM-L6-v2` |\n\n## How dedup works\n\nEach 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.\n\n## Runtime compatibility\n\nThe 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.\n\n[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`.\n\n## Known limitations\n\n### CLI commands and the MCP server cannot run at the same time\n\nsuggestion-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.\n\n**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.\n\n**Workaround:** use MCP tools through your agent while the server is active:\n\n| CLI command | MCP tool equivalent |\n|-------------|---------------------|\n| `status` | `suggestion_box_status` |\n| `list` | `suggestion_box_list_feedback` |\n| `submit` | `suggestion_box_submit_feedback` |\n| `dismiss` | `suggestion_box_dismiss_feedback` |\n| `publish` | `suggestion_box_publish_to_github` |\n| `triage` | `suggestion_box_triage` |\n\nOr stop the MCP server (end your agent session) first, then use the CLI.\n\nCLI commands that don't touch the database (`init`, `uninit`, `hook`, `serve`, `doctor`, `help`) always work normally.\n\nA future version may add a CLI-to-server communication channel to remove this restriction.\n\n## Badge\n\nUsing suggestion-box? Add the badge to your README:\n\n```markdown\n[![suggestion-box](https://img.shields.io/badge/feedback-suggestion--box-blue)](https://github.com/igmagollo/suggestion-box)\n```\n\n## Acknowledgments\n\nInspired 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.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figmagollo%2Fsuggestion-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figmagollo%2Fsuggestion-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figmagollo%2Fsuggestion-box/lists"}