Troubleshooting agegr/pi-web Setup

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). 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:

• 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

Model list is empty

• Cause: Missing 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

# 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

// 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

// 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	Quick-start, architecture diagram, development warnings	README.md
package.json	Scripts (dev, lint, typecheck), dependency versions	package.json
next.config.ts	Next.js server configuration, API route handling	next.config.ts
tailwind.config.ts	UI styling configuration	tailwind.config.ts
lib/agent-client.ts	Typed HTTP client for /api/agent/* endpoints	agent-client.ts
lib/rpc-manager.ts	AgentSessionWrapper lifecycle management	rpc-manager.ts
lib/allowed-roots.ts	Security policy for file-system access	allowed-roots.ts
components/ChatWindow.tsx	Main chat UI, SSE event handling	ChatWindow.tsx
components/SessionSidebar.tsx	Session tree and worktree navigation	SessionSidebar.tsx

When errors persist, examine these files in order: start with README.md for context, check package.json for script definitions, then trace through lib/agent-client.ts and 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 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 reads this directory directly, and the AgentSession wrapper in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}