# Pi-web Development Roadmap: Current Focus and Future Directions

> Explore the Pi-web development roadmap focusing on AgentSession stability, Git integration, internationalization, and security. See current priorities and future directions.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: architecture
- Published: 2026-07-27

---

**Pi-web's development roadmap prioritizes stabilizing AgentSession lifecycle management, enhancing Git worktree integration, expanding internationalization support, and hardening security measures, with all priorities inferred from the architecture notes in [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md) and the existing TypeScript implementation in the `agegr/pi-web` repository.**

Pi-web is an actively maintained local web UI for the [pi coding agent](https://github.com/badlogic/pi-mono) that transforms terminal-based interactions into a browser-based experience. While the project does not maintain a separate standalone roadmap file, the development trajectory is clearly documented through the codebase structure, key design decisions in [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md), and the implementation patterns found throughout the repository. This article examines the current Pi-web development roadmap by analyzing the source files that define its architecture and upcoming enhancements.

## Session Management and Branching Stability

The core of the Pi-web development roadmap centers on refining **AgentSession lifecycle management** and the distinction between forking and branching workflows.

According to [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md), a critical design decision requires that "Fork must destroy the wrapper," which is implemented in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts). This indicates ongoing work to tighten the UI/UX around these two distinct workflows. The [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts) module currently handles reading `.jsonl` session files, while [`app/api/agent/new/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/agent/new/route.ts) manages the creation of new sessions that are forkable and tool-preset aware.

The roadmap suggests future refinements will focus on session file rewrites and ensuring robust handling of the `fork` command versus in-session branching, as managed by the [`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts) hook which reconciles these actions during SSE streaming.

## Git Worktree Integration Enhancements

A major priority on the Pi-web roadmap involves deepening **Git worktree support** for seamless multi-branch development.

