ghafk

Works your GitHub issues while you are away from the keyboard.

How it works · Quick start · Daily use · Configuration · Troubleshooting · Security

Label an issue agent. A timer on your machine gives the issue to a coding agent, checks the result and merges the pull request. GitHub holds all the state, so github.com is your dashboard.

Warning

ghafk runs coding agents as you, on your machine. The text of the issue is their prompt. Read the security model before you register a repository.

How it works

On each tick, ghafk does one step for each registered repository. By default, a tick starts every 2 minutes.

flowchart TD
    A([Issue labeled agent]) --> B[Groom]
    B --> C[Implement]
    C --> D[Pull request]
    D --> E{Checks}
    E -->|pass| F{Judge}
    E -->|fail| R[Repair]
    F -->|reject| R
    R --> E
    F -->|approve| G([Merge])
    G --> H[Reconcile]
    B -.->|question| P[/Park/]
    R -.->|second failure| P
    P -.->|"/answer"| B
    P -.->|"/retry"| E

Loading

Term	Meaning
Groom	An agent turns the issue into a contract, or asks you one question.
Contract	The change to make, its acceptance criteria and its commit line.
Card	One comment on the issue that shows the contract and the progress. ghafk edits it in place.
Judge	A second agent that compares the diff with the contract.
Park	ghafk stops, adds needs-human and tells you what to do. It does not retry alone.
Reconcile	After a merge, ghafk checks the other open issues that the change touched.

Quick start

• Linux with a systemd user session, or macOS
• Go 1.26 or newer, and git with a commit identity
• On Linux, the bubblewrap package. On stock Ubuntu 24.04, ghafk prints the one-time sudo step that enables it.
• gh, logged in with gh auth login
• A coding agent CLI that ghafk supports. See harness profiles.

1. Install ghafk. Go puts it in $(go env GOPATH)/bin. Add that folder to your PATH if your shell cannot find ghafk.

   go install github.com/mike-diff/ghafk@latest
   export PATH="$PATH:$(go env GOPATH)/bin"

2. Set the default harness and model. Then test them. ghafk harness list shows the harnesses that ghafk knows.

   ghafk harness default <harness> <model>
   ghafk harness test <harness> <model>

3. Register a repository. Then commit and push the file that ghafk writes.

   cd ~/src/your-repo
   ghafk init
   git add .ghafk/WORKFLOW.md && git commit -m "chore: configure ghafk" && git push

   ghafk also works each repository that you own where .ghafk/WORKFLOW.md is on the default branch. It finds a repository that you push on its next tick. See repositories.

4. Start the timer. ghafk runs as you, and each agent run and each checks run goes into an OS sandbox: bubblewrap on Linux, sandbox-exec on macOS. The sandbox hides the rest of your home and reaches the network only through an allowlisted proxy. See security. A tick stops if the sandbox cannot start. A run parks with the fix if the proxy or a program is missing. On Linux, keep the timer after you log out with loginctl enable-linger "$USER".

   ghafk start

   [!TIP] Claude Code with a subscription on macOS keeps its login in the Keychain, which the sandbox blocks. Run claude setup-token once and put CLAUDE_CODE_OAUTH_TOKEN=<token> in ~/.ghafk/env (chmod 600).

5. Label an issue agent, or comment /start on it. To get good results, read how to write an issue.

To update ghafk, run ghafk update.

What happens next

ghafk checks for labeled issues on each tick. On the next tick, it adds a card to the issue. The card shows the contract and a progress table. ghafk edits the card at each step:

Step	Status	Duration	Tokens	Harness
Groom	✅	1m 52s	115k	<harness> <model:effort>
Implement	✅	2m 40s	140k	<harness> <model:effort>
Checks	✅	41s
Judge	⏳			<harness> <model:effort>
Merge	⬜

A small issue goes from label to merge in approximately 10 minutes. You can change the tick interval and the columns of the table. See machine settings.

Daily use

Control ghafk from GitHub. Put a command at the start of a comment on the issue or its pull request.

Command	Result
/start	Starts work on the issue.
/answer <text>	Answers a question from ghafk. Grooming continues.
/retry	Continues a parked issue or pull request.
/close	Closes the issue, or closes the pull request.
/stop	Removes the labels. ghafk ignores the issue until you label it again.

Note

ghafk accepts commands only from people with write access. It adds 👍 to each command that it accepts.

On your machine, use ghafk status to see the timer, the log and each repository. Use ghafk stop to stop the timer. If something does not work, see troubleshooting.

Configuration

Each repository has a .ghafk/WORKFLOW.md file. Most repositories need only checks:

---
checks: go build ./... && go vet ./... && go test ./...
---
Use the standard library only.

The text after the settings block holds the rules of your repository. ghafk adds it to the prompt of each agent.

The configuration reference lists every setting, label, harness profile and file. To show ghafk as a bot on GitHub, run it as a GitHub App.

Security

• Every agent run and every checks run goes into a new OS sandbox that ends with the run: bubblewrap on Linux, sandbox-exec on macOS. The sandbox sees the worktree, a fresh home, per-repository caches and the harness login only. Your other files, your gh login, your SSH keys and /run/user stay invisible. See the sandbox model.
• The sandbox has no direct network. A proxy outside the sandbox allows only model APIs, npm, the Go module proxy, PyPI and models.dev. An egress: line in .ghafk/WORKFLOW.md adds hosts; denied hosts appear in the park comment.
• ghafk's own git commands ignore git files that an agent changes, and the repository .git is read-only inside the sandbox.
• Only people with write access can send commands or add prompt text.
• ghafk works only the pull requests that it opened.
• A change to .github/ or .ghafk/ always waits for you.
• Prompts are not controls. Use branch protection for a real gate.

Read the full security model. To report a vulnerability, see SECURITY.md.

Limits

• ghafk runs on Linux with systemd, and on macOS with launchd. Support for macOS is new. Report problems as issues.
• Each tick does one step for each repository, one repository at a time.
• Checks run on your machine. ghafk does not wait for GitHub Actions.
• The origin remote of the clone must be the GitHub repository.

For agents

llms.txt lists the docs for language models. The ghafk skill teaches a coding agent to install, configure and operate ghafk. To use it with Claude Code, copy skills/ghafk to .claude/skills/ in your project or home folder.

Contributing

Each change must keep the engine able to take a real issue to a merged pull request. .ghafk/WORKFLOW.md is the configuration of this repository, and an example.

License

MIT