Does penguin-harness auto-invoke its skills?

Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.

Is penguin-harness free?

Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.

Development

Plugin

penguin-harness

🐧 Automated Agent Builder. Create Self-Evolving Agents in One Click (DeepSeek/Kimi/GPT/Claude/Gemini)

FLOW.md

prism-shadow@prism-shadow

GitHub

Plugin Signal82/100Strong

maintained99

capable59

documented100

adopted65

Install

$ npx -y skills add Prism-Shadow/penguin-harness --agent claude-code

Run the curl in your terminal, the rest in Claude Code.

Stats

TypeScript Node HTML Bash PowerShell

+7 tags

Linux GitHub Markdown Anthropic OpenAI Gemini LangChain

1,102

Stars

104

Forks

Active

Maintenance

TypeScript

Language

Apache-2.0

License

49m ago

Last commit

22d ago

Created

Repo: Prism-Shadow/penguin-harness

In this plugin

16 skills

See everything inside

What's inside

Skills

/agent-creationCreate or configure an Agent State from a user requirement by writing AGENTS.md, setting identity metadata, and installing only needed Skills./agent-evaluationRun one specified Test Agent on one specified Benchmark Case exactly once, privately score that execution, and return one protocol result./agent-optimizationImprove an Agent State through versioned scores and score-linked Traces from a frozen Benchmark./agenthub-modelsCall model APIs through @prismshadow/agenthub — streaming text generation, image generation, speech synthesis, embeddings and the supported-model registry with one client./benchmark-designDesign and calibrate a multi-Case capability Benchmark and establish a traceable Formal Baseline./bento-slidesCreate and edit Bento presentations — self-contained .bento.html decks whose document is JSON. Use whenever the user wants a slide deck or presentation: from scratch, from source material, or by improving an existing file.

Show all 16 skills

/data-analysisComplete data-analysis tasks with bounded inspection, correct data semantics, native artifact handling, complete delivery, and risk-based verification./firecrawlSearch the web and scrape pages into clean markdown with the Firecrawl API — query-based discovery, single-URL extraction including public PDFs, driven by curl with a vault-stored API key./llamafactoryFine-tune LLMs with LlamaFactory — register datasets, train via YAML configs, merge LoRA adapters and serve the result./ollamaDeploy and serve local models with Ollama — pull and run them, then expose the OpenAI-compatible endpoint to apps and agents./penguin-cliManage model API keys, default models and per-agent vault secrets with the penguin CLI./penguin-sdkBuild AI apps on the Penguin Harness SDK — self-contained projects, the createSession/run streaming loop with thinking and image messages, and a complete RAG recipe that ingests documents into a knowledge base and answers with citations behind a web UI./skill-portingInstall skills from external ecosystems into this agent's agent_state/skills/ — resolve Claude Code plugin marketplaces, the Codex plugin repo, skills.sh registry names, GitHub repos, or local folders to their skill directories, review every file, and normalize SKILL.md /software-engineeringComplete software-engineering tasks — investigate and review code, implement bug fixes, features and refactors with minimal scope, validate changes, and report verified outcomes./vllmDeploy and serve LLMs with vLLM behind an OpenAI-compatible endpoint, with tool calling enabled for agent workloads./web-designPenguin visual language for generated web pages and app UIs — GitHub-style simplicity with a single blue accent, light and pure-black dark themes, design tokens, component and chat-interface recipes, plus an opt-in warm paper editorial theme.

README

Read on GitHub

Why PenguinHarness

With LangChain, you build agents by hand — at 1× speed.With PenguinHarness, agents build agents — at 100×.

Three reasons, in deliberate order — from task quality, to how agents get built, to how they keep improving.

1. 🏆 Outstanding results at tens of times less cost

A deliberately minimal toolset over clean low-level interfaces: fewer tool calls, fewer tokens — deeply tuned for open models like DeepSeek. Each harness on the model it is normally paired with, same tasks, head-to-head:

Best accuracy on data analysis — at 1/70 of Claude Code's cost.

2. ⚡ One sentence, and an agent builds your agent app

Type one sentence, and an agent builds the complete agent application for you — scaffold, code, and run instructions, end to end:

Collect the docs from https://github.com/ericbuess/claude-code-docs and build a RAG app that answers Claude Code questions as a configuration expert, citing its sources.

And this is the finished product — a docs expert with retrieval, cited sources that link to the original files, and example questions built in:

https://github.com/user-attachments/assets/9b7033e8-f08a-4c3f-bd33-547896664e6e

And generating this entire RAG app burned just $0.02 (¥0.2) of tokens — on DeepSeek V4 Pro.

3. 🧬 Self-evolution: it gets stronger with use

With PenguinHarness Skills, an agent evaluates and optimizes itself: run the benchmark, find the lost points, ship version N+1 — with a snapshot before every round, and every request observable in the Trace view.

https://github.com/user-attachments/assets/922d13a6-5ffc-4685-9a39-352f02f9afc0

Built-in Skills

Four Skill groups ship in the box (docs); agents can also write and optimize their own:

Group	Skills
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`

Supported Models

Model	Providers
DeepSeek V4	DeepSeek, OpenRouter, Fireworks AI, SiliconFlow, Qwen Token Plan, Qwen Pay-As-You-Go
Kimi K3	Moonshot AI, OpenRouter, Qwen Pay-As-You-Go
GLM 5.2	Z.AI, OpenRouter, Fireworks AI, SiliconFlow, Qwen Token Plan, Qwen Pay-As-You-Go
Hunyuan 3	OpenRouter
Qwen 3.8 Max	Qwen Token Plan, Qwen Pay-As-You-Go, OpenRouter
GPT 5.6	OpenRouter
Gemini 3.6 Flash	Google Gemini, OpenRouter
Claude 5	Anthropic, OpenRouter
Inkling	OpenRouter, Fireworks AI

Each family's latest generation only — the app's Models page lists every built-in preset, and any OpenAI-protocol endpoint works too: pick a preset, or point a custom endpoint at any of the 1000+ online and local models.

Requirements

Requirement	Supported
OS	Linux, macOS, Windows 10+
Architecture	x64, arm64
Runtime	bundled by the one-line installer (npm installs need Node >= 24)
Model	an API key for at least one model

Installation

Two ways in — both work on the same ~/.penguin/data root, so a desktop install and a CLI install can be mixed freely:

🖥️ Desktop app — a double-click install: it embeds the server and opens already signed in, no terminal involved.
⌨️ CLI — a one-line installer (or npm / offline package) puts the penguin command on the machine; penguin web then serves the full Web experience in your browser at http://127.0.0.1:7364 (multi-session chat, agent / skill / model management, usage stats, Trace observability, evaluation center). The online installers bundle their own Node runtime — unpack and run; upgrades and reinstalls never touch your data.

[!NOTE] On a CLI install, the first Web login is admin, with the initial password printed on the server's first start (of the form penguin-1234) — change it right after. Models are configured on the in-app Models page.

🖥️ Desktop app

The full Web experience as a standalone application: it embeds the server and opens already signed in — no terminal, no login page, no initial password to copy. It works on the same ~/.penguin/data root as a CLI install, so the two can be used interchangeably (a data root only ever runs one server; if a CLI-started instance is already up, the app attaches to it).

⬇️ Get it from the download page — the page serves the OSS-accelerated mirror when it is reachable, and every installer is also attached to each GitHub Release.

Platform	Installers
macOS 11+	dmg (Apple Silicon / Intel)
Windows 10+	installer (.exe, x64)
Linux (x64)	AppImage / deb

Current builds are unsigned, so the system may block the very first launch. Expand your platform for the one-time fix:

macOS quarantines files downloaded from the internet, and the missing signature makes that flag surface as a false “damaged” alert. Deleting the flag clears it:

Open the downloaded dmg and drag PenguinHarness.app into the Applications folder.
Open Terminal (Launchpad → Other → Terminal).
Paste this command into Terminal and press Enter, then type your login password (nothing shows while you type; press Enter when done):
```
sudo xattr -rd com.apple.quarantine /Applications/PenguinHarness.app
```
Once it finishes, double-click the app — it now opens normally.

The installer is not signed yet, so SmartScreen holds the first run: click More info, then Run anyway to continue installing — first run only.

Browsers download AppImages without the execute permission. Grant it once and the app starts normally from then on (the deb package installs through the package manager and is not affected):

chmod +x penguin-desktop-linux-x86_64.AppImage

🐧🍎 Linux / macOS (online install)

curl -fsSL https://penguin.ooo/install.sh | sh
penguin web        # start the service and open http://127.0.0.1:7364

🪟 Windows (online install, PowerShell)

irm https://penguin.ooo/install.ps1 | iex
penguin web        # start the service and open http://127.0.0.1:7364

📦 npm (any platform, Node >= 24)

npm install -g @prismshadow/penguin-cli
penguin web        # start the service and open http://127.0.0.1:7364

Every GitHub Release attaches exactly one package per target — Linux and macOS in x64 / arm64, Windows in x64, plus a runtime-less universal package — and the same file serves online and offline installation. Each package seals the program payload, its SHA256 checksum and the platform's installer: download the one file on a networked machine, copy it to the target, extract once and run the bundled installer — no network, no separate checksum file to carry (the sealed SHA256 is always verified).

Linux (on arm64, use penguin-linux-arm64.tar.gz):

mkdir penguin-install
tar -xzf penguin-linux-x64.tar.gz -C penguin-install
./penguin-install/install.sh

macOS (Apple silicon shown; on Intel, use penguin-darwin-x64.tar.gz):

mkdir penguin-install
tar -xzf penguin-darwin-arm64.tar.gz -C penguin-install
./penguin-install/install.sh

Windows (unzip, then double-click install.cmd — or run it in PowerShell):

Expand-Archive penguin-win32-x64.zip -DestinationPath penguin-install
cd penguin-install
.\install.cmd

🤖 CLI & SDK — for agents

The same engine, scriptable — made to be driven by agents (and agents building agents):

penguin config model add --provider deepseek --model-id deepseek-v4-flash --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)
penguin server     # headless service (same API the Web App uses)

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);
  }
}

Roadmap

Public release of the benchmark suite
Desktop app
Windows support
Agent company and templates
Company-level self evolving
OpenShell integration (permission-governed shell)
More to come…

Development

pnpm install && pnpm build   # build first: core's exports point at dist/
pnpm dev                     # backend + web app together (prefixed logs, deps built once)

See CONTRIBUTING.md for the full workspace guide: dev commands, quality gates, repo layout, and the changelog rule.

Contributors

Thanks to everyone who has contributed to PenguinHarness!

Citation

If you use PenguinHarness in your research, please cite:

@software{penguinharness2026,
  author  = {{PrismShadow Team}},
  title   = {PenguinHarness: Efficient Self-Improving Harness for Everyone},
  year    = {2026},
  url     = {https://github.com/Prism-Shadow/penguin-harness},
  license = {Apache-2.0}
}

License

Built with ❤️ by Yaowei Zheng (author of LlamaFactory), the PrismShadow AI Team, and Fable 5.

File tree

960

Prism-Shadow/penguin-harnessView on GitHub

.env.example
.gitattributes
.github/
  workflows/
    ci.yml
    desktop-build.yml
    oss-staging.yml
    pages.yml
    release.yml
.gitignore
.prettierignore
.prettierrc.json
assets/
  readme/
    benchmark-dark.svg
    benchmark-light.svg
    rag-app-en-dark.webp
    rag-app-en-light.webp
    rag-app-zh-dark.webp
    rag-app-zh-light.webp
changelog/
CHANGELOG.md
  0.1.0/
    2026-07-20-landing-site.md
    2026-07-20-models-and-credentials.md
    2026-07-20-readme-blog-and-docs.md
    2026-07-20-skills.md
    2026-07-20-tooling.md
    2026-07-20-web-app.md
    2026-07-21-model-reference-and-review-fixes.md
    2026-07-21-site-preferences-sync.md
    README.md
  0.1.1/
    2026-07-22-docs-and-examples.md
    2026-07-22-models-and-core.md
    2026-07-22-sites-and-blog.md
    2026-07-22-skills.md
    2026-07-22-tooling.md
    2026-07-22-web-app.md
    README.md
    RELEASE.md
  0.1.2/
    2026-07-22-web-app.md
    2026-07-24-backward-compatibility.md
    2026-07-24-llm-request-errors.md
    2026-07-24-models-and-core.md
    2026-07-24-sites-and-blog.md
    2026-07-24-tooling.md
    README.md
    RELEASE.md
  0.1.3/
    2026-07-26-core.md
    2026-07-26-goal-mode.md
    2026-07-26-web-app.md
    2026-07-26-windows-support.md
    2026-07-27-backward-compatibility.md
    2026-07-27-llm-request-errors.md
    2026-07-27-models-and-composer.md
    2026-07-27-tooling.md
    README.md
    RELEASE.md
  0.1.4/
    2026-07-27-release-pipeline.md
    2026-07-27-sites-and-blog.md
    README.md
    RELEASE.md
  0.1.5/
    2026-07-25-agent-tuning-pipeline.md
    2026-07-27-input-images.md
    2026-07-27-sites-and-blog.md
    2026-07-27-windows-bundled-shell.md
    2026-07-28-duration-and-byte-formatting.md
    2026-07-28-web-app.md
    2026-07-29-composer-attachments-and-switch-commands.md
    2026-07-29-cost-center-errors.md
    2026-07-29-default-system-prompt.md
    2026-07-29-harness-env-and-dev-ports.md
    2026-07-29-llm-request-lifecycle.md
    2026-07-29-offline-install-bundles.md
    2026-07-29-session-elapsed.md
    2026-07-30-backward-compatibility.md
    2026-07-30-docs-tools-and-configuration-reference.md
    2026-07-30-install-docs-and-landing.md
    2026-07-30-paste-filter-utf8.md
    2026-07-30-skills-web-design-and-penguin-sdk.md
    2026-07-30-web-app-refinements.md
    README.md
    RELEASE.md
  0.2.0/
    2026-07-30-file-summary-task-boundary.md
    2026-07-31-backward-compatibility.md
    2026-07-31-evaluation-center-case-details.md
    2026-07-31-recover-truncated-tool-output.md
    2026-07-31-unified-installer-artifact.md
    2026-08-02-file-tool-missing-path-diagnostics.md
    2026-08-02-update-check-feedback.md
    2026-08-02-web-app-steering-and-session-list.md
    2026-08-03-model-catalog-qianwenai-flash.md
    2026-08-03-oss-distribution.md
    2026-08-03-web-chat-navigation.md
    README.md
    RELEASE.md
  0.2.1/
    2026-08-04-agent-skills-and-list.md
    2026-08-04-ansi-tool-output.md
    2026-08-04-cli-web-probe-diagnostics.md
    2026-08-04-compaction-retry-observability.md
    2026-08-04-data-analysis-skill-v2.md
    2026-08-04-deps-hono-redos.md
    2026-08-04-desktop-app.md
    2026-08-04-desktop-distribution-and-download-page.md
    2026-08-04-download-source-selection.md
    2026-08-04-io-hotspots-scheduler-messages.md
    2026-08-04-model-catalog-openrouter-qwen38-max.md
    2026-08-04-project-chat-defaults.md
    2026-08-04-skill-porting-library-skill.md
    2026-08-04-traces-page-scaling.md
    2026-08-04-web-app.md
    2026-08-04-web-chat-refinements.md
    README.md
    RELEASE.md
  README.md
  unreleased/
    2026-08-03-chat-toolbar-layout.md
    2026-08-06-desktop-app.md
    2026-08-06-landing-desktop-first.md
    2026-08-06-model-catalog-inkling-dsv4-flash-0731.md
    2026-08-06-release-version-guard.md
    2026-08-06-system-proxy-switch.md
    2026-08-06-web-app.md
    2026-08-07-core-runtime.md
    README.md
CONTRIBUTING.md
examples/
  build-agent-with-agent/
    build-agent.ts
    package.json
    README.md
    README.zh.md
  self-improving-agent/
    package.json
    README.md
    README.zh.md
    self-evolve-recursive.ts
    self-evolve.ts
    self-improve.ts
install.cmd
install.ps1
install.sh
LICENSE
package.json
packages/
  cli/
    package.json
    README.md
    src/
      approval.ts
      commands/
        chat.ts
        config.ts
        run.ts
        serve.ts
        update.ts
      goal-command.ts
      i18n.ts
      index.ts
      input.ts
      lang-config.ts
      render.ts
      task-loop.ts
      tool-render.ts
    test/
      approval.test.ts
      chat.test.ts
      config-format.test.ts
      config-model.test.ts
      config-vault.test.ts
      goal-command.test.ts
      i18n.test.ts
      input.test.ts
      lang-config.test.ts
      model-ref-pairing.test.ts
      render.test.ts
      serve.test.ts
      task-loop.test.ts
      tool-render.test.ts
      update-refusal-markers.test.ts
      update.test.ts
    tsconfig.json
    tsup.config.ts
  core/
    package.json
    README.md
    src/
      agent.ts
      engine/
        context-engine.ts
      environment/
        environment.ts
        index.ts
        tools/
          background/
            capped-buffer.ts
            index.ts
            limits.ts
            registry.ts
            wake-signal.ts
          command/
            index.ts
            limits.ts
            session-manager.ts
            session.ts
            shell.ts
          describe-image.ts
          diff.ts
          edit-file.ts
          exec-command.ts
          file-utils.ts
          input-command.ts
          input-subagent.ts
          path-hint.ts
          read-file.ts
          read-image.ts
          registry.ts
          run-subagent.ts
          subagent/
            collect.ts
            index.ts
            limits.ts
            session-manager.ts
            session.ts
          types.ts
          write-file.ts
        truncated-tool-output-archive.ts
      goal/
        goal-file.ts
        goal-loop.ts
        goal-prompts.ts
        goal-stream.ts
        index.ts
      index.ts
      interfaces.ts
      internal/
        dates.ts
        model-visible-path.ts
        ports.ts
        session-support.ts
        session-title.ts
        version.ts
      llm/
        context-limits.ts
        generative-model.ts
        index.ts
        tool-call-ids.ts
      omnimessage/
        aggregate.ts
        builders.ts
        index.ts
        markers/
          attachment-lines.ts
          block.ts
          engine-blocks.ts
          goal-block.ts
          index.ts
          origin-blocks.ts
          steering.ts
          strip.ts
          tags.ts
        types.ts
      session.ts
      state/
        agent-state.ts
        agent-vault.ts
        builtin-agents.ts
        default-config.ts
        example-benchmark.ts
        index.ts
        model-catalog.ts
        paths.ts
        project-config.ts
      trace/
        index.ts
        resume.ts
        writer.ts
    test/
      agent-lifecycle.test.ts
      agent-skills.test.ts
      agent.test.ts
      background-registry.test.ts
      builtin-agents.test.ts
      capped-buffer.test.ts
      compaction.test.ts
      context-limits.test.ts
      describe-error.test.ts
      describe-image.test.ts
      engine.test.ts
      environment.test.ts
      example-benchmark.test.ts
      exec-session.test.ts
      file-tools.test.ts
      goal.test.ts
      input-images.test.ts
      llm.e2e.test.ts
      llm.test.ts
      markers.test.ts
      model-catalog.test.ts
      model-visible-path.test.ts
      omnimessage.test.ts
      provider-keys.ts
      read-image.test.ts
      replay.test.ts
      resume.test.ts
      session-title.test.ts
      shell-resolver.test.ts
      state.test.ts
      subagent.test.ts
      tool-call-ids.test.ts
      trace.test.ts
      truncated-tool-output-archive.test.ts
      validate-id.test.ts
      wake-signal.test.ts
      workspace.test.ts
    tsconfig.json
    tsup.config.ts
    vitest.config.ts
  desktop/
    .gitignore
    build/
      icon.png
      icons/
        128x128.png
        256x256.png
        512x512.png
      linux/
        after-install.tpl
        after-remove.tpl
    electron-builder.yml
    package.json
    scripts/
      preflight.mjs
      render-icon.mjs
      stage.mjs
    src/
      app-icon.ts
      cli-install.ts
      launcher.ts
      main.ts
      menu.ts
      os-proxy.ts
      port-memory.ts
      server-process.ts
      util.ts
    test/
      app-icon.test.ts
      launcher.test.ts
      os-proxy.test.ts
      port-memory.test.ts
      util.test.ts
    tsconfig.json
    tsup.config.ts
  docs/
    content/
      agent-loop.en.md
      agent-loop.zh.md
      architecture.en.md
      architecture.zh.md
      cli.en.md
      cli.zh.md
      configuration.en.md
      configuration.zh.md
      goal-mode.en.md
      goal-mode.zh.md
      installation.en.md
      installation.zh.md
      interfaces.en.md
      interfaces.zh.md
      introduction.en.md
      introduction.zh.md
      message-flow.en.md
      message-flow.zh.md
      models.en.md
      models.zh.md
      omni-message.en.md
      omni-message.zh.md
      quickstart.en.md
      quickstart.zh.md
      self-improvement.en.md
      self-improvement.zh.md
      server-api.en.md
      server-api.zh.md
      sessions-and-traces.en.md
      sessions-and-traces.zh.md
      skills.en.md
      skills.zh.md
      tools.en.md
      tools.zh.md
      web-app.en.md
      web-app.zh.md
    index.html
    package.json
... 686 more

FAQ

penguin-harness is a Claude Code plugin with 16 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes agent-creation, agent-evaluation, agent-optimization. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.

What is penguin-harness?: 🐧 Automated Agent Builder. Create Self-Evolving Agents in One Click (DeepSeek/Kimi/GPT/Claude/Gemini)
How do I install penguin-harness?: Run these in Claude Code: npx -y skills add Prism-Shadow/penguin-harness --agent claude-code. Then prompt normally.
Does penguin-harness auto-invoke its skills?: Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
Is penguin-harness free?: Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.

Development

Plugin

penguin-harness

🐧 Automated Agent Builder. Create Self-Evolving Agents in One Click (DeepSeek/Kimi/GPT/Claude/Gemini)

FLOW.md

prism-shadow@prism-shadow

GitHub

Plugin Signal82/100Strong

maintained99

capable59

documented100

adopted65

Install

$ npx -y skills add Prism-Shadow/penguin-harness --agent claude-code

Run the curl in your terminal, the rest in Claude Code.

Stats

TypeScript Node HTML Bash PowerShell

+7 tags

Linux GitHub Markdown Anthropic OpenAI Gemini LangChain

1,102

Stars

104

Forks

Active

Maintenance

TypeScript

Language

Apache-2.0

License

49m ago

Last commit

22d ago

Created

Repo: Prism-Shadow/penguin-harness

In this plugin

16 skills

See everything inside

What's inside

Skills

Show all 16 skills

README

Read on GitHub

Why PenguinHarness

With LangChain, you build agents by hand — at 1× speed.With PenguinHarness, agents build agents — at 100×.

Three reasons, in deliberate order — from task quality, to how agents get built, to how they keep improving.

1. 🏆 Outstanding results at tens of times less cost

Best accuracy on data analysis — at 1/70 of Claude Code's cost.

2. ⚡ One sentence, and an agent builds your agent app

Type one sentence, and an agent builds the complete agent application for you — scaffold, code, and run instructions, end to end:

Collect the docs from https://github.com/ericbuess/claude-code-docs and build a RAG app that answers Claude Code questions as a configuration expert, citing its sources.

And this is the finished product — a docs expert with retrieval, cited sources that link to the original files, and example questions built in:

https://github.com/user-attachments/assets/9b7033e8-f08a-4c3f-bd33-547896664e6e

And generating this entire RAG app burned just $0.02 (¥0.2) of tokens — on DeepSeek V4 Pro.

3. 🧬 Self-evolution: it gets stronger with use

https://github.com/user-attachments/assets/922d13a6-5ffc-4685-9a39-352f02f9afc0

Built-in Skills

Four Skill groups ship in the box (docs); agents can also write and optimize their own:

Group	Skills
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`

