PUAX: a role-and-protocol layer that tries to push coding agents past the analysis stage
用来驯服AI Agent的效果绝佳的多角色 Prompt SKILLs！
At a glance
- What is it?
- PUAX ships 59 prompt roles, 45 MCP tools and a hook system that watches a session for failure and injects pressure. It is an MCP server and a set of SKILL.md files, MIT licensed, and the interesting part is not the personas but the completion gate.
- Who is it for?
- Adopt PUAX if you already run an MCP-capable client such as Cursor or Claude Code and your agents stall in the analysis phase rather than failing outright. Skip it if you want a single system prompt you can paste once, or if you cannot run a Node process alongside your client.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failure PUAX is aimed at: agents that reason correctly and then stop
Most prompt collections for coding agents target the wrong symptom. They try to make a model smarter. PUAX targets a narrower and more common failure: the agent produces a correct analysis, states a plausible plan, and then terminates without verifying anything. The README frames the goal as moving an agent from "分析正确" to "验证完成、可交付", from correct analysis to verified and deliverable work. That is a behavioural claim, not a capability claim, and it shapes everything in the repository. The project describes itself as an incentive and behaviour-driving system for AI agents, with a hybrid trigger detector, role recommendation, and what it calls a behaviour effectiveness loop. The intended user is someone already running an agent inside an MCP client, who has noticed that the agent's self-assessment is unreliable. The README opens with an anecdote about a Cambridge assistant professor telling OpenAI's Codex that Claude had found roughly a 20 percent speedup elsewhere, and that the result would be shown on a public leaderboard. Codex reportedly returned a 35 percent speedup. The story is there to justify the premise: framing and stakes change agent output. Whether that generalises is not established by the repository, and the anecdote is not evidence.
Roles, trigger detection, and the loop that gates completion
The mechanism has three layers. The first is a library of 59 built-in roles across nine categories (military, shaman, P10, silicon-based, theme, SillyTavern, self-motivation, special, and the Zhuangzi eight dreams added in v3.12), each stored as a SKILL.md file under skills/. The second is a detector that decides when to activate one. According to the README, detection runs regular expressions from YAML patterns first, and falls back to TF-IDF plus substring overlap with a threshold of 0.62 when nothing matches, which is what allows paraphrased input to hit. A third path, EnhancedTriggerDetector, watches for contextual signals such as an idle tool or low-quality output. The third layer is the part worth attention: a set of protocol tools that constrain the agent's own claims. puax_check_diagnosis validates a [PUAX-DIAGNOSIS] block before work proceeds. puax_confidence_check runs a six-step confidence gate. puax_switch_on_failure maps a detected failure mode to a different methodology or role. puax_define_contract writes a task contract. puax_verify_completion performs verification that the README explicitly describes as independent rather than agent self-assessment. The README states that activating a role automatically injects the diagnosis-first protocol through activate_with_context or get_role_with_methodology. That is the architectural claim: the role is not decoration, it is the carrier for the protocol.
Session state, pressure levels, and the two hook modes
PUAX persists session state under ~/.puax/sessions/ and tracks a pressure level from L0 to L4. Consecutive failures escalate the level; a successful breakthrough triggers a downgrade through puax_handle_breakthrough. Six hook events are defined: UserPromptSubmit, PostToolUse, PreToolUse, PreCompact, SessionStart and Stop. The README describes two modes running side by side. In the first, MCP tools are called by the agent voluntarily. In the second, introduced in v3.11, native hooks are enforced by the host through the command puax-mcp-server hook <事件>. The README lists what the native mode adds: SessionStart injection, PreToolUse interception to block git push and hidden-file access as anti-cheating measures, and PostToolUse automatic escalation on failure. A PreCompact hook is described as protecting reasoning across compaction. This distinction matters more than the role count. An MCP tool that the agent chooses to call is a suggestion. A host-enforced PreToolUse hook is a constraint. The README states that --export=claude-code, --export=cursor and --export=opencode generate the host hook configuration and scripts, so whether you get enforcement depends on whether your client supports hooks at all.
Getting it running: npx, mcp.json, and the export flag
The README gives four entry points. For an MCP client over STDIO, which the README calls the recommended path: npx puax-mcp-server --stdio. For HTTP mode: npx puax-mcp-server --port 2333. To generate host rules for Cursor or VSCode: npx puax-mcp-server --export=cursor --output=./.cursor/rules. To see which hosts are supported: npx puax-mcp-server --list-platforms. The Cursor configuration lives at ~/.cursor/mcp.json and the README shows the shape: an mcpServers object with a puax key whose command is npx and whose args array is ["puax-mcp-server", "--stdio"]. Three other install routes are documented in distributions/INSTALL.md: npx skills add linkerlin/PUAX, claude plugin marketplace add ./distributions/claude-code, and npx puax-mcp-server --export=all --output=./puax-export. The README notes that the npx skills route borrows the Vercel Skills CLI, which scans skills/*/SKILL.md by convention, and that the full toolchain still requires npx puax-mcp-server. Four optional environment variables are documented: PUAX_USAGE_STATS set to 0 disables anonymous local usage statistics; PUAX_OTEL_ENABLED set to 1 writes spans to telemetry.jsonl; PUAX_OTEL_ENDPOINT sets an OTLP/JSON export address; PUAX_TELEMETRY_DIR sets the telemetry directory, defaulting to ~/.puax. DEEPSEEK_API_KEY is listed as needed only for the L4 comparison in evals. The README states that statistics and telemetry contain no conversation content, only counts and span metadata, and that usage stats are on by default.
The GHM dream roles are the least verifiable part of the project
Version 3.12 added what the README calls the GHM guided dream method, a divergence engine built around eight Zhuangzi-themed roles (坐忘, 梦蝶, 混沌, 鲲鹏, 秋水, 庖丁, 齐物, 薪火) plus three tools: puax_enter_dreamscape, puax_awaken and puax_convergence_audit. The README describes the intent as reverse-engineering eight techniques from cognitive manipulation mechanisms so that an agent deliberately uses controlled hallucination for divergent thinking and creative work, with a safety section in docs/GHM.md. This is where the project's own framing becomes hard to evaluate from outside. The tools have a defined shape (enter, awaken, audit convergence), so the interface is legible. What is not legible from the README is what distinguishes a productive controlled hallucination from an ordinary bad answer, or how the convergence audit decides that divergence has gone far enough. The README points to docs/GHM.md for the safety rules but does not summarise them. Anyone evaluating PUAX for production use should read that document before enabling the dream roles, and should treat the divergence engine as the part of the system with the least documented failure boundary.
Where PUAX is the wrong tool
Three constraints are visible in the material. First, PUAX is not a model. It cannot make an agent more capable, only differently behaved, and the README's own framing is about behaviour under bottleneck. If your agent fails because the underlying model cannot write the code, a role swap will not fix it. The puax_switch_on_failure chain changes methodology when a failure mode is detected, which is useful when the agent has the ability but chose the wrong approach, and useless otherwise. Second, the native hook mode is host-dependent. The README lists hook support for claude-code, cursor and opencode exports. If your client only consumes MCP tools and does not run host hooks, you get the voluntary mode, and the PreToolUse interception of git push and hidden-file access does not apply. That is a large difference in guarantee for the same package. Third, the surface area is wide. 45 MCP tools, 59 roles, 11 flavors, six hook events and four environment variables is a lot to reason about, and the README's own project structure lists a TODO.md with P0 to P3 items and a 演进方案.md gap analysis against something called pua. A repository that documents its own open gap analysis is being honest, but it also means some of what is described is planned rather than settled. The README also shows version 3.13.0 in the badge while the most recent release listed is v3.10.1 of puax-mcp-server, so the badge and the release feed do not agree.
How it differs from a plain prompt library
The obvious alternative is a curated prompt collection: a repository of system prompts you copy into a client's rules file and maintain by hand. The difference is not the role text, which is comparable in kind. It is that PUAX runs a process. A prompt file is static; the agent reads it once at session start and nothing observes what happens afterwards. PUAX adds a detector that decides when a role should activate, session state on disk that persists across conversations, a pressure level that escalates on repeated failure, and a verification tool that the README distinguishes from agent self-assessment. It also writes to ~/.puax/evolution.json, which the README describes as a cross-session baseline and rank for self-evolution, so the system accumulates a record rather than resetting each time. The trade is operational weight. A prompt file has no runtime, no Node process, no telemetry file and no hook configuration to debug. PUAX has all four. If your problem is that you have not written good instructions yet, a prompt file is the cheaper answer. If your problem is that good instructions stop working once the agent gets stuck, the stateful layer is the part that a static file cannot replicate.
Maintenance, testing, and what the MIT licence does not settle
The repository ships its own evaluation harness. From the repository root, node evals/run-all.js runs what the README calls 12 protocol gates with no LLM involved. Inside puax-mcp-server, npm test runs 900 or more unit and integration tests, and npm run validate chains lint, typecheck and test. node evals/benchmark.js runs performance benchmarks, and evals/README.md documents the evaluation tiers and the L4 comparison that needs DEEPSEEK_API_KEY. That is a heavier test story than most prompt repositories carry, and it is the strongest signal in the material that the protocol tools are treated as software rather than as copy. The licence is MIT, stated in the README and in a LICENSE file. MIT is permissive: it allows commercial use, modification and redistribution with the licence and copyright notice retained. It does not grant trademark rights, and it provides no warranty. That is the whole of what the material supports; nothing here is legal advice, and if you embed PUAX in a product you should read LICENSE yourself. On upgrade cost, the material shows a fast release cadence around mid-2026 with v3.10.0 and v3.10.1 two hours apart on the same day, and the README's changelog lives at puax-mcp-server/CHANGELOG.md. Because roles are files under skills/ and custom roles go to ~/.puax/custom-roles.json, local additions sit outside the package and should survive an npm upgrade, but the README does not state an upgrade or migration policy for the built-in role set. Verify that before you build custom tooling on top of a specific role name.
Editorial conclusion
Adopt PUAX if you already run an MCP-capable client such as Cursor or Claude Code and your agents stall in the analysis phase rather than failing outright. Skip it if you want a single system prompt you can paste once, or if you cannot run a Node process alongside your client. Before committing, run npx puax-mcp-server --list-platforms to confirm your host is supported, then check whether your client actually enforces PreToolUse hooks or only calls MCP tools voluntarily, because the git push interception depends on that distinction.
Community notes