# tanweai/pua: an agent skill that refuses to let your coding agent give up

> pua is a skill plugin for Claude Code, Codex CLI and other coding agents that fires on repeated failure and pushes the agent into a structured debugging checklist. It is part methodology, part rhetoric, and the README states a productivity gain has not been established.

**tanweai/pua** — 你是一个曾经被寄予厚望的 P8 级工程师。Anthropic 当初给你定级的时候，对你的期望是很高的。  一个agent使用的高能动性的skill。  Your AI has been placed on a PIP. 30 days to show improvement.

- Repository: https://github.com/tanweai/pua
- Website: https://openpua.ai/
- Stars: 19,701 · Forks: 1,204
- Language: Python
- License: not declared
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/tanweai-pua

## The failure loop pua is built to interrupt

The README lists five patterns it wants to stop, and they are all variations of the same behaviour: the agent runs out of ideas but keeps producing output. Brute-force retry runs the same command three times and then declares the task unsolvable. Blame-shifting pushes the problem back to the user with phrases like "I suggest you handle this manually" or "probably an environment issue". Idle tools means the agent has WebSearch, Read and Bash available and uses none of them. Busywork is repeated parameter tweaking that produces no new information. Passive waiting is fixing the visible symptom and stopping without verification.

The intended user is someone who already pays for a coding agent and has watched it circle. The README's worked example is an MCP server that failed to load: the agent kept changing the protocol format and guessing version numbers until the user typed /pua manually. That manual trigger is the honest part of the story. The skill did not notice the loop on its own in that case; the user did.

## How the trigger and the 7-point checklist actually fit together

pua is a skill package, not a separate program. The repository ships per-client directories: .claude-plugin/, .codex/, .trae/, codebuddy/, cursor/, kiro/, pi/, vscode/, plus a chatgpt/ folder and a compat/ folder for portable packages. Each client gets the skill in the format it expects, which is why the repository tree is wider than the Python label suggests.

The mechanism has two halves. The first half is a trigger table. The skill activates when a task has failed two or more times consecutively, when the agent is about to say it cannot solve something, when it blames the environment without verifying, or when the user types frustration phrases in any of several languages. The README is explicit about what does not trigger it: a first-attempt failure, or a known fix that is already running.

The second half is the response. On a level-3 trigger the agent is supposed to execute a 7-point checklist rather than try again. In the MCP example the checklist pushed the agent to read error messages word by word, find Claude Code's own MCP log directory, and discover that registration through claude mcp behaves differently from editing .claude.json by hand. The checklist is the part that produced the fix; the rhetoric is what made the agent start the checklist instead of apologising. That ordering matters when you evaluate the project, because the checklist is the reusable asset and the tone is the delivery mechanism.

## Installing pua for Claude Code or Codex CLI

The README does not print a single install command. It points to docs/MODEL-COMPAT-20260909.md for usage and to the landing page at openpua.ai for a beginner guide, and the repository carries a plugin.json plus per-client plugin directories. Treat the plugin directory as the install surface rather than a package manager.

For Claude Code, the repository keeps .claude-plugin/ at the top level, and plugin.json sits beside it. A plugin manifest in that directory is what a Claude Code plugin install reads, so the practical first step is to point your client at this repository. The README does not spell out the exact syntax, so confirm it against docs/MODEL-COMPAT-20260909.md before relying on it.

For Codex CLI the equivalent lives under .codex/, and the README's compatibility note says portable Claude Code, Codex and ChatGPT skill packages were added in 3.5.1.

Once installed, the first real use is a manual trigger. Reproduce a failure your agent has already hit twice, then type the slash command the README uses in its case study:

```text
/pua
```

The README's case study shows exactly this: the user typed /pua after the agent had spun on the MCP registration problem, the skill escalated to L3, and the 7-point checklist ran. What you should see is the agent stop proposing variations on the same fix and start reading logs. If it keeps guessing, the trigger did not fire for your client and you are looking at a packaging problem, not a methodology problem.

## The productivity claim is not backed by the project's own numbers

The README opens with "Double your Codex / Claude Code productivity and output" and then, in the same block, states that not all models passed and that a productivity increase has not been established by the evaluation. Those two sentences sit next to each other in the 3.5.1 compatibility note. Take the second one seriously.

