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
Metadata
Release files for agentpad 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentpad-0.1.0.tar.gz | 6.7 kB | Without provenance | Details for agentpad-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentpad-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agentpad-0.1.0-py3-none-any.whl |
Total release size: 15.1 kB
Release files / agentpad-0.1.0.tar.gz
| Download URL | agentpad-0.1.0.tar.gz |
|---|---|
| Size | 6.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
16663544411c3046a8e54bac2e4121e57e9fa4780641377e4be926b241217f83
|
|
BLAKE2b-256 checksum How to use checksums |
25f2c23b54e9135addb3299b730b7eafffe5700cbebbd0839bb76532425d2f07
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Hatch/1.16.5 cpython/3.14.3 HTTPX/0.28.1
|
Release files / agentpad-0.1.0-py3-none-any.whl
| Download URL | agentpad-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d6fa720d48cfc1b11ea2b3e589b69d44e4fdeed5e01ee2c1b46fc2daca7b027c
|
|
BLAKE2b-256 checksum How to use checksums |
64f2957b155c48b71f4d19bf039c59361c164101c0c49a7f2874534d84e0d472
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Hatch/1.16.5 cpython/3.14.3 HTTPX/0.28.1
|
Security for agentpad 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.