Where to Find Configuration Files for Pi-Web: Repository and Runtime Paths

Configuration files for pi-web exist at two distinct levels: repository-level files in the project root control the build pipeline and UI theming, while user-level files in ~/.pi/agent/ manage runtime AI model settings and session data.

Pi-web is a Next.js-based interface for the Pi-Agent system maintained in the agegr/pi-web repository. Locating its configuration files is essential for customizing the build process, adjusting Tailwind styling, or modifying AI behavior through model configurations and user preferences.

Repository-Level Configuration Files

The project root contains standard Next.js and TypeScript configuration files that govern the build process, code quality, and styling pipeline.

Build and Type Configuration

• next.config.ts – Controls Next.js server behavior, including API route handling, rewrites, and headers. This file customizes how the application builds and serves content.
• tsconfig.json – Sets TypeScript compiler strictness, module resolution strategy, and target JavaScript version for the entire project.
• package.json – Defines dependencies, npm scripts (such as npm run dev and npm run lint), and the required Node.js version.

Styling and Linting Configuration

• tailwind.config.ts – Defines the design system including custom colors, spacing scales, and fonts used throughout the UI components.
• postcss.config.mjs – Connects Tailwind CSS to the PostCSS processing pipeline used by Next.js during compilation.
• eslint.config.mjs – Enforces code style rules and catches common bugs during development through project-wide ESLint configuration.

User-Level Pi-Agent Configuration

At runtime, pi-web reads user-specific configuration from the Pi-Agent data directory, defaulting to ~/.pi/agent/. You can override this location by setting the PI_CODING_AGENT_DIR environment variable.

Core Runtime Config Files

• ~/.pi/agent/settings.json – Stores global preferences including the default model, thinking level, and other UI settings. The server reads this via lib/models-config-store.ts when handling API routes under app/api/models-config/*.
• ~/.pi/agent/models.json – Contains the list of available AI models, provider credentials, and per-model enable/disable flags. The UI accesses this data through GET /api/models, which utilizes lib/model-scope.ts to resolve enabled model patterns.
• ~/.pi/agent/sessions/…/*.jsonl – Houses raw chat logs for each conversation session. The session API routes in app/api/sessions/* read these files directly via lib/session-reader.ts.

Runtime Configuration Modules

Beyond static JSON files, pi-web uses several TypeScript modules in the lib/ directory to manage dynamic configuration logic.

Model and Settings Management

• lib/models-config-store.ts – Implements the read/write logic for settings.json and models.json, handling persistence and validation of user configurations.
• lib/model-scope.ts and lib/model-discovery.ts – Translate the enabledModels patterns from models.json into the filtered list displayed in the UI, managing model visibility and discovery logic.
• lib/tool-preset-preference.ts – Persists the last selected tool preset to localStorage and applies it to new sessions.

Security and Project Configuration

• lib/allowed-roots.ts – Configures which filesystem paths the file-browser APIs may expose, including the current working directory, worktree roots, and user-added roots.
• lib/project-trust.ts – Reads per-project .pi/extensions and .pi/settings.json files to enable trusted plugins and repository-specific UI extensions.

Customizing Configuration Paths and Values

You can modify pi-web's configuration behavior through environment variables and file edits.

Changing the Data Directory

Set the PI_CODING_AGENT_DIR environment variable to redirect all runtime configuration reads to a custom location:

export PI_CODING_AGENT_DIR=$HOME/custom-pi-agent
npm run dev

Programmatic Configuration Access

When extending pi-web, you can read Pi-Agent settings server-side using Node.js filesystem APIs:

import { readFile } from "fs/promises";
import { join } from "path";

async function loadPiSettings() {
  const home = process.env.HOME || process.env.USERPROFILE!;
  const settingPath = join(home, ".pi", "agent", "settings.json");
  const data = await readFile(settingPath, "utf-8");
  return JSON.parse(data);
}

Project-Specific Overrides

Create a .pi/settings.json file within any project root to override global settings.json values for that specific repository. Similarly, place a .pi/extensions file to configure trusted plugins via lib/project-trust.ts.

Summary

• Repository configs (next.config.ts, tailwind.config.ts, tsconfig.json, package.json) control the build pipeline, TypeScript compilation, and UI theming.
• User configs in ~/.pi/agent/ (settings.json, models.json, session JSONL files) store runtime AI preferences and chat history.
• Environment variable PI_CODING_AGENT_DIR redirects the runtime configuration directory to a custom path.
• Library modules (lib/models-config-store.ts, lib/model-scope.ts, lib/allowed-roots.ts, lib/project-trust.ts) implement the logic that reads and applies these configurations.

Frequently Asked Questions

How do I change the default AI model in pi-web?

Edit the ~/.pi/agent/settings.json file to modify the default model field, or use the Models UI in the sidebar which calls the API routes handled by lib/models-config-store.ts. You can also set per-project defaults by creating a .pi/settings.json file in your project root.

Where does pi-web store conversation history?

Session data persists as .jsonl files in ~/.pi/agent/sessions/. The API routes in app/api/sessions/* read these files via lib/session-reader.ts to populate the chat interface. Set PI_CODING_AGENT_DIR to relocate this data directory.

Can I customize the Tailwind theme in pi-web?

Yes. Modify tailwind.config.ts in the repository root to adjust colors, fonts, or spacing. The configuration processes through postcss.config.mjs during the Next.js build. Changes require rebuilding the application to take effect.

Which file controls which filesystem paths pi-web can access?

The lib/allowed-roots.ts module manages accessible paths, configuring which directories the file-browser APIs expose to the UI. This includes the current working directory, git worktree roots, and any user-added paths defined in the runtime configuration.

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