@agimon-ai/po-file-edit

Native session-scoped file-change tracking and review APIs for Po and po-web.

Part of the Po distribution.

The package tracks files changed through session tool calls and captures content for diffs, without requiring a Git repository. edit and write name their file in the call, so the package can capture the before and after content within its size and format limits. Bash calls instead trigger a bounded tree comparison. See What this cannot see for gaps in that coverage.

Alpha: timeline and UI contracts may change between releases.

Requirements

• Node.js 24 or newer
• Git for diffs against HEAD

Install

po init include File Edit in default.packages in .po/modes.yaml. Remove it or move it to a named layer to change which major modes load it.

In the cockpit

The # files group in the activity dock lists every file the session changed. Selecting one opens a temporary tab holding three views of it:

• diff: what the session did to the file, followed by each recorded change on its own, so a file edited four times shows four distinct diffs rather than one merged blur.
• source: the file as it stands, editable. Saving writes straight to disk and is refused if the file changed since it was opened, so a hand edit cannot silently discard what the agent wrote.
• preview: rendered Markdown, or HTML in a sandboxed frame.

Selecting text in any view raises a comment box. Comments queue on the tab and one send review builds a single message quoting each anchor, so several comments cost one turn.

Diffs here do not use Git. The package captures the file's content before an edit or write runs and keeps it, content-addressed, beside the session timeline; both go when the session ends.

What this cannot see

• A file the session changed and then deleted. The dock lists things to open, so a row that can only answer "this is gone" is left out. The timeline still holds the change, so a tab already open on the file keeps working and says why it has nothing to show.
• A file changed by a background process that outlives its Bash call. The tree is compared when the call ends.
• A file changed outside any tool. There is no always-on watcher.
• Content past 1 MiB, and binary files. These are listed as changed, without content.
• A file found only by comparing the tree has no baseline, so it is listed, readable and editable, but never diffed. Rows and versions say so rather than showing an empty diff.
• The tree walk skips dependency and build directories and is capped on entries and depth, so a very deep or very large checkout can under-report.

Data behavior

The timeline contains file paths, and the snapshot store holds copies of the file content the session changed. That content can be sensitive. Both live under the Pi agent directory, $PI_CODING_AGENT_DIR or ~/.po/agent/po-file-edit, never inside the working tree, and should be protected with the same access controls as Pi session data.

A parent session removes its own timeline and snapshots on final disposal. Child sessions share the parent timeline and do not clear it. Activity selection stops retain review data for reactivation. A session that is killed cannot, so each session also sweeps state that no longer belongs to anyone: a timeline and its snapshots are removed once nothing has written to them for a week. An older build kept this state in the repository's git common directory, and that directory is cleared away under the same rule.

The session API reads and writes only files the timeline already records, so a request cannot reach a file this session never changed.

Public API

import { createFileEditDependencies } from '@agimon-ai/po-file-edit';
import type { FileDiff, FileEditEntry } from '@agimon-ai/po-file-edit';

The root also exports editor-resolution and timeline domain types for host integrations.

Development

pnpm build
pnpm typecheck
pnpm test
pnpm lint

Maintained by Agimon.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.

The native server loader lives in src/extensions. Execution-boundary hooks and one session activity own tracking, startup sweeps and telemetry. Final disposal drains admitted work before clearing parent-owned stores and shutting down telemetry. Terminal UI construction helpers and types are retired.