Puny

Puny is a minimal natively compiled single-binary coding agent with a ~1 MB footprint.

It's designed for people who want a fast, lightweight coding agent that runs smoothly on limited hardware or remote machines. This is a coding agent that starts in under 1 millisecond, uses around 1 MB of disk space, uses minimal memory, uses <1% CPU, and stays out of your way.

• Multiple providers: local-first LM Studio, Unsloth, or Ollama, or hosted models via Ollama Cloud, OpenCode Zen, OpenCode Go, or your GitHub Copilot subscription.
• Interactive model picker: choose the model to load when Puny starts.
• Multi-turn chat: keeps the conversation history across messages.
• Session management: each run, /new, or /reset creates a new UUID-identified session, with the conversation automatically saved after every turn and PRDs saved to the session folder. Sessions can be resumed with /resume or --session.
• Branch review mode: review committed branch changes against the latest origin/main and produce an automation-ready merge-worthiness report.
• Orchestrate loop: /orchestrate and --orchestrate run implement → review → fix until the branch is merge worthy, each phase from a fresh context.
• Crash reports: a run that fails writes a small markdown report to the config directory; the next interactive start offers to file it as a GitHub issue.
• Tool calling: the LLM can use built-in tools to work with your project.
• Skills system: extend Puny with reusable prompt-engineering skills stored in markdown files.
• Built-in tools:
  • Read, edit, write, and list files in your project
  • Run shell commands
  • Search your codebase
  • Load skills
  • Fetch web pages

Startup time ~1ms means Puny is always ready when you are — no spinner, no animations, no waiting. The ~1 MB binary and minimal memory footprint mean it runs comfortably on a Raspberry Pi, a slow remote server over SSH, or a cheap decade-old laptop. Every millisecond and megabyte is deliberate: there is no hidden runtime, no garbage collector, no Node.js dependencies, no JavaScript.

Puny is designed around the way I work. It is highly opinionated. That means it will never try to be everything to everyone. It's a tool and will never take credit itself for your work by adding itself as a co-author to your commits. It will never try to be a platform, a framework, or a plugin ecosystem.

Other coding agents include MCP, subagents, plugins, extensions, animations, and dozens of other features I never asked for. Puny does not. The feature set is limited to what I need to get results: read files, write files, run commands, search code, load skills, fetch web pages. If you want parallel work, run another instance.

Each feature earns its place. Nothing ships because it looks good on a comparison table. This is not a platform — it is a tool.

Puny does not show the model's reasoning or thinking output by default. I do not care about the model's internal monologue. I see it as a wall of text, a huge TL;DR you have to scroll past to get to the actual answer. If you want it, pass --show-thinking. If you think you want it later, pass --chat-log which saves the entire conversation, noise included, to puny_chat.log

The supported providers are the ones I use personally:

• LM Studio — local inference on my own hardware
• Unsloth — local inference through Unsloth Studio
• OpenCode Zen — wide selection of reliable optimized models
• OpenCode Go — cheaper hosted models when I need them
• GitHub Copilot — comes with my sponsored GitHub subscription

Puny also supports Ollama, both a local Ollama server and Ollama Cloud.

Puny lets you chat with an LLM and gives it a curated set of coding tools so it can read, edit, search, and inspect your codebase.

Linux/macOS:

curl -fsSL https://christianhelle.com/puny/install | bash

Windows (PowerShell):

irm https://christianhelle.com/puny/install.ps1 | iex

The install scripts download the latest release from GitHub and install the binary (Linux/macOS detects x86_64 and aarch64; Windows currently installs the x86_64 build).

Custom installation directory:

# Linux/macOS
curl -fsSL https://christianhelle.com/puny/install | bash -s -- --dir "$HOME/.local/bin"
# Windows
$install = irm https://christianhelle.com/puny/install.ps1
& ([scriptblock]::Create($install)) -InstallDir "C:\Tools"

Pin a specific version:

# Linux/macOS
VERSION=v0.1.0 curl -fsSL https://christianhelle.com/puny/install | bash

# Windows
$install = irm https://christianhelle.com/puny/install.ps1
& ([scriptblock]::Create($install)) -Version "v0.1.0"

If Puny is already installed, upgrade to the latest version:

puny --upgrade

