Getting Started

Tapioca builds for Linux, macOS and Windows. The shell tools expect a POSIX sh, so on Windows install Git for Windows or WSL (cmd.exe is the fallback).

Build

With nix (flake):

nix run .
nix build .
nix develop
nix profile install .

nix run . runs straight from the repo, nix build . puts the binary at ./result/bin/tapioca, nix develop opens a dev shell with go, gopls, gh, tmux and python3, and nix profile install . installs onto your PATH.

Without nix, you need Go 1.26+:

go build -o tapioca .
cp tapioca ~/.npm-global/bin/

go run . and go build must run inside the repo (Go needs go.mod); the compiled binary has no such requirement — install it on your PATH and start it from any project directory, which becomes the agent's working directory.

Run

tapioca

starts a new session in the current directory. On first run Tapioca writes a commented config to ~/.config/tapioca/config.toml and points itself at a local Ollama — with Ollama running locally it works out of the box. Any other provider is a few lines of config away; see Providers.

Common invocations:

tapioca -c
tapioca -r
tapioca --model ollama:qwen3
tapioca --permission-mode plan
tapioca -p "fix the failing test"

-c continues this directory's most recent session, -r opens the resume picker, --model sets the model for this run, --permission-mode sets the starting permission mode, and -p runs headless: one prompt, print the answer, exit. The full flag list is in the CLI reference.

First steps inside the app

• Type a prompt and press enter. The agent streams its answer and calls tools; every mutating call shows a permission prompt.
• Type / to open the slash-command popup — /model picks a model, /theme a palette, /help lists everything. See Slash Commands.
• shift+tab cycles the permission mode, shown in the status bar.
• tab moves focus into the dashboards, where settings are editable in place and written back to the config file.
• f1 shows every keybinding. Defaults are in the Keybindings reference.

Where things live

What	Where
Config	~/.config/tapioca/config.toml
Sessions & state	~/.local/share/tapioca/
Personal custom commands	~/.config/tapioca/commands/
Project custom commands	.tapioca/commands/

Both directories honor XDG_CONFIG_HOME / XDG_DATA_HOME, and can be overridden with TAPIOCA_CONFIG_DIR / TAPIOCA_DATA_DIR.

Project instructions

AGENTS.md (also TAPIOCA.md, and other tools' CLAUDE.md/GEMINI.md/CRUSH.md) are read from the repository root down to the working directory, plus a global one in the config dir. @path on its own line inlines another file.