# pyobfus — agent guide

> Local-first AST-based Python obfuscation for Python 3.9–3.15. 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 multi-file project or package must be obfuscated as a whole, with names renamed consistently across modules and imports rewritten to match.
- 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
pyobfus --check-delivery dist/ --json   # since 0.7.1: check for mappings, keys or originals in dist/
# since 0.7.1: --verify-names checks newly unbound globals without execution
# success JSON includes name_verification; review skipped modules when coverage_complete is false
```

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`, `check_delivery`, `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.
- Community `--check` flags common hardcoded-secret shapes and sensitive literal contexts without showing values; medium/info advisories keep exit codes unchanged. This is coarse screening: use gitleaks or detect-secrets, move secrets to runtime environment/secret-manager reads, and rotate any previously shipped or committed credentials. Obfuscation does not hide string values.
- 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.
- pyobfus has no telemetry and never uploads source or mappings. The only network requests are the `--check` PyPI lookup, `pyobfus-trial start --email` and Pro licence verification: https://pyobfus.readthedocs.io/en/latest/NETWORK_BEHAVIOR/
- pyobfus is for protecting software you own or are licensed to ship. It is unrelated to `pyobfuscate`, `pyobfuscator` and `python-obfuscator`.
- 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/
- Network behavior: https://pyobfus.readthedocs.io/en/latest/NETWORK_BEHAVIOR/
- 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.