This is the limitation that matters most. The project ships docs/MODEL-MATRIX-20260909.md for model results and known limits, and docs/TESTING.md for build and offline tests. If your client is not in the passing set, the skill may install cleanly and never trigger, or trigger and produce the checklist without the behaviour change. The repository does not document rollback, so an install that changes your agent's tone in ways you dislike has no described undo path beyond removing the plugin directory yourself.

There is a second, quieter cost. The skill deliberately injects pressure language. On a codebase where a junior engineer reads the agent transcript, or in a client-facing session, that tone is a product decision, not a neutral default. The README treats the rhetoric as the feature. You may not.

## Where pua sits next to plain prompting and agent frameworks

The obvious alternative is doing nothing and writing better prompts: telling the agent up front to read logs before retrying, or adding a line to your project instructions that says "if you fail twice, stop and enumerate what you have not checked". That costs nothing and works with any client. The difference is enforcement. A prompt is a suggestion the model can drift away from after a long context; pua is a skill with an explicit trigger table and a level system, so the escalation is a state the agent enters rather than a preference it may forget.

A second comparison is a general agent framework with retry and reflection loops built into the runtime. Those operate below the model, at the orchestration layer, and they apply to every task whether or not the task is stuck. pua operates inside the conversation, only on the failure patterns its README enumerates, and it ships as per-client plugin directories rather than as a runtime you adopt. If you want retries handled by infrastructure, a framework is the cleaner fit. If you want the model itself to change what it does on the third failure, pua is aimed at that gap.

## Maintenance, licence and upgrade cost

The last push was on 2026-09-09, which is eight days before this writing, and the repository is not archived. Release cadence is visible: v3.4.6 on 2026-05-13, v3.5.0 on 2026-06-12, v3.5.1 on 2026-09-09. The 3.5.0 entry mentions blockquote rendering and source annotation, which tells you the project is still adjusting how the skill presents itself to the model, not only adding capability. Budget for reading CHANGELOG.md at each upgrade, because a change to the tone or the trigger table can change how your agent behaves on unrelated tasks.

Licensing is muddier than it looks. The README badge says MIT, and the repository metadata does not state a licence. The badge is the only signal available, so verify the actual licence file before you vendor the skill into a commercial product. Nothing in the repository addresses redistribution or the per-client plugin directories specifically, and this is not legal advice.

The upgrade cost is mostly re-verification. Each release can change which clients are covered and which models passed, so a version bump means re-reading the model matrix for your client rather than assuming the previous result carries over.

## Conclusion

Adopt pua if you already run a coding agent that spins on the same failing command and you want a trigger that interrupts that loop with a checklist. Do not adopt it if you need measured productivity numbers: the README states a productivity increase has not been established, and the compatibility note records that not all models passed. Before installing, read docs/MODEL-MATRIX-20260909.md and docs/TESTING.md for your own agent, and check that the repository carries a plugin directory for the client you use, since it keeps separate ones for Claude Code, Codex, Cursor, Kiro, CodeBuddy, Trae and VSCode.

## FAQ

### What is the pua skill for Claude Code?

It is a skill plugin that activates when a coding agent fails repeatedly or starts blaming the environment, and pushes it into a 7-point debugging checklist instead of another retry. The README describes three parts: rhetoric that makes the agent afraid to give up, a debugging methodology, and proactivity enforcement.

### How do I install pua for Claude Code or Codex CLI?

The README does not print install commands; it points to docs/MODEL-COMPAT-20260909.md for usage and openpua.ai/guide.html for a beginner guide. The repository ships per-client plugin directories such as .claude-plugin/ and .codex/, and version 3.5.1 added portable Claude Code, Codex and ChatGPT skill packages.

### Does the pua skill actually double productivity?

The README's own 3.5.1 compatibility note says not all models passed and that a productivity increase has not been established by the evaluation. The headline claim and that disclaimer appear in the same block, so treat the number as unverified.

## Sources

- [Issues](https://github.com/tanweai/pua/issues)
- [Project website](https://openpua.ai/)
- [README](https://github.com/tanweai/pua/blob/main/README.md)
- [Releases](https://github.com/tanweai/pua/releases)
- [tanweai/pua on GitHub](https://github.com/tanweai/pua)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tanweai-pua