Headsign

headsign

[日本語](README.ja.md) · [npm](https://www.npmjs.com/package/headsign)

[](https://www.npmjs.com/package/headsign) [](https://github.com/meganemura/headsign/actions/workflows/ci.yml)

A headsign is the destination display on the front of a train. This one is for agent loops. In each iteration, the agent asks where it may go. headsign runs the gates and answers: proceed, retry, or terminus.

**headsign is a tiny phase gate for coding agents.** Your agent does the work and keeps the conversation. headsign holds the run's state and decides whether the work may move to the next phase. An agent needs one rule: **do the work, run `headsign next`, and obey the first line of the answer.**

It holds only that decision. headsign does not define your phases or how the agent completes a phase. If the agent wants to hand a step to three subagents, or run two things at once, that is its call to make, not this tool's to grant. You or the agent can rewrite the workflow file between runs. Better judgment about agent work will improve that file, and judgment about how to shape agent work is getting better quickly on the agent's side of the line. The loop your agent designs for your repository beats the one a harness author guessed at from outside it. A harness that encodes today's answer would limit later improvements. You can change the graph while the tool stays stable.

TL;AR — Too Long; Agents Read.

A picture based on your repository can help you decide whether you need headsign. Paste the block below into your coding agent. The agent reads the repository, works out the phases itself, draws the loop, and stops there. It runs nothing, installs nothing, and changes no file.

You are looking at a repository. I am considering headsign, a phase gate for
agent work: an agent does the work, then asks a small CLI whether the work