python-executor (pyx)

pyx is a local, cross-platform executor for LLM/Agent workflows. It is built for evidence-based debugging and repeatable prompting: run work via MANIFEST_IO (files + manifest), keep an inspect log, and turn incident work into reusable skills.

Start with these prompt-first use cases:

• Incident debugging with data-layer access
• Project skills vs global skills (template without project leakage)
• Migration baseline for a rewrite (Python → Rust, SQLite → Postgres)

This repo is designed around three repeatable outputs:

• Skills: reusable, file-based rules + references (bootstrap for new sessions)
• MANIFEST_IO runs: scripts + input JSON + manifest + log + outputs
• Investigation logs: reproducible code verification and audits

Start Here (Public Repo Workflow)

1) Generate the pyx Claude skill (interactive)

Run:

pyx gs

Behavior:

• Asks public vs local privacy mode (default: public)
• Generates the pyx skill and prints it to the terminal
• Asks whether to save
• If saving, asks whether to overwrite existing output
• Finally asks where to save:
  • docs\pyx (default)
  • %USERPROFILE%\.claude\skills\pyx
  • custom path

2) Use MANIFEST_IO for all real work

MANIFEST_IO is the file-first execution contract:

• Inputs come from files (JSON for structured input)
• Outputs are files, indexed by a manifest
• Stdout is only a short summary (paths + sizes)
• Always check output size before loading into an LLM context

Reference: docs/manifest/references/manifest-io.md

Core Workflows

Generate skills

Generate skill packages (Claude-style: SKILL.md + references/):

# Public-safe (recommended for committing)
pyx gs --skill all --privacy public -o skills

# Local (machine-specific; may include absolute paths/package inventory)
pyx gs --skill all --privacy local -o skills

Notes:

• --skill manifest generates the standalone MANIFEST_IO spec.
• --skill learn generates skill-extraction workflow + summary reference.
• --skill pyx focuses on execution, and depends (softly) on manifest + learn.
• --skill inspect focuses on investigation logs + code verification, and depends (softly) on manifest + learn.
• --skill summary generates leader-summary templates.
• --skill all generates: manifest + learn + pyx + inspect + summary.

Session bootstrap (what the LLM should do first)

LLM chat history is unreliable. Treat the repo as the source of truth.

Minimal bootstrap sequence:

1. Read the skills/pyx/ files listed above
2. Run pyx info --json if environment/tooling matters
3. Execute tasks via pyx run --file using MANIFEST_IO

MANIFEST_IO (file-first execution)

Recommended pattern:

pyx ensure-temp --dir "temp"
# Write: temp/<task>.py
# Write: temp/<task>.input.json
pyx run --file "temp/<task>.py" --input-path "temp/<task>.input.json"

The executed script can read these runtime variables (auto-set by pyx run):

• PYX_INPUT_PATH (optional)
• PYX_OUTPUT_DIR (always)
• PYX_OUTPUT_PATH (always; manifest path)
• PYX_LOG_PATH (always)
• PYX_RUN_ID (always)

Code verification + investigation logs

For “verify against actual code” tasks, use the inspect workflow:

• Create a dedicated log: temp/<topic>.<run_id>.inspect.md
• Collect evidence via MANIFEST_IO scripts
• Record manifest/log/output file paths in the log

References:

• docs/inspect/references/code-verification.md
• docs/inspect/references/investigation-log-template.md

Learn skill (extract reusable workflows)

Use the phrase “learn skill” to trigger a token-efficient workflow that:

1. Reads temp/.history.jsonl and recent manifests/logs
2. Summarizes headers only
3. Proposes create / merge / overwrite
4. Generates a SKILL preview
5. Saves only after explicit user confirmation

Reference: docs/learn/references/learn-skill.md

Installation (Local Development)

git clone https://github.com/Anudorannador/python-executor.git
cd python-executor
uv tool install -e ".[full]"

Configure .env:

• Windows: %APPDATA%\pyx\.env
• Unix/macOS: ~/.config/pyx/.env

Start from: .env.example.

Verify:

pyx info

Configuration (.env)

Common PYX_* configuration variables:

• PYX_UV_HTTP_PROXY, PYX_UV_HTTPS_PROXY, PYX_UV_NO_PROXY, PYX_UV_INDEX_URL (uv/pip proxy/index) See: .env.example

Project structure

docs/ contains public reference docs and example outputs. skills/ is the recommended committed bootstrap for LLM sessions.

python-executor/
├── .env.example
├── docs/
│   ├── pyx.instructions.md
│   ├── pyx/
│   ├── inspect/
│   ├── manifest/
│   ├── learn/
│   └── summary/
├── skills/                    # Recommended committed bootstrap
│   ├── manifest/
│   ├── learn/
│   ├── pyx/
│   ├── inspect/
│   └── summary/
└── src/
    ├── pyx_core/
  └── pyx_cli/