# Troubleshooting agegr/pi-web Setup

> Troubleshoot common agegr/pi-web setup issues like build errors, missing directories, or Node version conflicts. Use this diagnostic checklist for quick resolution.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: how-to-guide
- Published: 2026-08-11

---

**Most setup failures in pi-web stem from running `next build` during development, missing the `~/.pi/agent/` session directory, or Node version mismatches—follow the diagnostic checklist below to resolve them systematically.**

The **pi-web** repository is a Next.js front-end for the [pi SDK (v2)](https://github.com/polarsignals/pi). It orchestrates browser-based AI sessions through an in-process **AgentSession** wrapper that communicates directly with pi SDK session files. Understanding this three-layer architecture is essential for effective troubleshooting.

## Architecture Overview

pi-web operates across three coordinated layers as diagrammed in the [README.md](https://github.com/agegr/pi-web/blob/main/README.md):

- **Browser** — Renders React components and streams Server-Sent Events (SSE) from API routes
- **Next.js Server** — Handles `/api/*` routes, reads from `~/.pi/agent/sessions/`, and proxies to the AgentSession
- **AgentSession (in-process)** — A thin wrapper around pi SDK sessions living in the same Node process

```

Browser                Next.js Server              AgentSession (in-process)
  │                        │                               │
  ├─ GET /api/sessions ────▶ reads ~/.pi/agent/sessions/   │
  ├─ GET /api/sessions/[id] reads .jsonl file directly     │
  ├─ POST /api/agent/new ──▶ createAgentSession()          │
  └─ GET /api/agent/[id]/events ◀── SSE stream of events ──┘

```

This architecture means most runtime failures fall into three categories: build artifacts corrupting dev mode, file system permissions blocking session creation, or configuration mismatches in the pi SDK integration.

## Common Setup Failures and Fixes

### `npm run dev` fails with module errors

- **Cause**: Missing dependencies or Node version < 20
- **Fix**: Run `npm ci` with Node 20+; verify with `node -v`

### UI hangs after first request

- **Cause**: `next build` pollutes `.next/` and breaks hot-module reloading
- **Fix**: `rm -rf .next` and **never run `next build` during development**

### Chat window shows no messages

- **Cause**: Session files cannot be created under `~/.pi/agent/`
- **Fix**: Ensure `mkdir -p ~/.pi/agent/sessions` and verify write permissions

### Tool access (file browser, git) is disabled

- **Cause**: Current working directory outside allowed roots
- **Fix**: Verify `cwd` passed to `POST /api/agent/new` matches an entry in [`lib/allowed-roots.ts`](https://github.com/agegr/pi-web/blob/main/lib/allowed-roots.ts)

### Model list is empty

- **Cause**: Missing [`models.json`](https://github.com/agegr/pi-web/blob/main/models.json) or invalid provider credentials
- **Fix**: Re-authenticate via **Models Config** in sidebar or manually edit `~/.pi/agent/models.json`

## Diagnostic Checklist

Follow these steps in order to isolate setup problems:

1. **Verify environment**: `node -v` (≥ 20), `npm -v`
2. **Clean install**: `rm -rf node_modules .next && npm ci`
3. **Start dev server**: `npm run dev` → `http://localhost:30141`
4. **Test API health**: `curl http://localhost:30141/api/agent/running` should return `[]`
5. **Check session directory**: `ls ~/.pi/agent/sessions/` should show subdirectories per project
6. **Inspect browser console** for uncaught errors pointing to missing env vars or permission failures

## Critical Development "Gotchas"

| Issue | Explanation | Prevention |
|-------|-------------|------------|
| **Stale build artifacts** | `next build` creates production bundles that override dev assets | Add `.next/` to `.gitignore` and never build in development |
| **Fork session failures** | The *Fork* button destroys the original `AgentSessionWrapper`; stray references cause "already forked" errors | Restart dev server if fork operations fail repeatedly |
| **Worktree path resolution** | The app resolves worktree paths to project root; case-folding filesystems hide the switcher | Use case-preserving filesystems (avoid legacy Windows FAT) |
| **Typecheck drift** | Runtime errors from uncompiled TypeScript | Run `node_modules/.bin/tsc --noEmit` before commits |

## Code Examples

### Clean installation and startup

```bash

# Install exact Node version

nvm install 20
nvm use 20

# Remove stale artifacts and reinstall

rm -rf node_modules .next
npm ci

# Start development server on port 30141

npm run dev

```

### Programmatic session creation

```typescript
// Mirrors logic in app/api/agent/new/route.ts
const response = await fetch('/api/agent/new', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    cwd: '/home/user/projects/my-repo',
    message: 'Explain the repository structure',
    toolNames: ['file_browser', 'git'],
    provider: 'anthropic',
    modelId: 'claude-sonnet-4-6',
  }),
});

const { id, state } = await response.json();

```

### Inspecting session state via client library

```typescript
// Using lib/agent-client.ts helper
import { createAgentClient } from '@/lib/agent-client';

const client = createAgentClient('session-id-123');
const state = await client.getState();
console.log(state.messages); // Array of conversation messages

```

## Key Source Files for Troubleshooting

| File | Role | Direct Link |
|------|------|-------------|
| [`README.md`](https://github.com/agegr/pi-web/blob/main/README.md) | Quick-start, architecture diagram, development warnings | [README.md](https://github.com/agegr/pi-web/blob/main/README.md) |
| [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json) | Scripts (`dev`, `lint`, `typecheck`), dependency versions | [package.json](https://github.com/agegr/pi-web/blob/main/package.json) |
| [`next.config.ts`](https://github.com/agegr/pi-web/blob/main/next.config.ts) | Next.js server configuration, API route handling | [next.config.ts](https://github.com/agegr/pi-web/blob/main/next.config.ts) |
| [`tailwind.config.ts`](https://github.com/agegr/pi-web/blob/main/tailwind.config.ts) | UI styling configuration | [tailwind.config.ts](https://github.com/agegr/pi-web/blob/main/tailwind.config.ts) |
| [`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts) | Typed HTTP client for `/api/agent/*` endpoints | [agent-client.ts](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts) |
| [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) | `AgentSessionWrapper` lifecycle management | [rpc-manager.ts](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) |
| [`lib/allowed-roots.ts`](https://github.com/agegr/pi-web/blob/main/lib/allowed-roots.ts) | Security policy for file-system access | [allowed-roots.ts](https://github.com/agegr/pi-web/blob/main/lib/allowed-roots.ts) |
| [`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatWindow.tsx) | Main chat UI, SSE event handling | [ChatWindow.tsx](https://github.com/agegr/pi-web/blob/main/components/ChatWindow.tsx) |
| [`components/SessionSidebar.tsx`](https://github.com/agegr/pi-web/blob/main/components/SessionSidebar.tsx) | Session tree and worktree navigation | [SessionSidebar.tsx](https://github.com/agegr/pi-web/blob/main/components/SessionSidebar.tsx) |

When errors persist, examine these files in order: start with [`README.md`](https://github.com/agegr/pi-web/blob/main/README.md) for context, check [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json) for script definitions, then trace through [`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts) and [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) for session lifecycle issues.

## Summary

- **Never run `next build` in development** — it corrupts the dev environment
- **Ensure `~/.pi/agent/` exists and is writable** — session creation fails without it
- **Use Node 20+ and `npm ci`** — version mismatches cause cryptic module errors
- **Verify `cwd` against allowed roots** — tools disable automatically for unauthorized paths
- **Consult source files directly** — the repository's `lib/` and `components/` directories contain self-documenting TypeScript that reveals most failure modes

## Frequently Asked Questions

### Why does `npm run dev` fail after I ran `next build`?

The `next build` command generates production artifacts in `.next/` that override Next.js's development file-watching behavior. The [README.md](https://github.com/agegr/pi-web/blob/main/README.md) explicitly warns that this "pollutes `.next/` and breaks `npm run dev`." Delete the `.next` directory and restart the dev server.

### Where does pi-web store active session data?

Session data lives in `~/.pi/agent/sessions/` as JSONL files. The Next.js server in [`app/api/sessions/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/sessions/route.ts) reads this directory directly, and the `AgentSession` wrapper in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) writes to it. If this directory is missing or non-writable, session creation silently fails.

### Why are tools like file browser disabled in my session?

The [`lib/allowed-roots.ts`](https://github.com/agegr/pi-web/blob/main/lib/allowed-roots.ts) module enforces a security policy: the `cwd` parameter passed to `POST /api/agent/new` must match a configured allowed root. Check your server logs or browser network tab for 403 responses from `/api/agent/new`, then adjust your `cwd` or allowed roots configuration.