This re-runs the install script for your platform.

Requires Zig 0.17.0 or later.

git clone https://github.com/christianhelle/puny.git
cd puny
zig build

The compiled binary is written to zig-out/bin/puny. Copy it to a directory on your PATH to run it from anywhere.

To build a release binary and install it to $HOME/.local/bin (the same directory used by the install scripts), run:

zig build install-release

Other optimization modes are available:

zig build install-release-safe   # safe release build (runtime safety checks enabled)
zig build install-release-fast   # fast release build (maximizes runtime performance)
zig build install-debug          # debug build

The install directory can be overridden with the INSTALL_DIR environment variable or the --prefix flag:

INSTALL_DIR=/custom/path zig build install-release
zig build install-release --prefix /custom/path

Run the test suite:

zig build test

Run the regression test suite:

zig build test-regression

On first run, Puny launches a one-time setup wizard that asks you to pick a provider and API key (and a URL only for LM Studio, Unsloth, and Ollama; Ollama Cloud, OpenCode Zen, OpenCode Go, and GitHub Copilot use fixed URLs). Your choices are saved to config.json and the wizard is skipped on later runs.

Start LM Studio and load a model with tool-calling support, then:

puny

Or, if you are running from the source tree:

zig build run

Start Unsloth Studio (for example with unsloth run) and download a model with tool-calling support, then:

puny --provider unsloth

Puny connects to http://127.0.0.1:8888 by default (http://host.docker.internal:8888 in the Docker image), lists models from /v1/models, and streams through the OpenAI-compatible /v1/chat/completions endpoint. Unsloth serves one loaded model at a time, so before the first chat with a model Puny loads it through POST /api/inference/load, replacing whichever model Unsloth had loaded. The first reply can take a while as the model loads, and Puny loads it again if Unsloth has since unloaded it. If Unsloth listens on another port (for example after unsloth run -p 9000), pass --url:

puny --provider unsloth --url http://127.0.0.1:9000

No API key is needed. If your Unsloth server is set up to require one (sk-unsloth-…), set it in PUNY_API_KEY or use --api-key-file; Puny sends it as a Bearer token.

Unsloth serves plain HTTP, so any API key travels unencrypted. To reach Unsloth on another machine, forward the port over SSH (ssh -L 8888:127.0.0.1:8888 gpu-box) or put it behind an HTTPS reverse proxy and pass that https:// URL, rather than exposing it with -H 0.0.0.0.

Start the Ollama server (the desktop app, or ollama serve) and pull a model with tool-calling support, then:

ollama pull qwen3:8b
puny --provider ollama

Puny connects to http://127.0.0.1:11434 by default (http://host.docker.internal:11434 in the Docker image), lists models from /v1/models, and streams through Ollama's OpenAI-compatible /v1/chat/completions endpoint, loading the selected model on first use. If Ollama runs elsewhere, pass --url:

puny --provider ollama --url http://gpu-box:11434

No API key is needed. If you point Puny at a remote Ollama behind an authenticating proxy and set a key, note that an http:// URL sends that key as a Bearer token in cleartext: use an https:// URL, or forward the port over SSH (ssh -L 11434:127.0.0.1:11434 gpu-box) and keep the URL on 127.0.0.1.

After ollama signin, the local server also offers Ollama's cloud models (for example gpt-oss:120b-cloud) and relays them to ollama.com for you.

To use Ollama's cloud models without running a local server, create an API key at ollama.com/settings/keys and set it in OLLAMA_API_KEY or PUNY_API_KEY (or use --api-key-file), then:

puny --provider ollama_cloud

Puny connects to https://ollama.com, sends the key as a Bearer token, and shows the cloud models in the picker. The key is resolved in this order: --api-key, then --api-key-file, then PUNY_API_KEY, then OLLAMA_API_KEY, then the key saved in config.json.

Sign in to OpenCode Zen, copy your API key, and set it in PUNY_API_KEY (or use --api-key-file), then:

puny --provider opencode_zen

Puny connects to https://opencode.ai/zen and shows the model picker. Puny chooses the streaming transport from the model ID:

• muse-spark-*, grok-*, and gpt-* use /v1/responses.
• claude-* uses Anthropic's /v1/messages.
• gemini-* uses Google's /v1/models/<model>:streamGenerateContent.
• All other model IDs use the OpenAI-compatible /v1/chat/completions endpoint.

