Pengy — Local-first AI agent harness

# What is Pengy?

It's like strapping a set of power tools to an LLM. The model thinks, calls tools, gets results, thinks again. It writes files, runs bash, searches the web, maps your repos, runs your tests — and shows you every step, asking permission when it matters.

🐧 Desktop

Qt6 GUI with tabbed chat, markdown rendering, collapsible tool blocks, sidebar with chat history & quick settings, and file attachments. The full cockpit.

🐧 CLI

Terminal REPL with slash commands, single-shot mode for scripting, inline @path attachments. Pipe it, cron it, live in it.

🐧 Web

Responsive web UI with SSE streaming and CSRF/DNS-rebinding protection. Run it on a server, use it from your phone. Bootstrap, no bloat.

# Pick Your Edition

Three editions, same tools, same chat format. Settings and history live in ~/.config/pengy/ — shared across all three. Pick the one that fits your stack, switch anytime.

Edition	Stack	Install	Vibe
Pengy Python	Python 3.10+ PySide6 + Flask	`pip install pengy[all]`	Reference Easiest to hack on
PengyR Rust	Rust core + Qt6 GUI Axum web · tokio	`./build_linux.sh` or download release (AppImage, .deb, macOS .dmg, Windows .zip)	High-perf Statically-linked core
PengyCPP C++	Pure C++17 + Qt6 No Rust, no Python	`./build_linux.sh` or download release (AppImage, .deb, macOS .dmg, Windows .zip)	Leanest Smallest binary & memory

All three ship pre-built releases for Linux (AppImage + .deb), macOS (.dmg), and Windows (.zip).

# Theme System

The desktop GUI lets you tailor the look and feel to your taste — no CSS wrangling required.

🌗 Mode

System, Light, or Dark. System follows your OS palette automatically — switch your desktop's theme and Pengy follows along.

🎨 Accent

Pick from Default, Blue, Teal, Green, Orange, Red, Pink, or Purple. Accent colours drive buttons, links, focus rings, and selection highlights across the whole UI.

Theme settings — theme_mode, theme_accent, and ui_scale (75–200%) — live in ~/.config/pengy/settings.json, shared across all three interfaces and all three editions (Python, Rust, C++). The chat view even scales markdown, code, and input fonts to match the UI scale, so everything stays consistent.

# Tasks

Reusable prompt templates for workflows you run on repeat — think of them as saved blueprints for your agent.

📝 Templates with placeholders

Write a prompt with %placeholder% tokens anywhere — a YouTube URL, a repo name, a topic. When you play a task, Pengy asks for each value once, then renders the full prompt and sends it through the normal chat pipeline.

▶ Play from sidebar

Open Tasks from the desktop sidebar to create, edit, delete, or run templates. Tools, skills, history, and confirmation settings all work exactly as if you'd typed the prompt by hand.

Example task:

Summarize this YouTube video: %Youtube Video URL%
Always use the youtube transcription skill.

Tasks are stored in ~/.config/pengy/tasks.json — shared between the Python, Rust, and C++ editions. Switch interfaces or switch editions, your templates follow you.

# Tools

15 built-in tools the LLM can call. You decide how much it's allowed to do without asking.

read_file / read_multiple_files

Read one or more files at once

write_file

Write or overwrite a file, creates parent dirs

replace_in_file

Exact string replacement — safer than full rewrites

apply_changes

Multi-file transactional edits with diff preview

run_bash

Shell commands with sudo support & timeout

run_python

Execute Python code in a temp file

web_search

DuckDuckGo search

download_file

Download a URL to ~/Downloads/

fetch_url

Fetch URL text content into context

directory_tree

Visual directory structure listing

search_content

Regex search across files in a codebase

glob

File pattern matching — respects .gitignore

todowrite

Structured task list for multi-step ops

ask_user_question

Multi-choice questions to clarify vague requests

# Skills

The 15 built-in tools handle the basics. Skills let you teach Pengy anything you need — custom workflows, API integrations, system tasks, domain knowledge.

Just a markdown file

A skill is a markdown file with optional scripts in a directory. Point Pengy at it and it figures out the rest.

Self-authoring

Ask Pengy to create a skill for you — it writes the markdown, writes the script, and updates the index. All in one conversation.

skills/
├── skill_index.md              ← the table of contents Pengy reads
├── weather/
│   ├── weather_skill.md          ← instructions (required)
│   └── get_weather_by_location.py  ← helper script (optional)
├── plot/                        matplotlib charts → PNGs
├── tts/                         text-to-speech on Ubuntu
├── repo_mapping/                map repo entry points & structure
└── test_orchestrator/           run tests, investigate failures

Included examples: weather via Tomorrow.io · matplotlib charts · text-to-speech · repo structure mapping · test orchestration · user profile · Pengy’s own bio.
📖 Read the full guide: github.com/patw/Pengy/skills

# How It Works

Each turn, the LLM can chain multiple tool calls — and you're in the loop.

You type a message → LLM responds with tool calls → You approve or decline → Tool executes locally → Result goes back to LLM → Final answer rendered

Three confirmation modes: All (auto-approve everything), Safe (auto-approve read-only tools only), or None (confirm every tool). You choose.