Documentation
Install and configure Handwork.
The npm package supports macOS on Apple Silicon. You need npm and access to a model provider.
01Quick start
# Install Handwork
npm install -g handwork
# Open a project
cd /path/to/your/project
handworkRun /provider in Handwork to connect a provider. Run /model to choose a model.
Run /permissions. The default auto mode reviews sensitive actions that no rule has approved. It can still approve an action, so it is not read only.
02Model providers
Handwork supports OpenAI, Anthropic, Gemini, xAI, DeepSeek, Mistral, Groq, Together AI, Fireworks AI, OpenRouter, MiniMax, and Ollama.
Run /provider, choose a provider, and enter its key. The input masks typed and pasted text. Press Enter to save the key and connect. Press Escape to cancel. Ollama can connect to your server without an API key.
The provider controls model access and billing. The official Codex and Copilot adapters run the provider's agent engine. They do not use Handwork's native tools, sessions, or permission checks.
Read the authentication reference03First task
Name the change and the checks you want Handwork to run.
Fix the failing parser test. Keep the change focused.
Run the parser tests and report the result.Use ask to run one request without opening the interactive interface.
handwork ask "Explain this project's entry points"
handwork ask --json "Review the current changes without editing files"The second prompt tells the model not to edit. It does not change tool permissions. Check the diff and command results after every coding task.
04Permissions and data
| Mode | Behavior |
|---|---|
ask | Prompts before sensitive actions that no rule has approved. |
auto | Reviews sensitive actions that no rule has approved. This is the default. |
full-access | Turns off Handwork's permission checks. |
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.
A request can include your prompt, code excerpts, tool results, and conversation history. Read the provider's data policy before sending private code. Handwork stores native API keys in files that only your account can read. It does not encrypt them at rest.
Permission checks do not isolate the process from the operating system. They also do not prove that generated code is correct.
05Commands
| Command | Action |
|---|---|
/help | Lists commands. |
/provider | Connects or switches providers. |
/model | Chooses a model and reasoning effort. |
/new | Starts a session. |
/resume | Opens a saved session. |
/compact | Summarizes the conversation in a new context window. |
/skills | Lists and manages skills. |
/mcp | Manages MCP servers and project trust. |
/quit | Exits Handwork. |
Run handwork --help in your shell for the full command list. Run handwork doctor to check the local setup. Run handwork update to update a global npm installation, then restart Handwork.
06Saved sessions
handwork sessions
handwork session resume lastHandwork stores native sessions in ~/.handwork/sessions. A resumed session restores the conversation. It does not restore old file contents or running programs. Check the 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.
07Build 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 --helpThe native agent can call model APIs without the JavaScript adapters. The official runtime adapters also need npm ci and Node.js 22.12 or newer, or Node.js 20.19 or newer. The project does not claim support for every source build target.