PyBun (Python Bundle)

🐍 The Agent-Native Python Control Plane 🤖

Safe, structured, deterministic Python execution for AI coding agents —
powered by uv/pytest underneath, with JSON-first output and a built-in MCP server.

Video Demo • Quick Start • Why PyBun? • MCP Server • Commands • Benchmarks • Roadmap

Video Demo

Quick Start

macOS / Linux:

curl -LsSf https://raw.githubusercontent.com/VOID-TECHNOLOGY-INC/PyBun/main/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/VOID-TECHNOLOGY-INC/PyBun/main/scripts/install.ps1 | iex

Or via pip/pipx (PyPI):

pipx install pybun-cli
# or
pip install pybun-cli

Then run:

pybun add requests
pybun run -c "import requests; print('Hello, PyBun!')"

Why PyBun?

Existing Python tools are built for humans. PyBun is designed for AI agents — and humans who work alongside them.

PyBun is not a speed competitor to uv. Tools like uv and pip are excellent at dependency resolution and installation — PyBun doesn't try to out-run them, and where uv is available PyBun delegates to it directly. What those tools lack is an agent-facing control layer: structured output, MCP integration, sandboxed execution, and audit/provenance that AI systems can rely on without fragile text scraping or unverifiable side effects.

The value PyBun adds isn't "faster pip." It's removing the ambiguity, non-determinism, and risk an agent faces when it operates a Python environment on its own.

Design Philosophy

           AI Agent
              │  MCP / JSON
              ▼
        ┌───────────────┐
        │     PyBun      │   Policy · Sandbox · Schema
        │ Control Plane  │   Diagnostics · Audit · Provenance
        └───────┬────────┘
                │  delegates execution
      ┌─────────┼─────────┐
      ▼         ▼         ▼
     uv       pytest    Python

PyBun stays a thin, structured control layer on top of proven execution backends rather than re-implementing the Python packaging/import ecosystem from scratch. See docs/SPECS.md for the reasoning behind this scope decision.

✨ What PyBun adds that other tools don't

• 🤖 JSON-first output: Every command supports --format=json as a first-class citizen. LLMs can parse outputs reliably — no regex, no brittle string matching.
• 🔌 Built-in MCP Server: MCP (Model Context Protocol) lets AI tools like Cursor and Claude Desktop operate your Python environment directly via stdio — no extra glue code required.
• 📋 Structured diagnostics: Errors come with machine-readable code, level, and message fields. Agents can act on failures without guessing what went wrong.
• 🛡️ Sandbox Mode: Run untrusted AI-generated code safely with --sandbox. File and network access are restricted when the flag is set.
• 📦 Single binary: No runtime dependencies. Download and run anywhere.

💡 Example: AI Agent Workflow

# AI agent asks: "Install pandas and show the version"
$ pybun --format=json add pandas
{"status": "ok", "detail": {"added": ["pandas==2.2.0"], ...}}

$ pybun --format=json run -c "import pandas; print(pandas.__version__)"
{"status": "ok", "stdout": "2.2.0\n", ...}

The AI receives structured JSON — no parsing required, no ambiguity.

Status

• Current: M1 (Fast Installer), M2 (Runtime Optimization), M3 (Tester), and M4 (MCP/JSON) are stable or near-stable.
  • pybun install / pybun x (with uv backend) / pybun run / pybun test (default pytest/unittest wrapper backend) are Stable for the common case. The native wheel installer used by pybun install does not yet implement the full PEP 427 .data installation semantics (entry points/scripts/headers beyond the common paths) — see Issue #402. Packages relying on those payloads may need pybun x uv -- pip install ... as a fallback.
  • pybun test --backend=pybun (native executor, integrated per PR-A4) and pybun watch (native monitoring on macOS/Linux, polling fallback on standard builds) are Preview — the native test backend still surfaces W_TEST_BACKEND_COMPAT_* diagnostics for known pytest-plugin/fixture gaps.
  • The Rust Module Finder (pybun module-find) is Experimental / not wired into CPython's runtime import path (Issue #403). Treat it as an opportunistic optimization under ROI evaluation, not a core dependency.
  • Windows support is Preview.
