Who Pstack Claude is for#
Developers fixing bugs that need reproduction evidence
Poteto-mode's bug playbook reproduces the failure first, uses how and why to trace root cause, then delegates the fix and reruns the failing case to confirm. You receive both the fix and the failure-to-passing evidence in the same session, replacing the pattern of applying a guess and hoping it holds.
Skip if:
The bug is already fully understood and isolated. If you have a confirmed root cause and need only a one-line patch, poteto-mode's investigation steps add overhead without benefit.
Teams running PR review and maintenance on Claude Code
The PR maintenance playbook covers review, comment resolution, and pre-merge checks as a structured sequence. On Claude Code, poteto-mode routes PR work through the appropriate skills automatically, including bringing in architect if a change crosses a function boundary.
Skip if:
Your PR workflow is already fully automated by CI or a dedicated review bot. Pstack-claude adds structure to agent-driven review; it does not replace automated linting or CI gates.
Developers using multiple coding agents
The same pstack skill set works on Claude Code, Codex, Pi, OpenCode, and Gemini CLI. A developer or team that switches between coding agents gets the same poteto-mode routing and playbooks on each, without maintaining separate prompt files or configuration per tool.
Skip if:
You are committed to a single coding agent long-term. The multi-platform portability is not useful if you have no plans to work with other agents.
The problem it solves#
Coding agents answer whatever prompt they receive with no enforced workflow. Asking an agent to fix a bug typically yields a change applied directly to the code, without first reproducing the failure, verifying the root cause, or confirming that the fix holds under the original failing conditions. The same gap shows up across every task type: a feature request skips planning, a refactor skips checking for unintended side effects, and a performance investigation skips measuring before proposing changes.
Teams shipping production code need agent outputs they can verify, not outputs they have to re-check by hand on every run. Without a structured workflow plugin, sessions start from scratch each time, with no investigation steps enforced before a change reaches the repository.
How it solves it#
poteto-mode goal routing
The main entry point. Tell poteto-mode your goal and it selects the matching playbook, from bug fixes to feature planning, refactoring, PR maintenance, and longer project runs. It delegates to architect, arena, or swarm as the task requires, and uses how and why for investigation before any change is applied.
Playbooks for every development task
Named workflows cover bug fixes, feature planning, refactoring, performance investigations, prototypes, PR maintenance, and shipping. Each playbook enforces a defined sequence: plan, delegate, verify. For concurrency bugs and invariants beyond test coverage, a companion plugin (agent-formal-verify) adds TLA+ and Lean proofs.
how and why investigative skills
Before a fix is applied, poteto-mode uses the how skill to reproduce the failure and the why skill to trace root cause. This gives you failure evidence and passing evidence on the same run, not just a diff. The skills are available as standalone slash commands for use outside poteto-mode.
Sub-agent delegation with architect, arena, and swarm
Architect plans cross-boundary changes before implementation begins. Arena runs multiple sub-agents in parallel to explore solutions or perform code review. Swarm coordinates larger task decompositions. Each sub-agent type is invoked by poteto-mode's routing or called directly as a slash command.
Per-role model and reasoning effort configuration
setup-pstack sets default models and reasoning effort per agent role. For example, arena runners can be set to Opus at extra-high effort while the session default stays lower. Claude Code dispatches these through pstack:effort and pstack:poteto-agent agents declared in the plugin manifest.
Strengths and trade-offs#
Strengths
- Multi-platform: one plugin set for Claude Code, Codex, Pi, and moreThe same skill set works across Claude Code, Codex, Pi, OpenCode, and Gemini CLI. On Claude Code and Codex the plugin installs a routing hook; on Pi the extension injects the same routing instruction. A team using multiple agents gets the same structured workflows without maintaining separate prompt files per platform.
- MIT license, no infrastructureThe plugin is MIT licensed with no server, no telemetry, and no cloud dependency. Scripts run locally; PR tools use the developer's existing GitHub CLI login. Any session data goes to the model provider under the developer's own account. There are no subscription tiers or hosting fees specific to pstack-claude.
- Tracks upstream with named policy forksPstack-claude tracks Lauren Tan's upstream Cursor pstack repository and declares any divergences as named forks in tools/forks.json. This keeps the port auditable: you can see exactly where pstack-claude differs from the original and why, rather than relying on undocumented behavioral divergences.
- Active project with 1,100+ starsThe repo reached 1,187 GitHub stars and 135 forks since its May 2026 launch, with the last push in October 2026. 10 open issues indicates an active project without a large unaddressed backlog. Contributor guidelines and a security disclosure policy are documented in CONTRIBUTING.md and SECURITY.md.
Trade-offs
- -Requires an existing coding agent and accountPstack-claude is a plugin, not a standalone tool. It requires an active Claude Code, Codex, or Pi account. Developers without an existing coding agent cannot use pstack-claude in isolation. The plugin also requires trusting the routing hook through the agent's /hooks interface, which Codex prompts you to approve before it runs.
- -Install via session commands, not shell scriptsInstallation on Claude Code uses /plugin slash commands typed inside an agent session, not shell commands you can script or automate in CI. Codex offers a terminal-level codex plugin command, but Claude Code's install path has no non-interactive equivalent documented in the README.
- -JavaScript-only implementationThe plugin is written in JavaScript with no TypeScript types exported. Teams using TypeScript-centric toolchains will not get type-checked integration with the plugin's internal APIs. The skills-and-hooks model suits JavaScript well, but it limits contribution from teams that require typed interfaces.
Pstack Claude vs alternatives#
pstack-claude vs. unstructured Claude Code sessions
Claude Code without a workflow plugin responds to whatever prompt it receives. Ask it to fix a bug and it applies its best interpretation of the fix, with no enforced reproduction step, no root-cause investigation, and no verification pass before the change lands. For one-off tasks where the prompt is specific and the scope is clear, this works well.
The gap shows up on recurring work: bug investigations that need a trail of evidence, features that cross architectural boundaries, or refactors where the risk of unintended side effects is real. In these cases, an unstructured session requires the developer to manually enforce the workflow, recheck outputs, and often re-run the agent when results drift.
| Capability | Claude Code alone | Claude Code + pstack-claude |
|---|---|---|
| Workflow structure | Ad-hoc, prompt-driven | Named playbooks per task type |
| Bug investigation | Direct fix attempt | Reproduce, trace root cause, fix, verify |
| Sub-agent delegation | Manual | architect, arena, swarm per playbook |
| Reasoning effort control | Session-level | Per-role via setup-pstack |
| Multi-platform portability | Claude Code only | Claude Code, Codex, Pi, OpenCode, Gemini CLI |
| License | Paid subscription | Plugin: MIT; platform: paid subscription |
Pstack-claude is the better choice when you want repeatable, verifiable workflows and you already use Claude Code. The bug playbook alone gives you failure evidence and passing evidence on the same run, replacing a manual verification step that adds meaningful time to each session.
Claude Code alone remains the right call for short, well-specified tasks where the overhead of a named playbook exceeds the benefit. If you are applying a trivial one-line change with a known correct answer, running poteto-mode adds steps without value. The plugin's value scales with task complexity and the cost of an incorrect agent output reaching the repository.
What it's built on#
- Languages
- JavaScriptTypeScript
FAQ#
Does pstack-claude replace Claude Code?
No. Pstack-claude is a plugin that runs on top of Claude Code, not a replacement for it. It adds structured workflow skills to Claude Code sessions, but you still need an active Claude Code account and the agent running in your terminal. Think of it as a set of verified playbooks that improve what Claude Code already does, not a substitute for it.
Which coding agents does pstack-claude support?
Claude Code, Codex, Pi, OpenCode, and Gemini CLI are all supported, plus any coding agent that accepts a shared skills-only install (documented in docs/reference.md#shared-skills-installation). On Claude Code and Codex, the routing hook installs automatically; on Pi, the extension injects the same routing instruction. Prime Agent is also listed in the README with a reference to shared installation.
How do I configure the model and reasoning effort per role?
Run setup-pstack (or /pstack:setup-pstack inside Claude Code) to set model defaults and reasoning effort per agent role. For example, you can set arena runners to Opus at extra-high effort while keeping the session default at a lower level. Roles without an explicit setting inherit the session's current effort. Automatic routing can also be turned off from setup-pstack.
Is pstack-claude free to use?
Yes. The plugin itself is MIT licensed with no subscription or licensing fee. You do pay for whatever coding agent you run it on, such as a Claude Code subscription. The plugin adds no cost on top of that. Scripts run locally with no telemetry sent to any pstack-claude server, because there is no pstack-claude server.
What is poteto-mode and how does it work?
Poteto-mode is the main entry point for pstack-claude. You describe your goal and it selects the correct playbook automatically: bug fixes run through reproduce-investigate-fix-verify; features go through planning and delegation; refactors check for side effects before committing. For concurrency bugs and formal invariants, a companion plugin (agent-formal-verify) extends this with TLA+ model checking and Lean proofs.
Similar open-source tools#
Gstack
Turn Claude Code into a virtual engineering team with 23 skills
PiG
Pi's coding agent, in Go. One binary, no Node.js required.
orbi
self-hosted, open-source (AGPL-3.0) AI coding agent
Pi
The minimal, self-extensible coding agent for the terminal
Jean
A dev environment for running AI agents in isolated git worktrees
fx
Native Zig CLI coding agent, 7.8 MiB, any AI model.