execpad 0.1.0

Multi-language code execution against a real directory for AI agents

execpad

Execute bash, Python, JavaScript (Node), and SQL against a real project directory—with optional overlay, read-only mode, file-change tracking, and a session run log. Built for AI agents, CI, and local tooling.

Same design in TypeScript (npm) and Python (PyPI / local install).

---

Install

JavaScript / TypeScript (npm)

npm install execpad

Requires Node.js ≥ 18. For SQL on Node, the sqlite3 binary must be on your PATH.

Python

pip install execpad

From a clone (editable):

pip install -e ./python

Requires Python ≥ 3.10. For SQL in Python, the runtime uses stdlib sqlite3 (no sqlite3 CLI required).

---

Quick start

TypeScript

import { Runtime } from "execpad";

const rt = new Runtime("./my-project");
const r = await rt.run("python", 'print(open("README.md").read()[:80])');
console.log(r.stdout);
console.log(r.files); // file changes under the workspace
rt.close();

Python

from execpad import Runtime

rt = Runtime("./my-project")
r = rt.run("python", "print(1 + 1)")
print(r.stdout)
rt.close()

---

Features

Capability	Summary
Languages	bash, python, javascript, sql
Workspace modes	Normal, read-only (readonly: true), or overlay (temp copy + apply() back to disk)
File tracking	includeGlobs / excludeGlobs (minimatch) scope which paths appear in RunResult.files
Limits	timeoutMs, maxOutputBytes per run or via limits on the runtime
Session log	getRunLog(), clearRunLog(), exportRunLogJSON / exportRunLogMarkdown, optional onRun
OpenAI tools	asOpenAITool() + executeToolCall({ language, code }) (TS); as_openai_tool / execute_tool_call (Python)
Persistence	serialize() / Runtime.deserialize() for overlay state

---

Documentation

Doc	Contents
Getting started	Install, first runs, overlay, read-only
Configuration	RuntimeOptions, RunOptions, globs, limits, run log
API reference	Runtime, types, filesystem adapters, exports
Security	Threat model, workspace boundaries, subprocess behavior
Python notes	Node vs Python differences

---

License

Apache-2.0