Your first agent session

Go to the project you want the agent to work on, then start an agent:

cd my-project
hearthwork claude      # also: codex, opencode, qwen, aider

If no model is running, Hearthwork starts one first. Run hearthwork alone for a menu with the same choices.

What happens

• A host starts in the background and owns the model and a single request queue. The model keeps running between agent sessions, and nothing opens a window. See How it works.
• The agent gets its connection settings through environment variables, flags or a generated file in the data folder. Your own agent configuration is never edited.
• Extra arguments go to the agent: hearthwork codex exec "...", hearthwork aider --message "...".

Look before you run

Add --dry-run as the first argument to print the exact command, the environment variables Hearthwork sets (keys masked) and the files it generates, without starting anything:

hearthwork opencode --dry-run

Stop and check

hearthwork status    # host, model, context, slots, requests per client, budget
hearthwork stop      # save the prompt cache, then stop the model and the host

hearthwork agents lists which agents are installed, the API each uses, and the install command for the missing ones. For per-agent notes see the guides: Claude Code, Codex, OpenCode, Qwen Code, Aider.

If something misbehaves, start with Troubleshooting.