# headless

> **Tool `tools/llm/headless.py`** (program, Models). Run one of GameFrame's agents through Claude Code and save its report.

Run it with `./gameframe run headless ARGS` or `python3 tools/llm/headless.py`. [Source on GitHub](https://github.com/tanepiper/game-frame/blob/main/tools/llm/headless.py).

## Its own help

This is the help text in the tool itself, as `./gameframe tool headless` prints it.

```text
Run one of GameFrame's agents through Claude Code and save its report.

Usage:
  headless.py AGENT TASK [--dir DIR] [--write] [--budget USD] [--model ID] [--report FILE]
  headless.py docs-check [PATH ...] [--budget USD] [--model ID] [--report FILE]

  AGENT     an agent in agents/ (re-decoder, re-measurer, re-checker...)
  TASK      what it should do, in one message: it cannot ask you anything
  --dir     the folder it works in (default: the project, GAMEFRAME_PROJECT)
  --write   let it edit and write files. Without it, it can read and run commands only.
            Give it a branch or a worktree of its own, and read its diff before you merge
  --budget  the most the run may spend, in US dollars (default 5.00)
  --report  the report's file (default: analysis/llm/runs/<date>-<agent>.md in the folder)

  docs-check  runs re-checker, then re-editor, over the PATHs (default: docs skills GAPS.md),
              without --write: they report and change nothing. The report lists claims whose
              evidence is missing, addresses or files that do not exist, gaps that are already
              covered, and sentences that break the writing rules. Its budget is split between
              the two (default 5.00 in all)

The agent's system prompt is its agents/<name>.md file plus the SKILL.md of every skill it
names, as Claude Code with --bare loads no skills or settings of its own. Configure an
Anthropic-compatible provider, which may be a local model server. The run ends when
the agent ends its turn or the budget runs out. The report is the agent's final message, under a
line with the agent, the model and the cost.

Schedule it with cron or launchd only when requested. It uses the configured provider through
client.py, so the Claude Code GitHub Action is not needed.

What it does not do: commit, push or merge. It never runs without a budget.
```