pengy 1.2.0

Local-first AI agent with tools — GUI and CLI

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 a set of tools to operate on your filesystem, run code, search the web, and fetch URLs — all with your approval.

Three interfaces, one agent:

🐧 Pengy Desktop	🐧 Pengy CLI	🐧 Pengy Web
Qt6 GUI with markdown rendering, multi-session sidebar, file attachments	Terminal REPL with slash commands, single-shot mode for scripting	Flask web UI with Bootstrap, responsive layout, SSE live streaming

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

---

Quick Start

Install

# Everything (GUI + CLI + Web)
pip install pengy[all]

# CLI only
pip install pengy[cli]

# GUI only
pip install pengy[gui]

# Web UI only
pip install pengy[web]

# Minimum (no GUI, no CLI — use as a library)
pip install pengy

Desktop GUI

pengy

CLI (interactive)

pengy-cli

CLI (single-shot)

pengy-cli "What is the capital of France?"
pengy-cli "List all files in /tmp"

Web UI

# Localhost only (default)
pengy-web

# Listen on all interfaces (for nginx reverse proxy)
pengy-web --host 0.0.0.0

# Custom port
pengy-web --host 0.0.0.0 --port 8080

The web UI is designed for single-user personal use. For remote access, put it behind nginx with SSL and HTTP basic auth — Pengy itself has no authentication.

---

Features

• OpenAI-compatible — Works with OpenAI, Ollama, vLLM, LM Studio, OpenRouter, Groq, or any local endpoint
• 11 built-in tools — Read, write, and edit files; run bash (with sudo support) and Python code; search the web and fetch URLs; explore directory trees and search codebases
• Agentic workflow — The LLM can call multiple tools per turn, chaining them to accomplish complex tasks
• Tool confirmation — Three modes: YOLO (All) skips all confirmations, Safe auto-approves read-only tools, None confirms everything
• Context management — Elide old tool results to save context window space; configurable per-chat
• Token usage display — See prompt/completion token counts after every turn (GUI sidebar + CLI footer)
• Model discovery — Fetch available models from your endpoint with one click or /models command
• Multi-session — Create, switch, and delete chat sessions; history saved locally as JSON; shared across all interfaces
• File attachments — GUI: attach files from the input bar; CLI: use /attach <path> or @path inline syntax
• Web UI — Responsive Bootstrap interface served by Flask; SSE live streaming; works great on mobile
• Slash commands (CLI) — /new, /load, /models, /yolo, /model, /list, /delete, /attach, /compact, and more
• Templated system message — Auto-fills {date}, {username}, {hostname}, {osinfo} at send time
• Persistent config — Settings and chat history live in ~/.config/pengy/, shared between GUI and CLI

---

Screenshot

---

Configuration

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

Setting	Description
Base URL	API endpoint (e.g. http://localhost:11434/v1 for Ollama)
API Key	Your API key (or anything for local endpoints)
Model	Model name, e.g. gpt-4o, llama3, gemma
System Message	Supports {date}, {username}, {hostname}, {osinfo} placeholders
Tool Confirmation	YOLO (All) / Safe Only / None — controls which tools require approval
UI Scale (GUI)	75 / 100 / 125 / 200 % — takes effect on next launch

---

Tools

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

Tool	Description
read_file / read_multiple_files	Read one or more files at once
write_file	Write or overwrite a file
replace_in_file	Targeted text replacement (safer than full rewrites)
run_bash	Execute shell commands (configurable timeout; sudo password dialog)
run_python	Execute Python code (uses the same interpreter/venv as Pengy)
web_search	DuckDuckGo web search
download_file	Download a URL to ~/Downloads/
fetch_url	Fetch a URL's text content into context
directory_tree	Visual directory structure listing
search_content	Regex search across files in a codebase

---

API Compatibility

Service	Base URL
OpenAI	https://api.openai.com/v1
Ollama	http://localhost:11434/v1
LM Studio	http://localhost:1234/v1
vLLM	http://localhost:8000/v1
OpenRouter	https://openrouter.ai/api/v1
Groq	https://api.groq.com/openai/v1

---

Project Structure

pengy/
├── main.py              # Desktop GUI entry point
├── cli/
│   └── main.py          # CLI entry point (interactive + single-shot)
├── assets/
│   └── icon.svg         # App icon
├── core/
│   ├── config.py        # Settings load/save + system message templating
│   ├── chat_manager.py  # Chat session CRUD
│   ├── llm_client.py    # API client (generator protocol for tool handling)
│   └── tools.py         # Tool definitions and execution
├── ui/
│   ├── main_window.py   # Main window; wires all signals
│   ├── chat_history.py  # Sidebar chat list + quick settings
│   ├── chat_view.py     # Markdown chat renderer
│   ├── chat_input.py    # Input field + file attachment
│   ├── chat_worker.py   # Background thread driving the LLM generator
│   └── settings_dialog.py  # Settings dialog
└── web/
    ├── app.py           # Flask application (routes, WebWorker, SSE)
    ├── main.py          # Web entry point (argparse, app.run)
    └── templates/
        ├── base.html    # Navbar, sidebar, Bootstrap layout
        ├── chat.html    # Chat view + JS SSE client
        └── settings.html # Settings form

---

Development

Install from source

git clone https://github.com/patw/pengy.git
cd pengy
pip install -e ".[all]"

Running tests

pip install -e ".[all]"
python -m pytest tests/ -v

---

Dependencies

Package	Purpose
PySide6	Qt6 GUI framework
flask	Web UI framework
openai	OpenAI-compatible API client
markdown	Markdown rendering (GUI + Web)
pygments	Syntax highlighting (GUI + Web)
ddgs	DuckDuckGo web search
rich	CLI formatting (tables, panels, markdown)