heliograph

Documentation

Codex

heliograph ships as a Codex skill, and as an MCP server. Install either and Codex can set up the transport, write the steps, drive the run and read the log back, on a machine it has no way to reach itself.

That last part is the point. Codex is excellent on a machine it can run commands on. On a production box behind a bastion, in a client-owned estate, or on the wrong side of a change-control policy, it cannot run anything at all.

Install the skill

git clone https://github.com/dbhq-uk/heliograph
cd heliograph && ./install-codex.sh

It installs into ~/.codex/skills/heliograph/.

Re-run it after editing SKILL.md. That one file is rewritten at install time rather than symlinked, because Codex does not substitute ${CLAUDE_SKILL_DIR} the way Claude Code does - the installer resolves that variable to the skill's real path on the way in. references/ is symlinked, so edits there are live immediately.

That is the only meaningful difference between the two installers, and it is worth knowing because a stale SKILL.md fails silently: the skill loads, and points at a path that moved.

Or as MCP tools

codex mcp add heliograph -- heliograph mcp

Every CLI command becomes a typed tool. The gates do not move: a tool call publishes a request, and the station still decides whether to run it. See the MCP server for the tool list.

Use the skill when you want the method as well as the tools - it carries the rules that change what an agent does, which a tool schema cannot. Use MCP alone when you only want the surface.

The binary is required either way

The skill drives the heliograph CLI and does not reimplement it. If the binary is missing the skill says so and prints the install command rather than improvising around it:

curl -sSL https://github.com/dbhq-uk/heliograph/releases/latest/download/heliograph-linux-amd64 \
  -o /usr/local/bin/heliograph && chmod +x /usr/local/bin/heliograph

What Codex gets that a human relay does not

The same thing Claude Code gets, and for the same reason: the evidence rather than somebody's summary of it.

  • A log with every line timestamped, so a hang is a gap rather than a

guess. heliograph logs --last --gaps turns reading it from a discipline into arithmetic

  • The real exit code, and the log whether the run passed or failed
  • A refusal it can act on. A gate says which flag would allow it, published

within one poll, so the agent is not left waiting on a request that will never run

Working on this repository

AGENTS.md at the repository root is the guidance for an agent working on heliograph rather than driving it. It is separate from the skill deliberately: one is a procedure for an investigation, the other is house rules for a codebase.

Start here

The quick start is the same for every agent. The method is the part worth reading before a hard investigation - every rule in it was paid for by a round trip that went wrong first.