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

> Locate pi-web configuration files easily. Discover repository paths for build settings and runtime paths in ~/.pi/agent/ for AI model management. Enhance your workflow today.

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

---

**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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/tsconfig.json)** – Sets TypeScript compiler strictness, module resolution strategy, and target JavaScript version for the entire project.
- **[`package.json`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/lib/models-config-store.ts)** – Implements the read/write logic for [`settings.json`](https://github.com/agegr/pi-web/blob/main/settings.json) and [`models.json`](https://github.com/agegr/pi-web/blob/main/models.json), handling persistence and validation of user configurations.
- **[`lib/model-scope.ts`](https://github.com/agegr/pi-web/blob/main/lib/model-scope.ts)** and **[`lib/model-discovery.ts`](https://github.com/agegr/pi-web/blob/main/lib/model-discovery.ts)** – Translate the `enabledModels` patterns from [`models.json`](https://github.com/agegr/pi-web/blob/main/models.json) into the filtered list displayed in the UI, managing model visibility and discovery logic.
- **[`lib/tool-preset-preference.ts`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/lib/project-trust.ts)** – Reads per-project `.pi/extensions` and [`.pi/settings.json`](https://github.com/agegr/pi-web/blob/main/.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:

```bash
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:

```typescript
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`](https://github.com/agegr/pi-web/blob/main/.pi/settings.json) file within any project root to override global [`settings.json`](https://github.com/agegr/pi-web/blob/main/settings.json) values for that specific repository. Similarly, place a `.pi/extensions` file to configure trusted plugins via [`lib/project-trust.ts`](https://github.com/agegr/pi-web/blob/main/lib/project-trust.ts).

## Summary

- **Repository configs** ([`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), [`tsconfig.json`](https://github.com/agegr/pi-web/blob/main/tsconfig.json), [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json)) control the build pipeline, TypeScript compilation, and UI theming.
- **User configs** in `~/.pi/agent/` ([`settings.json`](https://github.com/agegr/pi-web/blob/main/settings.json), [`models.json`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/lib/models-config-store.ts), [`lib/model-scope.ts`](https://github.com/agegr/pi-web/blob/main/lib/model-scope.ts), [`lib/allowed-roots.ts`](https://github.com/agegr/pi-web/blob/main/lib/allowed-roots.ts), [`lib/project-trust.ts`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/lib/models-config-store.ts). You can also set per-project defaults by creating a [`.pi/settings.json`](https://github.com/agegr/pi-web/blob/main/.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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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.