Supported Models

Model	Providers
DeepSeek V4	DeepSeek, OpenRouter, Fireworks AI, SiliconFlow, Qwen Token Plan, Qwen Pay-As-You-Go
Kimi K3	Moonshot AI, OpenRouter, Qwen Pay-As-You-Go
GLM 5.2	Z.AI, OpenRouter, Fireworks AI, SiliconFlow, Qwen Token Plan, Qwen Pay-As-You-Go
Hunyuan 3	OpenRouter
Qwen 3.8 Max	Qwen Token Plan, Qwen Pay-As-You-Go, OpenRouter
GPT 5.6	OpenRouter
Gemini 3.6 Flash	Google Gemini, OpenRouter
Claude 5	Anthropic, OpenRouter
Inkling	OpenRouter, Fireworks AI

Requirements

Requirement	Supported
OS	Linux, macOS, Windows 10+
Architecture	x64, arm64
Runtime	bundled by the one-line installer (npm installs need Node >= 24)
Model	an API key for at least one model

Installation

Two ways in — both work on the same ~/.penguin/data root, so a desktop install and a CLI install can be mixed freely:

🖥️ Desktop app — a double-click install: it embeds the server and opens already signed in, no terminal involved.
⌨️ CLI — a one-line installer (or npm / offline package) puts the penguin command on the machine; penguin web then serves the full Web experience in your browser at http://127.0.0.1:7364 (multi-session chat, agent / skill / model management, usage stats, Trace observability, evaluation center). The online installers bundle their own Node runtime — unpack and run; upgrades and reinstalls never touch your data.

