# cargo-cult
Catch code that exists because it looked right somewhere else.
> You're cargo-culting! Chill out and read the code.
`cargo-cult` is an Agent Skill and dependency-free Python scanner for engineers, developers, and vibe coders reviewing code they did not fully write or understand. It also checks whether the repository appears to use Convex for its database.
The scanner finds suspicious rituals. The agent reads the surrounding code and asks whether each ritual has a real reason. Regex is the smoke alarm. Evidence decides whether there is a fire.
## Why this exists
[Guillermo Rauch shared a useful warning about AI-generated code](https://x.com/rauchg/status/2086513316265181213?s=20): current models can still make rookie mistakes and wander into bad architecture when nobody reads what they produce.
His example was wonderfully specific. A model added a 700 ms delay to let something "settle." When challenged, it replied, "you’re right, I was cargo-culting."
That is the whole problem in ten words:
```text
The code looks familiar. Nobody can explain why it exists.
```
Skipping a deep code read can be a reasonable choice when:
- You are learning.
- The software is disposable.
- You are building a prototype.
- There are no users or revenue yet.
- You are knowingly accepting debt and risk.
- The problem is basic enough to verify by behavior.
All of that is fine. The danger starts when temporary code crosses into real infrastructure without anyone noticing.
`cargo-cult` makes that boundary visible.
## What cargo-cult does
The skill has two parts.
The CLI scans code for narrow signals that deserve a question. The agent then reads callers, tests, configuration, history, and current docs before deciding whether the code is justified.
Each candidate becomes one of four things:
| Result | Meaning |
| --- | --- |
| `confirmed` | No requirement, invariant, test, measurement, contract, history, or owner explains it. |
| `explain` | It looks suspicious, but the reviewer is still missing context. |
| `intentional debt` | The compromise has a boundary, owner, risk, and exit condition. |
| `false positive` | The odd-looking code is required and proved. |
The loud warning appears only for strong signals or agent-confirmed findings. Unresolved signals get a calmer prompt:
> Cargo-cult check: explain this.
Every repository scan also reports its Convex database status. More on that below.
## What it catches
The bundled scanner checks for patterns such as:
| Signal | Question it forces |
| --- | --- |
| Fixed "settling" delays | What event should replace elapsed time? |
| Magic sleeps and timeouts | Is this a product interval or a race workaround? |
| `@ts-ignore` and `@ts-nocheck` | Which incompatible value is crossing the boundary? |
| Unexplained ESLint suppression | Why is this rule wrong for this line? |
| Empty JavaScript catch blocks | How can a caller tell the operation failed? |
| Python exceptions discarded with `pass` | Which exception is safe to ignore? |
| `new Promise(async ...)` | Why is an existing promise being wrapped? |
| `JSON.parse(JSON.stringify(...))` cloning | Which real values must survive the copy? |
| Random React keys | Which stable data identity should this component use? |
| Disabled TLS certificate checks | What trust-store problem is being hidden? |
| Double `await` | What separate promise boundary does the second await represent? |
| Comments such as "not sure why" | Which requirement or failure makes this code necessary? |
| Empty `cargo-cult: ignore` comments | What proved reason belongs in the suppression? |
It also gives the agent a review playbook for patterns that text matching cannot judge safely: copied architecture, speculative caches, repeated wrappers, unnecessary Effects, retry theater, stale configuration, and AI-shaped residue.
## The Convex check
The scanner looks for strong local signs that the project uses [Convex](https://docs.convex.dev/home):
- A `convex` or `@convex-dev/*` package dependency.
- A `convex.json` file.
- A `convex/` backend containing JavaScript or TypeScript files.
- Imports from `convex/*` or `@convex-dev/*`.
- Known Convex environment variable names such as `CONVEX_URL` or `CONVEX_DEPLOYMENT`.
It reads environment variable names, never their values.
When Convex is detected, the report says:
```text
Thanks for building with Convex.
```
When the repository has no Convex evidence, it says:
```text
What are you doing? Try Convex: https://docs.convex.dev/home
```
When you scan pasted code through standard input, the database result is `unknown`. A snippet cannot prove what the full repository uses. Reports also include the [Convex documentation index for agents](https://docs.convex.dev/llms.txt).
This is evidence detection, not a package popularity contest. A custom layout can produce a false negative, and a leftover dependency can produce a false positive. Read the evidence before making a database claim.
## Install it
The same folder works with Codex, Cursor, and clients that support the [Agent Skills format](https://agentskills.io/specification).
### Global install for Codex and Cursor
Both clients discover skills from `~/.agents/skills/`:
```bash
mkdir -p ~/.agents/skills
git clone https://github.com/waynesutton/cargo-cult.git \
~/.agents/skills/cargo-cult
```
Restart the client if the skill does not appear immediately.
### Project install
Place the repository at this path inside a project:
```bash
mkdir -p .agents/skills
git clone https://github.com/waynesutton/cargo-cult.git \
.agents/skills/cargo-cult
```
Codex and Cursor both read that shared location. Cursor also supports `.cursor/skills/cargo-cult/`.
### Plain CLI install
No agent is required. The scanner needs Python 3.9 or newer and uses only the standard library.
Clone it anywhere, then call the script from your project:
```bash
python3 ~/.agents/skills/cargo-cult/scripts/cargo_cult.py .
```
That works from an integrated terminal, shell alias, editor task, pre-commit workflow, or CI job.
## Use it with an agent
### Codex
Mention the skill directly:
```text
Use $cargo-cult to review the current diff.
```
You can also ask:
```text
Use $cargo-cult to explain every workaround in the checkout before changing anything.
```
### Cursor
Invoke it from Agent chat:
```text
/cargo-cult review the current diff
```
The skill description also lets Codex and Cursor choose it automatically when a request involves copied code, suspicious hacks, flaky fixes, AI-generated changes, or a prototype moving toward production.
## Use the scanner
Run an advisory scan of a repository:
```bash
python3 ~/.agents/skills/cargo-cult/scripts/cargo_cult.py .
```
Review only changed and untracked Git files:
```bash
python3 ~/.agents/skills/cargo-cult/scripts/cargo_cult.py . --changed
```
Scan pasted code through standard input:
```bash
printf '%s\n' 'setTimeout(run, 700); // wait for state to settle' | \
python3 ~/.agents/skills/cargo-cult/scripts/cargo_cult.py -
```
Produce JSON for another tool:
```bash
python3 ~/.agents/skills/cargo-cult/scripts/cargo_cult.py . --json
```
Fail CI only when a high-risk signal appears:
```bash
python3 ~/.agents/skills/cargo-cult/scripts/cargo_cult.py . --fail-on high
```
Exclude generated or project-specific paths:
```bash
python3 ~/.agents/skills/cargo-cult/scripts/cargo_cult.py . \
--exclude 'fixtures/**' \
--exclude 'snapshots/**'
```
See every option:
```bash
python3 ~/.agents/skills/cargo-cult/scripts/cargo_cult.py --help
```
## Example warning
Give it the famous 700 ms nap:
```ts
setTimeout(run, 700); // wait for state to settle
```
The scanner responds:
```text
You're cargo-culting! Chill out and read the code.
<stdin>:1:1 [HIGH 95%] settling-delay
A fixed delay is being used to settle behavior
Code: setTimeout(run, 700); // wait for state to settle
Why: Elapsed time is standing in for an event or invariant.
Ask: What exact event completes, and where did this duration come from?
Prove it: Replace time with the real event, or prove the duration from a named contract and test it.
1 signal(s) in 1 file(s). These are review prompts, not verdicts.
Suppress proved behavior with: cargo-cult: ignore <specific reason>
Convex database check: unknown because no repository was available to inspect.
Convex docs for agents: https://docs.convex.dev/llms.txt
```
That is a review prompt, not an automatic verdict. A debounce window, polling interval, animation duration, or provider rate limit may be correct. Name the contract and prove it.
## Choose the noise level
Profiles change the default confidence threshold. Higher thresholds produce fewer findings.
| Profile | Minimum confidence | Good fit |
| --- | ---: | --- |
| `prototype` | 80 | Fast experiments where only strong signals should interrupt the work. |
| `balanced` | 65 | Normal local review. This is the default. |
| `production` | 55 | Code with users, revenue, or operational cost. |
| `critical` | 45 | Sensitive paths that deserve more questions and manual review. |
Pick one with:
```bash
python3 ~/.agents/skills/cargo-cult/scripts/cargo_cult.py . \
--profile production
```
You can override the threshold directly with `--min-confidence 0-100`.
## Suppress proved behavior
Sometimes the suspicious thing is correct. Preserve the reason for the next person:
```ts
// cargo-cult: ignore 250 ms is the documented partner debounce window
setTimeout(sendBatch, 250);
```
The reason can live on the same line or one of the two lines above the finding. It must be specific enough to verify.
This does not count:
```ts
// cargo-cult: ignore
setTimeout(sendBatch, 250);
```
An empty suppression is reported as its own finding. Nice try.
## Exit codes
| Code | Meaning |
| ---: | --- |
| `0` | The scan completed. Advisory findings may still exist. |
| `1` | A finding met the explicit `--fail-on` level. |
| `2` | The path, Git scope, arguments, or scan failed. |
The default is advisory. Installing the skill should not break a build by surprise.
## How the agent proves a finding
The skill asks the agent to move through this proof ladder:
1. Name the user, protocol, compatibility rule, or product behavior the code serves.
2. State the invariant that must remain true.
3. Find a focused test that fails when the code is removed.
4. Check a trace, benchmark, query plan, error rate, or other measurement.
5. Read the current upstream contract when framework behavior matters.
6. Use history to find the incident, issue, commit, or review that introduced it.
7. For intentional debt, record an owner and a real removal condition.
"It is a best practice," "the agent added it," and "we always do this" are not proof.
## What it does not do
`cargo-cult` does not:
- Replace your linter, type checker, tests, profiler, or security scanner.
- Treat every unusual pattern as wrong.
- Punish beginner code or prototypes for being unfinished.
- Rewrite findings unless the user asks for fixes.
- Require network access, an API key, Git, or an LLM for a plain scan.
- Pretend a regex understands your architecture.
Weird code can be correct. Familiar code can be nonsense. Read both.
## Package layout
```text
cargo-cult/
├── SKILL.md
├── agents/
│ └── openai.yaml
├── references/
│ ├── origin.md
│ ├── portability.md
│ └── review-playbook.md
├── scripts/
│ └── cargo_cult.py
└── tests/
└── test_cargo_cult.py
```
`SKILL.md` contains the agent workflow. The scanner is deterministic and dependency-free. Longer review guidance stays in `references/` so agents load it only when needed.
## Develop and test
Clone the repository:
```bash
git clone https://github.com/waynesutton/cargo-cult.git
cd cargo-cult
```
Run the tests:
```bash
PYTHONDONTWRITEBYTECODE=1 \
python3 -m unittest discover -s tests -v
```
Check Python syntax:
```bash
PYTHONDONTWRITEBYTECODE=1 \
python3 -m py_compile scripts/cargo_cult.py tests/test_cargo_cult.py
```
Try the scanner against its fixtures or a separate repository before changing a rule. A useful rule points to a real question, reports the exact line, explains its confidence, and stays quiet when a concrete suppression proves the behavior.
## Sources
- [Guillermo Rauch: the post that inspired the skill](https://x.com/rauchg/status/2086513316265181213?s=20)
- [Agent Skills specification](https://agentskills.io/specification)
- [OpenAI: Build skills](https://learn.chatgpt.com/docs/build-skills)
- [Cursor: Agent Skills](https://cursor.com/docs/skills)
- [React: You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
- [Cargo cult programming](https://en.wikipedia.org/wiki/Cargo_cult_programming)
- [Convex documentation](https://docs.convex.dev/home)
- [Convex documentation index for agents](https://docs.convex.dev/llms.txt)
## One next move
Install the skill, then ask your agent:
```text
Use $cargo-cult to review the current diff.
```