Chopin: a GitHub Next prototype for repository-grounded planning documents

The problem Chopin targets: plans that drift from the code

Implementation plans, technical specifications, RFCs, proposals and decision records usually live away from the repository they describe. They go stale, and the reasoning behind a choice gets flattened into prose that a later rewrite can quietly contradict. Chopin, a GitHub Next research prototype, is aimed at that gap: a channel combines one repository-connected document with its collaboration context, and a hosted agent named Planner reads the selected repository, proposes changes, and asks the team when the code cannot settle a choice. The README states the split plainly: people shape the document and own its decisions.

The audience is narrow. The README says there is no public Chopin instance for general use, so you run it locally or host it yourself. That means a team willing to register a GitHub App, run PostgreSQL, and accept the prototype's operational limits. It is not a tool for a writer who wants a hosted editor, and it is not a replacement for a code review workflow.

How a channel, its document and its Decisions fit together

A channel holds three things. Chat is shared by the team and the hosted agent; ordinary messages do not start an agent turn, though they can enter its bounded context, and typing @chopin asks Chopin to act. Document is a multiplayer rich-text artifact backed by restricted MDX, labelled Plan in the current interface, where people and the agent edit the same document with presence, cursors, and transient markers for recent agent changes. Decisions retain attributed questionnaire answers and accepted comments separately from the prose they produced, so a later rewrite cannot silently change what the team decided. That separation is the most interesting design choice here: the prose is editable, the record of what was agreed is not folded into it.

Research is a separate path. Typing /research in a document starts one durable request from the exact brief and leaves an inline progress card in place. Completed research publishes as an ordinary child document beneath its parent, with its own document, Chat, and Decisions. Pending, failed and cancelled requests never appear as documents in navigation. The Planner itself inspects the selected GitHub repository and its pull requests through bounded, read-only tools. It cannot write to GitHub, edit a checkout, or implement code. A separate coding agent can connect through MCP to create documents or consume an approved implementation graph. The README notes the document model supports broader artifacts while the current Planner prompt and tool vocabulary remain optimized for planning.

Running Chopin locally with Bun and Docker Compose

The development path needs Bun 1.3.2, Docker Engine with Docker Compose for PostgreSQL, a GitHub App owned by the deployment, and a GitHub account with push or administration access to a test repository plus an active Copilot entitlement to use the Planner. Register three local URLs on the App: homepage http://127.0.0.1:8787, callback http://127.0.0.1:8787/auth/github/callback, and setup URL http://127.0.0.1:8787/auth/github/setup. Enable expiring user authorization tokens, disable OAuth during installation, disable webhooks, and grant read access to Contents, Pull requests, Checks and Commit statuses. The README points to docs/authentication.md for the exact App settings.

Install, configure and start the app with the commands the README gives:

bun install
cp .env.example .env
openssl rand -hex 32
# Fill in the GitHub App values and generated session key in .env.
bun run db:up
bun run migrate
bun run dev

The generated value goes into SESSION_ENCRYPTION_KEY, which the .env.example comments describe as encrypting only the short-lived OAuth state and PKCE cookie. The same file sets STORAGE_DRIVER=postgres, AGENT=on, MODEL=claude-sonnet-4.6, BACKGROUND_JOBS=on and WEB_RESEARCH=on as defaults, with GITHUB_ALLOWED_USERS and GITHUB_ALLOWED_ORGANIZATIONS left empty to admit every authenticated GitHub user. Then open http://127.0.0.1:8787, sign in, install or update the GitHub App when the repository picker asks, select a repository and create a channel. Opening the channel in a second browser profile shows the multiplayer path. Ctrl-C stops the development supervisor, and bun run db:down tears down the local Compose project. Setting AGENT=off prevents Planner turns and disables the background-job runner, but the README notes this does not disable the /mcp endpoint used by external coding agents.

What @chopin actually does in the composer

The composer treats @chopin as an instruction for the Planner, and the README gives this example exchange:

should we cover the export format?     -> channel chat transcript
yes, Markdown for now                  -> channel chat transcript
@chopin                                -> act on the recent conversation
@chopin draft the export section       -> act on that request
@chopin compare #Release plan          -> read another document, then respond here

