One typed tool for Pi, instead of a toolbox.
Pit is an extension for the Pi coding agent. It replaces Pi's built-in coding tools with a single typescript tool, so the agent can read files, run commands, and act on the results in one call:
async ({ workspace: { read }, git: { status: gitStatus } }) => {
const [manifest, status] = await Promise.all([
read("package.json", { format: "raw" }),
gitStatus(["--short"]),
]);
const pkg = JSON.parse(manifest.content);
return {
package: pkg.name,
scripts: Object.keys(pkg.scripts ?? {}),
status: status.stdout,
};
}That call reads a file and checks Git status in parallel, then returns a three-field summary, not two raw outputs. The agent writes the TypeScript; you don't need to learn the API to use Pit.
- Fewer round trips. Related reads, commands, and edits, plus the logic between them, fit in one call. Independent work can run in parallel.
- Quieter context. Only what the call returns reaches the model, so intermediate output never fills the conversation.
- Sandboxed execution. Each call runs in a fresh QuickJS sandbox with no direct access to files, the network, or processes. It reaches the host only through the functions it requests, and results are bounded to keep the context and TUI compact.
- Earlier feedback. Calls are type-checked before they run, catching misspelled methods and bad arguments before anything happens.
- Reusable workflows. A useful call can become a saved function, ready to reuse in the session, share with a project, or carry across your projects.
Pit makes typescript the only coding tool the model sees by default. Extension and MCP tools remain available through it; if your setup needs them visible directly, you can allow selected tools alongside it.
Want to see what that looks like over time? I Wasn't Trying to Build an App follows a music-recommendation system growing through everyday Pit use.
Pit needs Node 22.19 or newer. It supports the Pi version it pins in package-lock.json, currently Pi 1.5.0; other Pi versions are not supported. Prebuilt runtimes are available for Linux, macOS, and Windows on ARM64 or x64.
Install the latest version:
pi install git:github.com/cv/pitThis tracks main, where changes land after CI passes. To update:
pi update git:github.com/cv/pitRun /reload after updating. Prefer a fixed release? Use pi install git:github.com/cv/pit@v0.33.0 instead; package updates won't move a pinned install.
For a one-session trial or a project-only install, see installation options. Pit is distributed from GitHub, not npm; releases and the changelog cover what's new.
Important
Pi extensions run with your user's permissions, so review the source before installing. Pit sandboxes the code the model writes, but the functions it exposes can still change files, run commands, and reach the network. Dependency injection is not an approval boundary. See the security model.
Start Pi and ask for work as usual: “Inspect this repository and summarize how to run its tests.” The agent writes the calls; you don't need to paste the example above or learn the API.
Calls appear as compact descriptions in the terminal. Press Ctrl+O to see the code, result, and execution details. The usage guide shows how to follow the work without wading through every intermediate output.
From there, try a workflow that fits your project:
- Work with more than text. Ask the agent to compare local screenshots or inspect a generated chart. Image viewing brings those files into the same workflow as code and commands.
- Keep your existing tools. Tools from other extensions and MCP servers can join the same calls, so the agent can combine their results with local work.
- Keep what works. Ask, “Save that test workflow so we can reuse it,” and the agent turns the call into a saved function.
- Manage and share functions. Use
/functionsto inspect saved functions, and promote proven ones to a trusted project or your user directory./pit-reflecthelps spot opportunities for reuse.
Start at the documentation index, or go directly to:
- Understand a call: how the agent combines operations, edits safely, and handles results.
- Make Pit fit your setup: installation options, tool visibility, and trusted project functions.
- Look up an API: available functions, parameters, and limits.
- Resolve a problem: installation and runtime diagnostics.
- Saved functions: reusable workflows and their lifecycle.
- Security model: the sandbox, injected capabilities, and trust boundaries.
- Contributing: local development and review requirements.
- Architecture and releasing: maintainer guides.
Use GitHub Issues for reproducible bugs and focused feature requests. Support is best effort for the tested Pi and Node.js versions above; other environments may work but are not guaranteed.
Do not report suspected vulnerabilities in public issues. Follow SECURITY.md instead. Contributions are welcome under CONTRIBUTING.md.