Quick Start

Get up and running with edge-pi in minutes. This guide covers both the SDK (for programmatic use) and the CLI (for interactive terminal use).

Prerequisites

Using the CLI

The fastest way to start is with the epi command.

1. Install

npm install -g edge-pi-cli

2. Set your API key

# Pick one (or more) of these:
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...

3. Run

# Interactive mode
epi

# One-shot mode
epi -p "List all TypeScript files in src/"

# With a specific model
epi --provider openai --model gpt-4o "Explain this codebase"

Using the SDK

Use the SDK to embed a coding agent in your own application.

1. Install

npm install edge-pi ai @ai-sdk/anthropic

Replace @ai-sdk/anthropic with your preferred provider package (@ai-sdk/openai, @ai-sdk/google, etc.).

2. Basic usage

import { CodingAgent } from "edge-pi";
import { anthropic } from "@ai-sdk/anthropic";

const agent = new CodingAgent({
  model: anthropic("claude-sonnet-4-20250514"),
});

// Non-streaming
const result = await agent.generate({
  prompt: "Read package.json and tell me the project name",
});
console.log(result.text);
console.log(`Steps: ${result.steps.length}, Tokens: ${result.totalUsage.inputTokens + result.totalUsage.outputTokens}`);

3. Streaming

const stream = await agent.stream({
  prompt: "Find all TODO comments in the codebase",
});

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

4. Custom tools

import { CodingAgent, createReadOnlyTools } from "edge-pi";
import { anthropic } from "@ai-sdk/anthropic";

// Use only read-only tools (read, grep, find, ls)
const agent = new CodingAgent({
  model: anthropic("claude-sonnet-4-20250514"),
  toolSet: "readonly",
});

// Or use all tools
const agentFull = new CodingAgent({
  model: anthropic("claude-sonnet-4-20250514"),
  toolSet: "all",
});

5. Session persistence

import { CodingAgent, SessionManager } from "edge-pi";
import { anthropic } from "@ai-sdk/anthropic";

// Create a persistent session
const session = SessionManager.create(process.cwd(), "./sessions");

const agent = new CodingAgent({
  model: anthropic("claude-sonnet-4-20250514"),
});

// Restore previous messages
const context = session.buildSessionContext();
if (context.messages.length > 0) {
  agent.setMessages(context.messages);
}

const result = await agent.generate({
  prompt: "What files have we discussed?",
});

// Messages are auto-saved if you integrate with session
// See the Sessions docs for full details

Next Steps