holon solve

holon solve is the headless command for automating GitHub issues and pull requests. Give it a target and it runs an agent that collects context, implements a fix, reviews a PR, or publishes a comment — then writes structured output artifacts you can consume in scripts or CI.

When to use solve

Use holon solve when you want to:

Automatically implement a GitHub issue without manual TUI interaction
Fix a PR based on review feedback in CI
Run a review pass on a pull request
Integrate Holon into a scripted pipeline (GitHub Actions, CLI scripting)

Do not use holon solve for interactive work — use holon tui or holon run when you need direct conversation with the agent.

Target reference formats

The first positional argument is the target ref. Holon accepts three formats:

Format	Example	Notes
Full URL	`https://github.com/holon-run/holon/issues/42`	Most explicit; kind is inferred from the URL
`owner/repo#NN`	`holon-run/holon#42`	Treated as an issue or pull request
`#NN` with `--repo`	`#42 --repo holon-run/holon`	Shortest form; requires `--repo`

Quick start

Solve an issue

# Full URL form
holon solve https://github.com/holon-run/holon/issues/42

# Short form
holon solve holon-run/holon#42

# Numeric ref with --repo
holon solve 42 --repo holon-run/holon

The agent clones the repository, reads the issue, collects related context, implements the fix, and commits the change. Output artifacts are written to a temporary directory.

Provide a custom goal

holon solve holon-run/holon#42 \
  --goal "Add a --dry-run flag to the solve command"

Use --goal to override the agent's interpretation of the target, or to scope the work when the issue body is large.

Review a pull request

holon solve https://github.com/holon-run/holon/pull/753 \
  --goal "Review only: check for security issues and publish one review"

When the goal mentions review, Holon adds guardrails that require the agent to publish exactly one review or one PR comment, then stop. This keeps review runs single-shot and predictable.

Fix a PR from review feedback

holon solve https://github.com/holon-run/holon/pull/753 \
  --base "feature-branch"

Use --base to set a different base branch for the fix branch. The default base is main.

Configuration

Solve reads the standard Holon runtime configuration (~/.holon/config.json). At minimum you need a model and credentials. Use the CLI to configure:

# Set the default model
holon config set model.default "anthropic/claude-sonnet-4-6"

# Store credentials securely (recommended)
holon config credentials set --kind api_key --stdin anthropic
# Paste your API key and press Enter, then Ctrl+D

Or use environment variables for quick setup:

export ANTHROPIC_AUTH_TOKEN="your-api-key"
holon config set model.default "anthropic/claude-sonnet-4-6"

Holon also needs a GitHub token. It reads GITHUB_TOKEN or GH_TOKEN from the environment:

export GITHUB_TOKEN="ghp_..."
holon solve holon-run/holon#42

Verify your configuration is complete:

holon config doctor
holon config models list

How solve works

When you run holon solve, these steps happen inside the runtime:

Parse the target — Holon extracts owner, repo, issue/PR number, and kind from the ref you provide.
Prepare directories — An output directory is created (default: $TMPDIR/holon-output-<uuid>) and a github-context/ subdirectory holds input metadata.
Create the agent — Holon creates an agent from the built-in holon-github-solve template, which includes the github-issue-solve, github-pr-fix, github-review, and ghx skills.
Run the prompt — The runtime constructs a prompt describing the target and goal, then runs the agent with the configured trust level and turn limit.
Collect artifacts — When the run finishes, Holon writes these files into the output directory:

File Content
manifest.json Outcome metadata: provider, status, outcome, target
summary.md Human-readable summary of what the agent did
run.json Full structured run response

File	Content
`manifest.json`	Outcome metadata: provider, status, outcome, target
`summary.md`	Human-readable summary of what the agent did
`run.json`	Full structured run response

Full flag reference

holon solve <REF> [OPTIONS]

Flag	Type	Default	Description
`REF` (positional)	string	(required)	GitHub URL, `owner/repo#NN`, or `#NN`
`--repo`	string	—	Repository for numeric-only refs (e.g. `holon-run/holon`)
`--base`	string	`main`	Base branch for fix branches
`--goal`	string	—	Override the agent's interpretation of the target
`--role`	string	—	Additional role context passed to the agent
`--agent`	string	`github-solve`	Agent ID to use or create
`--template`	string	`holon-github-solve`	Template for the agent
`--model`	string	—	Override the configured model (sets `HOLON_MODEL`)
`--max-turns`	integer	—	Maximum agent turns before forced stop
`--trust`	string	`trusted-operator`	Trust level for the run
`--json`	flag	false	Print output as JSON instead of text
`--home`	path	`~/.holon`	Holon home directory
`--workspace`	path	—	Working directory for the agent
`--cwd`	path	—	Current working directory for the agent
`--input`	path	—	Directory for input context (overrides default)
`--output`	path	—	Directory for output artifacts (overrides default)

Differences from holon run

holon run and holon solve both execute agents in headless mode, but they serve different purposes:

	`holon run`	`holon solve`
Use case	General headless tasks	GitHub issues and PRs
Input	Free-text prompt	GitHub target ref
Agent template	`holon-default`	`holon-github-solve` (GitHub skills pre-loaded)
Output	Text or JSON to stdout	Structured artifacts in output directory
GitHub integration	Manual (`gh` CLI)	Automatic context collection and skill dispatch
Pipeline-friendly	Use `--json` for structured output	Built-in manifest and summary files

Use holon run for general automation and scripting. Use holon solve when your task starts from a GitHub issue or pull request and you want automatic skill selection.

Scripting with solve

JSON output for scripting

holon solve holon-run/holon#42 --json | jq '.final_status'
# "completed"

Custom output directory

holon solve holon-run/holon#42 --output ./solve-results/
cat ./solve-results/run.json
# { "provider": "holon-solve", "status": "completed", ... }

CI integration sketch

#!/bin/bash
# Run solve and fail on incomplete outcome

OUTPUT=$(mktemp -d)
holon solve "$ISSUE_URL" --output "$OUTPUT" --json

STATUS=$(jq -r '.final_status' "$OUTPUT/run.json")
if [ "$STATUS" != "completed" ]; then
  echo "Solve did not complete: $STATUS"
  exit 1
fi

# The agent may have committed changes; push them
git push origin HEAD