Skip to main content
GitHub is Helix’s transport for your agent’s source. It reads your agent from a repo and ships every approved fix back as a pull request — it never writes to your default branch.

​
What Helix does with your repo

  • Reads the subject. Helix resolves the agent it’s working on from the repo — harness markdown (e.g. .claude/agents/*.md) or agent code — so Spec, Build, and Evaluate reason over the real definition, not a copy.
  • Writes via PR only. When Optimize applies an approved remedy, Helix prepares the change on a branch and opens a pull request with the diff. Markdown targets apply as file edits; code targets apply as a code change. Review and merge on GitHub — the apply gate is your merge.
Every apply is approval-gated. Helix proposes; GitHub is where you accept. Nothing lands on your default branch without your merge.

​
Configure it

Point a target at the repo and how fixes apply. A local target uses a checkout you already have; a remote target clones from repo_url:
.mutagent/config.yaml
platform selects the harness or framework; root scopes where fixes are written; apply.kind is markdown for agent files or code-pr for a code change. See the config reference for every key, and apply targets for the harness vs code split.

​
Authentication

Local targets use your existing git credentials — the same gh/ssh setup you push with. Remote targets clone over repo_url using the credential named by credential_ref (an env-var name, never the secret itself). Helix needs only read access to evaluate and write access to open the PR branch.
For the hosted loop, GitHub is also how Managed Agents reaches your code. See Managed Agents.