Skip to content
HearthworkHearthwork

Command reference

This page is generated from hearthwork <command> --help, so it always matches the installed version. Run hearthwork --help for the short list.

claude, codex, opencode, aider, qwen

Section titled “claude, codex, opencode, aider, qwen”

Each agent launcher passes every argument after its name to the agent itself, so --help there shows the agent’s own help. Hearthwork’s own flag is --dry-run, and only as the first argument.

hearthwork <claude|codex|opencode|aider|qwen> [--dry-run] [agent arguments]

agents

Section titled “agents”
hearthwork agents             supported agents: installed?, version, API, how Hearthwork connects each

task

Section titled “task”
usage: hearthwork task [-h] [--agent {aider,claude,codex,opencode,qwen}] [--allow PATTERN]
                       [--cwd CWD] [--timeout TIMEOUT] [--json] [--dry-run]
                       task


Run one coding task with the local model through a coding agent.


positional arguments:
  task                  what to do; "-" reads it from stdin


options:
  -h, --help            show this help message and exit
  --agent {aider,claude,codex,opencode,qwen}
  --allow PATTERN       command pattern the agent may run, e.g. "pytest *" (not Codex or Aider;
                        repeatable)
  --cwd CWD             folder to work in (default: here)
  --timeout TIMEOUT     seconds before the agent is killed (default 900)
  --json                report as JSON
  --dry-run             print the command, environment and generated files; start nothing

mcp

Section titled “mcp”
usage: hearthwork mcp [install claude|codex|print]

start

Section titled “start”
usage: hearthwork start [-h] [--model MODEL] [--context CONTEXT] [--force] [--over-budget]


options:
  -h, --help         show this help message and exit
  --model MODEL      part of a model file name; skips the model menu
  --context CONTEXT  context for this start, e.g. 98304 or 96K (default: auto, see `hearthwork
                     context`)
  --force            interrupt running requests
  --over-budget      start even if the memory estimate exceeds the budget

idle

Section titled “idle”
Usage: hearthwork idle [minutes|off]

budget

Section titled “budget”
Usage: hearthwork budget [show] | use dedicated|balanced|work | set vram=10GB ram=12GB slots=1 threads=8 idle=20m | reset  [--force] [--over-budget]

stop

Section titled “stop”
hearthwork stop [--force]     stop the model and the host (saves the prompt cache); --force even with requests running

serve

Section titled “serve”
usage: hearthwork serve [-h] [--model MODEL] [--context CONTEXT] [--force] [--over-budget]


options:
  -h, --help         show this help message and exit
  --model MODEL      part of a model file name; skips the model menu
  --context CONTEXT  context for this start, e.g. 98304 or 96K (default: auto, see `hearthwork
                     context`)
  --force            interrupt running requests
  --over-budget      start even if the memory estimate exceeds the budget

logs

Section titled “logs”
usage: hearthwork logs [-h] [--server] [-f] [-n N]


Show the host's log (requests, queue, start and stop).


options:
  -h, --help    show this help message and exit
  --server      show llama-server's own output instead
  -f, --follow  keep printing new lines (Ctrl+C stops)
  -n N          how many lines to start with (default 100)

alias

Section titled “alias”
Usage:
  hearthwork alias add <name> <agent>   create a short command, e.g. `hearthwork alias add ccl claude`
  hearthwork alias list
  hearthwork alias remove <name>

context

Section titled “context”
hearthwork context [model] [N|auto]   context per model: range for this computer; save N for a model

diagnose

Section titled “diagnose”
usage: hearthwork diagnose [-h] [--last N] [--since DURATION] [--all] [--client CLIENT] [--json]
                           [--export FILE]


Explain what limited your agent sessions, from measured requests (HOME/logs/requests.jsonl).
Nothing leaves this computer; prompts and code are not recorded.


options:
  -h, --help        show this help message and exit
  --last N          only the last N requests
  --since DURATION  only requests from the last period, e.g. 90s, 30m, 2h, 1d
  --all             every recorded request, not only the last 24 hours (the default)
  --client CLIENT   only this client (part of its id, e.g. opencode, api, share)
  --json            print the report as JSON
  --export FILE     write a sanitized JSON report (numbers only: no prompts, code, or credentials)

status

Section titled “status”
hearthwork status [--json]    host, model, context, slots, requests per client; switching, idle and recovery state

share

Section titled “share”
usage: hearthwork share [-h] [--port PORT] [--allow-public] [--tailscale]


