Set up Handwork.

01Quick start

# Install Handwork
npm install -g handwork

# Open a project
cd /path/to/your/project
handwork

Connect a provider with /provider, then choose a model with /model.

Check Windows limitations. Windows x64 runs in CI. ARM64 is cross-compiled.

02Model providers

Connect a cloud provider or an Ollama server. Providers include OpenAI, Anthropic, Gemini, and OpenRouter.

Use /provider to choose a provider and enter its key. Enter saves and connects. Escape cancels. Ollama servers can connect without a key.

Your provider controls model access and billing. Codex and Copilot adapters use their own agent engines, tools, sessions, and permissions.

03First task

Describe the change and the checks to run.

Fix the failing parser test. Keep the change focused.
Run the parser tests and report the result.

Run a single request from your shell with ask.

handwork ask "Explain this project's entry points"
handwork ask --json "Review the current changes without editing files"

A prompt to avoid edits does not change permissions. Review the diff and test results after each task.

04Permissions and data

Run /permissions ask to require prompts. Use /allowlist to manage saved rules. If auto mode returns a caution, Handwork holds the action instead of opening a prompt.

Permission checks do not isolate the process from the operating system. They also do not prove that generated code is correct.

05Commands

Use handwork --help for all commands, handwork doctor to check setup, and handwork update to update the CLI. Restart after updating.

06Saved sessions

handwork sessions
handwork session resume last

Native sessions live in ~/.handwork/sessions. Resuming restores the conversation, not files or running programs. Check your workspace after an interrupted task.

Run handwork ask --no-save "Your task" when you do not want to save the request. Provider runtime sessions use the provider's storage.

07Images and diagrams

Handwork displays local images, SVG, and supported Mermaid diagrams. Image quality depends on your terminal.

Try a diagram

Ask for a fenced mermaid or svg block.

Return only a fenced mermaid block, without tools or explanation.
Create a flowchart: Open project -> Run tests -> Tests pass?
If yes, finish. If no, fix the code and run tests again.

Handwork renders flowcharts, state diagrams, sequence diagrams, and pie charts. Other types stay as code. Its renderer may produce a different layout than Mermaid in a browser.

Show a local image

Ask for a Markdown image on its own line:

![Test results](out/results.png)

Use an existing PNG, JPEG, GIF, or WebP file. Relative paths start where you launched Handwork. Animated images show their first frame.

Choose a terminal

Enable images in VS Code

Add these settings, then open a new VS Code terminal and restart Handwork:

{
  "terminal.integrated.enableImages": true,
  "terminal.integrated.gpuAcceleration": "auto"
}

See VS Code's terminal image documentation for host requirements.

Controls and limits

Press Control-O to open the conversation viewer. Use the trackpad or Page Up / Page Down to scroll. In Apple Terminal, enable View > Allow Mouse Reporting for trackpad scrolling.

To keep image labels and diagram source as text, start Handwork with:

HANDWORK_IMAGES=off handwork

Remote image URLs are off by default. SVG supports common shapes, paths, gradients, and text, but not every browser feature: masks, filters, clipping paths, patterns, and embedded images are not drawn. SVG text uses Handwork's stroke font rather than the font named in the file.

08Build from source

The repository uses Zig 0.16.0.

git clone https://github.com/loveconnor/handwork.git
cd handwork
zig build
./zig-out/bin/handwork --help

For Codex or Copilot adapters, also run npm ci. They require Node.js 22.12 or newer, or 20.19 or newer.