Run a GitHub task with holon solve

holon solve turns a GitHub issue or pull request into a finished task. Point it at a target and it runs an agent that gathers context, makes the change, reviews the pull request, or posts a comment, then writes structured output a script or CI job can read.

The flag catalog lives in the CLI reference; this page covers the runs you will actually make.

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:

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:

1. Parse the target — Holon extracts owner, repo, issue/PR number, and kind from the ref you provide.

2. Prepare directories — An output directory is created (default: $TMPDIR/holon-output-<uuid>) and a github-context/ subdirectory holds input metadata.

3. Create the agent — Holon creates an agent from the configured solve template, normally the command-owned github-solver preset. It includes sview, code-review, github-issue-solve, github-pr-fix, github-review, and ghx.

4. 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.

5. 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

Every flag, its type, and its default are in the CLI reference.

Differences from holon run

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

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. The solve preset is one-shot: merging, approval, or continued PR event tracking requires explicit instructions.

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

GitHub Actions

Use the composite action when you want a repository workflow with normal step-level environment variables for model providers:

jobs:
  holon:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: holon-run/holon@main
        with:
          trigger: auto
          model: deepseek/deepseek-v3.2
        env:
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}

trigger: auto derives the target and goal from supported issue, pull request, label, assignment, and @holonbot comment events. For explicit runs, pass ref: owner/repo#123 instead.

The reusable workflow at .github/workflows/holon-solve.yml remains available as a compatibility wrapper, but the composite action is the recommended entry point when you need arbitrary provider environment variables.

See also

• CLI reference — full command tree, including holon solve flags
• Configuration reference — model and provider setup
• Automate Holon over HTTP — drive the same runs from code
• Delegate work to another agent — hand work to a child agent