Skip to content
tokenworm ★ GitHub

Home / Quickstart

Install, set a key, ask

Four ways to install, one native binary. Set a key for any of the five providers and the agent loop, tool dispatch, and sandbox are already wired up.

1 · Install

~ install
# Homebrew (macOS / Linux)
brew install tokenworm

# npm
npm install -g tokenworm

# pip
pip install tokenworm

# From source (Zig 0.16)
zig build -Doptimize=ReleaseSmall

2 · Set a provider key

~ providers
# Default: OpenCode Zen
export OPENCODE_ZEN_API_KEY="your-key"

# Or Anthropic / OpenAI / MiniMax
export ANTHROPIC_API_KEY="your-key"

# Or run local with Ollama (no key)
tokenworm --provider ollama "..."

3 · Run a task

~ tokenworm
# One-shot
tokenworm "what does src/main.zig do?"

# Interactive REPL
tokenworm -i

# Switch provider at runtime
tokenworm --provider anthropic "refactor auth"

4 · Drive it from Python

~ python
# pip install tokenworm
from tokenworm import Agent

agent = Agent(provider="opencode-zen")
async for chunk in agent.run("add a test"):
    print(chunk)

# Portable session
tokenworm --export-session s.tworm "..."

Each step, in order

  1. 1

    Install the binary

    Install with Homebrew (brew install tokenworm), npm (npm install -g tokenworm), or pip (pip install tokenworm). All resolve to the same Zig-compiled native binary. Or build from source with Zig 0.16: zig build -Doptimize=ReleaseSmall.

  2. 2

    Set a provider key

    Pick one of the five providers and export its key: OPENCODE_ZEN_API_KEY (default), ANTHROPIC_API_KEY, OPENAI_API_KEY, or MINIMAX_API_KEY. For a fully local run, install Ollama — no API key needed.

  3. 3

    Run a one-shot task

    Ask the agent to do something: tokenworm "what does src/main.zig do?". The bash tool is sandboxed by default and all tools are workspace-scoped.

  4. 4

    Switch providers or persist a session

    Switch at runtime with --provider anthropic. Export a portable session with --export-session session.tworm and resume it later, in the CLI or any SDK.

The Python snippet is illustrative; see the documentation for the exact SDK surface.

Where to next

Use cases Providers How it works