Skip to content
AI OutfitterAI OutfitterAI Outfitter

File Talk

Synced from file-talk/README.md. The repository is the source of truth.

Alpha/experimental: Review this extension carefully before relying on it for important files or workflows.

Pi extension for animate files: ordinary files paired with a durable instruction/history file at:

<directory>/.file_talk/<filename>

When that marker file exists, the parent agent should not edit the file directly with edit or write. Instead it must call the file_talk tool so a file-specific maintainer subprocess can apply changes and preserve semantic history.

Install

Section titled “Install”

Install from the GitHub package source:

Terminal window
pi install git:github.com/applepi-ai/file-talk

Then run Pi normally from a project that has the package installed.

Local development

Section titled “Local development”

Clone and install/use the package locally:

Terminal window
git clone https://github.com/applepi-ai/file-talk.git
cd file-talk
pi -e ./index.ts

For development inside another project, use an explicit extension path or symlink this checkout into that project’s Pi extension directory:

Terminal window
mkdir -p .pi/extensions
ln -s /path/to/file-talk .pi/extensions/file-talk
pi

This package declares Pi core packages as peer dependencies so the host Pi installation supplies them.

What it does

Section titled “What it does”

The extension registers a file_talk tool with:

  • path — animate file path
  • request — requested change or question
  • reason — required rationale for semantic history
  • thread — optional prior thread id to continue

file_talk starts a non-interactive Pi subprocess with the full .file_talk/<filename> contents appended as instructions. The subprocess may edit the animate file and should update the .file_talk instruction/history file with durable context, rationale, decisions, and revision history.

Threads are persisted as Pi session files under:

<directory>/.file_talk/.threads/<filename>/<thread-id>.jsonl

The tool response always begins with the thread id so follow-up calls can continue the same semantic conversation.

Direct-edit guard

Section titled “Direct-edit guard”

The extension also listens for edit and write tool calls. If the target has a matching .file_talk/<filename> instruction/history file, the direct mutation is blocked and the agent is told to use file_talk instead.

Files

Section titled “Files”
  • index.ts — Pi extension entry point.
  • package.json — standalone Pi package manifest.