Pi Sych

Visible project state · bounded delegation · human-owned decisions

Pi Sych

Pi Sych logo: inspectable files, bounded tasks, durable state, and human decisions

pipeline status coverage npm version npm downloads license

Pi Sych helps serious LLM-assisted projects remain understandable beyond one conversation. It is a small Pi package that keeps durable state in ordinary files, gives bounded tasks to short-lived model contexts, and keeps consequential decisions with the user.

Long chats mix accepted decisions with stale assumptions, rejected ideas, and review debate. That makes it easy for a later task to inherit context that was discussed but not adopted. Pi Sych takes a file-first approach: ordinary project files form the durable record, mechanical status reports changed content and dependency impact, and short-lived workers make clean-context delegation and independent review possible.

It is deliberately not an autonomous project manager or a hierarchy of persistent agents. It does not silently decide what a project means or promote model output into project truth.

At a glance, you describe the work in ordinary language; Pi Sych makes project files and task-specific guidance available and, when useful, helps the supervisor give one bounded task to a short-lived worker. You review the result and retain consequential decisions.

Pi Sych overview: a request can use task-specific skills and project files, optionally involve a focused worker, and return for human review and decision

This is an orientation, not a required sequence or a complete runtime contract. Direct work need not use a worker, skills guide rather than decide, and important decisions remain yours.

Pi Sych requires Node 26 or newer and is installed as a package for Pi. In this README, the supervisor is the model in your main Pi session. A worker is a separate, short-lived model process created for one bounded task. A skill is reusable model guidance, not a persistent agent. project_status is the mechanical tool that checks or acknowledges project state.

Quick start

Install Pi Sych:

pi install npm:pi-sych

A project can begin with the starter PROJECT.md. Add the starter SYNC.json when you want mechanical fingerprint and dependency tracking for project files.

Open the project in Pi and inspect its state:

/pi-sych-status

The status command reports tracked files, missing files, declared dependency impact, project-file problems, and pending review proposals. It does not decide whether a change is scientifically, conceptually, or editorially correct.

Worker setup is optional. Direct work with project files, local literature lookup, and skills does not require it. To dispatch bounded workers, configure a private model catalogue and initialize a worker directory. See configuration for worker setup.

A typical research workflow

Pi Sych does not impose a fixed workflow. One useful worked pattern is to separate independent review, revision, and verification into fresh contexts.

  1. You write or update a manuscript.
  2. The supervisor checks project state and launches an independent reviewer with the manuscript, relevant evidence, and a focused brief.
  3. You read the findings and decide which to accept, reject, prioritize, or clarify.
  4. The supervisor launches a fresh edit worker with the accepted corrections and only the source context needed to implement them.
  5. Another fresh worker verifies the revised manuscript against the original evidence and requirements.
  6. After you approve the result, Pi Sych can acknowledge the reviewed files and identify any dependent files that now require attention.

Detailed review and edit workflow: independent review, human decision, clean-context editing, fresh verification, and acknowledgement

The separation between review and editing is deliberate. Rejected alternatives and the arguments used to evaluate them do not normally belong in the writer’s context.

Suppose an earlier draft said X. A reviewer recommends Y, and you agree. A writer exposed to the entire debate may produce “Not X, but Y.”

A fresh edit worker given the accepted correction can instead produce the clean statement “Y.”

See the review and revision workflow for the worked pattern and its limits.

Project files as shared memory

Pi Sych does not treat the conversation transcript as the authoritative record of a project. Durable information belongs in ordinary files that a collaborator, another model, or a future session can inspect.

A project can begin with PROJECT.md and add other files only when they become useful. EVIDENCE.md is optional task evidence, not a required repository file.

File Typical purpose
PROJECT.md The objective, accepted direction, definition of done, previous action, and immediate next step.
EVIDENCE.md Important claims, sources, quotations, outputs, caveats, and material that may support the artifact.
DECISIONS.md Accepted methodological, conceptual, editorial, or architectural decisions and their reasons.
TODO.md Open work that has not yet been completed.
STYLE.md Stable terminology, spelling, venue conventions, and writing preferences.
SYNC.json Mechanical fingerprints, statuses, and declared relationships between files.
INBOX.md Unreviewed proposals that have not become authoritative project state.

These files are not an invitation to document everything. They preserve the information that another person or model would need to continue the work without reconstructing it from chat history.

For example, a small manuscript project might contain:

my-paper/
├── PROJECT.md
├── manuscript.qmd
├── DECISIONS.md
├── TODO.md
├── STYLE.md
└── SYNC.json

Why separate contexts?

A model can be influenced by everything in its current context window, including ideas that were considered and rejected. That can be useful during discussion, but it is not always useful during implementation.

Reviewing and revising a manuscript in one long conversation can cause the final prose to retain traces of the debate. Rejected alternatives may reappear as unnecessary qualifications, contrasts, defensive language, or explanations that the reader never needed.

Pi Sych can instead launch a short-lived worker in the default clean context mode with a deliberately selected packet:

Context files normally use project-relative paths. For a deliberately selected external input, the supervisor may instead supply a readable absolute path; it remains external in the worker packet. Worker-reported files remain project-relative.

A trajectory worker receives Pi’s active, compaction-aware supervisor branch ending before the assistant message containing that dispatch; it does not receive that message or any of its tool calls. This is useful when prior exploration materially helps the bounded assignment. It fails rather than silently becoming clean when the persisted branch boundary is unavailable. Context mode is independent of files, skills, model, tool mode, and research access.

