# PenguinHarness

> An open-source, locally deployed AI agent harness that lets agents autonomously build and recursively self-improve other agents, supporting 1000+ models on desktop or server.

PenguinHarness is an open-source AI agent harness built by the PrismShadow AI Team, led by Yaowei Zheng (author of LlamaFactory). It runs fully locally — all data stays in `~/.penguin/data` — and reaches 1000+ online and local models through a unified model gateway. The project is licensed under Apache-2.0 and available on GitHub.

## What It Is

PenguinHarness is a complete TypeScript stack for constructing and evolving AI agents. It ships four tightly integrated layers — an SDK (`@prismshadow/penguin-core`), a CLI (`@prismshadow/penguin-cli`), a server (`@prismshadow/penguin-server`), and a browser web app (`@prismshadow/penguin-web`) — all sharing a single data directory and a unified message protocol called OmniMessage. The project describes itself as "the first open-source harness to ship 'agents building agents' and recursive self-improvement."

## Three Core Pillars

The harness is organized around three design principles:

- **Simplest Is the Best** — A deliberately minimal toolset over clean low-level interfaces: dedicated file tools (`read_file`, `edit_file`, `write_file`) and a shell fallback (`exec_command`), tuned to minimize token usage on open models like DeepSeek.
- **Harness for Building Agents** — With the PenguinHarness SDK, an agent builds complete agent applications autonomously from a single sentence of input, delivering scaffold, code, and run instructions end to end.
- **Harness for Recursive Self-Improvement** — With PenguinHarness Skills, an Optimizer orchestrates multiple Evaluators to score a Target Agent in parallel, uses scores and run traces to find where points were lost, and upgrades the agent from version N to N+1 — with a snapshot before every round.

## Architecture and Design Tenets

The harness enforces a CONTRACT.md that defines the boundary of evolution: self-improvement is strictly confined to Workspace and Skills, while the harness kernel and its safety mechanisms never change. Key design tenets include:

- **Full tracing** — Every model request and tool call is written to the Trace in full, including token count, latency, and failure reason; sessions are fully restorable from the Trace.
- **Approvals and audit** — Every tool call requires user approval before it runs, and every decision leaves an audit record.
- **Credential isolation** — API keys land as hidden 0600 files, are barred from the system prompt, and stay masked throughout the UI.
- **Model decoupling** — Models are not bound to agents; you pick one per session and can switch without rewriting the agent.
- **Progressive loading** — Content is indexed first and read on demand, never dumped wholesale into context.
- **Error convergence** — Errors split into retryable and fatal; retryable ones retry automatically, fatal ones become messages the model can react to.

## Built-in Skill Library

Four skill groups ship out of the box, and agents can write and optimize their own:

- **Office Productivity**: `data-analysis`, `firecrawl`
- **Software Development**: `web-design`, `software-engineering`
- **AI App Development**: `penguin-sdk`, `penguin-cli`, `agenthub-models`, `vllm`, `ollama`, `llamafactory`
- **Agent Tuning**: `agent-creation`, `benchmark-design`, `agent-evaluation`, `agent-optimization`

## Deployment and Platform Support

PenguinHarness supports two installation paths that share the same local data root:

- **Desktop app** — A double-click installer for macOS 11+, Windows 10+, and Linux (AppImage/deb) that embeds the server and opens already signed in.
- **CLI** — A one-line installer (`curl | sh` on Linux/macOS, PowerShell on Windows) or `npm install -g @prismshadow/penguin-cli`; `penguin web` then serves the full web UI at `http://127.0.0.1:7364`. Offline/air-gapped installs are also supported via GitHub Release packages.

The system requires only a single CPU at minimum and supports x64 and arm64 architectures. Node >= 24 is required for npm installs; the one-line installer bundles its own runtime.

## Update: v0.2.1

The latest release is v0.2.1, published on 2026-08-04. The repository was created on 2026-07-19 and last pushed on 2026-08-07, indicating rapid early development. Recent blog posts announce availability of Kimi K3 and free models like Ling 3.0 Flash in PenguinHarness, as well as a Fireworks AI AMD Developer Program credit offer. The roadmap lists upcoming items including a public benchmark suite release, agent company templates, company-level self-evolving, and OpenShell integration.

## Features
- Agents building agents autonomously from a single sentence
- Recursive self-improvement via Optimizer and Evaluator multi-agent loop
- 1000+ supported models via unified model gateway
- Fully local deployment — data never leaves the machine
- Desktop app for macOS, Windows, and Linux
- CLI with interactive REPL and one-shot task runs
- Web UI with multi-session chat, agent management, skill library, and Trace observability
- Built-in skill library (Office Productivity, Software Development, AI App Development, Agent Tuning)
- Full tracing of every model request and tool call
- Per-tool-call approval and audit records
- Credential isolation (hidden 0600 files, masked in UI)
- Model decoupling — switch models per session without rewriting agents
- Scheduled cron-style tasks
- Subagent delegation with parallel isolated execution
- Multi-user management with per-project data isolation
- Cost center with daily token, request, and cost trends
- Version snapshots before each optimization round
- Offline/air-gapped install support
- TypeScript SDK (@prismshadow/penguin-core) for programmatic agent control
- CONTRACT.md safety boundary — harness kernel never modified by self-improvement

## Integrations
DeepSeek, OpenRouter, Fireworks AI, SiliconFlow, Moonshot AI (Kimi), Google Gemini, Anthropic Claude, OpenAI GPT, Z.AI (GLM), Qwen, vLLM, Ollama, LlamaFactory, Firecrawl

## Platforms
WINDOWS, MACOS, LINUX, WEB, CLI, API, DEVELOPER_SDK

## Pricing
Open Source

## Version
v0.2.1

## Links
- Website: https://penguin.ooo/
- Documentation: https://penguin.ooo/docs/
- Repository: https://github.com/Prism-Shadow/penguin-harness
- EveryDev.ai: https://www.everydev.ai/tools/penguinharness