This Open Pstack distribution lets Codex and Claude Code coordinate coding work across the AI subscriptions you already have. Arjit Jaiswal maintains it as an intelligent model router built around Pstack's engineering workflows.
setup-pstack checks provider and model access, asks about subscriptions it cannot verify, and recommends models for implementation, investigation, and review. You approve the assignments and backup chains during setup. Pstack routes workers to those models and automatically uses approved backups when the saved policy allows recovery. It tells you what failed and which model is taking over, and inspects and preserves partial work before continuing.
This repository maintains its own provider integrations, recovery behavior, and tested releases while tracking Cursor's Pstack directly. It builds on Lauren Tan's original Pstack and Eric Litman's Open Pstack port, with their attribution preserved.
See release evidence and recovery limits, why use this distribution, and upstream status.
- Match models to the work and the subscriptions you have. Setup considers task fit, confirmed access, capacity where known, and the effort level you choose.
- Check the routes you will actually use. Setup verifies selected models through their native app or signed-in CLI. An unused provider does not block setup.
- Combine Codex, Claude, Grok, Devin SWE-2 or SWE-1.6, and Cursor CLI workers. Keep one set of engineering skills across Codex and Claude Code.
- Save backup chains instead of choosing a replacement during a failure. Recovery follows your saved policy, reports the actual provider and model, and respects your API-spend settings.
- Follow Cursor's Pstack directly. Scheduled checks detect changes and prepare proposals. Adaptation, review, and real Codex and Claude Code checks come before a release.
Routing follows the role assignments you approve. Setup recommends a mix based on task fit and confirmed access. The saved policy controls which models run and when a backup can take over.
Recovery can cover recognized quota limits, unavailable routes, terminal backend failures, and explicitly configured deadlines. Existing configurations remain quota-only until a broader policy is saved. A quiet worker is not assumed to have failed; an exhausted parent or a chain with no safe, approved backup cannot recover automatically. See tested behavior and limits.
The parent is the app where you start a task. It coordinates the work and keeps your tools and conversation context. A worker is a model it delegates a bounded task to.
| Worker provider | From a Codex parent | From a Claude Code parent |
|---|---|---|
| OpenAI / Codex | Native Codex subagent | External codex CLI |
| Anthropic / Claude | External claude CLI |
Native Claude Code subagent |
| xAI / Grok | External grok CLI |
External grok CLI |
| Devin SWE-2 / SWE-1.6 | External devin CLI |
External devin CLI |
| Cursor models | External cursor-agent CLI |
External cursor-agent CLI |
This distribution supports Codex and Claude Code as parents. Grok, Devin, and Cursor are worker providers here. For Cursor as your parent app, use Cursor's original Pstack. Provider availability does not guarantee access to every model: setup checks the exact models you select.
External workers use their own authentication and do not inherit the parent's MCP connections. Why and Reflect stay native so they retain those tools. See compatibility for supported models, permissions, and tested routes.
pstack is a plugin for coding agents. It is not a new model or a hosted service. It gives your agent engineering rules, step-by-step workflows for different kinds of work, focused skills, and small local tools.
The normal entry point is poteto-mode. You give it a task in plain language. It then:
- reads the task and chooses a workflow that fits;
- learns how the current system works before changing it;
- compares designs when the choice matters;
- favors small, simple changes over extra machinery;
- asks several models to challenge important decisions when useful;
- runs the code and checks real behavior instead of stopping at “the tests pass”; and
- carries the work through review, continuous integration (CI), and a ready-to-merge pull request when asked.
pstack does not ask you to trust an agent on day one. It helps the agent leave evidence you can inspect. Start with supervised work. Let it run more work in parallel only after its checks have earned that trust in your own repositories.
Start with a current Claude Code or Codex installation. Install and sign in to the command-line tools for the external providers you choose; unused providers are optional. Bun runs Pstack's local routing tools. Setup checks access before saving your model choices.
Run these commands inside Claude Code:
/plugin marketplace add arjitj2/open-pstack#v1.4.1-arjit.5
/plugin install pstack@open-pstack
/reload-plugins
Run these commands in your shell:
codex plugin marketplace add arjitj2/open-pstack --ref v1.4.1-arjit.5
codex plugin add pstack@open-pstackTurn on Codex subagents in ~/.codex/config.toml so pstack can compare work in parallel:
[features]
multi_agent = trueStart a new Codex task after installation so it can discover the new skills and setting.
Configure your model access once for each parent app you use. Then start a task. Repository-specific verification is a separate step below.
In Claude Code, run:
/pstack:setup-pstack
In the Codex app, type / and select pstack:setup-pstack from the skill list. You can also mention the skill with $pstack:setup-pstack. In Codex CLI, use /skills or type $pstack:setup-pstack. Asking for the skill by name works too; the words “Use pstack” are not required. See OpenAI's slash commands and skill invocation.
Setup discovers the models you can run, asks about subscriptions it cannot verify, and recommends assignments for each role. It shows which models will run natively and which will use external workers, then asks before saving. Included subscription access and permission for metered API spending are recorded separately; unknown remaining capacity stays unknown.
You can save an ordered backup chain for each role, with up to three attempts. During a run, Pstack follows those approved choices and reports substitutions. Recovery depends on the installed release and saved policy; see recovery support and validation. If a failed worker may have changed files, the parent inspects and preserves that work before continuing in a fresh workspace. An unsafe or ambiguous result stops that lane with a checkpoint.
Only selected providers need to pass setup. You can mix providers across implementation, investigation, and review or keep the configuration small. See the model matrix for supported models and effort levels.
Setup also migrates older versioned Fable, Opus, and Sonnet entries to rolling aliases while preserving role assignments and effort. Run setup after an update to persist that migration.
Start any task that needs careful engineering with poteto-mode.
In Claude Code:
/pstack:poteto-mode Add saved filters to search. Keep the design simple, verify it in the real app, and open a pull request.
In the Codex app, type /, select pstack:poteto-mode, and add your task. A skill mention also works in Codex:
$pstack:poteto-mode Add saved filters to search. Keep the design simple, verify it in the real app, and open a pull request.
For that feature, poteto-mode should first understand how search works today. It should decide how the data should be represented before writing code, implement the smallest complete version, run the feature the way a user would, review the result, and prepare the pull request.
The skill name is poteto-mode, spelled with an “e”. Claude Code also loads this distribution's startup instruction for non-trivial engineering work. In Codex, select the skill explicitly or add a standing instruction if you want it used by default. Model setup saves routing preferences; it does not install an always-on Codex workflow instruction.
That is the main workflow. The other skills are there when poteto-mode needs them or when you want to call one directly.
setup-pstack verifies model access, saves your approved model sheet and parent integration, reads them back, and runs a small worker-and-reviewer smoke test. It does not create an app feature map or schedule repository maintenance.
For a repository without a repeatable way to test real behavior, invoke pstack:create-verification-skill. It inspects how the app starts and can be driven, creates a project-local verification skill, and seeds a feature map with the first few user-facing features. Each entry describes how to reach the feature, exercise it, and recognize success. The generated skill must prove one mapped feature live before handoff; that initial map is a starting point, not a claim of complete coverage.
Use pstack:maintain-verification-skill as the app changes. It checks the map against source and live behavior and can propose a PR correcting drift. These skills work through the same picker or mention mechanism described above. Use /pstack:create-verification-skill and /pstack:maintain-verification-skill in Claude Code.
This release includes the creation and maintenance workflows, but no automatic feature-map maintenance schedule. Recurring upkeep must be configured separately in your parent app or another scheduler. Installing Pstack does not silently start background jobs.
| Skill | Use it when |
|---|---|
how |
You want a clear explanation of how part of the system works. |
why |
You want evidence for why the system was built that way. |
architect |
A change crosses a function or module boundary and the design needs to be settled first. |
arena |
You want several complete attempts, followed by a comparison of their best parts. |
interrogate |
You want different models to try to break a design or diff. |
create-verification-skill |
Your project has no repeatable way for an agent to prove real behavior. |
maintain-verification-skill |
The project's verification instructions no longer match the product. |
babysit |
A pull request needs CI failures and review comments handled until it is ready. |
reflect |
A hard task is finished and its lessons should improve the next run. |
Plugin skills include pstack: in their name. In Claude Code, invoke /pstack:architect. In Codex, select pstack:architect from the skill picker or mention $pstack:architect. See the technical reference for the full list.
Codex or Claude Code can delegate selected roles to SWE-2 or SWE-1.6 through an authenticated Devin CLI. Ask setup-pstack to use devin:swe-2@high (medium/high/max) or devin:swe-1.6@default for named roles. Devin remains an external worker; the default three-model panel stays unchanged.
This adapter extracts the final response from a private conversation export and pins the CLI model UID. It does not report provider-verified model identity, tokens, or cost. Read-only workers cannot execute shell commands. See the Devin dispatch contract for permissions and live verification requirements.
Some pstack workflows use one model. Skills such as architect, arena, and interrogate can run several models in parallel. Each model run uses the access configured for its native app or external CLI: included subscription capacity or explicitly approved API spending.
setup-pstack lets you choose the models, one requested effort per assigned model family, and how many run in parallel. Choose role assignments first; setup checks only the models those roles use. Unused providers need no CLI or subscription. If a selected model fails, repair its availability or explicitly change the affected roles before saving. A model from the app you are using runs inside that app. Other models run through their own command-line tools. Open Pstack does not quietly replace a failed model with a weaker one.
Lauren's pstack guide walks through a real task, verification, and longer unattended runs. It uses Cursor's interface, but the ideas are the same. Use the translated skill invocations above in Claude Code or Codex.
This repository also keeps:
- the original README, unchanged;
- the technical reference for every skill, dependency, and Claude Code or Codex detail;
- the upstream sync record and update process;
- the change record for every adaptation; and
- the attribution record for pstack and the imported Cursor Team Kit skills.
The stable release v1.4.1-arjit.5 incorporates pstack 0.15.5 at Cursor commit 12d587dfb20741cafc376c42c696c5f6e2a64487.
The two projects have separate version numbers. The pstack version identifies Lauren's upstream content. The Open Pstack version identifies the Claude Code and Codex package built from it.
In this repository, “upstream” means Lauren's original pstack. Open Pstack does not promise instant updates. It records the exact version it follows, reviews new changes in order, and adapts them for the shared Codex and Claude Code workflows. This distribution also maintains its own provider discovery, model routing, and recovery features, with independent release decisions. Useful fixes from other ports are reviewed separately. Pending Cursor changes remain visible until they are adopted, adapted, or excluded with a reason.
Fixes for Claude Code or Codex and help bringing over new pstack releases are welcome. Search GitHub Issues before opening a new issue. For larger behavior changes, explain why the change belongs in Open Pstack instead of Lauren's original project.
Read CONTRIBUTING.md and UPSTREAM.md before changing content brought over from Lauren's pstack. Pull requests must keep one shared skill tree for Claude Code and Codex and pass the repository's tests, type checks, plugin validation, and static checks.
MIT. pstack was created by Lauren Tan. Open Pstack builds on Michael Denyer's pstack-claude port and includes attributed MIT-licensed work from Cursor Team Kit and Superpowers. See NOTICE.md and the preserved license files for details.