Getting started

panto

panto is a terminal coding agent with a small Zig core and a Lua extension surface. Run it interactively in a project directory, or use -p/--print for one-shot non-interactive turns. These pages cover the current CLI, configuration layers, key bindings, and extension API.

Overview

The default entry point is just panto: it opens the TUI in the current directory, selects a model from your layered config, and lets the agent work through tools. The shipped file tools are themselves Lua extensions, so the same loader that powers your own add-ons also powers std.read, std.write, std.edit, and std.shell.

Configuration covers [defaults].model/reasoning, [tui].editor/theme/tools_collapsed, [api].timeout/retries, [compaction], and [extensions] allow, deny, paths, and rocks. The Lua surface includes register_tool, register_command, register_protocol, run_foreground, events, syntax highlighting, styles, JSON helpers, session/model helpers, panto.ext.dirs, and panto.text.*.

The TUI key table covers Enter, Ctrl+Enter, Shift+Enter, Ctrl+C/D, Esc, history and navigation, Tab completion, model/reasoning/theme selectors, tool collapse, tree controls, $EDITOR, editing keys, and selector filtering; see Key bindings.

The first argument dispatches named commands such as panto sessions, panto models sync, panto auth, panto bootstrap [--force], panto version, panto update [--check], panto extension install, panto extension update, and panto extension remove, and panto lua [args...]; these run and exit. panto run <file.agent> extracts an agent bundle and starts a session, using its bundled PROMPT.md unless --interactive is supplied. panto --help (also -h and help) and panto --version print and exit; -p/--print runs one non-interactive turn.

Install

Install the latest release binary:

curl -fsSL https://tjp.lol/pantograph/install.sh | sh

The installer writes to /usr/local/bin by default. Set PANTO_INSTALL_DIR to choose another directory. It uses sudo only when the destination (or its nearest existing parent) is not writable, and warns if the destination is not in PATH. Prebuilt binaries support macOS arm64, Linux x86_64 with glibc 2.28+, and FreeBSD x86_64.

To build from source, install the pinned Zig and Rust toolchains, Rust targets, and cargo-zigbuild with mise install:

mise install
mise run build:release

Release artifacts are written to zig-out/release/panto-<ver>-macos-arm64, zig-out/release/panto-<ver>-linux-x86_64, zig-out/release/panto-<ver>-freebsd-x86_64, and zig-out/release/SHA256SUMS. Normal builds fetch the pinned libpantograph package and build panto_lua internally; run zig build for a native development binary. The explicit local-build mode uses the sibling checkout:

mise run build:local   # uses --fork=../libpantograph

On a target platform (or under emulation), sh scripts/check-release-binary.sh /path/to/panto smoke-tests the native Lua module and Rust highlighting. Starting panto normally bootstraps the bundled Lua/LuaRocks runtime; run panto bootstrap to prepare it separately, or panto bootstrap --force to rebuild the per-Lua-version tree.

The data home is $XDG_DATA_HOME/panto (or ~/.local/share/panto when XDG_DATA_HOME is unset). It contains base config.toml and models.toml, the staged agent/ tree, OAuth files under auth/, versioned rocks/lua-5.4.7/, and default debug logs. User config lives under $XDG_CONFIG_HOME/panto (or ~/.config/panto); Git extensions use dist/ in the data home and symlinks under its extensions/ directory. Configuration precedence is state → base → user → project → local. state.toml remembers picker selections and extensions.rocks; delete it to reset remembered selections. PANTO_DEBUG redirects debug logging to the data home, while PANTO_SESSION_DIR can place sessions elsewhere.

Updating

panto update checks for the latest semver release, verifies its checksum, and atomically replaces the running binary. panto update --check reports whether a newer release is available without installing it. If the binary is not writable, panto prints permission denied writing <path>; rerun with sudo. Updates keep no backup; to roll back, rerun install.sh.

Versions

panto versions are semantic versions. panto version prints the installed version; release tags use the form v<x.y.z>. Download releases from Codeberg releases.

First run

Start an interactive session with no arguments:

cd ~/code/ledger
panto

Useful first-day flags:

The TUI also provides /help, /quit, /model, /theme, /reasoning, /new, /resume, /tree, and /status. Lines beginning with ! run shell commands at the tool boundary; !! also starts a turn. Agent bundles use panto run <file.agent>; a fresh bundle reads PROMPT.md, while --interactive skips it.

The TUI requires both stdin and stdout to be interactive terminals. If you only want a single answer in a script or CI job, use -p instead of trying to pipe the full-screen UI. Core themes include Panto, Tidepool Tumble, Mossmallow, Peachy Pudding, Plum Pips, and Gilded Inkblot; install the optional panto-popular-themes rock for Tokyo Night, Catppuccin, Gruvbox, Solarized, Nord, Dracula, and Kanagawa themes. Ctrl+Y or /theme previews them live.

Authenticate

Providers refer to named auth sessions in layered config.toml. The generated base config uses OPENAI_API_KEY and ANTHROPIC_API_KEY for its default API-key providers:

export OPENAI_API_KEY=…
export ANTHROPIC_API_KEY=sk-ant-…
panto auth status

For a configured OAuth device session, replace <name> with its auth name. panto prints a device URL and code, saves the resulting token under the data home, and resolves it when the provider is used:

panto auth login <name>
panto auth status