effect-pi

Use the Pi coding agent in an Effect application.

effect-pi wraps Pi's SDK so you can send prompts, follow responses as they arrive, and pick up saved conversations later. It handles session cleanup and makes sure prompts for the same session run one at a time.

Start with sessions running in your own process. If you later want to run them on separate workers, switch to Effect Cluster—the code that uses a session stays the same.

This is a small, experimental project for personal use. The API may change.

What using it looks like

Once you've set up a Sessions layer, your application code looks like this:

import * as Console from "effect/Console"
import * as Effect from "effect/Effect"
import * as Stream from "effect/Stream"

import { Session, Sessions } from "@jpowersdev/effect-pi"

export const program = Effect.gen(function* () {
  const sessions = yield* Sessions

  const id = Session.Id.make("my-project")

  const session = yield* sessions.open(id)

  yield* session.events.pipe(
    Stream.runForEach((event) => event._tag === "AssistantMessage"
      ? Effect.flatMap(event.content, (content) => Console.log(content))
      : Effect.void),
    Effect.forkScoped({ startImmediately: true })
  )

  const reply = yield* session.prompt("Explain how this project is organized")

  yield* Console.log(reply.text)
}).pipe(Effect.scoped)

Use the same id and storage to continue the conversation later. AssistantMessage events expose a finite stream of start/delta/end parts plus an awaitable content effect. A tool-using prompt can emit several assistant messages in sequence. You can also check progress with session.snapshot or stop the current prompt with session.abort.

Model and resource setup are Effect layers too: ResourceLoader feeds ModelRuntime, which sessions consume. Define and compose them at module scope; layerConfig reads configuration when they're built. The library handles Pi's asynchronous setup and errors—you don't need to write Promise adapters.

The complete local example shows how to provide these layers and storage around this code.

Try it

You'll need Node.js 26+, pnpm, and a model provider's credentials to send prompts.

pnpm install --frozen-lockfile
pnpm build

Follow the example setup to create the data directory and configure a model and credentials, then run:

pnpm example:pool "Say hello in one sentence"

The examples use SQLite to save conversations and explicitly configure Pi rather than loading your usual extensions and settings.

There are three ways to use the library:

• One session: single-session.ts sends a prompt and saves the conversation.
• A pool of sessions: local-session-pool.ts opens a session, releases it, and reopens it in another request. This is the best place to start.
• Cluster-backed sessions: cluster-session.ts starts a client and runner in one process, communicating over a local socket.

Each example is self-contained, including its configuration and storage setup.

For use in another project, see installation and compatibility. The package is named @jpowersdev/effect-pi and currently uses Effect 4.0.0 and Pi 0.86.1.

A few things to know

• This isn't a sandbox. Pi's tools and extensions run with your process's permissions. Even read-only tools can read outside the working directory, so use trusted workspaces and protect your credentials.
• Saved conversations can contain private data. Choose storage and access controls accordingly. The examples don't encrypt their database.
• Stopping work doesn't undo it. Cancellation waits for Pi and its tools to stop. A timeout or lost connection doesn't undo file changes or model charges, so don't blindly retry a prompt.

Pi still handles the agent loop and its conversation format. This library adds the Effect integration; it doesn't try to replace Pi or provide a hosted agent service.

The reference guide covers configuration, storage requirements, cancellation, and the limits of cluster execution.

Development

pnpm check
pnpm test
pnpm pack

Tests don't make paid model requests. pnpm pack runs a clean build, checks, and tests before producing the package. Nix/direnv is available but optional.

See CONTRIBUTING.md for development and release notes, and CHANGELOG.md for changes.

License

MIT, the same license used by Effect.