{"slug": "show-hn-porcupine-a-terminal-ai-agent-built-for-safe-autonomy", "title": "Show HN: Porcupine, a terminal AI agent built for safe autonomy", "summary": "Porcupine, a terminal AI agent built for safe autonomy, has been released as an open-source tool on GitHub, requiring Node.js 22.19+ and installable via npm. It offers Ask, Normal, and Auto modes to let users control permission boundaries, with hardline destructive actions always blocked. The agent can reason, use tools, delegate to parallel sub-agents, and verify results, supporting multiple interfaces including terminal, Telegram, Discord, and iMessage.", "body_md": "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.\n\n[ Get started](#start-in-60-seconds) ·\n\n[Why Porcupine](#why-porcupine)·\n\n[Capabilities](#what-it-can-do)·\n\n[Evaluation](#evaluation)·\n\n[Safety](#safety-boundaries)·\n\n[Documentation](#documentation)\n\nBuilt on top of [Pi](https://github.com/earendil-works/pi) (MIT).\n\nPorcupine does not treat autonomy as all-or-nothing. You choose how much it may do before asking.\n\n| Porcupine | |\n|---|---|\nSafe autonomy |\nAsk, 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. |\nEnd-to-end work |\nPorcupine 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. |\nNative-first |\nIt 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. |\nParallel execution |\nContext-isolated sub-agents can research, inspect, implement, and review in parallel. Web of Thoughts lets them coordinate live. |\nOne session, more surfaces |\nContinue the same attended session from the terminal, Telegram, Discord, or iMessage. Use headless and server modes for scripts, CI, IDEs, and clients. |\nOpen capability system |\nTools and skills live in 18 capability stacks. Extend Porcupine through Agent Skills, MCP, TypeScript extensions, packages, prompts, themes, and custom providers. |\n\nRequires **Node.js 22.19+**.\n\n```\nnpm install -g @porcupineai/porcupineai\nporcupine\n```\n\nThen connect a provider inside the TUI:\n\n```\n/login cline\n/model\n/guide\n```\n\nCline provides a free API route. Select `cline/deepseek/deepseek-v4-flash`\n\nfrom `/model`\n\n, or connect another supported provider with `/login`\n\n.\n\nGive it a real goal:\n\n```\nReview this repository, explain how it works, run its checks, and make the safest high-impact improvement you can verify.\n```\n\nPorcupine 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.\n\n**Build from source**\n\n```\ngit clone https://github.com/Abd0r/porcupineai.git\ncd porcupineai/Porcupine\nnpm install --ignore-scripts\nnpm run build\nnpm link\nphp\nflowchart LR\n    G[Your goal] --> R[Reason and route]\n    R --> B{Permission and safety boundaries}\n    B --> T[Tools and skills]\n    B --> A[Parallel sub-agents]\n    T --> V[Tests and verification]\n    A --> V\n    V --> E[Evidence-backed result]\n```\n\nThe model leads the work. The harness supplies the capability tree, permission boundary, durable state, recovery paths, and verification loop.\n\n| Mode | Behavior | Best for |\n|---|---|---|\nAsk |\nConfirms every shell command and file mutation | Unfamiliar repositories and maximum oversight |\nNormal |\nRuns safe operations and asks on flagged actions | Everyday interactive work |\nAuto |\nWorks autonomously while flagged shell actions pass through a fail-closed safety gate | Longer goals in trusted projects |\n\nReasoning depth is separate from permission. `/reasoning`\n\nand `/adaptive`\n\nchange thinking effort; `/modes`\n\nchanges what Porcupine may do without asking.\n\nAuto is not unrestricted. Hardline destructive actions remain blocked in every mode.\n\n| Faculty | Capabilities |\n|---|---|\nBuild and maintain |\nRead and edit repositories, run shell commands, debug failures, use Git, build, test, review, and document changes. |\nDevelop for the web |\nFrontend and backend workflows, accessibility, responsive design, APIs, authentication, migrations, observability, browser QA, performance, SEO, and deployment readiness. |\nResearch |\nFree web-search cascade, page extraction, Reddit and arXiv search, evidence grading, durable literature tracking, and parallel deep research. |\nUse the web and computer |\nPlaywright browser tools, semantic snapshots, screenshots, responsive checks, diagnostics, and confirmation-gated native desktop interaction. |\nCoordinate |\nUp to three parallel sub-agents by default, fresh context windows, hard step budgets, live progress, instant reports, steering, cancellation, and WoT peer messaging. |\nRemember and continue |\nDurable sessions, branching, compaction, memory, reusable project workspaces, and cross-session history search. |\nAutomate attended work |\nDurable tasks, success and failure chains, file and script triggers, and UTC Cron schedules while the interactive session is open and idle. |\nCommunicate |\nTelegram, Discord, and iMessage bridges; email over IMAP/SMTP; free X search and reading; local drafts and compose-then-paste posting. |\nIntegrate |\nMCP tools, resources and prompts; `porcupine serve` ; JSONL and RPC modes; a Node.js SDK; custom tools and providers. |\nObserve |\nPer-turn usage, cost estimates, session evidence, task history, browser diagnostics, sub-agent activity, and a full-screen Markdown viewer. |\n\nPorcupine can delegate self-contained work to background sub-agents. Each worker receives:\n\n- a fresh context window;\n- the whole tool stack minus agent-level tools, user questions, and native computer control;\n- a hard step budget, 120 by default;\n- the same working directory and permission policy;\n- instant report injection when the worker finishes.\n\nGive workers the same `peerGroup`\n\nto 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`\n\nor stop it when it goes off track.\n\nSee [Sub-agents](/Abd0r/porcupineai/blob/main/Porcupine/packages/coding-agent/docs/subagents.md).\n\n| Surface | Use |\n|---|---|\nTerminal TUI |\nThe full interactive experience, including permission dialogs, session tree, Markdown viewer, usage, cost, and live activity. |\nTelegram, Discord, iMessage |\nMessage the same attended session from another device. Confirmation buttons and reactions race the TUI; first response wins. |\nHTTP server |\n`porcupine serve` exposes sessions, asynchronous prompts, SSE events, and programmatic approval for IDEs and clients. |\nHeadless mode |\n`porcupine --headless \"task\"` runs a CI-friendly task and exits `0` on success or `1` on failure or abort. |\nRPC and JSONL |\nEmbed Porcupine in scripts and applications through structured process protocols. |\n\nRemote bridges are allowlist-gated and attended. They drive the shared session; they are not unattended daemons.\n\n| Extension point | What it adds |\n|---|---|\nStacks |\nOne discoverable hierarchy for filesystem, shell, web, web development, VCS, build, debugging, safety, data, ML, research, computer use, and orchestration capabilities. |\nAgent Skills |\nOn-demand procedures in portable `SKILL.md` packages. Porcupine can extract skills from documents or craft them from research. |\nMCP |\nConnect stdio and Streamable HTTP servers. Their tools, resources, and prompts become first-class capabilities. |\nTypeScript extensions |\nAdd tools, commands, event handlers, UI, providers, and lifecycle behavior. |\nPackages |\nBundle and share extensions, skills, prompts, and themes. |\nSDK and protocols |\nEmbed the agent loop through the Node.js SDK, RPC, JSONL, or the HTTP server. |\n\nExplore 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).\n\nPorcupine separates the agent from the model route. Use a free path, a subscription, your own API key, or a local router.\n\n| Route | Setup |\n|---|---|\nCline API |\nCreate a free key at\n`/login cline` , then choose `cline/deepseek/deepseek-v4-flash` from `/model` . |\n\n**OpenCode Go**`/login opencode-go`\n\n, then choose an available model and reasoning level from `/model`\n\n.**Built-in providers**`/login`\n\nor provider environment variables.**Local models** Porcupine publishes its harness results with methodology, raw records, failures, and caveats.\n\n| Suite | Porcupine result | Evidence |\n|---|---|---|\nAider Polyglot |\n194/225, 86.2% |\nSix languages, hidden tests restored after the agent run.\n|\n\n**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.\n\nPorcupine is native-first. By default, it runs with the permissions of the account that launches it.\n\n**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`\n\nroutes 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.\n\nRead [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.\n\nContributions are welcome. Keep changes focused, test behavior changes, and update documentation when the user-facing contract moves.\n\n- Read\n[CONTRIBUTING.md](/Abd0r/porcupineai/blob/main/CONTRIBUTING.md). - Browse or open\n[issues](https://github.com/Abd0r/porcupineai/issues). - Report security problems according to\n[SECURITY.md](/Abd0r/porcupineai/blob/main/SECURITY.md). Never include credentials in a report.\n\nPorcupine is released under the [MIT License](/Abd0r/porcupineai/blob/main/LICENSE).\n\nBuilt on top of [Pi](https://github.com/earendil-works/pi) (MIT).\n\n**If Porcupine helps you do real work, a GitHub star helps more people find it.**\n\n[GitHub](https://github.com/Abd0r/porcupineai) ·\n[npm](https://www.npmjs.com/package/@porcupineai/porcupineai) ·\n[Releases](https://github.com/Abd0r/porcupineai/releases) ·\n[MIT License](/Abd0r/porcupineai/blob/main/LICENSE)", "url": "https://wpnews.pro/news/show-hn-porcupine-a-terminal-ai-agent-built-for-safe-autonomy", "canonical_source": "https://github.com/Abd0r/porcupineai", "published_at": "2026-08-11 12:52:27+00:00", "updated_at": "2026-08-11 13:13:35.794862+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-safety", "developer-tools"], "entities": ["Porcupine", "Pi", "Node.js", "npm", "Cline", "DeepSeek", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/show-hn-porcupine-a-terminal-ai-agent-built-for-safe-autonomy", "markdown": "https://wpnews.pro/news/show-hn-porcupine-a-terminal-ai-agent-built-for-safe-autonomy.md", "text": "https://wpnews.pro/news/show-hn-porcupine-a-terminal-ai-agent-built-for-safe-autonomy.txt", "jsonld": "https://wpnews.pro/news/show-hn-porcupine-a-terminal-ai-agent-built-for-safe-autonomy.jsonld"}}