porcupineai

The open-source terminal AI agent built for safe autonomy.

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 · Why Porcupine · Capabilities · Evaluation · Safety · Documentation

Built on top of Pi (MIT).

Why Porcupine

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

Start in 60 seconds

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.

git clone https://github.com/Abd0r/porcupineai.git
cd porcupineai/Porcupine
npm install --ignore-scripts
npm run build
npm link

How work flows

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.

Choose the autonomy level

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.

What it can do

Parallel work without losing the thread

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.

One agent, more than one surface

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

Extensible by design

Explore the 18-stack capability tree, skills, MCP, and extensions.

Providers

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

See Providers and llama.cpp.

Evaluation

Porcupine publishes its harness results with methodology, raw records, failures, and caveats.

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.

Safety boundaries

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 and Containerization before using Porcupine on untrusted work.

Documentation

Contributing

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.

License and foundation

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