Skip to content
Ghostbranchdocs
GitHub

Working with a coding agent

Let a coding agent such as Claude Code or Codex run the Ghostbranch loop, while publishing stays with you.

Ghostbranch is built to be driven by agents as much as by people. Every command takes --json, every result lists the commands to run next, and anything that needs a person says so.

Point the agent at the guide

Section titled “Point the agent at the guide”

ghostbranch guide prints a guide written for coding agents: the loop, the rules, and every exit and error code. It comes from the binary itself, so it always matches the version you have installed. An agent should read it before it runs anything else.

To have your agent find it on its own, install a small skill that points at the guide. Preview where it goes with --plan, then run the same command without it:

Terminal
ghostbranch guide --install codex --plan
Dry run; nothing was changed. This would:
- write /home/you/.agents/skills/ghostbranch/SKILL.md

--install claude does the same for Claude Code, in .claude/skills/ in your home folder. The skill is yours, never a file in your repo. --plan shows where it would go, and --uninstall claude or --uninstall codex removes it.

Say who is acting

Section titled “Say who is acting”

Set GHOSTBRANCH_ACTOR in the agent’s environment, so the ledger records that an agent ran each command:

Terminal window
export GHOSTBRANCH_ACTOR=agent:claude-code

It’s a label only. It never grants or blocks anything.

What an agent may do

Section titled “What an agent may do”

An agent can run the whole loop up to the publish: sync, feature start, commits and pushes to the shadow repo, gate, wait, and promote --plan. Each result’s next field says what to run next. When an entry in next has needs_human: true, the agent stops and gives you that exact command.

An agent never:

  • pushes a feature branch to the public repo with git, or skips the push guard with --no-verify;
  • types or reads a console code, or fakes a terminal to get one;
  • runs ghostbranch agents allow or ghostbranch waivers add, or edits grants.json, waivers.json, plan files or .ghostbranch.yml to get past a check;
  • creates or deletes repos, or changes repo settings, tokens or secrets;
  • runs ghostbranch login or logout, or relies on your stored login.

Agents often add a Co-Authored-By line to their commit messages. Ghostbranch keeps commit messages as they are written: the default history mode publishes every commit message unchanged, trailers included. If you don’t want them public, reword those commits before you promote, or publish in squash or curated mode, which publish only the messages you write.

Let an agent publish

Section titled “Let an agent publish”

Publishing needs you. When an agent runs promote or apply, it stops with APPROVAL_REQUIRED, and you finish the publish at your own terminal by typing a one-time code.

If you’d rather let the agent publish on its own for a while, give it a grant. Run this yourself, at a terminal:

Terminal
ghostbranch agents allow --repo you/project --for 6h
Allow coding agents on this machine to publish to you/project (shadow you/project-shadow) with --yes, without this code, for 6h, until 2026-10-12 21:03 UTC.
Agents still need a green gate and a clean leak scan for every publish. Revoke with: ghostbranch agents revoke --repo you/project
To confirm, type this code and press Enter: K7QZM4
Leave it empty, or type n, to cancel.
> K7QZM4
Agents on this machine may publish to you/project with --yes, until 2026-10-12 21:03 UTC.
Take it back with: ghostbranch agents revoke --repo you/project
  • How long: --for takes 1h, 6h (the default), 1d, 7d, 15d, 30d or 90d. --until-revoked never expires.
  • What it covers: one repo pair, on this machine only. A new grant for the same pair replaces the old one.
  • What it doesn’t: the agent still needs a green gate and a clean leak scan for every publish, and it has to pass --yes.
  • Taking it back: ghostbranch agents revoke --repo you/project.

When an agent publishes under the grant, nobody is asked whether to archive the feature or keep it. Under --yes, apply archives it unless the agent passes --keep, and data.after_publish tells the agent which happened. Fixes to an archived feature’s pull request then go straight to its branch with plain git, with no gate and no leak scan: see After publishing: Archive or Keep. If you’d rather the agent’s fixes keep going through the gate, tell it to pass --keep.

Add --plan to see the grant without making it. ghostbranch agents status shows the grants in force.

In Claude Code

Section titled “In Claude Code”

Claude Code may still stop an agent from running ghostbranch apply … --yes, as a step it approves for itself. If you want the agent to publish under your grant, also allow the command in Claude Code, for example in your project’s .claude/settings.local.json:

.claude/settings.local.json
{ "permissions": { "allow": ["Bash(ghostbranch apply:*)"] } }

Keep that file out of your commits.

Give the agent its own token

Section titled “Give the agent its own token”

The console code, grants and the push guard stop an agent’s mistakes. They don’t stop an agent that is set on getting around them, since it runs as you, on your machine. The real boundary is the token.

Give each agent a fine-grained token that reaches only the shadow repo, set as GHOSTBRANCH_TOKEN in the agent’s environment only. With that, the agent can do everything up to the publish, and only you can publish. ghostbranch doctor and ghostbranch agents status warn AGENT_ON_PERSON_LOGIN when an agent is using your own login instead.