okffs

okffs

Turn a conversation with Claude into GitHub issues, branches, and pull requests — without leaving Claude Code.

okffs is a Model Context Protocol server that gives Claude Code a clean issue → branch → PR → close workflow on GitHub. Talk through the work in plain language; okffs creates the issues, matching branches, and pull requests, keeps them linked, and (optionally) syncs a GitHub Projects board — all in one shot.

• One-shot planning — describe a chunk of work and get every issue + branch created, with relationships wired up.
• The whole loop — create, comment, commit, open PRs, handle review feedback, and close, each as a simple ask.
• Sensible defaults — Claude infers labels, priority, and effort from the task; GitHub stays the single source of truth.
• Little to no config — signed in with the gh CLI inside your repo? You're ready.

Quick start

1. Run the setup wizard from your project root:

npx @neturely/okffs setup

It walks you through auth, repo, and any optional features, writes a .env, then runs a quick GitHub sanity check. Re-run it any time (e.g. after upgrading okffs) — it only asks about options that are new since your last run. If you're happy relying on the GitHub CLI (gh auth login) and working inside the repo you want to manage, you can skip this step entirely — okffs works with no config at all.

Already in Claude Code? Once okffs is connected you can configure it conversationally instead — run the `/okffs:setup` slash command and Claude will interview you and write the .env for you (no terminal needed). okffs also nudges you to run it after an upgrade introduces new options.

2. Add a `.mcp.json` to your project root:

{

"mcpServers": { "okffs": { "command": "npx", "args": ["@neturely/okffs@latest"] } } }

That's it — npx fetches okffs on first use, and Claude Code picks up the tools automatically. To use a token or a different repo instead of the gh/auto-detect defaults, run okffs setup (above) or edit .env by hand — see Configuration.

Now just ask Claude:

• *"Create an issue called 'Fix login button' and start a branch for it."*
• *"Plan the work for adding user authentication and create the issues."*
• *"Create issues from this task list: …"*
• *"List all open issues."*
• *"Mark issue #5 as blocked by issue #3."*
• *"Done with issue #42 — open a PR and close it."*
• *"Address the review comments on PR #42."*

Claude infers labels (bug, enhancement, …) from the title and description and merges them with any you've set as defaults.

Tools

Destructive tools (delete_issue, delete_branch) always warn on the first call and only act when re-called with confirmed: true, posting a comment to the issue before doing anything.

Handling PR reviews

okffs has a built-in loop for review feedback — just ask (*"address the review comments on PR #42"*). Claude reads the threads, fixes the valid ones, commits and pushes, replies per thread, and posts a summary. Claude brings the judgment and the fixes; okffs handles the GitHub plumbing. There's also a slash command, `/okffs:address_pr_review` (takes a PR number), that runs the same loop.

By default review threads are left open for you to resolve; set OKFFS_RESOLVE_THREADS=true to have okffs resolve them once addressed.

Autopilot (minimum interference)

For a hands-off session, ask Claude to *"fully handle this"* (or *"minimum interference"*) — or set OKFFS_AUTOPILOT=true to make it the default. In autopilot, Claude stops asking you to choose between options for reversible decisions, takes the recommended option at each fork, and drives an issue all the way to a PR into the base branch (and a base merge when OKFFS_AUTO_MERGE_BASE=true) — then posts an "Autopilot decisions" report (one line per choice, with a one-line why) to the PR and the issue, so you can redirect anything in a single message.

It removes confirmation friction; it does not grant new powers. The hard stops always interrupt, even in autopilot: destructive tools (delete_issue / delete_branch), and anything into OKFFS_PROTECTED_BRANCH (merge/tag/publish), billable, or irreversible that you have not opted into. An explicit env opt-in is the consent and is never re-asked: OKFFS_PROMOTION_AUTO_REVIEW (the Copilot review is your own GitHub billing choice), OKFFS_AUTO_MERGE_PROTECTED, OKFFS_TAG_RELEASE. Correctness stops — a failing check, a pending review, an unresolved thread, a moved branch tip — are never overridden by a flag. And for a real *missing-information* call — where only you hold the context — Claude still asks one quick question rather than guess. Off by default.

Releases and the promotion gate

prepare_release bumps the version and rolls the changelog on a release/X.Y.Z branch into your base branch. promote_branch then opens the issue-less promotion PR (e.g. develop → main), boards it, optionally requests reviewers such as Copilot, and lists the releases the promotion carries. From there, each further step is your call, or an explicit opt-in:

With both flags on, the loop is: promote_branch → review lands → address it → re-run promote_branch merges and tags. okffs still