• Platforms: macOS/Linux (arm64/amd64), Windows (preview)

PyBun's priority is the agent-facing control layer (JSON/MCP/diagnostics/sandbox/audit/drift), not re-implementing Python packaging/import internals. See docs/SPECS.md for feature maturity, phased rollout policy, and the current scope decisions.

Installation

The easiest way to install PyBun:

pip install pybun-cli

curl -LsSf https://raw.githubusercontent.com/VOID-TECHNOLOGY-INC/PyBun/main/scripts/install.sh | sh

irm https://raw.githubusercontent.com/VOID-TECHNOLOGY-INC/PyBun/main/scripts/install.ps1 | iex

cargo install --path .

Note: If your PATH resolves pybun to Bun, use pybun-cli instead.

Command Reference

Package Management

# Initialize a new project (pyproject.toml)
pybun init
pybun init --name my-project --python ">=3.11" --template package

# Install dependencies (generates lockfile)
pybun install --require requests==2.31.0 --index fixtures/index.json

# Add a package (updates pyproject.toml)
pybun add requests

# Remove a package
pybun remove requests

# Lock dependencies for a PEP 723 script
pybun lock --script script.py

# Check for outdated dependencies
pybun outdated

# Upgrade dependencies within constraints (or specific packages)
pybun upgrade
pybun upgrade requests
pybun upgrade --dry-run

Script Execution

# Run a Python script
pybun run script.py

# Run with arguments
pybun run script.py -- arg1 arg2

# Run inline code
pybun run -c "import sys; print(sys.version)"

# Run with profile
pybun run --profile=prod script.py

PEP 723 inline metadata is also supported:

# /// script
# requires-python = ">=3.11"
# dependencies = ["requests>=2.28"]
# ///
import requests

※ Metadata parsing, automatic dependency installation, and isolated-environment execution are all implemented and stable (cached per script/dependency/Python-version key; see docs/PLAN.md for details).

Ad-hoc Execution (pybun x)

Install a package in a temporary environment and execute it (Python version of npx). If uv is available, it is used for faster environment creation.

# Temporarily install and run cowsay
# (Use -t flag for Python cowsay package)
pybun x cowsay -- -t "Hello"

# Specify version
pybun x cowsay==6.1

# With arguments
pybun x black -- --check .

Python Version Management

# Show installed versions
pybun python list

# Show all available versions
pybun python list --all

# Install Python
pybun python install 3.12

# Remove Python
pybun python remove 3.12

# Show Python path
pybun python which
pybun python which 3.11

Runtime Optimization