Sign in to OpenCode Zen, subscribe to Go, copy your API key (the same key works for Zen and Go), and set it in PUNY_API_KEY (or use --api-key-file), then:

puny --provider opencode_go

Puny connects to https://opencode.ai/zen/go and shows the model picker. Models beginning with muse-spark-, grok-, or gpt- use /v1/responses; minimax-* and qwen* use Anthropic's /v1/messages; all other model IDs use /v1/chat/completions.

Requests to OpenCode Zen and OpenCode Go carry an x-opencode-session header holding the full current session id, so OpenCode can group the requests belonging to one conversation exactly. Starting a new session with /new or /reset sends a new id; resuming a session with /resume or --session keeps the original one. Puny also identifies itself as puny/<version> in the User-Agent of every request.

Use Puny with your existing GitHub Copilot subscription:

puny --provider copilot

Puny resolves a GitHub OAuth token in this order:

1. A token you supply manually via --api-key, --api-key-file, PUNY_API_KEY, config.json, or the GITHUB_COPILOT_OAUTH_TOKEN environment variable.
2. Auto-discovery of an existing token from the GitHub Copilot editor plugin (apps.json/hosts.json) or from OpenCode's auth.json.
3. An interactive device-flow login: Puny prints a code and a URL to open in your browser, then persists the acquired token to config.json for future runs.

It then exchanges that OAuth token for a short-lived Copilot token and shows the model picker. The picker lists the same curated models the GitHub Copilot CLI offers — the models your subscription marks as picker-enabled. Models served over the OpenAI-compatible /chat/completions endpoint use it; models Copilot only serves over the Responses API (e.g. GPT-5.5, GPT-5 Codex, Grok) are streamed through /responses instead. Legacy models (e.g. GPT-3.5, GPT-4o) and internal agent models are filtered out. The general-purpose GH_TOKEN/GITHUB_TOKEN environment variables are intentionally not used, so an unrelated GitHub token can't break the exchange.

Support for GitHub Copilot is experimental, but both chat and tool calling work across the listed models (Claude, GPT-5, Gemini, Grok, Kimi, and more).

Run Puny from the project directory you want the agent to work in:

puny

Puny uses the provider saved during setup and reuses its saved model when available. If no usable model is saved, Puny opens the provider's model picker before opening the chat prompt. When using LM Studio, Unsloth, or Ollama, start it and load or pull a tool-capable model first.

Type your request and press Enter:

> Explain what this project does

The model replies in the terminal. You can keep sending follow-up messages; Puny remembers the conversation.

> Now list the source files

🔧 Listing directory "src"

The project has source files under src/, including main.c, utils.h, and a tests/ folder.

The prompt supports shell-style (readline) editing:

On POSIX terminals whose erase key is Ctrl+H, Ctrl+Backspace sends the same byte as Backspace and deletes a single character. Use Alt+Backspace or Ctrl+W there instead.

On Linux and macOS, Ctrl+Z suspends Puny like any other terminal program, at the prompt or while a response streams. Run fg to bring it back: the prompt returns with whatever you had typed, and a streaming response carries on.

Type @ at the start of a prompt or after whitespace to open a searchable file picker rooted at the current directory. Selecting a file inserts an @path mention:

> Explain @src/main.zig and compare it with @src/config/config.zig

You can also type @path mentions directly. Before sending the prompt, Puny appends the contents of each readable file. Each attachment is limited to 64 KiB; unreadable files, larger files, and paths containing whitespace are not attached.

When Puny starts inside a Git repository, it loads the first instruction file found at the repository root in this order:

1. AGENTS.md
2. .github/copilot-instructions.md
3. CLAUDE.md

Only one file is loaded. Use it for project-specific build commands, conventions, and constraints that should apply to every request. Puny restores these instructions after /new, /reset, and between orchestrate phases.

Run one prompt and exit:

puny --prompt "List all source files" --oneshot

--oneshot requires either --prompt or --prompt-file. It reuses the model saved during setup; pass --model (or set PUNY_MODEL) to make an unattended run independent of that saved selection:

puny --model model-id --prompt "List all source files" --oneshot