[!NOTE] On a CLI install, the first Web login is admin, with the initial password printed on the server's first start (of the form penguin-1234) — change it right after. Models are configured on the in-app Models page.

🖥️ Desktop app

⬇️ Get it from the download page — the page serves the OSS-accelerated mirror when it is reachable, and every installer is also attached to each GitHub Release.

Platform	Installers
macOS 11+	dmg (Apple Silicon / Intel)
Windows 10+	installer (.exe, x64)
Linux (x64)	AppImage / deb

Current builds are unsigned, so the system may block the very first launch. Expand your platform for the one-time fix:

macOS quarantines files downloaded from the internet, and the missing signature makes that flag surface as a false “damaged” alert. Deleting the flag clears it:

Open the downloaded dmg and drag PenguinHarness.app into the Applications folder.
Open Terminal (Launchpad → Other → Terminal).
Paste this command into Terminal and press Enter, then type your login password (nothing shows while you type; press Enter when done):
```
sudo xattr -rd com.apple.quarantine /Applications/PenguinHarness.app
```
Once it finishes, double-click the app — it now opens normally.

The installer is not signed yet, so SmartScreen holds the first run: click More info, then Run anyway to continue installing — first run only.

Browsers download AppImages without the execute permission. Grant it once and the app starts normally from then on (the deb package installs through the package manager and is not affected):