options:
  -h, --help      show this help message and exit
  --port PORT
  --allow-public  share even on a network Windows calls Public
  --tailscale     accept only Tailscale computers (and this local network when it is not Public):
                  safe on any Wi-Fi

api

Section titled “api”
usage: hearthwork api [-h] [--port PORT] [--api-key API_KEY] [--allow-switch] [--show]


One local OpenAI + Anthropic compatible endpoint for the running model (Ctrl+C stops it). It
listens on this computer only (127.0.0.1); to use the model from other devices run `hearthwork
share`.


options:
  -h, --help         show this help message and exit
  --port PORT        port to listen on (default 8080)
  --api-key API_KEY  require this key (Authorization: Bearer or x-api-key); without it any program
                     on this computer may use the model
  --allow-switch     a request whose "model" is part of another local model file name restarts the
                     server with it (interrupts everyone using the model); otherwise any model
                     name uses the running model
  --show             print copy-paste setup for the OpenAI/Anthropic SDKs, curl, Aider, OpenCode,
                     Continue, Cursor and exit

devices

Section titled “devices”
Usage: hearthwork devices [remove <name>]

connect

Section titled “connect”
usage: hearthwork connect [-h] [--pin PIN] [--name NAME] [host]


positional arguments:
  host         host or host:port (default: look on the local network)


options:
  -h, --help   show this help message and exit
  --pin PIN    the PIN shown on the host (otherwise asked)
  --name NAME  name for this device on the host (default: this computer's name)

disconnect

Section titled “disconnect”
hearthwork disconnect         back to local models

model

Section titled “model”
usage: hearthwork model [-h] [link]


Download a GGUF model from Hugging Face into your models folder.


positional arguments:
  link        Hugging Face repo or .gguf file link


options:
  -h, --help  show this help message and exit

bench

Section titled “bench”
usage: hearthwork bench [-h] [--agent {aider,claude,codex,opencode,qwen}] [--all] [--warmup]
                        [--show]


Benchmark the running model through a coding agent.


options:
  -h, --help            show this help message and exit
  --agent {aider,claude,codex,opencode,qwen}
  --all                 release check: every installed agent, one after another, after a warmup
  --warmup              run the 30K-token warmup even for a single agent (--all always does)
  --show                only print the scoreboard

tune

Section titled “tune”
usage: hearthwork tune [-h] [--time TIME] [--min-context N]
                       [--agent {aider,claude,codex,opencode,qwen}] [--quick-tasks N] [--dry-run]
                       [--json]


Try a few installed configurations and save the best tested one as a profile (nothing is
downloaded; the original model is restored).


options:
  -h, --help            show this help message and exit
  --time TIME           time limit for the whole run, e.g. 30m, 90s or 1h (default 30m)
  --min-context N       minimum context a candidate must offer, e.g. 65536 or 64K
  --agent {aider,claude,codex,opencode,qwen}
                        agent to drive the tasks
  --quick-tasks N       how many of the graded tasks to run per candidate (default 3)
  --dry-run             list the candidates and their estimated needs, then exit
  --json                print the result as JSON

doctor

Section titled “doctor”
usage: hearthwork doctor [-h] [--agent {aider,claude,codex,opencode,qwen}] [--all] [--quick]
                         [--json] [--keep]


Check that the model server, the relay and your coding agents work together.


options:
  -h, --help            show this help message and exit
  --agent {aider,claude,codex,opencode,qwen}
                        check one agent (default: every installed agent)
  --all                 every installed agent (the default)
  --quick               skip the coding task
  --json                print the report as JSON
  --keep                keep the temporary folders

check

Section titled “check”
usage: hearthwork check [-h] [--json]


Will Hearthwork (local models for coding agents) be worth it here?


options:
  -h, --help  show this help message and exit
  --json      machine-readable output

profile

Section titled “profile”
usage: hearthwork profile [-h] {save,list,show,check,apply,export,import} ...


Verified setup profiles.


positional arguments:
  {save,list,show,check,apply,export,import}


options:
  -h, --help            show this help message and exit

runtime

Section titled “runtime”
Usage: hearthwork runtime [install <name> | use <name> | update | rollback]

setup

Section titled “setup”
usage: hearthwork setup [-h] [--update-llama] [--reset] [--import FOLDER]


Set up llama.cpp for Claude Code on this computer.


options:
  -h, --help       show this help message and exit
  --update-llama   download the newest llama.cpp build
  --reset          ask for the models folder again
  --import FOLDER  copy settings, llama.cpp and caches from an older Hearthwork folder (a git
                   clone)

update

Section titled “update”
hearthwork update             update Hearthwork itself (stops a running model first, restarts it after)