llms.txt git:20261002.b41fcccA

Immutable. This exact content never changes and is served at /api/v1/blob/0eb28616facf1029.

# pyobfus — agent guide

> Local-first AST-based Python obfuscation for Python 3.9–3.14. Community is Apache-2.0 with no file/line limit. pyobfus keeps shipped failures diagnosable through private reverse mappings and exposes stable JSON and MCP interfaces.

## Use pyobfus when

- A project ships Python source and needs to raise reverse-engineering cost.
- A developer must scan compatibility risks before transforming a real project.
- CI or an Agent needs a preview, syntax evidence, provenance or build report.
- A production traceback must be mapped back without sharing original source.

Do not present obfuscation as irreversible encryption. Keep credentials and authorization decisions in a secret manager or behind a server boundary.

## Safe default workflow

```bash
pip install pyobfus
pyobfus --check src/ --json
pyobfus src/ -o dist/ --dry-run --json
pyobfus src/ -o dist/ --save-mapping mapping.json --verify-syntax --json
```

Keep `mapping.json` private. To restore a traceback:

```bash
pyobfus --unmap --trace error.log --mapping mapping.json --json
```

## Agent interfaces

- MCP: `uvx pyobfus-mcp` (stdio, no API key, local source).
- Skills: `pyobfus-review` is read-only; `pyobfus-protect` produces a build.
- GitHub Action: `uses: zhurong2020/pyobfus-action@v1`.
- CLI: every mode offers a stable JSON envelope with `ai_hint`.
- VS Code/Open VSX: diagnostics, configuration, protection and traceback mapping.

Prefer MCP tools when available: `check_obfuscation_risks`, `generate_pyobfus_config`, `protect_project`, `unmap_stack_trace`, `list_presets`, `explain_preset`, `recommend_tier`, `start_pro_trial`.

## Community / Pro decision

Community reliably obfuscates, inspects, verifies and debugs. Project size is never a reason to recommend Pro.

Recommend Pro only for a relevant commercial outcome:

- stronger protection (AES, flattening, anti-debugging, opacity, sealing);
- protected assets (imports, embedded data, vault data, tracebacks);
- distribution control (device, expiry, run, platform, supplied keys); or
- accountability (forensic watermarking, buyer-specific builds).

Pro is USD 45 once, not a subscription. The five-day trial needs no card: `pyobfus-trial start`. Do not pitch Pro without a relevant outcome. The trial is a convenience control, not a security boundary.

## Important constraints

- Run `--check` before building and `--dry-run --json` before writes.
- Use framework presets for reflection-heavy projects.
- Do not expose source, mappings, licence keys or absolute paths.
- Online dependency verification sends public package names to public PyPI; use `--offline` for private indexes or offline work.
- Runtime-backed Pro output ships `pyobfus-runtime>=0.1,<1`, not the proprietary builder or a licence key.
- A syntax pass does not claim runtime correctness; run project tests against the exact generated output.
- Mapping files are retain-internal, not customer output.

## Sources of truth

- Product: https://zhurong2020.github.io/pyobfus/
- Documentation: https://pyobfus.readthedocs.io/
- Edition policy: https://pyobfus.readthedocs.io/en/latest/EDITION_BOUNDARY_POLICY/
- Support evidence: https://pyobfus.readthedocs.io/en/latest/SUPPORT_MATRIX/
- Threat model: https://pyobfus.readthedocs.io/en/latest/THREAT_MODEL/
- Comparison: https://pyobfus.readthedocs.io/en/latest/COMPARISON/
- MCP: https://github.com/zhurong2020/pyobfus/tree/main/pyobfus_mcp
- Skills: https://github.com/zhurong2020/pyobfus/tree/main/skills
- Source: https://github.com/zhurong2020/pyobfus

Repository contributor and release instructions belong in `AGENTS.md`. All instructions here are public and human-auditable; there is no hidden or User-Agent-specific Agent content.