agentpad 0.1.0

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

agentpad

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 agentpad

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

Python

pip install agentpad

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 "agentpad";

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 agentpad 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

Hosted on slaps.dev:

Doc	Contents
Overview	Product summary and doc index
Getting started	Install, first runs, overlay, read-only
Use cases	Agents, testing patterns, stubfetch
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

---

Source

Package and issue tracker: github.com/vgulerianb/agentpad (canonical repo). The slaps.dev monorepo may carry a vendored copy of this tree for the website and doc sync scripts—it is not the package’s primary repository URL on npm/PyPI.

License

Apache-2.0