Home / FAQ
Frequently asked questions
Everything here is grounded in the tokenworm README. For the full design rationale see About, and for how it runs see How it works.
+ What language is tokenworm written in, and why?
Zig 0.16. A systems language gives explicit control over allocations, comptime metaprogramming, and real C interop — which is what lets tokenworm ship as a small native binary with a stable C ABI that any language can call.
+ How big is the binary and what does it depend on?
Per the README, the ReleaseSmall build is about 960KB with zero runtime dependencies. There is no Node runtime, Python interpreter, or Docker image required to run the CLI.
+ Which LLM providers does it support?
Five: OpenCode Zen (the default), Anthropic, OpenAI, Ollama (local, no API key), and MiniMax. You can switch between them at runtime with --provider on the CLI or switch_provider() in an SDK.
+ What tools can the agent use?
Six built-in, workspace-scoped tools: read, write, edit, bash, grep, and glob. The agent cannot access files outside the project directory, and the bash tool runs inside an OS-level sandbox.
+ Can I call tokenworm from C, Python, TypeScript, or Go?
Yes. The core is exposed through a C ABI (libtokenworm.so / .dylib), and tokenworm ships idiomatic SDKs for Python, TypeScript, and Go over that same boundary. Any language with FFI can drive the agent.
+ Is it safe to let the agent run shell commands?
By default, yes. The bash tool runs in an OS-native sandbox — bubblewrap on Linux, sandbox-exec on macOS — with allowlist, restricted, and noop fallbacks. You can disable it with --no-sandbox if you need to.
+ Does it support MCP and skills?
Yes. tokenworm integrates with the Model Context Protocol over stdio and SSE, supports SKILL.md skills, and exposes 18 lifecycle hooks for shaping the agent loop.
+ How do sessions work, and are they portable?
Sessions are stored in the .tworm binary format — conversation history, provider metadata, timestamps, token counts, and workspace snapshots, with an O(1) offset table. Per the README it is 5x smaller and 20x faster to parse than JSONL, and a session exported from one surface resumes in any other.
+ How does it compare to Claude Agent SDK or OpenAI Agents SDK?
tokenworm ships as a native binary with no runtime dependency and multi-provider support, while those SDKs require a Node or Python runtime and are single-provider. See the comparisons page for the full per-row breakdown, sourced from the README’s vs-table.
+ Is it open source?
Yes — MIT-licensed. Source lives at github.com/neul-labs/tokenworm, and it is a Neul Labs project.