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 — and shows you every step, asking permission when it matters.

🐧 Desktop

Qt6 GUI with markdown rendering, collapsible tool blocks, multi-session sidebar, 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. 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 AppImage	High-perf Statically-linked core
PengyCPP C++	Pure C++17 + Qt6 No Rust, no Python	`./build_linux.sh` or download AppImage	Leanest Smallest binary & memory

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

# Tools

11 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

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

# Skills

The 11 built-in tools are just the start. Skills let you teach Pengy anything you need — custom workflows, API integrations, system tasks, domain knowledge.

No SDK. No plugins. No manifest.

A skill is a markdown file with optional scripts in a directory. That's it. 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/
│   ├── plot_skill.md
│   └── make_plot.py
└── tts/
    ├── tts_skill.md
    └── speak.py

Included examples: weather via Tomorrow.io · matplotlib charts (line, bar, scatter, pie) · text-to-speech · 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: YOLO (auto-approve everything), Safe (auto-approve read-only tools only), or None (confirm every tool). You choose.