On a fresh installation, run puny once to complete the setup wizard before using one-shot mode in a non-interactive job.

Run one autonomous review of the current branch and exit:

puny --review

Puny fetches origin/main, fixes the review scope to merge-base(origin/main, HEAD)..HEAD, reviews committed changes, and writes review-results.md in the repository root. Staged, modified, and untracked work is reported separately and does not affect the branch verdict. Existing build, test, and lint checks run in the current worktree, so their generated artifacts are allowed, but review mode does not expose generic file writing.

The report always includes review scope, change summary, quality and regression assessment, validation performed, findings, and a binary conclusion: MERGE WORTHY: YES or MERGE WORTHY: NO. Incomplete evidence forces NO. A branch with no committed changes also receives NO.

Review mode rejects main, detached HEAD, and directories outside a Git repository. Invoking it on main exits with code 2 without writing a report. For a single autonomous review pass use puny --review directly. To loop implement → review → fix until merge worthy, use /orchestrate or --orchestrate (see below).

/orchestrate and --orchestrate run the autonomous flow [plan] → implement → (while review != merge worthy) → fix findings in a single process, and exit with the same code puny --review would.

[plan (interactive, /orchestrate --plan only)]
  → implement (build mode, the model commits as it works)
    → commit anything left in the worktree (excluding generated files)
    → review (0 = merge worthy, 1 = rejected, 2 = operational failure)
    → on 0: done; on 1: feed review-results.md back for fixes and loop

Every phase starts from a fresh conversation and hands off through artifacts — the saved PRD into implement, commits into review, and review-results.md back into fix. Nothing accumulates across phases, so the loop stays inside the context window of a small local model.

# Implement, then loop until merge worthy (default 5 iterations)
puny --orchestrate --prompt "Add CSV export to the report command"

# From a spec file, capped at 3 iterations
puny --orchestrate --prompt-file spec.md --max-iterations 3

Inside a chat session:

/orchestrate Add CSV export to the report command
/orchestrate --iterations 3 Add CSV export
/orchestrate --plan Add CSV export     # plan interactively first, then run
/orchestrate                           # implement the PRD this session saved

/orchestrate --plan runs the normal interactive planning interview. The loop starts by itself the moment the model calls save_prd, reading the PRD straight from the session folder — nothing is copied into your repository. Bare /orchestrate does the same for a plan the session already has.

The headless --orchestrate flag never plans: it needs --prompt or --prompt-file and goes straight to implementing.

Commits. The review only sees committed changes, so the model is told to commit as it works: one logical change per commit, one-line plain-English imperative messages, no Conventional Commits prefixes, no trailers, no co-author, never pushing or amending. Anything it leaves behind is swept into a single backstop commit before the review runs, so a review never passes judgement on a partial diff. review-results.md, puny_http.log, and puny_chat.log are never committed. Override the instructions with the prompts.orchestrate entry in config.json.

Preconditions: run from a repository on a feature branch (not main, not detached HEAD). The branch needs origin/main available so the review can compute merge-base(origin/main, HEAD)..HEAD.

Exit codes mirror puny --review: 0 merge worthy, 1 still not merge worthy after the iteration budget, 2 operational failure (missing repo, detached HEAD, on main, fetch failure, a failed commit, or an interrupted run).

Press Ctrl+C to stop a run. Work already committed stays committed; anything still in the worktree is left for you. Interrupts are noticed between phases — use double-Esc to cancel a turn already in flight.

Load the first prompt from a local file or an http:///https:// URL, either at startup via the CLI or interactively with /file:

# CLI: local file or remote URL, optionally one-shot
puny --model model-id --prompt-file spec.md --oneshot
puny --prompt-file https://example.com/spec.md

# Interactive
/file spec.md
/file https://example.com/spec.md

At startup, --prompt-file loads the content and sends it as the first user message, exactly like --prompt. --oneshot accepts --prompt-file in place of --prompt, and using both --prompt and --prompt-file is an error.

In the interactive loop, /file loads the content and sends it as the next user message instead.

Both flows load from local files or remote URLs; local files and remote responses are limited to 10 MiB, and remote fetches time out after 30 seconds.

