# Show HN: Porcupine, a terminal AI agent built for safe autonomy

> Source: <https://github.com/Abd0r/porcupineai>
> Published: 2026-08-11 12:52:27+00:00

Give Porcupine a goal. It reasons, routes capabilities, uses tools, delegates work, verifies the result, and keeps risky action inside the permission boundary you control.

[ Get started](#start-in-60-seconds) ·

[Why Porcupine](#why-porcupine)·

[Capabilities](#what-it-can-do)·

[Evaluation](#evaluation)·

[Safety](#safety-boundaries)·

[Documentation](#documentation)

Built on top of [Pi](https://github.com/earendil-works/pi) (MIT).

Porcupine does not treat autonomy as all-or-nothing. You choose how much it may do before asking.

| Porcupine | |
|---|---|
Safe autonomy |
Ask, Normal, and Auto modes let you choose the permission boundary. Normal asks on flagged actions; Auto applies a fail-closed safety gate. Hardline destructive actions remain blocked. |
End-to-end work |
Porcupine reads the real project, chooses tools and skills, edits files, runs checks, recovers from failures, and reports evidence instead of stopping at a plausible answer. |
Native-first |
It works on your computer with your tools and files by default. Gondolin, Docker, and OpenShell isolation remain opt-in when you want a stronger boundary. |
Parallel execution |
Context-isolated sub-agents can research, inspect, implement, and review in parallel. Web of Thoughts lets them coordinate live. |
One session, more surfaces |
Continue the same attended session from the terminal, Telegram, Discord, or iMessage. Use headless and server modes for scripts, CI, IDEs, and clients. |
Open capability system |
Tools and skills live in 18 capability stacks. Extend Porcupine through Agent Skills, MCP, TypeScript extensions, packages, prompts, themes, and custom providers. |

Requires **Node.js 22.19+**.

```
npm install -g @porcupineai/porcupineai
porcupine
```

Then connect a provider inside the TUI:

```
/login cline
/model
/guide
```

Cline provides a free API route. Select `cline/deepseek/deepseek-v4-flash`

from `/model`

, or connect another supported provider with `/login`

.

Give it a real goal:

```
Review this repository, explain how it works, run its checks, and make the safest high-impact improvement you can verify.
```

Porcupine decides whether the turn needs a direct answer, tools, a skill, a plan, or parallel workers. It continues until the requested result is real or a genuine decision requires you.

**Build from source**

```
git clone https://github.com/Abd0r/porcupineai.git
cd porcupineai/Porcupine
npm install --ignore-scripts
npm run build
npm link
php
flowchart LR
    G[Your goal] --> R[Reason and route]
    R --> B{Permission and safety boundaries}
    B --> T[Tools and skills]
    B --> A[Parallel sub-agents]
    T --> V[Tests and verification]
    A --> V
    V --> E[Evidence-backed result]
```

The model leads the work. The harness supplies the capability tree, permission boundary, durable state, recovery paths, and verification loop.

| Mode | Behavior | Best for |
|---|---|---|
Ask |
Confirms every shell command and file mutation | Unfamiliar repositories and maximum oversight |
Normal |
Runs safe operations and asks on flagged actions | Everyday interactive work |
Auto |
Works autonomously while flagged shell actions pass through a fail-closed safety gate | Longer goals in trusted projects |

Reasoning depth is separate from permission. `/reasoning`

and `/adaptive`

change thinking effort; `/modes`

changes what Porcupine may do without asking.

Auto is not unrestricted. Hardline destructive actions remain blocked in every mode.

| Faculty | Capabilities |
|---|---|
Build and maintain |
Read and edit repositories, run shell commands, debug failures, use Git, build, test, review, and document changes. |
Develop for the web |
Frontend and backend workflows, accessibility, responsive design, APIs, authentication, migrations, observability, browser QA, performance, SEO, and deployment readiness. |
Research |
Free web-search cascade, page extraction, Reddit and arXiv search, evidence grading, durable literature tracking, and parallel deep research. |
Use the web and computer |
Playwright browser tools, semantic snapshots, screenshots, responsive checks, diagnostics, and confirmation-gated native desktop interaction. |
Coordinate |
Up to three parallel sub-agents by default, fresh context windows, hard step budgets, live progress, instant reports, steering, cancellation, and WoT peer messaging. |
Remember and continue |
Durable sessions, branching, compaction, memory, reusable project workspaces, and cross-session history search. |
Automate attended work |
Durable tasks, success and failure chains, file and script triggers, and UTC Cron schedules while the interactive session is open and idle. |
Communicate |
Telegram, Discord, and iMessage bridges; email over IMAP/SMTP; free X search and reading; local drafts and compose-then-paste posting. |
Integrate |
MCP tools, resources and prompts; `porcupine serve` ; JSONL and RPC modes; a Node.js SDK; custom tools and providers. |
Observe |
Per-turn usage, cost estimates, session evidence, task history, browser diagnostics, sub-agent activity, and a full-screen Markdown viewer. |

Porcupine can delegate self-contained work to background sub-agents. Each worker receives:

- a fresh context window;
- the whole tool stack minus agent-level tools, user questions, and native computer control;
- a hard step budget, 120 by default;
- the same working directory and permission policy;
- instant report injection when the worker finishes.

Give workers the same `peerGroup`

to enable **Web of Thoughts**. They can exchange findings live while the main agent remains the gatekeeper. The main agent can steer a worker with `send_to_subagent`

or stop it when it goes off track.

See [Sub-agents](/Abd0r/porcupineai/blob/main/Porcupine/packages/coding-agent/docs/subagents.md).

| Surface | Use |
|---|---|
Terminal TUI |
The full interactive experience, including permission dialogs, session tree, Markdown viewer, usage, cost, and live activity. |
Telegram, Discord, iMessage |
Message the same attended session from another device. Confirmation buttons and reactions race the TUI; first response wins. |
HTTP server |
`porcupine serve` exposes sessions, asynchronous prompts, SSE events, and programmatic approval for IDEs and clients. |
Headless mode |
`porcupine --headless "task"` runs a CI-friendly task and exits `0` on success or `1` on failure or abort. |
RPC and JSONL |
Embed Porcupine in scripts and applications through structured process protocols. |

Remote bridges are allowlist-gated and attended. They drive the shared session; they are not unattended daemons.

| Extension point | What it adds |
|---|---|
Stacks |
One discoverable hierarchy for filesystem, shell, web, web development, VCS, build, debugging, safety, data, ML, research, computer use, and orchestration capabilities. |
Agent Skills |
On-demand procedures in portable `SKILL.md` packages. Porcupine can extract skills from documents or craft them from research. |
MCP |
Connect stdio and Streamable HTTP servers. Their tools, resources, and prompts become first-class capabilities. |
TypeScript extensions |
Add tools, commands, event handlers, UI, providers, and lifecycle behavior. |
Packages |
Bundle and share extensions, skills, prompts, and themes. |
SDK and protocols |
Embed the agent loop through the Node.js SDK, RPC, JSONL, or the HTTP server. |

Explore the [18-stack capability tree](/Abd0r/porcupineai/blob/main/Porcupine/packages/coding-agent/docs/stacks.md), [skills](/Abd0r/porcupineai/blob/main/Porcupine/packages/coding-agent/docs/skills.md), [MCP](/Abd0r/porcupineai/blob/main/Porcupine/packages/coding-agent/docs/mcp.md), and [extensions](/Abd0r/porcupineai/blob/main/Porcupine/packages/coding-agent/docs/extensions.md).

Porcupine separates the agent from the model route. Use a free path, a subscription, your own API key, or a local router.

| Route | Setup |
|---|---|
Cline API |
Create a free key at
`/login cline` , then choose `cline/deepseek/deepseek-v4-flash` from `/model` . |

**OpenCode Go**`/login opencode-go`

, then choose an available model and reasoning level from `/model`

.**Built-in providers**`/login`

or provider environment variables.**Local models** Porcupine publishes its harness results with methodology, raw records, failures, and caveats.

| Suite | Porcupine result | Evidence |
|---|---|---|
Aider Polyglot |
194/225, 86.2% |
Six languages, hidden tests restored after the agent run.
|

**Terminal-Bench 2.1****45 clean passes**[Scoring and raw results](/Abd0r/porcupineai/blob/main/benchmarks/tbench/README.md).Both runs used DeepSeek V4 Flash through the Porcupine harness. These results measure the exact model and harness combination, not every model, provider, workload, or commercial agent.

Porcupine is native-first. By default, it runs with the permissions of the account that launches it.

**Project trust is not a sandbox.** It controls project-local resource loading, not operating-system permissions.**Interaction modes are the autonomy dial.** Ask, Normal, and Auto control approvals; reasoning settings do not grant permission.**Auto fails closed on flagged shell actions.** Hardline destructive actions remain blocked in every mode.**Native computer input is confirmation-gated.** The workflow starts with observation, treats screen text as untrusted, takes one approved action, then verifies the visible result.**Isolation is optional.**`/sandbox on`

routes built-in tools into a Gondolin micro-VM. Docker and OpenShell workflows are also documented.**Extensions and skills are trusted code and instructions.** Review them before loading them, and use trusted repositories.

Read [Security](/Abd0r/porcupineai/blob/main/Porcupine/packages/coding-agent/docs/security.md) and [Containerization](/Abd0r/porcupineai/blob/main/Porcupine/packages/coding-agent/docs/containerization.md) before using Porcupine on untrusted work.

Contributions are welcome. Keep changes focused, test behavior changes, and update documentation when the user-facing contract moves.

- Read
[CONTRIBUTING.md](/Abd0r/porcupineai/blob/main/CONTRIBUTING.md). - Browse or open
[issues](https://github.com/Abd0r/porcupineai/issues). - Report security problems according to
[SECURITY.md](/Abd0r/porcupineai/blob/main/SECURITY.md). Never include credentials in a report.

Porcupine is released under the [MIT License](/Abd0r/porcupineai/blob/main/LICENSE).

Built on top of [Pi](https://github.com/earendil-works/pi) (MIT).

**If Porcupine helps you do real work, a GitHub star helps more people find it.**

[GitHub](https://github.com/Abd0r/porcupineai) ·
[npm](https://www.npmjs.com/package/@porcupineai/porcupineai) ·
[Releases](https://github.com/Abd0r/porcupineai/releases) ·
[MIT License](/Abd0r/porcupineai/blob/main/LICENSE)