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
• 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. If the engine runs as its own account, run ghafk init in your own clone and push. The engine finds the repository on its next tick. See repositories.

4. Start the engine. We recommend its own account:

   ghafk engine setup

   The command asks for your sudo password once. It creates a system account, installs a hardened service and asks for a GitHub token. Then install your harness as that account. The command tells you how. To run the engine as you instead, use ghafk start. See the engine account.

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

To update ghafk and the engine, run ghafk update.

Tip

The timer has no SSH agent. If you push over HTTPS, run gh auth setup-git. On Linux, run loginctl enable-linger "$USER" to keep the timer on after you log out. On macOS, the timer runs only while you are logged in.

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

• Agents run as the account of the engine. With ghafk engine setup, that is a separate system account. On Linux, a hardened service also hides the home directories. With ghafk start, agents run as you, with your credentials. See the engine account.
• ghafk's own git commands ignore git files that an agent changes.
• 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