# PenguinHarness

> Run PenguinHarness in NeuroSquad cards — how to install it, how the cards work, and what to know.

Source: https://docs.neurosquad.ai/en/agents/penguin

**PenguinHarness** is an open-source (Apache-2.0), local-first agent platform from the PrismShadow
AI team: a server with a web app, and the `penguin chat` command on top of it. In NeuroSquad each
Penguin card runs the real `penguin chat` in its terminal.

Measured on PenguinHarness 0.2.13 and on its main branch.

## Install

**1. Install the penguin command**

```bash
npm install -g @prismshadow/penguin-cli
```

It needs Node 24 or newer. Penguin's own install script from [penguin.ooo](https://penguin.ooo)
works too. **Settings → Setup** in NeuroSquad can run the npm install for you.

**2. Add your models**

Set up your providers and models in Penguin as usual — cards use them. A card can also run on
[OpenRouter](https://docs.neurosquad.ai/en/providers/openrouter) or on [your own server](https://docs.neurosquad.ai/en/providers/your-servers).

**3. Add a PenguinHarness card**

Add an agent card and choose **PenguinHarness**.

## How the cards work

NeuroSquad runs **its own Penguin server** for its own data folder, starts it with the first Penguin
card and stops it when you quit. **Each card is a Penguin agent of its own** (`ns_<card>`) with its
own hooks, MCP servers and instructions. Your Penguin project config — your models and keys — is
copied in on every launch; your own `~/.penguin` is never written.

## What works

- **Exact status.** The card follows the server's status stream for its session — working and
finished — and a NeuroSquad hook decides which calls need you. NeuroSquad's own tools, `read_file`
and subagents run unasked; anything else waits on Penguin's own `? Approve this tool call? [Y/n]`,
and the toast names it (`PenguinHarness needs your permission: write_file: a.txt`).
- **Arrows.** NeuroSquad's MCP server is in the card's agent. Penguin takes a snapshot of its tools,
so every NeuroSquad tool is offered from the start and the arrows decide at call time; a skill or
an installed MCP server needs the card's next start. Installed servers ask before every call.
- **Canvas mode.** The hook refuses `exec_command` and `input_command` — Penguin's shell, and its
only way to the web — even in dangerous mode. See [Canvas mode](https://docs.neurosquad.ai/en/squads/canvas-mode).
- **Dangerous mode without a restart.** While the switch is on, the hook allows every call. See
[Dangerous mode](https://docs.neurosquad.ai/en/agents/dangerous-mode).
- **Stop.** Stop, the budget brake and the phone's Stop use Penguin's own abort API; the chat stays
open.
- **Sessions.** After a restart the card continues the same conversation (`--resume`); a deleted
session starts fresh.
- **Long sessions.** Context meter, **Compact** (`/compact`), the rate-limit chip, the prompt queue,
the journal and hand-off.
- **Usage.** Every request is read from Penguin's Trace files, subagents marked, in
[Usage & costs](https://docs.neurosquad.ai/en/usage), [Run Stats](https://docs.neurosquad.ai/en/cards/run-stats) and [Agent Pulse](https://docs.neurosquad.ai/en/cards/agent-pulse).
- **Models.** A lead agent can change the model with `agent_set_model`, or move the conversation to
Claude Code and back. OpenRouter and your own servers go through NeuroSquad's local relay — no key
on disk.

## Good to know

- **Conversations live in NeuroSquad's Penguin folder.** Your own `penguin chat --resume` doesn't
list them; with `PENGUIN_HOME` pointing at that folder and `--agent-id ns_<card>`, it does.
- **Models added inside a card** last only until its next launch — add them in your own Penguin.
- **Plugins.** [Caveman](https://docs.neurosquad.ai/en/plugins/caveman), [Memory](https://docs.neurosquad.ai/en/plugins/mem0-memory),
[Context7](https://docs.neurosquad.ai/en/plugins/context7-docs) and [Graphify](https://docs.neurosquad.ai/en/plugins/graphify) add text to each turn through
a hook Penguin runs on every prompt only after 0.2.13; on 0.2.13 their tools still work by arrow.
The [token saver](https://docs.neurosquad.ai/en/plugins/rtk-ai-token-saver) can't work: Penguin's hook can't rewrite a command.
- **Usage columns.** Penguin folds cache creation into the input and reasoning into the output, so
those columns read "not reported"; on Claude models the price is a little low for it.
- **The card's MCP token** sits in its agent's config (Penguin can't read it from the environment
there). It is loopback-only, per card, and changes every app run.

> PenguinHarness cards run on this computer only — not in WSL or SSH workspaces.