diff options
Diffstat (limited to 'index.html')
| -rw-r--r-- | index.html | 39 |
1 files changed, 39 insertions, 0 deletions
diff --git a/index.html b/index.html new file mode 100644 index 0000000..f8ef07f --- /dev/null +++ b/index.html @@ -0,0 +1,39 @@ +<!doctype html> +<html lang="en"> +<head> +<meta charset="utf-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<title>panto — Getting started</title> +<link rel="stylesheet" href="_ds/pantograph-design-system-56a1c74e-41c1-486b-ba3c-4eabdfacef31/styles.css"> +<link rel="stylesheet" href="_shared/components.css"> +<link rel="stylesheet" href="_shared/docs.css"> +</head> +<body> +<div class="pd-app"> +<header class="pd-header"> +<div class="pd-header__left"> +<button class="pd-menu" type="button" aria-label="Menu" data-menu-toggle><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="1em" height="1em"><path d="M4 12h16"/><path d="M4 6h16"/><path d="M4 18h16"/></svg></button> +<a class="pd-brand" href="index.html"><img src="assets/logo-mark.svg" width="28" height="28" alt=""><span class="pd-brand__word">panto</span><span class="pd-brand__div">/</span><span class="pd-brand__sub">docs</span></a> +<span class="pg-badge pg-badge--outline">CLI</span> +</div> +<nav class="pd-nav"><a href="index.html" class="pd-nav__link pd-nav__link--active">Getting started</a><a href="cli.html" class="pd-nav__link">Command line</a><a href="configuration.html" class="pd-nav__link">Configuration</a><a href="keybindings.html" class="pd-nav__link">Key bindings</a><a href="lua.html" class="pd-nav__link">Lua extensions</a></nav> +<div class="pd-header__right"><a class="pd-ghlink" href="https://code.tjp.lol/pantograph.git/" target="_blank" rel="noreferrer"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="1em" height="1em"><path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 .5 5 .5 5 .5c-.3 1.15-.3 2.35 0 3.5A5.4 5.4 0 0 0 4 7.5c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4"/><path d="M9 18c-4.51 2-5-2-7-2"/></svg> Source</a></div> +</header> +<div class="pd-shell"> +<aside class="pd-sidebar"><div class="pd-sidebar__scroll"><div class="pd-navsec pd-navsec--current"><p class="pd-navsec__title"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="1em" height="1em"><path d="m16.24 7.76-1.804 5.411a2 2 0 0 1-1.265 1.265L7.76 16.24l1.804-5.411a2 2 0 0 1 1.265-1.265z"/><circle cx="12" cy="12" r="10"/></svg>Getting started</p><ul class="pd-navsec__list"><li><a href="index.html#overview" class="pd-navsec__link pd-navsec__link--active">Overview</a></li><li><a href="index.html#install" class="pd-navsec__link">Install</a></li><li><a href="index.html#first-run" class="pd-navsec__link">First run</a></li><li><a href="index.html#authenticate" class="pd-navsec__link">Authenticate</a></li></ul></div><div class="pd-navsec"><p class="pd-navsec__title"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="1em" height="1em"><path d="m4 17 6-6-6-6"/><path d="M12 19h8"/></svg>Command line</p><ul class="pd-navsec__list"><li><a href="cli.html#starting" class="pd-navsec__link">Starting a session</a></li><li><a href="cli.html#sessions" class="pd-navsec__link"><code>panto sessions</code></a></li><li><a href="cli.html#models" class="pd-navsec__link"><code>panto models</code></a></li><li><a href="cli.html#auth" class="pd-navsec__link"><code>panto auth</code></a></li><li><a href="cli.html#bootstrap" class="pd-navsec__link"><code>panto bootstrap</code></a></li><li><a href="cli.html#lua" class="pd-navsec__link"><code>panto lua</code></a></li><li><a href="cli.html#slash-commands" class="pd-navsec__link">Slash commands</a></li><li><a href="cli.html#environment" class="pd-navsec__link">Environment</a></li></ul></div><div class="pd-navsec"><p class="pd-navsec__title"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="1em" height="1em"><path d="M3 5h11"/><path d="M19 5h2"/><path d="M3 12h6"/><path d="M14 12h7"/><path d="M3 19h10"/><path d="M18 19h3"/><circle cx="16" cy="5" r="2"/><circle cx="11" cy="12" r="2"/><circle cx="15" cy="19" r="2"/></svg>Configuration</p><ul class="pd-navsec__list"><li><a href="configuration.html#files" class="pd-navsec__link">Files & layers</a></li><li><a href="configuration.html#providers" class="pd-navsec__link"><code>[providers]</code></a></li><li><a href="configuration.html#auth" class="pd-navsec__link"><code>[auth]</code></a></li><li><a href="configuration.html#defaults" class="pd-navsec__link"><code>[defaults]</code></a></li><li><a href="configuration.html#policies" class="pd-navsec__link">Tools & extensions</a></li><li><a href="configuration.html#compaction" class="pd-navsec__link"><code>[compaction]</code></a></li><li><a href="configuration.html#models" class="pd-navsec__link"><code>models.toml</code></a></li><li><a href="configuration.html#system-prompt" class="pd-navsec__link">System prompt</a></li></ul></div><div class="pd-navsec"><p class="pd-navsec__title"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="1em" height="1em"><rect x="2" y="4" width="20" height="16" rx="2"/><path d="M6 8h.001"/><path d="M10 8h.001"/><path d="M14 8h.001"/><path d="M18 8h.001"/><path d="M8 12h.001"/><path d="M12 12h.001"/><path d="M16 12h.001"/><path d="M7 16h10"/></svg>Key bindings</p><ul class="pd-navsec__list"><li><a href="keybindings.html#editing" class="pd-navsec__link">Editing & cursor</a></li><li><a href="keybindings.html#submit" class="pd-navsec__link">Submit & newline</a></li><li><a href="keybindings.html#control" class="pd-navsec__link">Selectors & control</a></li><li><a href="keybindings.html#terminal" class="pd-navsec__link">Terminal protocol</a></li></ul></div><div class="pd-navsec"><p class="pd-navsec__title"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="1em" height="1em"><path d="M2.97 12.92A2 2 0 0 0 2 14.63v3.24a2 2 0 0 0 .97 1.71l3 1.8a2 2 0 0 0 2.06 0L12 19v-5.5l-5-3-4.03 2.42Z"/><path d="m7 16.5-4.74-2.85"/><path d="m7 16.5 5-3"/><path d="M7 16.5v5.17"/><path d="M12 13.5V19l3.97 2.38a2 2 0 0 0 2.06 0l3-1.8a2 2 0 0 0 .97-1.71v-3.24a2 2 0 0 0-.97-1.71L17 10.5l-5 3Z"/><path d="m17 16.5-5-3"/><path d="m17 16.5 4.74-2.85"/><path d="M17 16.5v5.17"/><path d="M7.97 4.42A2 2 0 0 0 7 6.13v4.37l5 3 5-3V6.13a2 2 0 0 0-.97-1.71l-3-1.8a2 2 0 0 0-2.06 0l-3 1.8Z"/><path d="M12 8 7.26 5.15"/><path d="m12 8 4.74-2.85"/><path d="M12 13.5V8"/></svg>Lua extensions</p><ul class="pd-navsec__list"><li><a href="lua.html#overview" class="pd-navsec__link">Overview</a></li><li><a href="lua.html#loading" class="pd-navsec__link">Loading extensions</a></li><li><a href="lua.html#tools" class="pd-navsec__link"><code>register_tool</code></a></li><li><a href="lua.html#commands" class="pd-navsec__link"><code>register_command</code></a></li><li><a href="lua.html#events" class="pd-navsec__link">Events: on & emit</a></li><li><a href="lua.html#components" class="pd-navsec__link">Lua components</a></li><li><a href="lua.html#runtime" class="pd-navsec__link">Runtime & luarocks</a></li></ul></div></div></aside> +<div class="pd-scrim"></div> +<main class="pd-main"><article class="pd-doc" data-screen-label="panto"><p class="panto-eyebrow pd-eyebrow">Getting started</p><h1 class="pd-doc__h1">panto</h1><div class="pd-doc__meta"><span class="pg-badge pg-badge--neutral">terminal agent</span><span class="pg-tag"><span class="pg-tag__dot" style="background:var(--red)"></span>zig</span><span class="pg-tag"><span class="pg-tag__dot" style="background:var(--green)"></span>lua</span></div><p class="pd-lead">panto is a small terminal coding agent built on libpanto. A minimal system prompt, a tool set you can swap or switch off, native binaries from Zig, extensions in Lua. This is the operator's reference — flags, configuration, key bindings, and the Lua surface.</p><h2 id="overview" class="pd-h2">Overview</h2><p class="pd-body">You run <code>panto</code> inside a project directory and talk to a model in a terminal UI. The agent reads and edits files and runs commands through <strong>tools</strong> — and even the standard tools (<code>read</code>, <code>write</code>, <code>edit</code>, <code>bash</code>) ship as extensions, so any of them can be denied individually.</p><p class="pd-body">There are no permission prompts and no hidden machinery: providers are declared in a TOML file, the model is chosen by a <code>provider:alias</code> reference, and anything beyond the core is added as a Lua extension. The rest of these pages document each of those surfaces in turn.</p><div class="panto-tick-rule pd-rule"></div><h2 id="install" class="pd-h2">Install</h2><p class="pd-body">panto builds from source with <a href="https://ziglang.org" target="_blank" rel="noreferrer">Zig</a>. Clone the repository and run the Zig build; the result is a single native binary.</p><div class="pg-code"><div class="pg-code__bar"><span class="pg-code__name">shell</span><span class="pg-code__lang">bash</span><button class="pg-code__copy" type="button" aria-label="Copy code"><svg class="pg-code__copyglyph" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg><svg class="pg-code__check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="m20 6-11 11-5-5"/></svg><span class="pg-code__label">Copy</span></button></div><div class="pg-code__scroll"><pre><code>git clone https://code.tjp.lol/pantograph.git +cd pantograph +zig build # native binary at zig-out/bin/panto</code></pre></div></div><p class="pd-body">On first use, run the one-time bootstrap. It stages the embedded Lua runtime and installs panto’s pinned <a href="lua.html#runtime">luarocks</a> batteries (just <code>luv</code>, the libuv event loop) under <code>$PANTO_HOME</code>:</p><div class="pg-code"><div class="pg-code__bar"><span class="pg-code__name">shell</span><span class="pg-code__lang">bash</span><button class="pg-code__copy" type="button" aria-label="Copy code"><svg class="pg-code__copyglyph" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg><svg class="pg-code__check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="m20 6-11 11-5-5"/></svg><span class="pg-code__label">Copy</span></button></div><div class="pg-code__scroll"><pre><code>panto bootstrap # prepare the rocks tree (idempotent)</code></pre></div></div><div class="pg-callout pg-callout--tip"><span class="pg-callout__icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 18h6"/><path d="M10 22h4"/><path d="M15.09 14c.18-.98.65-1.74 1.41-2.5A4.65 4.65 0 0 0 18 8 6 6 0 0 0 6 8c0 1 .23 2.23 1.5 3.5A4.61 4.61 0 0 1 8.91 14"/></svg></span><div class="pg-callout__body"><p class="pg-callout__title">Where things live</p>By default panto keeps its runtime and rocks tree in <code>$PANTO_HOME</code> (falling back to <code>$XDG_DATA_HOME/panto</code>), and reads configuration from a layered set of TOML files. See <a href="configuration.html#files">Configuration → Files & layers</a>.</div></div><h2 id="first-run" class="pd-h2">First run</h2><p class="pd-body">Run <code>panto</code> with no arguments inside a project to start a fresh conversation. The agent loads your config, selects the default model, and opens the terminal UI. Type a message and press <span class="pd-kbd">Enter</span> to send it.</p><div class="pg-term"><div class="pg-term__bar"><span class="pg-term__dot" style="background:var(--red)"></span><span class="pg-term__dot" style="background:var(--brass)"></span><span class="pg-term__dot" style="background:var(--green)"></span><span class="pg-term__title">panto · first run</span></div><div class="pg-term__body"><div class="pg-term__line pg-term__line--cmd"><span class="pg-term__prompt">$ </span>export ANTHROPIC_API_KEY=sk-ant-…</div><div class="pg-term__line pg-term__line--cmd"><span class="pg-term__prompt">$ </span>cd ~/code/ledger && panto</div><div class="pg-term__line"> </div><div class="pg-term__line pg-term__line--accent"> panto v0.1.0</div><div class="pg-term__line pg-term__line--dim"> cwd: ~/code/ledger</div><div class="pg-term__line"> </div><div class="pg-term__user">add a --json flag to the stats command</div><div class="pg-term__line"> </div><div class="pg-term__line">I’ll wire a <code>--json</code> branch into the stats command. Let me read it first.</div><div class="pg-term__tool"><div class="pg-term__tool-head">read src/stats.zig</div><div class="pg-term__tool-body">pub fn run(args: Args) !void { + const summary = try compute(args); + try printHuman(summary); +}</div></div><div class="pg-term__tool"><div class="pg-term__tool-head">edit src/stats.zig (1 edit)</div><div class="pg-term__tool-body"><span class="pg-term__del">- try printHuman(summary);</span> +<span class="pg-term__add">+ if (args.json) try printJson(summary) else try printHuman(summary);</span></div></div><div class="pg-term__line"> </div><div class="pg-term__line">Done — <code>stats --json</code> now prints a machine-readable summary.</div><div class="pg-term__line"> </div><div class="pg-term__rule"></div><div class="pg-term__line pg-term__line--cmd"> <span class="pg-term__cursor"></span></div><div class="pg-term__rule"></div><div class="pg-term__line pg-term__line--dim">anthropic:sonnet 18.4k ctx 2.1k tok $0.03</div></div></div><p class="pd-body">panto’s UI needs an interactive terminal (a tty). Sessions are saved per directory, so you can pick up where you left off with <code>panto --resume</code>. The full command surface — resuming, listing sessions, auth, the embedded Lua interpreter — is on the <a href="cli.html#starting">Command line</a> page, and every key is listed under <a href="keybindings.html#editing">Key bindings</a>.</p><h2 id="authenticate" class="pd-h2">Authenticate</h2><p class="pd-body">A provider draws its credential from a named <em>auth session</em>. There are two kinds. The simplest is an API key from the environment — the default OpenAI and Anthropic providers read <code>OPENAI_API_KEY</code> and <code>ANTHROPIC_API_KEY</code> directly:</p><div class="pg-code"><div class="pg-code__bar"><span class="pg-code__name">shell</span><span class="pg-code__lang">bash</span><button class="pg-code__copy" type="button" aria-label="Copy code"><svg class="pg-code__copyglyph" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg><svg class="pg-code__check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="m20 6-11 11-5-5"/></svg><span class="pg-code__label">Copy</span></button></div><div class="pg-code__scroll"><pre><code>export ANTHROPIC_API_KEY=sk-ant-… +panto # the anthropic provider is now live</code></pre></div></div><p class="pd-body">The second is an OAuth device flow, for providers that authenticate interactively. Log in once and panto stores (and refreshes) the token for you:</p><div class="pg-code"><div class="pg-code__bar"><span class="pg-code__name">shell</span><span class="pg-code__lang">bash</span><button class="pg-code__copy" type="button" aria-label="Copy code"><svg class="pg-code__copyglyph" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg><svg class="pg-code__check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="m20 6-11 11-5-5"/></svg><span class="pg-code__label">Copy</span></button></div><div class="pg-code__scroll"><pre><code>panto auth login github_copilot +panto auth status # show every session and its login state</code></pre></div></div><div class="pg-callout pg-callout--note"><span class="pg-callout__icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg></span><div class="pg-callout__body"><p class="pg-callout__title">If a provider seems missing</p>An <code>api_key</code> session whose environment variable is empty resolves to nothing, and any provider using it is silently dropped (export the key to bring it back). OAuth providers always survive and resolve at turn time. Auth sessions are declared under <a href="configuration.html#auth"><code>[auth]</code></a> in config.</div></div><nav class="pd-prevnext"><span style="flex:1"></span><a class="pd-pn pd-pn--next" href="cli.html"><span class="pd-pn__dir">Next →</span><span class="pd-pn__title">Command line</span></a></nav></article></main> +<aside class="pd-toc"><p class="pd-toc__title">On this page</p><ul class="pd-toc__list"><li><a href="#overview" class="pd-toc__link pd-toc__link--active">Overview</a></li><li><a href="#install" class="pd-toc__link">Install</a></li><li><a href="#first-run" class="pd-toc__link">First run</a></li><li><a href="#authenticate" class="pd-toc__link">Authenticate</a></li></ul></aside> +</div> +</div> +<script src="_shared/docs.js"></script> +</body> +</html>
\ No newline at end of file |