In either mode the result returns to the supervisor, where the user decides what should happen next. Context selection is not an operating-system sandbox. The supervisor still chooses what the worker receives. Depending on the task, that may include editing tools, Bash, or remote-research tools.

What Pi Sych can help with

Skills are reusable guidance for a model, not persistent agents. Pi Sych initially exposes six broad skills and loads more specific guidance only when it is relevant.

Each umbrella skill contains small ordered task recipes. A recipe selects only the shared methods and local modules needed for that task:

Shared methods have no SKILL.md, so Pi still discovers exactly six public skills. The recipes are plain Markdown links, not a loader, inheritance system, or workflow controller. Project, user, and packaged versions can override one another without enlarging the public catalogue. See skill customization for the lookup order and customization paths.

Commands you can use

Human-facing commands:

Plannotator is a separately selectable human review adapter. It does not add a plan controller, automatically accept feedback, or promote generated output into project state.

Enable, disable, and narrow runtime resources

Pi Sych’s package enables its workbench and Plannotator extensions by default. Use pi config to disable either extension or use a package filter such as "extensions": ["extensions/workbench/index.ts"] to keep the core while omitting Plannotator; use "extensions": [] to load no package extensions while retaining package skills. Use --no-extensions for a session with no extensions. For a selected session, --tools allow-lists tools and --exclude-tools removes named tools; these control visible Pi tools, not host permissions. See configuration and the public contract.

Tools available to the supervising model

Pi Sych gives the supervisor three tools:

A separately installed and active read-only web tool can also remain available to the supervisor. Pi Sych does not register one. Direct read-only retrieval is appropriate for small or tightly connected exploration; dispatch is reserved for cases where independent context, breadth, specialization, or substantial execution materially helps.

In Pi’s terminal interface, a collapsed dispatch_worker call shows a compact task summary, requested model role (or catalog default), and effective context mode and timeout. Omitted context is presented as the clean default. Expand it with the configured tool-expansion shortcut (Ctrl+O by default) to inspect the raw submitted request. While it runs, its tool row shows a bounded live list of worker tool starts; it is activity visibility, not a worker console or result protocol.

These tools support a workflow; they do not decide what the workflow must be.

Research workers and local literature

The supervisor can call literature_search directly. A worker selected with the exact research skill also receives the same read-only tool; it is not added to other workers. The tool searches a local SQLite FTS5 database. Its v7 schema stores canonical metadata in papers and uses an external-content FTS5 table named papers_fts. It searches filepath, title, abstract, tags, and DOI; returns ranked metadata (title, nullable itemType, nullable or structured creators, year, and doi), a marked snippet from abstract, a score, and each source path resolved relative to the database. Pi Sych performs shallow creator shape checks but does not validate CSL semantics, format citations, or choose roles for a citation style. v6 databases require an external migration or rebuild before upgrading; first_author is not converted because it may be a lossy citation stem. See configuration for the schema, database resolution, and literatureDatabase.

Optional: enable workers

Direct work does not require a worker model catalogue. To let the supervisor launch separate workers, first create a private catalogue. A common user-level setup begins with:

mkdir -p ~/.config/pi/pi-sych
$EDITOR ~/.config/pi/pi-sych/models.json

Then request a worker dispatch. If the worker directory is not yet initialized, Pi Sych reports the exact bootstrap command with the resolved package and configuration paths. Run that command once.

The catalogue contains provider model identifiers and remains outside the package. Pi Sych does not ship credentials, rank providers, or choose models for you. The bootstrap operation is explicit and does not silently modify your home directory during ordinary use.

See configuration for model roles, worker directories, canonical paths, skill overrides, and optional remote research.

How it works

Pi Sych supplies a few mechanical pieces rather than a general orchestration system:

This is intentionally not an autonomous project manager. It does not silently turn model output into evidence, citations, release state, approval, or project truth.

Limits and responsibilities

Pi Sych provides context and process boundaries, not proof that an artifact is correct.

Inspect sources, generated outputs, external results, and package behaviour before relying on them for consequential work.

Why I built this

Pi Sych grew out of my move from OpenCode to Pi. I was attracted to Pi because its core is small and its extension model leaves room for users to build the workflow they need.

I did not want to reproduce a large orchestration framework or maintain a roster of persistent specialist agents. Other extensions already explore those approaches, and they may be a better fit for people who want them. I wanted to see how far a smaller set of mechanisms could go: explicit project files, normal Pi skills, short-lived workers, and human review.

The project was also shaped by experience with memory systems. Many of those tools are useful, and Pi Sych is not an argument that they should not exist. My difficulty was that memories could become large, opaque, or closely tied to one model and one conversation. Important findings were not always easy for another researcher, collaborator, or model to inspect.

Pi Sych therefore treats ordinary files as the durable record. The conversation remains useful working space, but accepted evidence, decisions, and project direction should be written somewhere that can be reviewed and handed over.

This is an experiment in keeping that approach useful without adding more machinery than the problem appears to require.

For supervising models

When working in a Pi Sych project:

See architecture for the complete runtime contract.

Status and contributions

Pi Sych is alpha software. Its current design reflects one approach to organizing long-running LLM-assisted work, and it will not suit every project.

Issues and contributions are welcome, especially from researchers, writers, analysts, and maintainers using it outside conventional software-development workflows.

Useful contributions include:

See contributing before proposing code or release changes.

Detailed documentation