🤏 Puny

A minimal AI coding agent for the terminal. Chat with an LLM and give it tools to read, edit, search, and inspect your codebase.

Install Now View on GitHub ↗
puny
Welcome to Puny 0.1.0 (6016ab8) - Your tiny AI coding assistant
AI makes mistakes - read the fucking code

  Provider: OpenCode Zen (https://opencode.ai/zen)
  Model: deepseek-v4-flash-free
  Session: 550e8400-e29b-41d4-a716-446655440000

Available commands:
  /quit, /exit       Exit Puny
  /reset             Clear the conversation
  /stats             Show session statistics
  /config            Reconfigure URL and API key
  /plan [task]       Enter planning mode
  /build [task]      Switch to build mode
  /sessions           List saved sessions
  /prune               Remove old sessions
  /model [id]        Switch to another model
  /provider [name]   Switch to another provider
  /skills            List global and repository skills

Type a prompt and press Enter to start chatting.

Prompt:

Features

🧠

Multiple Providers

LM Studio, OpenCode Zen, OpenCode Go, and GitHub Copilot

🔧

Tool Calling

Read, write, and list files, run shell commands, search code, check git status, and fetch web pages

📦

Skills System

Load reusable prompt-engineering skills from markdown files

💬

Interactive Chat

Multi-turn conversations with session management and PRD export

🎯

Model Picker

Interactive model selection on startup

🐳

Docker

Published as a container image to Docker Hub and GHCR

Installation

Quick Install

Recommended

One-command installation that automatically detects your platform, downloads the latest release, and installs it to your chosen directory.

Linux / macOS

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

Windows (PowerShell)

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

Custom installation directory

Linux / macOS

INSTALL_DIR=$HOME/.local/bin curl -fsSL https://christianhelle.com/puny/install | bash

Windows

$install = irm https://christianhelle.com/puny/install.ps1
& ([scriptblock]::Create($install)) -InstallDir "$env:USERPROFILE\bin"

Build from Source

Dev

Requires Zig 0.16.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.

Docker

Container

Puny is published as a container image.

docker pull christianhelle/puny:latest
docker run -it --mount "type=bind,source=${PWD},target=/app" christianhelle/puny

Usage

Sessions

Each session is identified by a UUID. A new session is created on every start and /reset. Use /sessions to list saved sessions and /prune to clean up old ones. In /plan mode, once you confirm the plan is ready, the model saves the final PRD as both plan.md and plan.html to the session folder via the save_prd tool.

Quick Start with LM Studio

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

puny

OpenCode Zen

puny --provider opencode --api-key YOUR_API_KEY

OpenCode Go

puny --provider opencode-go --api-key YOUR_API_KEY

GitHub Copilot

puny --provider copilot