Use --provider to switch between LM Studio (lmstudio, the default), OpenCode Zen (opencode_zen), OpenCode Go (opencode_go), GitHub Copilot (copilot), Unsloth (unsloth), Ollama (ollama), and Ollama Cloud (ollama_cloud). The same identifiers apply to PUNY_PROVIDER and the provider field in config.json.

puny --provider opencode_zen

Precedence is: --provider > PUNY_PROVIDER > config.json > lmstudio.

If LM Studio is running on another machine, point Puny at it:

puny --url http://192.168.1.42:1234

If your provider requires an API token, provide it through the environment, a key file, or the encrypted config:

# Environment variable (session only)
export PUNY_API_KEY=lmstudio-token-123
puny

# Read from a file (session only)
puny --api-key-file /run/secrets/lmstudio-key

# Save to config interactively
puny --reconfigure

Precedence is: --api-key > --api-key-file > PUNY_API_KEY > config.json. The --api-key flag is available for ephemeral use, but its value can appear in shell history and process listings; prefer the sources shown above.

OpenCode Zen and OpenCode Go require an API key. Puny exits early with a hint if the key is missing.

GitHub Copilot does not need an API key up front — Puny discovers an existing GitHub OAuth token or runs a device-flow login on first use, then persists it. You can still supply a token manually (via --api-key, PUNY_API_KEY, or GITHUB_COPILOT_OAUTH_TOKEN) to skip discovery and login.

Run --reconfigure to choose a provider and save its URL and API key to config.json:

puny --reconfigure

You will be prompted for:

1. Provider — LM Studio (lmstudio), OpenCode Zen (opencode_zen), OpenCode Go (opencode_go), GitHub Copilot (copilot), Unsloth (unsloth), Ollama (ollama), or Ollama Cloud (ollama_cloud).
2. Provider URL — only for LM Studio, Unsloth, and Ollama; press Enter to use the default (http://127.0.0.1:1234, http://127.0.0.1:8888, and http://127.0.0.1:11434 respectively, or the same ports on http://host.docker.internal in the Docker image). Ollama Cloud, OpenCode Zen, OpenCode Go, and GitHub Copilot use fixed URLs (https://ollama.com, https://opencode.ai/zen, https://opencode.ai/zen/go, and https://api.githubcopilot.com respectively).
3. API key — press Enter to keep the existing key, or - to clear it.

Once saved, Puny uses the stored provider and key on subsequent runs, so you only need to pass --provider or --api-key again if you want to override them for a single session. If an OpenCode Zen or OpenCode Go request fails with an authentication error, Puny prints an auth hint; use --reconfigure to update the key.

--url and PUNY_PROVIDER_URL only affect LM Studio, Unsloth, and Ollama; Ollama Cloud always uses https://ollama.com, OpenCode Zen always uses https://opencode.ai/zen, OpenCode Go always uses https://opencode.ai/zen/go, and GitHub Copilot always uses https://api.githubcopilot.com.

The config file stores per-provider settings (URL, API key, and last-selected model) so you can switch between providers without re-entering credentials.

Configuration is stored at:

Use --reconfigure at startup or /config during a session to update this file. Provider keys written by Puny are encrypted, so copying an apiKey value without its encryption key does not produce a usable configuration.

Puny tracks how large each request is getting. Once a request reaches 80% of the context limit, Puny asks the current model to summarize the older part of the conversation and replaces those messages with the summary. The most recent exchanges, the system prompt, and loaded skills are kept as they are. Run /compact to do this at any time.

The context limit comes from the first of these that is set:

1. /context <tokens> for the current conversation
2. --max-context <tokens>
3. max_context_tokens in config.json
4. The context window the provider reports for the selected model: LM Studio, GitHub Copilot (its prompt limit, which leaves room for the reply, in the chosen context tier), and Ollama Cloud report one. For OpenCode Zen and OpenCode Go it comes from the models.dev catalog, downloaded without your API key. Local Ollama reports the context a model was loaded with, so the limit applies from the first reply onwards. Unsloth does not report one

When none is set, auto compaction is off, but /compact still works.

Run /context to see how full the context is and what fills it. The breakdown estimates each part at roughly four characters per token:

Context: ~12480 of 128000 tokens (9%); compacts at 80%.
  System prompt      2310 tokens (1.8%)
  System tools       4125 tokens (3.2%)
  Skills              860 tokens (0.6%)
  Messages           5185 tokens (4.0%)

Skills covers the list of available skills and the instructions of every skill loaded into the conversation.

{
  "max_context_tokens": 64000
}

GitHub Copilot prices many models in two context tiers, the same choice the Copilot app offers as a smaller and a larger context size. Puny budgets the cheaper default tier unless you choose long_context.

Puny shows each size as the Copilot app does: the whole window, holding the prompt and the reply. Auto compaction works against the smaller prompt limit inside it, since Copilot rejects longer prompts:

The long tier lets a conversation grow far longer before it is compacted, but GitHub Copilot charges more per token for it. Models with a single window, such as Kimi K3, keep it in either tier, and other providers ignore the tier.

Picking a model with /model asks for the context size after the reasoning effort when the model has both, and remembers the choice. The model line then shows it, e.g. gpt-6-luna - max - 400K, and /context reports usage within it:

Context: ~3751 of 272000 tokens (1%) in a 400K window; compacts at 80%.

You can also choose the tier with --context-tier long, with /context long (or /context default) for the current conversation, or for every session:

{
  "context_tier": "long_context"
}

Puny does not write API keys to config.json as clear text. When Puny saves a configuration containing keys, each key is encrypted at rest with XChaCha20-Poly1305 and written as an enc:v1: blob. The encryption key is a random 32-byte file that never leaves your machine:

The key file is created automatically (permissions 0600 on POSIX) the first time a configuration containing an API key is saved, and config.json itself is written with 0600 permissions on POSIX.

• Existing plaintext keys are migrated to encrypted blobs on the next configuration save (--reconfigure, /config, /provider, or the Copilot device-flow login). Re-entering the API key during --reconfigure migrates immediately; pressing Enter on every prompt does not save and does not migrate.
• Backups: back up config.json together with the key file. A config without its key file degrades gracefully — Puny warns and treats the stored keys as unset until you re-enter them with --reconfigure.
• Docker: the image uses /app as its home directory. Mount the project at /workspace and a named volume at /app, as shown in the Docker guide, to keep config, sessions, and the encryption key across container recreation without writing them into the project.
• No keys at rest: if you prefer not to persist credentials at all, pass --api-key, --api-key-file, PUNY_API_KEY, or GITHUB_COPILOT_OAUTH_TOKEN per session — these are never written to disk.

This protects against accidental exposure — a leaked, synced, or committed config.json contains no usable credentials. It does not defend against an attacker who already has full access to your user account (they can read the key file and process memory like any other tool).

Puny can load reusable prompt-engineering skills from markdown files. Skills are instructions that get injected into the system prompt so the model knows how to behave for a specific task. They can be loaded by slash command, by mentioning a trigger phrase in your message, or by the model itself via tool call.

To disable skills entirely, pass --no-skills (or set PUNY_NO_SKILLS=1). No skill directories are scanned, /skills reports that skills are disabled, and skill commands are treated as ordinary prompts.

Puny scans two directories for skills:

• Global: ~/.agents/skills/ — skills available across all repositories
• Repository: <repo-root>/.agents/skills/ — project-specific skills (auto-detected via git rev-parse --show-toplevel)

Each subdirectory inside these paths is treated as a skill. The skill's name is the directory name.

A skill directory must contain a SKILL.md file. The file starts with YAML frontmatter that can include the following fields:

---
name: my-skill
description: >
  Expert knowledge of MyTool for integration testing.
  Covers setup, configuration, and common patterns.
triggers: mytool, integration test, configure
disable-model-invocation: false
---

# MyTool Instructions

When asked about MyTool, follow these guidelines...

The body after the frontmatter is the skill content that gets injected into the conversation when the skill is loaded.

Skills can be loaded in three ways:

1. Slash command — type /<skill-name> in the prompt:

   > /nano-commits
   

2. Keyword trigger — mention a trigger phrase from the skill's triggers field in your message. For example, a caveman skill with triggers: talk like caveman, be brief loads automatically when you say:

   > talk like caveman from now on
   

   Skills are also triggered by their directory name as a whole word — saying grill me on this design loads the grill-me skill.

3. Model invocation — the model can load a skill it considers relevant by calling the load_skill tool. This happens automatically when the model sees a matching skill in the <available_skills> block. Skills with disable-model-invocation: true won't appear for model invocation and must be loaded by slash command only.

Use /skills to list all discovered skills from both global and repository locations:

> /skills

Available skills:

  nano-commits
  grill-me

Skills with a description field in their frontmatter show a description next to their name.

When Puny starts, it scans both skill directories and builds a registry. Available skills and their descriptions (if scanned) are injected into the system prompt as an <available_skills> block:

<available_skills>
  <skill>
    <name>nano-commits</name>
    <description>Commit often. One logical change per commit.</description>
  </skill>
</available_skills>

When a skill is loaded (via slash command, keyword trigger, or model invocation), Puny reads the SKILL.md body, strips the frontmatter, and adds the content as a system message. The model can then follow the skill's instructions for the remainder of the conversation.

Skills stay loaded for the session. To clear all loaded skills, use /reset.

Puny sends a list of available tools to the model on every request. When the model decides to call a tool, Puny executes it automatically and feeds the result back into the conversation.

Tool-call status lines use concise action-oriented summaries instead of raw JSON:

🔧 Reading "src/main.zig"
🔧 Running "zig build test"
🔧 Writing 12 lines (384 bytes) to "README.md"
🔧 Editing "src/chat/chat.zig"

Large payloads, such as file writes, are summarized rather than printed in full.

Tools execute automatically without confirmation. This includes file writes (which overwrite files) and shell commands (which run arbitrary commands). Only run Puny in directories where you are comfortable with the model making changes.

While in a chat session:

• /quit or /exit — exit Puny
• /new or /reset — clear the conversation, start a new session, and unload all skills
• /stats — show session statistics (turns, requests, and tokens summed over every request) and memory usage
• /compact — summarize the conversation so far into one message to free context
• /context [tokens|off|default|long] — show how full the context is and a breakdown of what fills it (system prompt, tools, skills, messages), set the context limit for this conversation, pick a context tier, or turn auto compaction off
• /config — reconfigure provider, URL, and API key mid-session; changing the provider rebuilds the connection and re-opens the model picker
• /plan [task] — enter planning mode (optionally with a task description); the resulting PRD is saved to the session folder as plan.md
• /build [task] — switch to build mode (optionally with a task description)
• /review — review committed changes against the latest origin/main; remain in read-only review mode afterward
• /orchestrate [task] — run the implement to review to fix loop until the branch is merge worthy; --plan <task> plans interactively first, --iterations <n> caps the rounds, and a bare /orchestrate implements the PRD this session saved
• /model [id] — switch to another model; shows the model picker if no ID is given
• /provider — open the provider picker, then choose a model for the new provider
• /thinking [level] — change the reasoning effort of the current model; shows the effort picker if no level is given (valid levels: default, none, low, medium, high, xhigh, max)
• /sessions — list all saved sessions, showing their UUID, whether they have a plan.md or saved conversation, and a preview of the first user message
• /resume [id] — list saved sessions and pick one to restore, or restore a specific session by UUID prefix
• /prune — delete all session directories except the current one
• /skills — list all available global and repository skills (prints "Skills are disabled." with --no-skills)
• /file <path|url> — load a prompt from a local file or URL and send it as the next message

Any unrecognized slash command (e.g. /nano-commits, /grill-me) is treated as a skill name and loads the matching skill if found. With --no-skills these commands are treated as ordinary prompts instead.

Skills also load automatically when your message contains the skill's directory name or a trigger phrase listed in its frontmatter triggers field. The model can also load skills on its own via the load_skill tool.

Each Puny session is identified by a UUID. A new session is created every time you start Puny or run /new (or /reset). The session ID is shown in the welcome screen and in the /stats header.

Sessions are stored at ~/.config/puny/sessions/<uuid>/ (Linux/macOS) or %APPDATA%\puny\sessions\<uuid>\ (Windows). The base directory is configurable: use $XDG_CONFIG_HOME/puny when set on Linux/macOS, and on Windows fall back to %USERPROFILE%\puny when %APPDATA% is unavailable. Each session folder can contain:

The entire conversation is saved to messages.json in the session folder after every completed chat turn. It is also saved automatically when you exit the session (/quit, Ctrl+C) or run /reset. Tool call results are included in the save so the restored session has the full context.

Sessions that end with no real content — no user message, no assistant reply, and no plan.md/plan.html — are removed automatically on exit so empty session folders don't accumulate.

You can resume a previous session in several ways:

• CLI flag: puny --session <uuid-or-prefix> loads a specific session by UUID or unique prefix. Use --session with a partial UUID for prefix matching (e.g. puny --session abc-12 matches abc-1234-...).
• CLI flag: puny --resume resumes the most recent session with a saved conversation. If multiple sessions have saved conversations, a hint is printed.
• CLI flag: puny --prune deletes all session directories. Use puny --prune --session <uuid> to delete all sessions except the one to keep.
• Interactive: /resume inside a chat session lists all saved sessions that have conversations and lets you pick one to restore. You can also pass a prefix: /resume abc-12.
• In-session restore: Calling /resume replaces the current conversation with the saved one, keeping the same provider and model configuration.

When a session is restored, the system prompt, skills blocks, and agent mode are restored exactly as they were saved — the conversation picks up where it left off.

In planning mode the model can only read files, list directories, search code, check git status/diff, and fetch web pages — plus use the save_prd tool to write the final PRD. When the user confirms readiness, the model calls save_prd with markdown and HTML content, which writes both plan.md and plan.html to the session folder. Planning mode state is persisted in session.json and restored when the session is resumed.

Run /review inside a chat to perform the same branch review as --review without exiting Puny. After the report is written, the session remains in read-only review mode for follow-up questions. Use /build to allow source changes again or /plan to enter planning mode.

When a run fails, puny writes a crash report to puny_crash_<session id>.md in its config directory (%APPDATA%\puny\crashes on Windows, $XDG_CONFIG_HOME/puny/crashes or ~/.config/puny/crashes elsewhere). The next plain interactive start finds pending reports and asks what to do with each one:

• Submit it as a GitHub issue files it against christianhelle/puny using the gh CLI, so it goes out under your own GitHub account. puny neither ships nor asks for a token. If gh is missing or not authenticated, the report is kept and the path is printed.
• Show me the report first prints the whole report so you can see exactly what would be posted.
• Delete it removes the file.
• Not now leaves it for later.

Configuration problems are not crashes: a missing API key, an unresolvable config directory, or a bad config path already print how to fix them, so they never produce a report. Neither does interrupting a run with Ctrl+C.

A report holds the error name, what puny was doing, the version and commit, the platform and build mode, and the session id, provider and model. It never contains prompts, conversation content, file paths, command-line values, or credentials. The five most recent reports are kept; older ones are pruned.

You are never asked during a --oneshot, --review, --orchestrate, --mock or --prompt run, or when stdin is not a terminal, so automation is never blocked by the question.

Because release builds are optimized for size (small), runtime safety checks are compiled out: reports cover failures that surface as returned errors, not memory-safety panics or segfaults.

Start without a running AI backend:

zig build run -- --mock

You can also set the PUNY_MOCK environment variable:

export PUNY_MOCK=1
zig build run

The mock provider returns canned responses and simulates tool calls based on keywords in your prompt:

Use --model to skip the model picker in mock mode:

zig build run -- --mock --model mock-model --prompt "search for something" --oneshot

To see the model's internal reasoning (thinking) output, use --show-thinking:

puny --show-thinking

Or set the PUNY_SHOW_THINKING environment variable:

export PUNY_SHOW_THINKING=true
puny

To verify this works without a real backend, use the mock provider's reasoning keyword, which streams a large amount of dimmed reasoning output before the final answer:

zig build run -- --mock --model mock-model --prompt "respond with reasoning" --show-thinking --oneshot

--effort sets how much reasoning to ask the model for. It takes precedence over PUNY_REASONING_EFFORT and over the level stored in your config:

puny --effort low

Both --show-thinking and --chat-log want reasoning tokens to exist at all, so on their own they raise the level to high. Passing --effort overrides that, which matters when you want the conversation log without paying for the extra reasoning:

puny --chat-log --effort low --oneshot --prompt "summarise this file"

Use --effort default to send no level at all and let the provider decide.

To log all HTTP requests and responses to puny_http.log, use --debug:

puny --debug

The debug log captures request payloads, response headers, and SSE chunks for troubleshooting. JSON bodies are pretty-printed for readability.

MIT