Pengy 🐧

A local-first AI agent with tools. Desktop GUI, web UI, and command-line — all backed by the same agent core, talking to any OpenAI-compatible API.

What is Pengy?

Pengy is an LLM agent that runs on your own machine. It connects to OpenAI, Ollama, vLLM, Groq, OpenRouter, or any local endpoint, and gives the model 15 built-in tools to operate on your filesystem, run code, search the web, and more — all with your approval.

Three interfaces, one agent:

All three share the same core, tools, chat history, and config. Use whichever fits your flow.

Quick Start

Install

# Recommended — uv installs Pengy with a compatible Python automatically
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install "pengy[all]"

# Or with pip (Python 3.10+)
pip install "pengy[all]"

You can install just the parts you need: pengy[gui], pengy[cli], or pengy[web].

Desktop GUI

pengy

CLI (interactive or single-shot)

pengy-cli
pengy-cli "What is the capital of France?"

Web UI

pengy-web

The web UI is for single-user personal use. For remote access, put it behind nginx with SSL; use --trusted-host to set the public hostname when reverse-proxying.

Features

• OpenAI-compatible — Works with OpenAI, Ollama, vLLM, LM Studio, OpenRouter, Groq, or any local endpoint
• 15 built-in tools — Read, write, and edit files; run bash (with sudo support) and Python; search the web and fetch URLs; explore directories, glob files, and search code; track multi-step ops with structured to-do lists; ask clarifying questions when instructions are vague
• Agentic workflow — The LLM chains multiple tool calls per turn, piping results from one into the next
• Tool confirmation — Three modes: auto-approve everything, auto-approve read-only tools only, or confirm every call
• Tabbed chat — Multiple concurrent chat sessions, each with its own worker thread
• Theme system — System/light/dark modes plus 8 accent colours; fonts scale with the UI
• Tasks — Reusable prompt templates with %placeholder% tokens for workflows you run on repeat
• Model discovery — Fetch available models from your endpoint with one click or /models
• File attachments — GUI: attach from the input bar; CLI: /attach or @path syntax
• Templated system message — Auto-fills {date}, {username}, {hostname}, {osinfo} at send time
• Persistent config — Settings, task templates, and chat history in ~/.config/pengy/, shared between all interfaces and across all editions (Python, Rust, C++)

Screenshots

Main chat UI	Settings / theme controls	Tasks templates

Configuration

Desktop: Click ⚙ Settings in the sidebar.
CLI: Run /config to view, /model <name> to switch models.
Web: Click ⚙ in the top-right navbar.

Tasks

Tasks are reusable prompt templates for workflows you repeat often — summarizing a YouTube video, drafting a release note, or running a code-review checklist. Open Tasks from the desktop sidebar to create, edit, delete, or play templates.

Use %placeholder% tokens anywhere in the template to ask for values when the task is played:

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

When you hit ▶ Play, Pengy collects each placeholder once, renders the full prompt, and sends it through the normal chat pipeline — tools, skills, history, and confirmation settings all work exactly like a hand-typed prompt. Tasks live in ~/.config/pengy/tasks.json, shared across all interfaces and editions.

Tools

Pengy gives the LLM these tools to operate on your machine:

Skills

The 15 built-in tools cover the basics, but Pengy is designed to be extended with skills — your own custom instructions and scripts stored as plain markdown files.

A skill is just a skillname/skillname_skill.md file with instructions Pengy can read, optionally backed by a bash or Python script. No SDK, no manifest, no packaging — point Pengy at a directory and it figures out the rest.

This means your Pengy can do whatever you need it to:

• Fetch weather from an API
• Control devices on your home network
• Query your local databases
• Generate reports from your own data
• Run system administration tasks
• Send notifications, emails, or messages
• Map repository structure and run test suites
• Anything you can describe in a prompt and a script

Skills are also self-authoring — ask Pengy to create one for you, and it writes the markdown, writes the script, and updates the index, all in one conversation.

📖 Read the full guide: skills/README.md — covers the philosophy, how skills work, 4 complete examples, and how to make your own.

API Compatibility

Development

Project structure

pengy/
├── main.py              # Desktop GUI entry point
├── cli/                 # CLI entry point
├── core/                # Config, chat manager, tools, LLM client
├── ui/                  # Chat view, input, workers, settings, theme
└── web/                 # Flask app, routes, SSE, templates

Install from source

git clone https://github.com/patw/pengy.git
cd pengy
uv sync --extra all

Or with pip:

pip install -e ".[all]"

Running tests

python -m pytest tests/ -v

Dependencies

Also Available

Pengy (Python) is the reference implementation. Two high-performance ports share the same ~/.config/pengy/ data directory:

All three offer the same 15 tools, desktop theme controls, reusable task templates, three interfaces (GUI/CLI/Web), and full chat/task interop. PengyR and PengyCPP ship pre-built AppImage, .deb, .dmg, and .zip releases.

Documentation

• Configuration reference — all settings.json fields explained
• Reverse proxy setup — nginx, Caddy, SSH tunnels, Docker
• Skills deep-dive — skill patterns, ~/.secrets, uv dependencies
• API compatibility — provider support, model discovery, local endpoints
• FAQ — common questions and troubleshooting
• Building from source — platform-specific build instructions
• Changelog — version history

License

MIT