decision-inbox-local
by BWBrook
README.md
# Decision Inbox
> **Retired (19 November 2026).** An experiment in structured decision questionnaires
> for Barry, hosted on ChatGPT Sites with a local MCP connector for agents. It was
> superseded by the agents' built-in question tools and is kept here as a record.
> Code is MIT licensed.
Private project questionnaires for Barry, hosted on Sites. Correspondence stays
unchanged: it remains the agents' discussion board.
## Human workflow
Open the inbox from any browser. Choose one option (radio buttons), several
(checkboxes), an alternative, or explicitly defer a question. No answer is
preselected. Drafts save to the service and can be resumed on another device.
Submit once ready; submitted answers are immutable. A changed decision belongs
in a follow-up questionnaire with a new request ID.
## Agent workflow
The reusable [decision guide](docs/decision-priming.md) includes a short priming
prompt and the complete creation, collection, and verification workflow for
both Claude and Codex sessions.
Priming introduces the capability for future feedback; it does not request a
questionnaire immediately.
The local `decision-inbox-local` connector exposes:
- `inbox_info`: check access and connection identity.
- `create_questionnaire(definition, repo_path)`: create immutable questions and
bind their project to the caller's local Git repository root.
- `list_questionnaires(project, archived)`: read statuses; drafts are not decisions.
- `collect_response(questionnaire_id, repo_path)`: verify the response hash, write
and read back JSON and Markdown in `docs/decisions/`, then acknowledge delivery.
The hosted `/mcp` also exposes creation, listing, question reads and submitted
response reads through the Site's private plugin. Local file delivery remains a
separate connector responsibility. Do not manually configure the hosted MCP as
a local Codex server; install its provisioned private plugin if desired.
Use the provided `examples/questionnaire.json`. Each question has 2–5 meaningful
options, `single` or `multiple` mode, and optional context/recommended IDs. Batches
support 1–60 questions, including 30-question sets. Label recommendations without
preselecting them. State what the answers will change. Distinguish preferences
from explicit approvals; stay inside the project's agreed scope. Preserve all
question wording, option labels, alternatives, comments and explicit deferrals.
`origin` identifies the project chat. `request_id` is stable for retries and must
change for new questions. Author attribution comes from the local connection's
`DECISION_INBOX_AUTHOR` (Claude or Codex); hosted tool authors are metadata.
## Lifecycle and deletion
Open → Submitted → Collected/Archived. Collection archives only after both local
files are written, synced and verified. Failed writes or acknowledgements can be
retried. Browser archive/restore is also available. Deleting an archived item
removes its hosted questions, draft and response; local files remain. A minimal
project/request-ID tombstone prevents an old retry recreating a deleted form.
There is one Site and one reusable questionnaire route, not separate Site objects.
No recurring job, automatic agent wakeup or automatic permanent deletion is used.
## Local connector setup
```sh
uv sync --directory connector
```
Connection file (permissions 0600): `~/.config/decision-inbox/config.json`:
```json
{"site_url":"https://YOUR-SITE","service_token":"PRIVATE-SITES-SERVICE-CREDENTIAL","agent_key":"APP-SERVICE-KEY"}
```
Keep these credentials out of source, prompts and browser code. Sites authenticates
machine requests at its private boundary; the application key adds an independent
check for agent routes. Human draft/submission/archive/deletion routes require
forwarded signed-in identity and same-origin browser requests. Machine callers
cannot submit on Barry's behalf or delete forms.
Run `connector/.venv/bin/python connector/inbox_connector.py` as a stdio MCP server
with `DECISION_INBOX_AUTHOR=Codex` or `Claude` and an optional explicit
`DECISION_INBOX_CONFIG` path. There is no default author: an unset, empty, or
invalid value stops the connector before it reads credentials, contacts the
service, or writes project bindings. It also supports no-model CLI operations `info`,
`create`, `list`, `collect`, taking a JSON argument object on stdin.
Project bindings are kept beside the connection file. A project cannot silently
switch to a different repo. Destinations are selected locally, not by remote data;
symlink escapes and differing existing files are rejected. Redirects are refused
so credentials cannot be forwarded to a different host.
## Development and verification
The portable Sites starter uses npm and D1 (`DB`). Preserve its build integration.
```sh
npm run db:generate
node /Users/bwbrook/.codex/plugins/cache/openai-curated-remote/sites/0.1.75/scripts/build-site.mjs
npx tsc --noEmit
node --experimental-strip-types --test tests/contracts.test.mjs
```
Apply generated migrations to the local preview using the command documented in
`docs/verification.md`. `tests/integration.py` is explicitly restricted to loopback
and simulates human identity only there. It tests both actual MCP transports,
CAS draft conflicts, duplicate creation, identity/origin rejection, response
checksums, failed delivery/retry, archive/restore and deletion tombstones. It never
submits production answers. Browser checks cover saved progress and all answer
modes. See `docs/verification.md` for the verified release evidence and limitations.
Sites publishing uses `.openai/hosting.json` and the private native workflow.
Never put runtime values or actual Cloudflare resource IDs in that manifest.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues