# Package exports

> Public npm surface for @earendil-works/pi-coding-agent: main, rpc-entry, client exports, bin name, and piConfig.configDir.

- Repository: earendil-works/pi
- GitHub: https://github.com/earendil-works/pi
- Human docs: https://grok-wiki.com/public/docs/earendil-works-pi-7860a70e44d1
- Complete Markdown: https://grok-wiki.com/public/docs/earendil-works-pi-7860a70e44d1/llms-full.txt

## Source Files

- `packages/coding-agent/package.json`
- `packages/coding-agent/README.md`
- `packages/coding-agent/examples/sdk/README.md`
- `packages/coding-agent/CHANGELOG.md`

---

---
title: "Package exports"
description: "Public npm surface for @earendil-works/pi-coding-agent: main, rpc-entry, client exports, bin name, and piConfig.configDir."
---

`@earendil-works/pi-coding-agent` is an ESM package (`"type": "module"`) that publishes one CLI binary and three import surfaces: the package root (SDK), `./rpc-entry` (process integration), and `./client` (experimental remote-session controller). Package metadata also declares `piConfig.configDir` as `.pi`, which aligns with the default agent config path used by the SDK.

## Package identity

| Field | Value |
|-------|--------|
| Name | `@earendil-works/pi-coding-agent` |
| Version (documented snapshot) | `0.84.1` |
| Description | Coding agent CLI with read, bash, edit, write tools and session management |
| Module type | `module` (ESM) |
| License | MIT |
| Node engines | `>=22.19.0` |
| Repository | `git+https://github.com/earendil-works/pi.git` (`packages/coding-agent`) |

Install (global CLI):

```bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
```

`--ignore-scripts` disables dependency lifecycle scripts. Pi does not require install scripts for normal npm installs. An installer alternative is `curl -fsSL https://pi.dev/install.sh | sh`.

## Export map

The public `exports` map is the supported import surface. Consumers should use these subpaths, not deep paths under `dist/`.

| Export subpath | Import specifier | Types | Runtime entry |
|----------------|------------------|-------|---------------|
| `.` (main) | `@earendil-works/pi-coding-agent` | `./dist/index.d.ts` | `./dist/index.js` |
| `./rpc-entry` | `@earendil-works/pi-coding-agent/rpc-entry` | *(not declared in package.json)* | `./dist/rpc-entry.js` |
| `./client` | `@earendil-works/pi-coding-agent/client` | `./dist/client/index.d.ts` | `./dist/client/index.js` |

Top-level `main` and `types` point at the same root as `exports["."]`:

- `main`: `./dist/index.js`
- `types`: `./dist/index.d.ts`

<Note>
`./rpc-entry` declares only an `import` condition. Root and `./client` declare both `types` and `import`. All three use ESM import conditions only—no `require` condition is published.
</Note>

## Binary entry

| Field | Value |
|-------|--------|
| Bin name | `pi` |
| Target | `dist/cli.js` |

The build script marks both CLI and RPC entry scripts executable:

```text
chmod +x dist/cli.js dist/rpc-entry.js
```

After a global install, the `pi` command starts the interactive agent. Authentication is typically an API key environment variable or interactive `/login`.

```bash
export ANTHROPIC_API_KEY=sk-ant-...
pi
```

Pi runs in four modes: interactive, print or JSON, RPC for process integration, and SDK embedding. Binary flags and auth subcommands are covered on the CLI and run-modes pages.

## Main export (SDK)

Import the package root to embed pi in application code:

```ts
import {
  createAgentSession,
  DefaultResourceLoader,
  ModelRuntime,
  SessionManager,
  SettingsManager,
} from "@earendil-works/pi-coding-agent";
```

SDK examples also document `createAgentSessionRuntime()` for runtime-backed session replacement when the active session cwd changes.

### Documented constructors and helpers

| Symbol | Role |
|--------|------|
| `createAgentSession(options)` | Construct an agent session |
| `createAgentSessionRuntime()` | Manage runtime-backed session replacement |
| `ModelRuntime.create(...)` | Canonical model and authentication runtime |
| `DefaultResourceLoader` | Load extensions, skills, prompts, themes, context files |
| `SessionManager.create(cwd)` / `SessionManager.inMemory()` | Session persistence or in-memory sessions |
| `SettingsManager.create(cwd, agentDir)` / `SettingsManager.inMemory()` | Settings load and overrides |

### `createAgentSession` options (from SDK examples)

| Option | Default | Description |
|--------|---------|-------------|
| `modelRuntime` | Runtime using `agentDir/auth.json` and `models.json` | Canonical model and authentication runtime |
| `cwd` | `process.cwd()` | Working directory |
| `agentDir` | `~/.pi/agent` | Config directory |
| `model` | From settings / first available | Model to use |
| `thinkingLevel` | From settings / `"off"` | `off`, `low`, `medium`, `high` |
| `tools` | `["read", "bash", "edit", "write"]` built-ins | Allowlist across built-in, extension, and custom tools |
| `customTools` | `[]` | Additional tool definitions |
| `resourceLoader` | `DefaultResourceLoader` | Resources for extensions, skills, prompts, themes, context files |
| `sessionManager` | `SessionManager.create(cwd)` | Persistence |
| `settingsManager` | `SettingsManager.create(cwd, agentDir)` | Settings overrides |

### Minimal embed

```ts
import { createAgentSession, ModelRuntime } from "@earendil-works/pi-coding-agent";

const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({ modelRuntime });

session.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await session.prompt("Hello");
```

### Full-control embed

```ts
import {
  createAgentSession,
  DefaultResourceLoader,
  ModelRuntime,
  SessionManager,
  SettingsManager,
} from "@earendil-works/pi-coding-agent";
import { getModel } from "@earendil-works/pi-ai";

const model = getModel("anthropic", "claude-opus-4-5");
const customRuntime = await ModelRuntime.create({
  authPath: "/my/app/auth.json",
  modelsPath: "/my/app/models.json",
});
await customRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY!);

const resourceLoader = new DefaultResourceLoader({
  systemPromptOverride: () => "You are helpful.",
  extensionFactories: [myExtension],
  skillsOverride: () => ({ skills: [], diagnostics: [] }),
  agentsFilesOverride: () => ({ agentsFiles: [] }),
  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
});
await resourceLoader.reload();

const { session } = await createAgentSession({
  model,
  modelRuntime: customRuntime,
  resourceLoader,
  tools: ["read", "bash", "my_tool"],
  customTools: [myTool],
  sessionManager: SessionManager.inMemory(),
  settingsManager: SettingsManager.inMemory(),
});
```

Run packaged examples from the package tree:

```bash
cd packages/coding-agent
npx tsx examples/sdk/01-minimal.ts
```

## `rpc-entry` export

| Item | Value |
|------|--------|
| Specifier | `@earendil-works/pi-coding-agent/rpc-entry` |
| File | `./dist/rpc-entry.js` |
| Conditions | `import` only |
| Build | Made executable alongside `dist/cli.js` |

Use this subpath for RPC process integration (JSON stream, command protocol). Command IDs, compaction constraints, and stream event shapes belong on the RPC mode page.

<Info>
Changelog 0.84.0 notes that JSON and RPC `message_update` events emit only `assistantMessageEvent` deltas. Clients assemble partial messages between `message_start` and `message_end`; `message_end` remains authoritative.
</Info>

## `client` export

| Item | Value |
|------|--------|
| Specifier | `@earendil-works/pi-coding-agent/client` |
| Types | `./dist/client/index.d.ts` |
| Runtime | `./dist/client/index.js` |

Added as experimental remote-session client APIs in 0.84.0. The documented controller is `RemoteSession`, with transcript reducers, alongside transport-neutral `PiClient`, a CBOR protocol, and Unix-socket transport.

Session list metadata uses durable `SessionMetadata`. `RemoteSession.sessions` does not expose runtime phase, model, thinking, attachment, or lock state; those remain available from acquired `SessionSnapshot` values.

Related runtime packages (same major line as this package snapshot):

| Dependency | Role in stack |
|------------|----------------|
| `@earendil-works/pi-client` | Client transport stack |
| `@earendil-works/pi-protocol` | Remote protocol |
| `@earendil-works/pi-agent-core` | Agent/session core |
| `@earendil-works/pi-ai` | Models and providers (for example `getModel`) |
| `@earendil-works/pi-tui` | Terminal UI |

## `piConfig.configDir`