These commands (Module Finder, Lazy Import, Watch) are opportunistic performance optimizations, evaluated independently for ROI — they are not required for PyBun's core agent-control-plane value (JSON/MCP/diagnostics/sandbox). Module Finder in particular is not yet connected to CPython's runtime import resolution (Issue #403).

Module Finder

Rust-based high-speed module search:

# Find a module
pybun module-find os.path

# Scan a directory for all modules
pybun module-find --scan -p ./src

# With benchmark
pybun module-find --benchmark os.path

Lazy Import

# Show configuration
pybun lazy-import --show-config

# Check module decision
pybun lazy-import --check numpy

# Generate Python code
pybun lazy-import --generate -o lazy_setup.py

# Specify allow/deny lists
pybun lazy-import --allow mymodule --deny debug_tools --generate

File Watch (Development Mode)

# Watch for file changes and re-run (currently preview)
# Native watching (macOS/Linux, `native-watch` feature) or a polling fallback
# (standard builds) is used automatically. --shell-command remains available
# for an external watcher.
pybun watch main.py

# Watch a specific directory
pybun watch main.py -p src

# Show configuration
pybun watch --show-config

# Generate shell command for external watcher
pybun watch --shell-command main.py

Dependency Drift

Detect undeclared imports and unused declared dependencies:

pybun drift
pybun drift --path ./src

Vulnerability Scanning

Scan installed packages against the OSV database (same scan logic as the MCP pybun_audit tool):

pybun audit

# Only report medium severity and above
pybun audit --severity-threshold=medium

# Exit non-zero when high/critical vulnerabilities are found (CI gating)
pybun audit --fail-on=high

Profile Management

# Show available profiles
pybun profile --list

# Show profile settings
pybun profile dev --show

# Compare profiles
pybun profile dev --compare prod

# Export profile
pybun profile prod -o prod-config.toml

Profiles:

• dev: Hot reload enabled, verbose logging
• prod: Lazy imports enabled, optimizations
• benchmark: Tracing and timing measurement

MCP Server

MCP server for AI agents:

# Start in stdio mode
pybun mcp serve --stdio

Tools: pybun_resolve, pybun_install, pybun_run, pybun_gc, pybun_doctor, pybun_lint, pybun_type_check, pybun_profile, pybun_fix
Resources: pybun://cache/info, pybun://env/info, pybun://audit/recent

※ Currently pybun_gc, pybun_doctor, pybun_run, pybun_resolve, pybun_lint, pybun_type_check, pybun_profile, pybun_fix, and resources are operational. pybun_install generates lockfiles via resolution. HTTP mode is not yet implemented.

pybun_run is sandboxed by default for MCP-originated calls. To preview code without executing it, pass dry_run: true; to disable the sandbox, pass unsafe_no_sandbox: true and treat the warning in the response as an approval checkpoint.

Build

# Build sdist/wheel artifacts (wraps `python -m build`)
pybun build

# Build and emit a CycloneDX SBOM alongside artifacts
pybun build --sbom

Diagnostics & Maintenance

# Environment diagnostics
pybun doctor
pybun doctor --verbose

# Compute a remediation plan for detected issues (preview)
pybun doctor --fix

# Apply safe, auto-applicable fixes from the remediation plan
pybun doctor --fix --apply

# Cache garbage collection
pybun gc
pybun gc --max-size 1G
pybun gc --dry-run

# Self-update check
pybun self update --dry-run
pybun self update --channel nightly

Sandbox usage

Use the sandbox for untrusted scripts or PEP 723 snippets:

pybun --format=json run --sandbox examples/hello.py
pybun --format=json run --sandbox --allow-network -c "print('net ok')"

The sandbox isolates file and network access; add --allow-network only when required. Combine with --profile=prod for production-like runs.

Profiles

Profiles tune defaults for performance vs. development ergonomics:

• dev (default): hot reload enabled, verbose logging.
• prod: lazy imports and optimizations enabled, quieter output.
• benchmark: stable timing/logging for reproducible benchmarks.

Examples:

pybun profile --list
pybun run --profile=prod app.py
pybun test --profile=benchmark --format=json

MCP server (stdio)

Operate PyBun as an MCP server for agents/IDEs:

pybun mcp serve --stdio
pybun --format=json mcp serve --stdio  # JSON envelope for tooling

Tools: pybun_resolve, pybun_install, pybun_run, pybun_gc, pybun_doctor, pybun_lint, pybun_type_check, pybun_profile, pybun_fix. Resources: pybun://cache/info, pybun://env/info, pybun://audit/recent.

MCP pybun_run applies the sandbox by default, including process/file-size limits and secret-like environment variable filtering. Use sandbox_policy to allow network/path/env exceptions, dry_run: true for a non-executing plan, or unsafe_no_sandbox: true only in controlled environments.

Configuration (Claude Desktop)

Add to your claude_desktop_config.json:

Option 1: Using uvx (No install required)

{
  "mcpServers": {
    "pybun": {
      "command": "uvx",
      "args": [
        "--from",
        "pybun-cli",
        "pybun",
        "mcp",
        "serve",
        "--stdio"
      ]
    }
  }
}

Option 2: Using pip install

Requires pip install pybun-cli.

{
  "mcpServers": {
    "pybun": {
      "command": "pybun",
      "args": [
        "mcp",
        "serve",
        "--stdio"
      ]
    }
  }
}

Note: If pybun is not in the PATH, provide the absolute path (e.g., /Users/username/bin/pybun).

JSON output examples

All commands support the --format=json option (schema v1). Examples:

pybun --format=json run -c "print('hello')"

{
  "version": "1",
  "command": "pybun run",
  "status": "ok",
  "detail": {
    "summary": "executed inline code"
  },
  "events": [],
  "diagnostics": []
}

Failure example:

pybun --format=json run missing.py

{
  "version": "1",
  "command": "pybun run",
  "status": "error",
  "diagnostics": [
    {
      "kind": "runtime",
      "message": "missing.py not found",
      "hint": "pass -c for inline code or a valid path"
    }
  ]
}

Tests/builds emit structured summaries (pass/fail counts, shard info) while keeping the same envelope:

pybun --format=json test --fail-fast
pybun --format=json build

Enable trace IDs for debugging:

PYBUN_TRACE=1 pybun --format=json run script.py

Print or validate the JSON schema itself:

pybun schema print
pybun schema check

Environment Variables

See CLAUDE.md's Environment Variables section for the full list, including testing/dry-run-only variables.

Release note automation

• Generate GA release notes from tags:
  python scripts/release/generate_release_notes.py --repo . --previous-tag v0.1.0 --tag v0.2.0 --notes-output release/RELEASE_NOTES.md --changelog CHANGELOG.md
• Attach the notes to the release manifest (served by installers/self-update via release_notes in JSON):
  python scripts/release/generate_manifest.py --assets-dir release --version 0.2.0 --channel stable --base-url https://github.com/VOID-TECHNOLOGY-INC/PyBun/releases/download/v0.2.0 --output pybun-release.json --release-notes release/RELEASE_NOTES.md
• CI-friendly JSON summary: python scripts/release/generate_release_notes.py --repo . --previous-tag v0.1.0 --tag v0.2.0 --format json

Upgrade guide

See docs/UPGRADE.md for pre-GA → GA migration notes, breaking changes, and the recommended CI checks (doc lint/link + release note automation).

Development

Requirements

• Rust stable (rustup, cargo)

Basic Commands

# Format
cargo fmt

# Lint
cargo clippy --all-targets --all-features -- -D warnings

# Test
cargo test

# Development scripts
./scripts/dev fmt
./scripts/dev lint
./scripts/dev test

Testing

# All tests
cargo test

# Specific tests
cargo test cli_smoke
cargo test json_schema
cargo test mcp

Benchmarks

PyBun is not a speed competitor to uv — it's an interface layer. PyBun uses uv as an optional execution backend for some operations (e.g. PEP 723 script runs). Where uv is available, PyBun delegates to it transparently — so warm-cache script execution is at parity with running uv directly.

The areas where PyBun intentionally differs from uv (JSON output, MCP, sandbox) are not speed-sensitive. For raw dependency resolution speed, uv's PubGrub solver is significantly faster than PyBun's current greedy resolver — this is a known roadmap item tracked in Issue #117.

Full numbers: docs/BENCHMARK_UV_COMPARISON.md

Roadmap

• M0: Repository & CI scaffold
• M1: Fast installer (lockfile, resolver, PEP 723)
• M2: Runtime optimization (module finder, lazy import, hot reload) — opportunistic, ROI under evaluation; see Issue #403
• M3: Test runner (discovery, parallel execution, snapshots)
• M4: JSON/MCP & diagnostics
• M5: Agent control plane hardening (extended doctor/drift, audit/provenance depth) — reprioritized over a full native wheel installer; see docs/SPECS.md §0.3
• M6: Release hardening (remote cache, workspaces, telemetry)

See docs/PLAN.md for details.

Privacy & Telemetry

PyBun does not collect telemetry by default (opt-in model).

# Check telemetry status
pybun telemetry status

# Enable telemetry
pybun telemetry enable

# Disable telemetry
pybun telemetry disable

Collected data (when enabled):

• Command usage (anonymized)
• Error diagnostics
• Performance metrics

Never collected: API keys, tokens, credentials, passwords, or file contents.

Environment override: PYBUN_TELEMETRY=0|1

License

MIT