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.
Built on top of 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.
| 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, skills, MCP, and extensions.
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 passesScoring and raw results.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 , 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 them, and use trusted repositories.
Read Security and Containerization 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. - Browse or open issues. - Report security problems according to SECURITY.md. Never include credentials in a report.
Porcupine is released under the MIT License.
Built on top of Pi (MIT).
If Porcupine helps you do real work, a GitHub star helps more people find it.
GitHub · npm · Releases · MIT License