chmod +x penguin-desktop-linux-x86_64.AppImage

🐧🍎 Linux / macOS (online install)

curl -fsSL https://penguin.ooo/install.sh | sh
penguin web        # start the service and open http://127.0.0.1:7364

🪟 Windows (online install, PowerShell)

irm https://penguin.ooo/install.ps1 | iex
penguin web        # start the service and open http://127.0.0.1:7364

📦 npm (any platform, Node >= 24)

npm install -g @prismshadow/penguin-cli
penguin web        # start the service and open http://127.0.0.1:7364

Linux (on arm64, use penguin-linux-arm64.tar.gz):

mkdir penguin-install
tar -xzf penguin-linux-x64.tar.gz -C penguin-install
./penguin-install/install.sh

macOS (Apple silicon shown; on Intel, use penguin-darwin-x64.tar.gz):

mkdir penguin-install
tar -xzf penguin-darwin-arm64.tar.gz -C penguin-install
./penguin-install/install.sh

Windows (unzip, then double-click install.cmd — or run it in PowerShell):

Expand-Archive penguin-win32-x64.zip -DestinationPath penguin-install
cd penguin-install
.\install.cmd

🤖 CLI & SDK — for agents

The same engine, scriptable — made to be driven by agents (and agents building agents):

penguin config model add --provider deepseek --model-id deepseek-v4-flash --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)
penguin server     # headless service (same API the Web App uses)

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);
  }
}

