Agent integration: Pi coding agent

[mcinteerj]

Summary

Proposing native Pi coding agent integration, similar to the existing Claude Code and Gemini CLI agents, and the in-progress OpenCode integration (#220).

Why Pi?

Pi is one of the fastest-growing coding agent CLIs right now:

• 10,000+ GitHub stars on pi-mono (993 forks)
• npm downloads exploding: ~4k/week in Dec 2025 → 1.3M/week by late Jan 2026 (300x growth in ~6 weeks)
• 207 published versions across 4 months — extremely active development cadence (multiple releases per week)
• Rapidly expanding user base that would benefit from Entire session tracking

How Extensible Pi Is (Implementation Feasibility)

Pi makes this integration straightforward due to its architecture:

JSONL Session Format (Same as Claude Code)

Pi stores sessions as JSONL at ~/.pi/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl. Each line is a typed JSON entry with id/parentId fields forming a tree. The format is well-documented (session.md) and closely parallels Claude Code's JSONL transcript format — meaning the existing ChunkJSONL/ReassembleJSONL utilities, transcript position tracking, and modified file extraction patterns all transfer directly.

TypeScript Extension System for Hooks

Pi has a rich extension API with lifecycle events that map cleanly to Entire's hook model:

Entire Hook	Pi Extension Event	Notes
session_start	session_start	Direct 1:1
session_end / stop	session_shutdown / agent_end	agent_end fires per-prompt; session_shutdown on exit
user_prompt_submit	before_agent_start	Provides event.prompt
pre_tool_use	tool_call	Can inspect tool name + input
post_tool_use	tool_result	Has result content + details

InstallHooks() would generate a .pi/extensions/entire.ts file that subscribes to these events and calls entire hooks pi <verb> via pi.exec() — the same bridge pattern used in the OpenCode integration (#220) with its .opencode/plugins/entire.js.

Extensions Are Auto-Discovered

Pi auto-discovers extensions from .pi/extensions/*.ts (project-local) or ~/.pi/agent/extensions/*.ts (global). TypeScript runs without compilation via jiti. No config file modification needed — just drop the file and it works on next session start. This makes InstallHooks()/UninstallHooks() trivially clean (create/delete a single .ts file).

Rich Session Metadata

Pi's session entries include:

• Token usage with cost breakdowns per assistant message
• Model/provider info on every response
• Tool call arguments and results with structured details
• Compaction summaries, branch summaries, labels
• bashExecution messages with command, output, exit code

This means ReadSession() can extract rich checkpoint metadata (modified files from write/edit tool results, token usage aggregation, etc.).

Proposed Implementation

New package: cmd/entire/cli/agent/pi/

File	Purpose
pi.go	PiAgent struct — Agent interface, session read/write, presence detection (.pi/ dir)
hooks.go	HookSupport + HookHandler — generate/remove .pi/extensions/entire.ts bridge
transcript.go	Parse Pi JSONL (tree walk from leaf → root to linearize), extract modified files
types.go	Pi-specific JSON types (session header, message entries, content blocks)

Key difference from Claude/Gemini: Pi's JSONL is a tree, not a flat log. ParseTranscript() would need to resolve the leaf, walk parentId chain to root, and produce a linear conversation. This is a well-defined operation — Pi's own buildSessionContext() does exactly this.

Notes

• Happy to implement this. Wanted to open an issue first to gauge interest and get architectural feedback before writing Go code.
• The OpenCode PR (Add OpenCode agent integration #220) establishes the extension-bridge pattern — would be good to see how that lands before/alongside this, since they share the same approach.
• Pi's .pi/extensions/ auto-discovery means zero friction for users: entire enable --agent pi generates one file, done.

[mcinteerj]

Happy to put together a PR for this if you're open to it — I've already mapped out the implementation approach and the hook event mappings. Let me know if there's any architectural direction you'd prefer before I start.

[LarsEckart]

Pi community never sleeps :D

For pi, it was just another extension to get this to work. For entire-cli, I also got it to work. Commits and changes show nicely on the dashboard, just the session details (thinking traces, tool calls etc) are not visible, I guess that would require an update to the parser for the entire web app.

I'm not comfortable with pushing a vibe-sloped PR, but at least good to see that integration is already somewhat possible and probably available soon.

Curious how this project develops :)

[Soph]

@mcinteerj if you have time we are happy to accept PRs with more agent contributions. I would suggest you reach out to @entireio/cli-maintainers if you can't make it work with the existing agent interface https://github.com/entireio/cli/blob/main/cmd/entire/cli/agent/agent.go#L13-L62 and let's discuss the approach in advance to safe your time.

Given that gemini is still in preview and we know some edges (for example #214) there might also be some changes on our side but I do hope nothing major.

[mcinteerj]

Thanks @Soph for the guidance, and @LarsEckart for the early validation that it works at a basic level!

I've done a deep dive into both codebases and have a refined approach. The high-level architecture from my original issue holds, but there are some important implementation details I want to surface before writing Go.

How this fits Entire's agent model

Pi integration follows the same pattern as Claude Code and Gemini CLI: implement the Agent interface (+ HookSupport, HookHandler, TranscriptAnalyzer, TranscriptChunker) in a new cmd/entire/cli/agent/pi/ package, self-register via init(), and wire up hook handlers in hook_registry.go.

The git hook side (checkpoint on commit, pre-push session upload) works identically — pi's session format is JSONL like Claude's, so ChunkJSONL/ReassembleJSONL and the transcript position tracking patterns all transfer.

Hook bridge: generated pi extension

Pi has a TypeScript extension system that auto-discovers .ts files in .pi/extensions/ (project-local) or ~/.pi/agent/extensions/ (global). Extensions run without compilation via jiti.

InstallHooks() would generate .pi/extensions/entire-hooks.ts — a small TypeScript file that subscribes to pi's lifecycle events and shells out to entire hooks pi <verb>. UninstallHooks() would delete it. AreHooksInstalled() would check if the file exists. This mirrors how the Claude integration writes/reads .claude/settings.json, just with a standalone file instead of editing JSON config.

The generated extension would use pi's ExtensionAPI — exporting a default function that receives the API object and calls pi.on("event_name", handler) to subscribe to events. Here's the event mapping:

Pi Extension Event	Entire Hook Verb	Key Data
session_start	session-start	sessionId, sessionFile, cwd
before_agent_start	user-prompt-submit	prompt text
tool_call	pre-tool-use	toolName, toolCallId, input
tool_result	post-tool-use	toolName, toolCallId, content, isError
agent_end	stop	sessionFile
session_shutdown	session-end	sessionFile
session_tree	tree-navigate	newLeafId, oldLeafId (pi-unique)
session_fork	session-fork	previousSessionFile (pi-unique)

The last two are pi-specific — more on why they matter below.

Data passing: temp file, not stdin

One divergence from the Claude/Gemini pattern: pi's pi.exec() spawns child processes with stdio: ["ignore", "pipe", "pipe"] — stdin is explicitly closed. So the generated extension couldn't pipe JSON to entire hooks pi <verb> via stdin.

Instead, each hook call would write its JSON payload to a unique temp file (via mkdtempSync) and pass the path as --input <path>, cleaning up in a finally block. Each call would get its own temp directory, so concurrent hook fires (e.g., rapid tool_call → tool_result) wouldn't race. All calls would use a 5-second timeout and warn-on-failure — never blocking pi.

Should --input <file> be added to the shared hook command infrastructure so all agents could use it, or should pi handle it internally in ParseHookInput?

The big difference: tree-structured sessions

This is the main engineering challenge vs Claude/Gemini.

Pi's JSONL is a tree, not a flat log. Each entry has id/parentId fields. When a user rewinds (via /tree or double-ESC), old entries stay in the file and new entries branch from an earlier point. A single .jsonl file can contain multiple divergent conversation branches. The file is append-only — branching never deletes anything.

This means a transcript parser couldn't just read lines sequentially. For every read operation, it would need to:

1. Build an id → entry map from all JSONL lines
2. Find the current leaf (most recently appended entry with no children)
3. Walk parentId chain from leaf → root to get the active branch
4. Only extract data (modified files, token usage) from entries on that branch

This tree-walk is ~100 lines of Go and well-defined — pi's own buildSessionContext() does the same thing.

Impact on specific interfaces:

• ExtractModifiedFilesFromOffset() — Offset would work as a "has the file changed?" gate, but new lines could be on abandoned branches. Would need to full-parse and tree-walk every time (pi sessions are typically <10MB).
• TruncateAtUUID() — Can't cut at line N. Would need to filter to only entries on the root→target path, producing valid JSONL where the target is the natural leaf.
• ChunkTranscript() — Would operate on the linearized active branch only. Dead branches excluded, keeping chunk sizes predictable.
• Checkpoint metadata — Would need to store the active leaf ID at checkpoint time for unambiguous branch identification during rewind.

This is also why the tree-navigate and session-fork hooks would matter: they'd tell Entire when the active branch changes (rewind) or when a new session file is created from the current one (/fork).

Questions for maintainers

1. --input flag: Shared infrastructure or pi-internal?
2. Leaf ID in checkpoints: Is there a natural place to store agent-specific checkpoint data beyond AgentSession, or should I add a field?
3. Fork = new session: Pi's /fork creates a separate .jsonl with a parentSession reference back to the original. I'd propose treating this as a new Entire session with lineage metadata. Sound right?

I have a full implementation spec with Go types, tree-walking algorithms, test matrix, and phased build order. Happy to share or just start PRing — let me know what's preferred.

[khaong]

Hi, I've just created #281 to track our refactor work - give us a little bit to get this into place before starting implementations please 🙏

The specific tree-log format is interesting, we'll need to keep that in mind in the transcript interfaces - thanks!

[bytes032]

Hey @mcinteerj I'm sorry but I totally missed this issue over here in my enthusiasm yesterday. I've opened a PR but happy to collab with you given your issue here was first. Apologies!

#251