The codebase currently implements worktree resolution in [`lib/worktree.ts`](https://github.com/agegr/pi-web/blob/main/lib/worktree.ts) and provides CRUD operations through [`app/api/worktrees/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/worktrees/route.ts), including safety checks that return 409 errors for dirty worktrees. The README's "Work across branches" documentation implies upcoming features will include smoother UI switching between worktrees, better error handling, and deeper project grouping functionality.

The extensive worktree handling code suggests the maintainers are investing in robust Git integration to allow developers to work across multiple branches without leaving the web interface.

## Tool-Call Compatibility and Normalization

The roadmap includes ongoing efforts to maintain **backward compatibility** with the pi agent's evolving tool-call schema.

The `normalizeToolCalls()` function in [`lib/normalize.ts`](https://github.com/agegr/pi-web/blob/main/lib/normalize.ts) explicitly normalizes mismatched fields between the pi agent and the UI. The prominence of this utility in [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md) signals that future development will continue adapting the UI to handle schema changes from the underlying pi-mono agent without breaking existing functionality.

## Internationalization and Model Configuration

Future directions for Pi-web emphasize **user experience improvements** through expanded language support and richer model management.

The presence of translation files in `lib/i18n/*.ts` and a UI language selector indicates plans to expand beyond current language offerings. Simultaneously, the [`app/api/models.ts`](https://github.com/agegr/pi-web/blob/main/app/api/models.ts) and [`app/api/models-config/test/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/models-config/test/route.ts) endpoints demonstrate a roadmap toward more sophisticated model configuration interfaces, allowing users to "configure less from the terminal" as noted in the README.

The existence of a dedicated testing route for model configurations suggests tighter integration with new model providers and validation workflows are under active development.

## Performance Optimization for Large Sessions

The Pi-web development roadmap addresses **scalability concerns** through specific optimizations for handling very large sessions.

The `handleAgentEvent` function includes specialized logic for compaction SSE handling, while `/api/sessions/[id]/export/route.ts` implements iterative HTML export to prevent stack overflows when processing massive session histories. These implementation details point to continued performance improvements targeting memory management and export reliability for enterprise-scale usage.

## Security Hardening and Proxy Support

Security remains a persistent focus, with the roadmap emphasizing **safe local deployment** and access controls.

The [`lib/http-dispatcher.ts`](https://github.com/agegr/pi-web/blob/main/lib/http-dispatcher.ts) module handles HTTP proxy configuration, while [`lib/file-access.ts`](https://github.com/agegr/pi-web/blob/main/lib/file-access.ts) maintains a strict allow-list for file system access. The README explicitly warns users not to expose Pi-web to the internet, indicating future roadmap items will continue to harden the server against misuse through stricter environment-variable handling and enhanced proxy support.

## Key Implementation Files

The following source files represent the primary touchpoints for the current Pi-web development roadmap:

- **[`app/api/agent/new/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/agent/new/route.ts)** – Handles creation of new Agent sessions with forkable, tool-preset aware logic
- **[`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts)** – Central registry for `AgentSessionWrapper` implementing the fork-destroy logic
- **[`lib/worktree.ts`](https://github.com/agegr/pi-web/blob/main/lib/worktree.ts)** – Resolves Git worktrees and ties them to session grouping
- **[`lib/normalize.ts`](https://github.com/agegr/pi-web/blob/main/lib/normalize.ts)** – Contains `normalizeToolCalls()` for schema compatibility
- **[`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts)** – Manages SSE streaming and reconciles fork/branch actions
- **[`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md)** – Architecture document containing key design decisions and development notes

## Practical Usage Examples

The following commands exercise the core APIs that the Pi-web roadmap aims to extend and refine:

```bash

# Start the development server (default port 30141)

npm run dev

# Create a new Pi-web session via the API

curl -X POST http://localhost:30141/api/agent/new \
  -H "Content-Type: application/json" \
  -d '{"cwd":"/home/user/project","message":"Explain the code"}'

# Fork an existing session (POST /api/agent/[id] with command "fork")

curl -X POST http://localhost:30141/api/agent/abcd1234 \
  -H "Content-Type: application/json" \
  -d '{"command":"fork"}'

# Add a new Git worktree

curl -X POST http://localhost:30141/api/worktrees \
  -H "Content-Type: application/json" \
  -d '{"repoRoot":"/home/user/project","branch":"feature-x"}'

# Test a model configuration

curl -X POST http://localhost:30141/api/models-config/test \
  -H "Content-Type: application/json" \
  -d '{"modelId":"claude-sonnet-4-6"}'

```

## Summary

The Pi-web development roadmap reveals a project focused on maturing its core architecture while expanding user-facing features:

- **Session stability** remains the highest priority, with ongoing refinements to fork handling and AgentSession lifecycle management in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) and related modules
- **Git integration** will deepen through enhanced worktree UI workflows and robust error handling for multi-branch development
- **Compatibility layers** like `normalizeToolCalls()` ensure the UI evolves alongside the pi-mono agent without breaking changes
- **Security and performance** improvements target safe local deployment and efficient handling of large-scale sessions through compaction and iterative export logic

## Frequently Asked Questions

### Is there a public roadmap file for Pi-web?

No, Pi-web does not maintain a separate roadmap document. Instead, the development priorities are inferred from the [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md) architecture notes, README documentation, and the implementation patterns found in critical source files like [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) and [`app/api/agent/new/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/agent/new/route.ts). This approach allows the roadmap to evolve dynamically based on the pi-mono agent's development needs.

### How does Pi-web handle session forking versus branching?

Pi-web distinguishes between forking and in-session branching through a key design decision documented in [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md): forking must destroy the wrapper. The [`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts) manages the SSE streaming and state reconciliation for these actions, while [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) implements the registry logic that handles the destruction and recreation of session wrappers during fork operations.

### What security measures are planned for Pi-web?

The roadmap emphasizes continued hardening of the local server deployment model. Current implementations include strict file-access allow-lists in [`lib/file-access.ts`](https://github.com/agegr/pi-web/blob/main/lib/file-access.ts), HTTP proxy handling in [`lib/http-dispatcher.ts`](https://github.com/agegr/pi-web/blob/main/lib/http-dispatcher.ts), and explicit warnings against internet exposure. Future development will likely expand these controls to prevent unauthorized access while maintaining the convenience of local web-based interaction.

### How can I contribute to Pi-web development?

Contributors should focus on the areas outlined in [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md), particularly the "Key Design Decisions & Traps" sections. High-impact contributions would address session lifecycle edge cases, improve Git worktree error handling, or expand the `lib/i18n/*.ts` translation files. The development workflow emphasizes using `npm run dev` for the live server and avoiding `next build` during active development to prevent conflicts with the hot-reloading environment.