Roadmap

Public release of the benchmark suite
Desktop app
Windows support
Agent company and templates
Company-level self evolving
OpenShell integration (permission-governed shell)
More to come…

Development

pnpm install && pnpm build   # build first: core's exports point at dist/
pnpm dev                     # backend + web app together (prefixed logs, deps built once)

See CONTRIBUTING.md for the full workspace guide: dev commands, quality gates, repo layout, and the changelog rule.

Contributors

Thanks to everyone who has contributed to PenguinHarness!

Citation

If you use PenguinHarness in your research, please cite:

@software{penguinharness2026,
  author  = {{PrismShadow Team}},
  title   = {PenguinHarness: Efficient Self-Improving Harness for Everyone},
  year    = {2026},
  url     = {https://github.com/Prism-Shadow/penguin-harness},
  license = {Apache-2.0}
}

License

Built with ❤️ by Yaowei Zheng (author of LlamaFactory), the PrismShadow AI Team, and Fable 5.

File tree

960

Prism-Shadow/penguin-harnessView on GitHub

.env.example
.gitattributes
.github/
  workflows/
    ci.yml
    desktop-build.yml
    oss-staging.yml
    pages.yml
    release.yml
.gitignore
.prettierignore
.prettierrc.json
assets/
  readme/
    benchmark-dark.svg
    benchmark-light.svg
    rag-app-en-dark.webp
    rag-app-en-light.webp
    rag-app-zh-dark.webp
    rag-app-zh-light.webp
changelog/
CHANGELOG.md
  0.1.0/
    2026-07-20-landing-site.md
    2026-07-20-models-and-credentials.md
    2026-07-20-readme-blog-and-docs.md
    2026-07-20-skills.md
    2026-07-20-tooling.md
    2026-07-20-web-app.md
    2026-07-21-model-reference-and-review-fixes.md
    2026-07-21-site-preferences-sync.md
    README.md
  0.1.1/
    2026-07-22-docs-and-examples.md
    2026-07-22-models-and-core.md
    2026-07-22-sites-and-blog.md
    2026-07-22-skills.md
    2026-07-22-tooling.md
    2026-07-22-web-app.md
    README.md
    RELEASE.md
  0.1.2/
    2026-07-22-web-app.md
    2026-07-24-backward-compatibility.md
    2026-07-24-llm-request-errors.md
    2026-07-24-models-and-core.md
    2026-07-24-sites-and-blog.md
    2026-07-24-tooling.md
    README.md
    RELEASE.md
  0.1.3/
    2026-07-26-core.md
    2026-07-26-goal-mode.md
    2026-07-26-web-app.md
    2026-07-26-windows-support.md
    2026-07-27-backward-compatibility.md
    2026-07-27-llm-request-errors.md
    2026-07-27-models-and-composer.md
    2026-07-27-tooling.md
    README.md
    RELEASE.md
  0.1.4/
    2026-07-27-release-pipeline.md
    2026-07-27-sites-and-blog.md
    README.md
    RELEASE.md
  0.1.5/
    2026-07-25-agent-tuning-pipeline.md
    2026-07-27-input-images.md
    2026-07-27-sites-and-blog.md
    2026-07-27-windows-bundled-shell.md
    2026-07-28-duration-and-byte-formatting.md
    2026-07-28-web-app.md
    2026-07-29-composer-attachments-and-switch-commands.md
    2026-07-29-cost-center-errors.md
    2026-07-29-default-system-prompt.md
    2026-07-29-harness-env-and-dev-ports.md
    2026-07-29-llm-request-lifecycle.md
    2026-07-29-offline-install-bundles.md
    2026-07-29-session-elapsed.md
    2026-07-30-backward-compatibility.md
    2026-07-30-docs-tools-and-configuration-reference.md
    2026-07-30-install-docs-and-landing.md
    2026-07-30-paste-filter-utf8.md
    2026-07-30-skills-web-design-and-penguin-sdk.md
    2026-07-30-web-app-refinements.md
    README.md
    RELEASE.md
  0.2.0/
    2026-07-30-file-summary-task-boundary.md
    2026-07-31-backward-compatibility.md
    2026-07-31-evaluation-center-case-details.md
    2026-07-31-recover-truncated-tool-output.md
    2026-07-31-unified-installer-artifact.md
    2026-08-02-file-tool-missing-path-diagnostics.md
    2026-08-02-update-check-feedback.md
    2026-08-02-web-app-steering-and-session-list.md
    2026-08-03-model-catalog-qianwenai-flash.md
    2026-08-03-oss-distribution.md
    2026-08-03-web-chat-navigation.md
    README.md
    RELEASE.md
  0.2.1/
    2026-08-04-agent-skills-and-list.md
    2026-08-04-ansi-tool-output.md
    2026-08-04-cli-web-probe-diagnostics.md
    2026-08-04-compaction-retry-observability.md
    2026-08-04-data-analysis-skill-v2.md
    2026-08-04-deps-hono-redos.md
    2026-08-04-desktop-app.md
    2026-08-04-desktop-distribution-and-download-page.md
    2026-08-04-download-source-selection.md
    2026-08-04-io-hotspots-scheduler-messages.md
    2026-08-04-model-catalog-openrouter-qwen38-max.md
    2026-08-04-project-chat-defaults.md
    2026-08-04-skill-porting-library-skill.md
    2026-08-04-traces-page-scaling.md
    2026-08-04-web-app.md
    2026-08-04-web-chat-refinements.md
    README.md
    RELEASE.md
  README.md
  unreleased/
    2026-08-03-chat-toolbar-layout.md
    2026-08-06-desktop-app.md
    2026-08-06-landing-desktop-first.md
    2026-08-06-model-catalog-inkling-dsv4-flash-0731.md
    2026-08-06-release-version-guard.md
    2026-08-06-system-proxy-switch.md
    2026-08-06-web-app.md
    2026-08-07-core-runtime.md
    README.md
CONTRIBUTING.md
examples/
  build-agent-with-agent/
    build-agent.ts
    package.json
    README.md
    README.zh.md
  self-improving-agent/
    package.json
    README.md
    README.zh.md
    self-evolve-recursive.ts
    self-evolve.ts
    self-improve.ts
install.cmd
install.ps1
install.sh
LICENSE
package.json
packages/
  cli/
    package.json
    README.md
    src/
      approval.ts
      commands/
        chat.ts
        config.ts
        run.ts
        serve.ts
        update.ts
      goal-command.ts
      i18n.ts
      index.ts
      input.ts
      lang-config.ts
      render.ts
      task-loop.ts
      tool-render.ts
    test/
      approval.test.ts
      chat.test.ts
      config-format.test.ts
      config-model.test.ts
      config-vault.test.ts
      goal-command.test.ts
      i18n.test.ts
      input.test.ts
      lang-config.test.ts
      model-ref-pairing.test.ts
      render.test.ts
      serve.test.ts
      task-loop.test.ts
      tool-render.test.ts
      update-refusal-markers.test.ts
      update.test.ts
    tsconfig.json
    tsup.config.ts
  core/
    package.json
    README.md
    src/
      agent.ts
      engine/
        context-engine.ts
      environment/
        environment.ts
        index.ts
        tools/
          background/
            capped-buffer.ts
            index.ts
            limits.ts
            registry.ts
            wake-signal.ts
          command/
            index.ts
            limits.ts
            session-manager.ts
            session.ts
            shell.ts
          describe-image.ts
          diff.ts
          edit-file.ts
          exec-command.ts
          file-utils.ts
          input-command.ts
          input-subagent.ts
          path-hint.ts
          read-file.ts
          read-image.ts
          registry.ts
          run-subagent.ts
          subagent/
            collect.ts
            index.ts
            limits.ts
            session-manager.ts
            session.ts
          types.ts
          write-file.ts
        truncated-tool-output-archive.ts
      goal/
        goal-file.ts
        goal-loop.ts
        goal-prompts.ts
        goal-stream.ts
        index.ts
      index.ts
      interfaces.ts
      internal/
        dates.ts
        model-visible-path.ts
        ports.ts
        session-support.ts
        session-title.ts
        version.ts
      llm/
        context-limits.ts
        generative-model.ts
        index.ts
        tool-call-ids.ts
      omnimessage/
        aggregate.ts
        builders.ts
        index.ts
        markers/
          attachment-lines.ts
          block.ts
          engine-blocks.ts
          goal-block.ts
          index.ts
          origin-blocks.ts
          steering.ts
          strip.ts
          tags.ts
        types.ts
      session.ts
      state/
        agent-state.ts
        agent-vault.ts
        builtin-agents.ts
        default-config.ts
        example-benchmark.ts
        index.ts
        model-catalog.ts
        paths.ts
        project-config.ts
      trace/
        index.ts
        resume.ts
        writer.ts
    test/
      agent-lifecycle.test.ts
      agent-skills.test.ts
      agent.test.ts
      background-registry.test.ts
      builtin-agents.test.ts
      capped-buffer.test.ts
      compaction.test.ts
      context-limits.test.ts
      describe-error.test.ts
      describe-image.test.ts
      engine.test.ts
      environment.test.ts
      example-benchmark.test.ts
      exec-session.test.ts
      file-tools.test.ts
      goal.test.ts
      input-images.test.ts
      llm.e2e.test.ts
      llm.test.ts
      markers.test.ts
      model-catalog.test.ts
      model-visible-path.test.ts
      omnimessage.test.ts
      provider-keys.ts
      read-image.test.ts
      replay.test.ts
      resume.test.ts
      session-title.test.ts
      shell-resolver.test.ts
      state.test.ts
      subagent.test.ts
      tool-call-ids.test.ts
      trace.test.ts
      truncated-tool-output-archive.test.ts
      validate-id.test.ts
      wake-signal.test.ts
      workspace.test.ts
    tsconfig.json
    tsup.config.ts
    vitest.config.ts
  desktop/
    .gitignore
    build/
      icon.png
      icons/
        128x128.png
        256x256.png
        512x512.png
      linux/
        after-install.tpl
        after-remove.tpl
    electron-builder.yml
    package.json
    scripts/
      preflight.mjs
      render-icon.mjs
      stage.mjs
    src/
      app-icon.ts
      cli-install.ts
      launcher.ts
      main.ts
      menu.ts
      os-proxy.ts
      port-memory.ts
      server-process.ts
      util.ts
    test/
      app-icon.test.ts
      launcher.test.ts
      os-proxy.test.ts
      port-memory.test.ts
      util.test.ts
    tsconfig.json
    tsup.config.ts
  docs/
    content/
      agent-loop.en.md
      agent-loop.zh.md
      architecture.en.md
      architecture.zh.md
      cli.en.md
      cli.zh.md
      configuration.en.md
      configuration.zh.md
      goal-mode.en.md
      goal-mode.zh.md
      installation.en.md
      installation.zh.md
      interfaces.en.md
      interfaces.zh.md
      introduction.en.md
      introduction.zh.md
      message-flow.en.md
      message-flow.zh.md
      models.en.md
      models.zh.md
      omni-message.en.md
      omni-message.zh.md
      quickstart.en.md
      quickstart.zh.md
      self-improvement.en.md
      self-improvement.zh.md
      server-api.en.md
      server-api.zh.md
      sessions-and-traces.en.md
      sessions-and-traces.zh.md
      skills.en.md
      skills.zh.md
      tools.en.md
      tools.zh.md
      web-app.en.md
      web-app.zh.md
    index.html
    package.json
... 686 more

FAQ

What is penguin-harness?: 🐧 Automated Agent Builder. Create Self-Evolving Agents in One Click (DeepSeek/Kimi/GPT/Claude/Gemini)
How do I install penguin-harness?: Run these in Claude Code: npx -y skills add Prism-Shadow/penguin-harness --agent claude-code. Then prompt normally.
Does penguin-harness auto-invoke its skills?: Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
Is penguin-harness free?: Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.