oh-my-pi/packages/coding-agent/docs/python-repl.md

Python REPL (Jupyter Kernel Gateway)

Requirements

• Python 3 available on PATH (or via an active virtualenv)
• jupyter-kernel-gateway (kernel_gateway module) and ipykernel installed in the selected Python environment

Install:

python -m pip install jupyter_kernel_gateway ipykernel

How It Works

The Python tool uses a Jupyter Kernel Gateway and talks to it over REST and WebSocket APIs. By default it uses a shared local gateway so multiple pi instances reuse the same gateway process.

Shared-gateway startup flow:

1. Filter the environment and resolve the Python runtime (including venv detection)
2. Acquire the shared gateway (reuse a healthy gateway or spawn python -m kernel_gateway on 127.0.0.1:PORT)
3. Wait for gateway readiness (GET /api/kernelspecs)
4. Create a kernel (POST /api/kernels)
5. Connect WebSocket for execution messages
6. Initialize kernel environment, run prelude helpers, and load extension modules

External Gateway Support

Instead of spawning a local gateway, you can connect to an already-running Jupyter Kernel Gateway:

# Connect to external gateway
export PI_PYTHON_GATEWAY_URL="http://127.0.0.1:8888"

# Optional: auth token if gateway requires it (KG_AUTH_TOKEN)
export PI_PYTHON_GATEWAY_TOKEN="your-token-here"

When PI_PYTHON_GATEWAY_URL is set:

• No local gateway process is spawned
• Kernels are created on the external gateway
• The gateway process is not killed on shutdown
• Availability check uses /api/kernelspecs endpoint instead of local module check

This is useful for:

• Remote kernel execution
• Shared kernel environments
• Pre-configured gateway setups

Environment Propagation

• The kernel inherits a filtered environment (explicit allowlist + denylist)
• Allowlisted prefixes include LC_, XDG_, and PI_; known API-key vars are removed
• PYTHONPATH is passed through if present
• Virtual environments are detected via VIRTUAL_ENV, .venv/, or venv/ and preferred when present

Prelude Extensions

Optional .py modules are loaded after the prelude from:

• ~/.omp/agent/modules and ~/.pi/agent/modules
• <project>/.omp/modules and <project>/.pi/modules

Project modules override user modules with the same filename.

Kernel Modes

Settings under python control exposure and reuse:

• toolMode: both (default), ipy-only, bash-only
• kernelMode: session (default) or per-call
• sharedGateway: true (default). Setting to false throws an error because local (per-process) gateways are not supported; the shared gateway is required.

Mode behavior:

• session: reuse kernels per session id, serialize execution, evict after 5 minutes of idle time (max 4 sessions)
• per-call: create a fresh kernel per tool call and shut it down afterward

Environment override:

• PI_PY=0|bash → bash-only
• PI_PY=1|py → ipy-only
• PI_PY=mix|both → both

Shell Helper

The Python prelude exposes run() which executes a shell command via bash -c (or sh -c fallback) and returns a ShellResult with stdout, stderr, and code.

Output Handling

• Streams stdout/stderr as text
• application/x-omp-status emits structured status events for the TUI
• image/png display data renders inline in TUI
• application/json display data renders as a collapsible tree
• text/markdown is rendered as-is, text/plain is used as a fallback
• text/html display data is converted to basic markdown

Troubleshooting

• Kernel unavailable: Ensure python + jupyter-kernel-gateway + ipykernel are installed; the session will fall back to bash-only.
• Python mode override: Check python.toolMode or PI_PY if the Python tool is missing.
• Shared gateway disabled: python.sharedGateway=false causes the Python tool to error because local (per-process) gateways are not supported.
• Skip preflight checks: Set PI_PYTHON_SKIP_CHECK=1 to bypass kernel availability checks.
• External gateway unreachable: Check the URL is correct and the gateway is running. If auth is required, set PI_PYTHON_GATEWAY_TOKEN.
• IPC tracing: Set PI_PYTHON_IPC_TRACE=1 to log kernel message flow.
• Stdin requests: Interactive input is not supported; refactor code to avoid input() or provide data programmatically.