```json
"piConfig": {
  "configDir": ".pi"
}
```

`configDir` is the package-declared Pi config directory name (`.pi`). SDK defaults place agent config under `~/.pi/agent` (`agentDir`), including paths such as:

| Path | Typical use |
|------|-------------|
| `~/.pi/agent` | Default `agentDir` |
| `agentDir/auth.json` | Auth credentials for `ModelRuntime` |
| `agentDir/models.json` (or `~/.pi/agent/models.json`) | Custom providers and models |
| `~/.pi/agent/keybindings.json` | Keybinding customization |
| `~/.pi/agent/sessions/` | Auto-saved JSONL sessions |

`ModelRuntime.create({ authPath, modelsPath })` can override credential and model catalog locations for embedded apps.

## Published package contents

`files` lists what is included on npm:

```text
dist/
docs/
examples/
containerization.md
CHANGELOG.md
npm-shrinkwrap.json
```

Build and publish scripts of note:

| Script | Behavior |
|--------|----------|
| `build` | Compile TypeScript, `chmod +x` on `dist/cli.js` and `dist/rpc-entry.js`, copy interactive theme/assets and export-html assets into `dist/` |
| `build:binary` | Build workspace deps, compile a Bun standalone binary to `dist/pi` with `--no-compile-autoload-bunfig`, copy binary assets |
| `prepublishOnly` | `clean` → `build` → `shrinkwrap` |

Standalone binary build notes: Bun compilation uses `--no-compile-autoload-bunfig` so binaries do not crash when the cwd contains a `bunfig.toml` with `preload`.

## Runtime requirements

| Requirement | Constraint |
|-------------|------------|
| Node.js | `>=22.19.0` |
| Module format | ESM only (`import`) |
| Optional dependency | `@mariozechner/clipboard` (clipboard support) |

Peer-style internal packages resolve at `^0.84.1` for this package version.

## Import quick reference

<Tabs>
  <Tab title="CLI">
```bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi
```
  </Tab>
  <Tab title="SDK (main)">
```ts
import {
  createAgentSession,
  ModelRuntime,
} from "@earendil-works/pi-coding-agent";
```
  </Tab>
  <Tab title="RPC entry">
```ts
import "@earendil-works/pi-coding-agent/rpc-entry";
// Or resolve the package export as a process entry for RPC integration
```
  </Tab>
  <Tab title="Client">
```ts
import /* RemoteSession controller */ from "@earendil-works/pi-coding-agent/client";
```
  </Tab>
</Tabs>

## Verification

<Steps>
  <Step title="Confirm package install">
    Install `@earendil-works/pi-coding-agent` and ensure Node is `>=22.19.0`.
  </Step>
  <Step title="Verify the binary">
    Run `pi` (or the path to `dist/cli.js`) and confirm the interactive harness starts.
  </Step>
  <Step title="Verify the main export">
    Import `createAgentSession` and `ModelRuntime` from `@earendil-works/pi-coding-agent`, create a session, and call `session.prompt(...)`.
  </Step>
  <Step title="Verify subpath exports">
    Resolve `@earendil-works/pi-coding-agent/rpc-entry` and `@earendil-works/pi-coding-agent/client` through the package `exports` map (for example via Node’s package resolution), not by hard-coding `node_modules` file paths.
  </Step>
</Steps>

## Related pages

<CardGroup>
  <Card title="Installation" href="/installation">
    npm and installer paths, bin entry, and verification for this package.
  </Card>
  <Card title="Run modes" href="/run-modes">
    Interactive, print/JSON, RPC, and SDK invocation shapes.
  </Card>
  <Card title="SDK" href="/sdk">
    Embed with the main export: sessions, models, tools, settings.
  </Card>
  <Card title="SDK examples" href="/sdk-examples">
    Copy-paste recipes for minimal, custom, and full-control setups.
  </Card>
  <Card title="RPC mode" href="/rpc-mode">
    Process integration via `rpc-entry`, commands, and JSON streams.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    `pi` binary flags, auth subcommands, and bin wiring.
  </Card>
  <Card title="Session runtime" href="/session-runtime">
    Runtime services for embedding without the interactive TUI.
  </Card>
  <Card title="Overview" href="/overview">
    What pi is, four run modes, and first docs routes.
  </Card>
</CardGroup>