One .intent/ folder. Define success once, work in any native tool, verify what happened.
"One project. Many AI tools. Visible handoffs."
Node-aware, nvm-aware, never sudo. No curl? Fallback: npm install -g phewsh
Fuller setups: front door on supported AI tools (shim + ambient) · plus the official vendored packs. All reversible.
Local-first & MIT. Read the source: github.com/cleverIdeaz/phewsh-cli — what it reads, writes, and sends is documented in SECURITY.md. Something off? phewsh feedback files it publicly.
Then phewsh pack — one place to discover and adopt the best of what the community is building. Browse the catalog ↓
Global CLI. Node.js 18+ required.
A guided walk through the Intent Compass — your answers become .intent/, project truth supported tools read through native adapters. In a hurry? phewsh init is the two-question version.
Syncs one canonical core into CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, and cloud.
No API key required — phewsh ai runs through the agent CLIs you already
have, on their own logins (Claude subscription, ChatGPT plan, Google account).
Packs are the installation interface: managed additions are previewed and reversible; linked projects remain with their creators. Metadata, provenance, and trust state come from the same catalog as the public Atlas.
Open the canonical Skills Atlas →
Move one repository from unfinished to verified and shippable, one bounded slice and one honest handoff at a time.
Phewsh Original · Phewsh tested
Choose which repository receives the next execution window without losing portfolio-level state.
Phewsh Original · Phewsh tested
Add concise think-first, simplicity, surgical-change, and goal-driven coding guidance to project agent files.
Adapted from · Phewsh tested
Plan high, execute wide, and judge high by routing work according to intelligence, taste, cost, and effort.
Phewsh Synthesis · Phewsh tested
Audit whether an AI-assisted project remains goal-oriented, evidence-backed, governable, and transferable.
Inspired by · Phewsh tested
Composable agent loops with explicit checks and stopping conditions.
Linked upstream · Unreviewed
Composable engineering skills for requirements, TDD, diagnosis, research, architecture, review, and handoffs.
Linked upstream · Unreviewed
A complete spec-driven planning, execution, research, debugging, and verification workflow.
Linked upstream · Unreviewed
An opinionated collection of CEO, design, engineering, QA, review, browser, and shipping workflows.
Linked upstream · Unreviewed
An agent harness with subagents, memory, sandboxes, and skills.
Linked upstream · Unreviewed
A separate agent harness mapped as a compatibility candidate.
Linked upstream · Unreviewed
A large security-focused community skill collection that requires deliberate scope review.
Linked upstream · Unreviewed
A security scanner for AI-agent skills; a scan is evidence, not a guarantee.
Linked upstream · Unreviewed
A persistent code-intelligence MCP server for repository memory and lookup.
Linked upstream · Unreviewed
A local or GPU OCR candidate for image and PDF workflows.
Linked upstream · Unreviewed
An open-source macOS video editor with an MCP surface.
Linked upstream · Unreviewed
An agentic video-production system with pipelines, tools, and skills.
Linked upstream · Unreviewed
HTML-to-video rendering for agent-produced demos and media.
Linked upstream · Unreviewed
An open-source AI voice studio for audio workflows.
Linked upstream · Unreviewed
In plain terms: you write down what you're building once, and native adapters let supported AI tools you already use — Claude Code, Codex, Cursor, Gemini — read the same project-owned record. You can switch tools without changing the source of truth. Their capabilities and transcripts remain separate, and each captured Phewsh handoff says what carried — and what did not.
Technically: a local project-truth router and execution bridge. It grounds the harnesses you already have before work starts, routes intent into each tool's native files, exposes an opt-in local worker bridge for the web and Ion, and records & verifies outcomes after. No model inside, no proxy in the default path.
.intent/ is plain markdown + JSON, committed with your code. Your goal, constraints, and the decisions you've made. Not locked to phewsh — any tool can read it.
phewsh compiles one canonical core into each tool's native file — shared truth inside a managed block, tool-specific notes preserved outside it.
Accepted success criteria travel with the verified brief into your installed tool, using its own login and native interface.
After exit, phewsh checks repository evidence, reports pass/fail/unknown/human verdicts, and updates shared intent only after your approval.
What sets it apart from every other CLI harness
Claude Code, Codex, Aider, Cursor, Goose — they're all execution engines. Each owns its own session, permissions, interface, and capabilities. They're routable choices at the coordination layer, even though their capabilities differ, and none can transfer a private transcript into the others.
phewsh is the one thing that isn't an engine. It keeps no model of its own, holds no capability list, and never sees your subscription credentials. It passes your prompt straight through to the real tool — so new native capabilities remain available without Phewsh maintaining a duplicate model or capability catalog.
The result: one project-owned truth across supported adapters, a record of what you decided and kept, and native context files those tools can read after adapter setup even when the Phewsh front door is closed. That cross-tool record is the moat — not the routing. Swap the engine without rebuilding the car.
phewsh is not another agent. It's the layer that uses the ones you already have. If Claude Code, Codex CLI, Gemini CLI, Cursor Agent, or OpenCode is installed, phewsh executes through it on its own login — your Claude subscription, your ChatGPT plan, your Google account. No API credits burned.
Prefer raw APIs? OpenRouter, Anthropic, Groq, Ollama and the PHEWSH gateway (pooled credits, budget-gated) all work too via phewsh login --set-key.
phewsh — everything. Intent authoring, sync, the bridges, receipts, dispatch — and the MCP server, bundled. phewsh mcp setup wires it into Claude Code, Cursor, or any MCP client via phewsh mcp serve --stdio. An interactive agent session gets your project's briefing, task queue, and enforcement gate — and shares state with the bridges, so everything lands in the same receipts. No second install.
Rule of thumb: phewsh serve dispatches tasks to your agents from the web. phewsh mcp setup lets agents pull tasks from PHEWSH mid-session. See it live at /mcp.
PHEWSH sits above supported AI tools as the continuity layer.
Or simpler: Models think. Agents act. Memory remembers. MCP connects. PHEWSH keeps everything continuous.
The AI ecosystem is fragmenting hard. Different models excel at different things. APIs change. Pricing shifts. Providers disappear. Context gets trapped inside silos.
Right now people repeatedly re-upload context, re-explain projects, rebuild prompts, migrate workflows manually, and lose continuity between devices, tools, and models.
PHEWSH's value: your workflow survives even if your tools change. Use whatever AI is best today without losing continuity tomorrow.
"Swap the engine without rebuilding the car."
Everything works as phewsh <cmd> from terminal or /<cmd> inside a session. The whole idea is four plain words — Project · Next · Work · Record — and they work even with no AI in the loop.
.intent/ truth--no-pushPart of Project: record constraints for supported tool briefs — and decide whether to build before you build.
phewsh > /gate
Budget? $50
Time? 15 hrs/week
Skill? expert
Urgency? highWhen you ask "what should I do next?", the answer respects what you can actually spend. No more AI suggesting $500 solutions to $50 problems.
Configured MCP clients can read bounded project context and tasks, then report results. MCP is an optional adapter, not project truth or permission for autonomous execution.
$ phewsh mcp setup # add to Claude Code configAgent tools: phewsh_start, phewsh_next_task, phewsh_complete_task, phewsh_flag_blocker, phewsh_get_context
A maintained, source-backed self-assessment — not an independent audit. Read the threat model and release checklist. npm provenance is not live yet.
Native tools keep their own trust boundary. When phewsh executes through Claude Code, Codex, or another installed tool, that tool uses its own login and data policy. phewsh does not read those credentials or receive the native transcript. Provider, cloud, and browse features still send the data their selected destination requires.
API keys are stored owner-only. A bring-your-own key lives in ~/.phewsh/config.json written at filesystem mode 0600 (only your user can read it), in a 0700 directory. A key you set is never written to command history. BYOK requests go directly to the provider — not through phewsh.
The local bridge is loopback-only by default, not authenticated. phewsh serve binds to 127.0.0.1 / ::1 and applies a browser origin allowlist. Another process on your machine may still call it; loopback is not authentication. Never expose the optional unauthenticated MCP HTTP host on an untrusted network.
Telemetry is counts, never content. Sustainability tracking sends the model name, token counts, and an energy estimate — never your prompts or the responses. There is no hidden content collection.
Ambient hooks do not read native transcripts. They read selected project-owned .intent/ files and Phewsh's local decision record to build a brief, then leave metadata breadcrumbs. Treat those project records as potentially sensitive.
No lock-in. .intent/ is plain markdown/JSON in your repo. Delete phewsh and it's all still there, readable by any tool.
Found something? Responsible disclosure: hello@phewsh.com.
Where to go next