PenguinHarness

Efficient Self-Improving Harness for Everyone

Open-source, local-first infrastructure that builds AI agents for you — from automatic agent construction to recursive self-improvement.

English | 简体中文 · Website · Docs · Blog

Why PenguinHarness

• Simplest Is the Best — a deliberately minimal toolset over clean low-level interfaces: fewer tool calls, fewer tokens, complex tasks done efficiently.
• Harness for Building Agents — with the PenguinHarness SDK, an Agent builds complete Agent applications for you, autonomously, from scratch.
• Harness for Recursive Self-Improvement — with PenguinHarness Skills, an Agent evaluates and optimizes itself: benchmark, find the lost points, ship version N+1, snapshot before every round.
• Local-first and lightweight — 100% open source, runs on a single CPU, your data never leaves the machine. 1000+ online and local models reachable through one gateway.
• Everything observable — every request, tool call and approval decision lands in an append-only Trace; any Session can be resumed from it.

Quickstart

Install with one command (Linux / macOS, x64 / arm64, bundled Node runtime):

curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh | sh

Or via npm (requires Node >= 24; the command it installs is penguin):

npm install -g @prismshadow/penguin-cli

Then launch the Web App — or stay in the terminal:

penguin web        # start the service and open http://127.0.0.1:7364 (first login: admin / admin123)
penguin server     # same service, headless

# configure a model once (or use the in-app Models page)
penguin config model add --model-id deepseek-v4-pro --api-key sk-... --set-default

penguin run -m "Create hello.txt containing Hello, Penguin"   # one-shot task
penguin chat       # interactive REPL (/compact, /exit, Ctrl-C to interrupt)

Using the SDK directly:

import { createAgent, isCompleteModelMessage, userText } from "@prismshadow/penguin-core";

const agent = await createAgent({ agentId: "default_agent" });
const session = await agent.createSession({ workspaceDir: process.cwd() });

for await (const output of session.run([userText("Create hello.txt containing hi")], {
  approve: async () => "allow", // per-tool-call approval
})) {
  if (isCompleteModelMessage(output) && output.payload.type === "text") {
    console.log(output.payload.text);
  }
}

What's inside

A pnpm monorepo (TypeScript, Node >= 24). One install ships four layers that share a single data directory (~/.penguin/data) and a single message protocol (OmniMessage):

Responsibilities split by source of truth: the SDK owns protocol and execution (message parsing, the agent loop, tools), the Server owns the multi-user runtime (auth, SSE streaming, scheduled tasks), and the file layer under ~/.penguin/data owns everything editable and recorded (prompts, Skills, secrets, Traces). The full design-by-design map is in Architecture → Division of responsibilities.

Documentation

The docs site covers both usage and design: Introduction · Quickstart · Architecture · The OmniMessage Protocol · Core Interfaces · The Agent Loop · CLI Reference · Server API · Configuration

Every doc page has a "Copy Markdown" button, so you can paste it straight into a model context.

Development

pnpm install
pnpm build       # build first: core's exports point at dist/
pnpm typecheck
pnpm test

pnpm dev:server  # backend at 127.0.0.1:7364
pnpm dev:web     # web app (Vite) at 127.0.0.1:7365, /api proxied
pnpm dev:docs    # docs site (Vite) at 127.0.0.1:7367

BASE_PATH=/ pnpm build:site   # assemble landing + docs exactly like the Pages deploy

Copy .env.example to .env for model credentials in development. E2E tests run against a live model (pnpm test:e2e, needs DEEPSEEK_API_KEY).

License

Apache-2.0 © 2026 Prism Shadow