The detail worth noticing is context. The recent channel chat transcript is supplied as bounded context for the next turn even when those messages did not address the Planner, so ordinary conversation is not inert. That is convenient and also a privacy boundary: the README states document and Chat context, along with repository material selected by the Planner, is sent to GitHub Copilot during a turn, and that model-backed background jobs send job-specific private material to isolated Copilot workers. The public research worker receives only the exact submitted brief, though it may derive or refine the queries it sends to web search. GitHub credentials remain process-local; documents, transcripts, decisions, research request staging, background-job inputs and artifacts, and token-free session records live in PostgreSQL.

Boundaries that decide whether Chopin fits

Chopin supports GitHub.com only; GitHub Enterprise Server endpoints are not configurable. The Planner's file, tree and history tools read the default branch captured when its session starts, and code search is repository-scoped. It never reads a local checkout or uncommitted changes, which means a plan written against a working tree you have not pushed is grounded in something else entirely. If your planning depends on uncommitted work, this is the wrong tool.

Access is layered in a way that surprises people. Every browser participant signs in, passes the instance admission policy, and needs repository access through the GitHub App installation. MCP callers also pass instance admission but use their own bearer token for repository authorization instead of the App installation. A public repository does not make its Chopin channels public. Pull access can view channels; push or administration access is required to create or change them and to invoke the Planner. The first eligible person to invoke the Planner or start a model-backed research request supplies the GitHub App user token and Copilot entitlement used for that channel, and a server restart signs everyone out and releases that ownership. That ownership model is a real operational constraint, not a footnote. Add the README's statement that one Chopin process may write to a database at a time, with no horizontal application scaling and no zero-downtime rolling deployment, and the deployment shape is fixed: a single writer behind a restart that interrupts everyone.

Where Chopin sits next to other planning tools

The obvious comparison is a plain Markdown file in the repository with a pull request, or a wiki page. Those are durable and free, but they have no repository-grounded agent and no separate record of decisions, so the reasoning behind a choice lives only in prose and review comments. Chopin's difference is the channel: a multiplayer MDX document, a chat shared with an agent that reads the repository through read-only tools, and a Decisions store that keeps attributed answers apart from the text they produced. The MCP endpoint is the other difference, letting an external coding agent create documents or consume an approved implementation graph rather than treating the plan as a dead artifact.

The cost of that difference is the operational surface. A Markdown file needs no GitHub App, no PostgreSQL, no Copilot entitlement and no admission policy. Chopin needs all four, and its README warns of incomplete workflows, operational limits and breaking changes. If your team will not run a database and manage a GitHub App, the repository-grounded agent is not worth the setup.

Licence, maintenance and upgrade cost

Chopin is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is the licence text, not legal advice; if you redistribute a modified Chopin, read LICENSE.md and your own counsel rather than this paragraph. The README's own warning matters more than the licence for adoption decisions: Chopin is experimental research software, not a supported GitHub product or a production-ready service, and you should expect incomplete workflows, operational limits and breaking changes. The repository is not archived and the last push was on 2026-09-16, so the code is moving, but movement in a research prototype is not a stability guarantee.

Upgrade cost follows from the pinned toolchain. The package manager is bun@1.3.2, declared both in package.json and as the Dockerfile's default BUN_VERSION argument, and the Dockerfile installs with --frozen-lockfile. Playwright is pinned at 1.62.1, dprint at 0.50.2 and oxlint at 1.51.0, and the browser editor depends on a patched build of @mdxeditor/editor@4.1.0 recorded under patchedDependencies. Any upgrade that touches those pins has to be revalidated against the patch and the lockfile. The database side is narrower still: because one process may write at a time, you cannot roll a new version in behind a load balancer and drain old connections, so an upgrade is a restart, and a restart signs everyone out and releases the channel's token ownership.

Editorial conclusion

Adopt Chopin if you want to evaluate repository-grounded document authoring on a trusted machine and can supply a GitHub App plus an active Copilot entitlement; the README is explicit that it is experimental research software with incomplete workflows and breaking changes. Do not adopt it as a production planning service, on GitHub Enterprise Server, or anywhere you need horizontal scaling or zero-downtime deploys, because the README states one process may write to a database at a time. Before committing, verify your App permissions match docs/authentication.md, confirm the Planner's default-branch snapshot behaviour suits your review flow, and check docs/self-hosting.md rather than the local Compose override, which publishes PostgreSQL on host port 5432 and is intended only for a trusted development machine.

Frequently asked questions

Official sources

1. githubnext/chopin on GitHub
2. Issues
3. License: MIT
4. Project website
5. README