Choose an integration

Every integration has the same options and the same defaults. An integration only changes the format of the tools, so that your host can use them. This page helps you choose one, and lists what they all share.

Choose an integration

Pi has more than one library. createPiFsTools() only fits the coding agent, because its tools get Pi's ExtensionContext on each call. pi-agent-core and pi-durable have their own bundles.

The Node, just-bash, Cloudflare Shell, and Cloudflare Computer packages are backends, not integrations. Pass their filesystem as fs, and a runner as the bash runner, to any factory. See Filesystems.

One interface in three layers

The core tools take the canonical input and return a result. A definition binds a core tool to its signature: the name, description, and JSON Schema to declare, a validate for model input, and an execute that maps model input and runs the tool. Every integration is an adapter over the definitions. Tool definitions shows how to use them in a framework of your own.

Each integration has one factory for each tool and one bundle:

A bundle creates read, edit, and write over one filesystem. When you ask for them, it also creates apply_patch and bash. The tools share one digest, one lock manager, and one clock. When you set state, they also share one read store, so edit and write know what the model has read.

The core bundle runs anywhere. This example uses an in-memory filesystem:

import { memoryFileSystem } from "@better-fs-tools/fs";
import { memoryStore, textOf } from "@better-fs-tools/read";
import { createFsTools } from "@better-fs-tools/write";

const fs = memoryFileSystem({ files: { "/src/index.ts": "const a = 1;\n" } });
const tools = createFsTools({ fs, state: memoryStore(), applyPatch: true });

await tools.read({ path: "/src/index.ts" });
const result = await tools.edit({
  path: "/src/index.ts",
  edits: [{ oldText: "a = 1", newText: "a = 2" }],
});
console.log(textOf(result));
// Edited /src/index.ts: 1 replacement at line 1.

Defaults

Every core tool, bundle, and integration has these defaults:

sha256Digest() and nodeDigest() give the same digest, with the id sha256, so records made with one are valid for the other. nodeDigest() uses node:crypto and is faster. sha256Digest() runs in a Worker.

Rules for every bundle

• A shared key (fs, state, digest, locks, clock) inside one tool's options throws TypeError. Set it once at the top level. An unknown option key also throws.
• state is a store, a factory of the call, or null. A factory gives each call its own store.
• The bash tool gets the bundle's digest and clock, so ctx.digest and ctx.clock in a bash hook match the file tools.
• The allowed roots do not limit what a bash command touches.
• The bash tool does not update the read records. To make the model read a file again after a command, call invalidate(path) from an afterRun hook. See Bash policy.

Single-tool factories

A single-tool factory shares nothing with another one. Each write tool makes its own lock manager, and there is no read store unless you pass one. To use single tools with read before write, give each tool the same state, and the same locks to the write tools. Use a bundle when a host installs more than one tool.

Tool signatures

A signature is the shape of a tool that the model sees. The core tools take the canonical input. Every definition and integration has the same default signatures:

To give a model other names, pass a default signature with options as the tool's signature. Every default signature takes name, description, describe, and names. names renames a parameter, keyed by the signature's own parameter names. Three presets give another shape:

• multiEditSignature(): edit({ path, edits: [{ oldText, newText }] }), for many replacements in one call.
• lineRangeSignature(): read({ path, start?, end? }), with inclusive lines.
• freeformPatchSignature(): apply_patch({ patch }), plus the Codex patch grammar. The Pi, pi-agent-core, and pi-durable integrations send that grammar as constrainedSampling. The AI SDK sends only the JSON schema.

Tool definitions has the options and the default descriptions of each signature.

Host options

An integration adds options only for its host's display or registration. It changes no default.

piToolRenderers() from @better-fs-tools/pi is a renderer resolver, not an option. Pi draws a tool named read, edit, write, or bash with its built-in renderer, which reads Pi's argument names. The resolver maps the shared arguments to them. See Renderers.

Recommended configurations

Each host has choices that suit it. They are options, not defaults, so each one is visible in your code. Each integration page starts with its recommended configuration:

Filesystems

The defaults above say "the backend's" where the backend decides. The Filesystems page lists what each filesystem does: buffering, maxBufferedBytes, symlinks, identity, write support, and new file modes. It also explains why a buffered backend fetches the whole file before authorize runs.