npm - @pipemd-core/pipemd - Versions diffs - 1.0.0 → 1.1.0 - Mend

@pipemd-core/pipemd 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md +25 -0
package/CONTRIBUTING.md +73 -0
package/README.md +192 -408
package/dist/index.js +727 -32
package/dist/plugins/opencode-server.js +23 -1
package/package.json +9 -4

package/README.md CHANGED Viewed

@@ -1,535 +1,319 @@
 <p align="center">
-  <picture>
-    <img src="PipeMD.jpg" alt="PipeMD Banner" width="100%" style="border-radius: 8px; max-width: 800px;" />
-  </picture>
+  <img src="PipeMD.jpg" alt="PipeMD" width="100%" style="border-radius: 8px; max-width: 800px;" />
 </p>
 <h1 align="center">PipeMD</h1>
 <p align="center">
-  <strong>The Dynamic Context Harness for AI Coding Agents.</strong><br>
-  <em>Never let Claude, Cursor, or Aider hallucinate on stale project state again.</em>
+  <strong>Real-time project context for AI coding agents.</strong><br>
+  Zero git churn. Always fresh. Works with any agent.
 </p>
 <p align="center">
-  <a href="#the-magic-render-on-read"><img src="https://img.shields.io/badge/Architecture-Render--on--Read%20%2B%20Smart%20Injection-blue?style=flat-square" alt="Architecture"></a>
-  <a href="#prompt-cache-optimization"><img src="https://img.shields.io/badge/Prompt%20Caching-Optimized-success?style=flat-square" alt="Prompt Cache Optimized"></a>
-  <a href="#compatibility"><img src="https://img.shields.io/badge/Works%20With-Claude%20%7C%20Cursor%20%7C%20Aider%20%7C%20Gemini-orange?style=flat-square" alt="Works With"></a>
-  <a href="https://opensource.org/licenses/ISC"><img src="https://img.shields.io/badge/License-ISC-purple?style=flat-square" alt="License"></a>
+  <a href="https://www.npmjs.com/package/@pipemd-core/pipemd"><img src="https://img.shields.io/npm/v/@pipemd-core/pipemd?style=flat-square" alt="npm"></a>
+  <a href="https://opensource.org/licenses/ISC"><img src="https://img.shields.io/badge/license-ISC-purple?style=flat-square" alt="License"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square" alt="Node">
+  <img src="https://img.shields.io/badge/works_with-Claude%20%7C%20Gemini%20%7C%20OpenCode%20%7C%20Cursor%20%7C%20Aider-orange?style=flat-square" alt="Compatibility">
 </p>
 ---
-## 🛑 The Problem: Stale Context & Git Churn
-AI coding agents need to know your current project state (git status, lint errors, TODOs) to be effective.
-Currently, you have two bad options:
-1. **Static Files:** You give the AI a `README.md` or `CONTEXT.md`. It goes stale after your first commit. The AI hallucinates.
-2. **Automated Scripts:** You run a script to update `CONTEXT.md` continuously. Your `git status` is ruined, merge conflicts run rampant, and your file history is a mess.
-## ⚡ The Solution: PipeMD
-PipeMD uses a brilliantly simple OS-level trick: **Named Pipes**.
-It creates an `AGENTS.md` file in your root directory that is actually a `mkfifo` pipe. When your AI agent attempts to read it, PipeMD intercepts the read, executes your bash scripts concurrently, injects real-time project state into a clean template, and streams it straight to the AI.
-*   **Zero Git Churn:** The template is clean. The live output is completely ephemeral.
-*   **Always Fresh:** The AI gets up-to-the-millisecond data *only* exactly when it reads.
-*   **Secure:** Commands run from your own `config.yml` — no need to grant the AI unsafe terminal execution permissions.
-But named pipes only solve half the problem: most AI agents read their context file only once at session start, then cache it. PipeMD's **Smart Context Injection** solves this by installing lightweight hooks that inject fresh, scoped context directly into the agent's working memory on every tool call — crew locks before edits, file errors before edits, validation results after edits, and status updates during idle time.
-PipeMD is a render-on-read daemon that uses OS-level named pipes (mkfifo) to serve real-time project context to
-AI coding agents. The key innovation: the file the AI reads (AGENTS.md or AI_CONTEXT.md) is itself a named pipe --
- when the AI opens it, the daemon intercepts the read, executes all configured shell commands concurrently,
-assembles the output into a Markdown template, prepends any base instructions (from `.pipemd/base.md`), and streams it back.
-Data flow:
-The Full Data Flow
-Agent tool call
-  → Harness hook fires (Claude: settings.json entry, OpenCode: plugin handler, Gemini: settings.json entry)
-    → `pmd inject --trigger <X> --file <Y> --session <Z> --format <F>`
-      → `resolveInjections()` in injection-engine.ts
-        → Loads injection.yml config
-        → Gets rules for trigger
-        → For each rule, runs the resolver (crew-status, file-errors, git-context, etc.)
-        → `checkInjectionStatus()` in dedup.ts -- checks `.pipemd/cache/injected/<session>.json`
-        → If "unchanged": skip (no payload returned)
-        → If "new"/"changed": `recordInjection()` -- writes hash to `.pipemd/cache/injected/<session>.json`
-        → Returns `InjectionPayload[]`
-      → `bumpInjectStats()` in statusline-data.ts -- writes `.pipemd/.inject-stats.json`
-      → Output in requested format (plain, claude-hook JSON, gemini JSON)
-  → OpenCode only (plugin side):
-    → Also calls `pushEvent()` which writes `.pipemd/.tui-stats.json`
-    → TUI panel reads `.pipemd/.tui-stats.json` every 2s
-  → `pmd statusline` (called by Claude Code automatically, or Gemini AfterAgent):
-    → Reads `.pipemd/.inject-stats.json`, `.pipemd/.status.json`, `.pipemd/.crew-status.json`
-    → Renders status line to developer
-.pipemd/base.md (committed, agent's own instructions)
-    ─────────────────────────────────────────────────────┐
-                                                        │
-.pipemd/template.md (committed, static)                 │
-    → daemon reads tags like <!-- pmd: git-status -->    │
-    → runs commands concurrently via Promise.allSettled   │
-    → assembles rendered Markdown                        │
-    → composes: base + "---\n\n<!-- pmd-context -->\n" + rendered template
-    → serves via named pipe (AGENTS.md) on read          │
+## TL;DR
-Two operational modes:
+AI coding agents need to know your project state — git status, lint errors, TODOs, who else is editing. Static context files go stale. Auto-updated files pollute your git history.
-1. Pipe Mode (macOS, Linux, WSL): Uses mkfifo to create named pipes. The root context file IS the pipe. Zero git
-churn. Supports bidirectional write-back — edits above `<!-- pmd-context -->` are saved to `base.md`,
-edits outside `<!-- pmd: -->` blocks in the template section are de-rendered and saved back to `template.md`.
+**PipeMD makes `AGENTS.md` a named pipe.** When your AI reads it, PipeMD intercepts the read, runs your scripts concurrently, and streams live context straight to the agent. Zero files change on disk. The output is completely ephemeral.
-2. Legacy Mode (native Windows fallback): Uses chokidar to watch template.md, writes rendered output to a regular
-file marked read-only (0o444). This causes git churn. Also supports write-back via file watcher.
+---
+## Quick Start
----
+```bash
+npm install -g @pipemd-core/pipemd
+pmd init      # Interactive setup — detects your ecosystem and harness
+pmd start     # Spawns the daemon — your AI now gets live context
+```
+Or run without installing:
-## ✨ Features: Built for Vibe Coding
+```bash
+npx @pipemd-core/pipemd init
+npx @pipemd-core/pipemd start
+```
-- **🔌 Universal AI Compatibility:** Claude Code, Gemini CLI, OpenCode, Cursor, Aider—it doesn't matter. If your AI agent can read a Markdown file, it works flawlessly with PipeMD. No plugins required.
-- **🏗️ Architecture Maps:** PipeMD generates live Mermaid dependency graphs (`graph TD`) for 7 ecosystems. AI agents get an instant mental model of your project's module structure — no need to read dozens of files to understand how things connect.
-- **🦾 Self-Improving Context:** Because your fetch scripts and templates live as plain text in `.pipemd/`, you can simply ask your AI to *edit its own context harness* to feed itself better data on the fly. Meta-coding at its finest.
-- **🛡️ Non-Destructive Setup:** Worried about losing your carefully crafted system prompts? `pmd init` is completely non-destructive. If an `AGENTS.md` or `AI_CONTEXT.md` already exists, PipeMD saves your instructions to `.pipemd/base.md` and keeps them separate from the template. Nothing gets overwritten.
-- **👻 Ephemeral & Git-Clean:** Output is generated in memory and streamed via the named pipe. The target file is automatically `.gitignored` and vanishes the second you stop the daemon. Zero commit noise.
-- **🧠 Prompt Cache Optimized:** Static rules stay at the top; highly volatile data (like `git status`) is anchored to the bottom. Your LLM prefix cache stays warm, giving you instant responses and saving massive amounts of tokens.
-- **🏎️ Concurrent & Fail-Safe:** Data-gathering scripts run concurrently so your AI isn't left waiting. Built-in 10-second timeouts and isolated failures mean one broken script won't crash your entire context stream.
-- **🤖 Smart Scaffolding:** Run `pmd init` and watch it automatically detect your ecosystem (Node, Python, TS, etc.) to scaffold the exact bash scripts you need to hit flow state immediately.
-- **🎯 Smart Context Injection:** Goes beyond render-on-read. Hooks inject fresh, scoped context into your agent's working memory on every tool call — crew locks, file errors, validation results — so the agent always knows the current state even mid-session.
+> **Bash required.** Windows users: use WSL or Git Bash.
 ---
-## 🚀 Quick Start
+## What Your AI Sees
-Get your dynamic context harness running in under 60 seconds:
+When your agent reads `AGENTS.md`, it gets a live-rendered Markdown document — not a static file. Here's what that looks like:
-```bash
-# Option 1: Global Install
-npm install -g pipemd
-pmd init
-pmd start
-# Option 2: Run via NPX (No global install required)
-npx pipemd init
-npx pipemd start
-```
+```markdown
+# AI Context — powered by PipeMD
-> **Bash Required:** PipeMD's context scripts rely on a Bash environment. Windows users must use WSL or Git Bash.
+> This file refreshes automatically. Content inside `<!-- pmd: -->` blocks
+> is read-only — everything else is yours to edit.
-*The setup wizard will auto-detect your ecosystem and configure the optimal `.pipemd/template.md` and context scripts for your workspace.*
+## Architecture
+<!-- pmd: arch -->
+graph TD
+    src/index --> chalk
+    src/index --> commander
+<!-- /pmd -->
-*The setup wizard will also ask how to deliver context — **Active** (recommended for most agents) or **Passive** (for Cursor, Aider, or CI).*
+## Project Structure
+<!-- pmd: tree -->
+.
+├── src/
+│   ├── commands/
+│   ├── core/
+│   └── index.ts
+├── tests/
+└── package.json
+<!-- /pmd -->
----
+## Git Status
+<!-- pmd: git-status -->
+## main...origin/main
+ M src/index.ts
+?? CONTRIBUTING.md
+<!-- /pmd -->
-## 🧠 How the Magic Works
-PipeMD bridges the gap between your static developer notes and the dynamic reality of your repository.
-```text
-┌────────────────────────────────────────────────────────┐
-│  1. You edit: .pipemd/template.md                      │
-│  (Clean, committed to Git, your source of truth)       │
-│                                                        │
-│  ## Rules                                              │
-│  Never use `any` in TypeScript.                        │
-│                                                        │
-│  ## Live Diff                                          │
-│  <!-- pmd: diff -->   <── PipeMD placeholder           │
-└────────────────────────┬───────────────────────────────┘
-                         │
-        (Agent reads AGENTS.md from root)
-                         │
-┌────────────────────────▼───────────────────────────────┐
-│  2. PipeMD Daemon (Intercepts read)                    │
-│  Prepends base.md + separator, renders template...     │
-└────────────────────────┬───────────────────────────────┘
-                         │
-┌────────────────────────▼───────────────────────────────┐
-│  3. The AI receives: (Streamed instantly)              │
-│                                                        │
-│  [Base instructions from .pipemd/base.md]              │
-│                                                        │
-│  ---                                                   │
-│                                                        │
-│  <!-- pmd-context -->                                  │
-│                                                        │
-│  ## Rules                                              │
-│  Never use `any` in TypeScript.                        │
-│                                                        │
-│  ## Live Diff                                          │
-│  + const daemon = new PipeMD();                        │
-│  - const daemon = null;                                │
-└────────────────────────────────────────────────────────┘
+## Type Errors
+<!-- pmd: type-check -->
+No type errors
+<!-- /pmd -->
 ```
-> **Note for Windows Users:** Native Windows lacks `mkfifo`. PipeMD falls back to **Legacy Mode**, gracefully watching your template and writing read-only (`0o444`) updates.
+Every block is live. The AI reads up-to-the-millisecond data — no stale context, no hallucinations.
 ---
-## 🧠 Smart Context Injection
-Most AI coding agents load their context file once at session start and never re-read it. This means even with named pipes serving fresh data, the agent works with stale information for the entire session.
-PipeMD's Smart Context Injection solves this by installing per-harness hooks that inject relevant context **on every tool call**, scoped to what the agent is about to do:
+## How It Works
-```text
-Agent is about to READ a file:
-  → Hook fires → "Crew: this file is unclaimed. Safe to read."
+```
+┌─────────────────────────────────────────────┐
+│  .pipemd/template.md                         │
+│  Your committed template with pmd: tags      │
+│                                              │
+│  ## Live Diff                                │
+│  <!-- pmd: diff-stat -->  ← placeholder      │
+└──────────────────────┬──────────────────────┘
+                       │
+       AI agent reads AGENTS.md from root
+                       │
+┌──────────────────────▼──────────────────────┐
+│  PipeMD Daemon intercepts the read           │
+│  1. Reads template.md                        │
+│  2. Runs all scripts concurrently            │
+│  3. Injects results into pmd: blocks         │
+│  4. Prepends base.md (your custom rules)     │
+│  5. Streams the result to the agent          │
+└──────────────────────┬──────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────┐
+│  The AI receives a complete, live document   │
+│  No file written to disk. Zero git churn.    │
+└─────────────────────────────────────────────┘
+```
-Agent is about to EDIT src/foo.ts:
-  → Hook fires → "File src/foo.ts: claimed by OpenCode (cr_abc123) 45s ago
-                   Type-check: 2 errors in this file
-                   Last edit: you, 2 minutes ago"
+Two operational modes:
-Agent just EDITED src/foo.ts:
-  → Background validation triggers → next tool call shows:
-     "After your edit to src/foo.ts: 1 error remaining (was 2)"
+| Mode | Platform | Mechanism |
+|------|----------|-----------|
+| **Pipe Mode** | macOS, Linux, WSL | `mkfifo` named pipes — zero disk writes |
+| **Legacy Mode** | Native Windows | File watcher + read-only output |
-Agent has been idle for 10 seconds:
-  → "Crew: Gemini session joined. Git: 1 new uncommitted file."
-```
+---
-### Three Delivery Modes
+## Delivery Modes
-During `pmd init`, choose how PipeMD delivers context to your agent:
+PipeMD can deliver context two ways: passively (the AI reads the pipe at session start) or actively (hooks inject scoped context on every tool call).
 | Mode | How it works | Best for |
 |------|-------------|----------|
-| **Active** (recommended) | Hooks installed. Fresh context injected on every tool call. Zero config. | Claude Code, OpenCode, Gemini CLI |
-| **Passive** | Context rendered to file/pipe. Agent reads at session start. No hooks. | Cursor, Aider, CI/CD |
+| **Passive** | Context rendered to pipe/file. Agent reads at session start. | Cursor, Aider, CI/CD |
+| **Active** | Hooks inject fresh context on every tool call. Zero config. | Claude Code, OpenCode, Gemini CLI |
 | **Expert** | Full control over injection rules via `.pipemd/injection.yml`. | Teams with custom workflows |
-### What gets injected
 Active mode injects context at four moments:
-| Trigger | Sources |
-|---------|---------|
-| **Before Read** | Crew status (who's working, any conflicts) |
-| **Before Edit** | Crew locks for target file, lint/type errors for target file, git context |
-| **After Edit** | Async validation: run lint + type-check on edited file, deliver results on next call |
-| **On Idle** | Crew status changes, git delta since last check |
-All injection is **deduplicated** — unchanged data is skipped, saving tokens. Results are cached with per-source TTL for sub-5ms hook latency.
-### The injection.yml file (Expert mode)
+| Trigger | What the AI gets |
+|---------|-----------------|
+| Before Read | Crew status — who's working, any conflicts |
+| Before Edit | File-specific: crew locks, lint/type errors, git context |
+| After Edit | Async validation results (lint + type-check on edited file) |
+| On Idle | Crew changes, git delta since last check |
-```yaml
-# .pipemd/injection.yml — customize injection rules
-delivery: expert
-rules:
-  before-edit:
-    - source: crew-locks
-      scope: target-file
-    - source: file-errors
-      scope: target-file
-      max-lines: 5
-  after-edit:
-    - source: validate-file
-      scope: target-file
-      async: true
-```
+All injection is deduplicated — unchanged data is skipped, saving tokens.
 ---
-## 🛠️ Commands
+## Features
-PipeMD is designed to stay out of your way.
-| Command | Description |
-|---------|-------------|
-| `pmd init` | **Interactive setup:** Auto-detects ecosystem + harnesses, scaffolds the template, scripts, and `.gitignore` entries. `--headless` for CI. |
-| `pmd start` | **Spawns daemon:** Creates the named pipe(s) and silently serves context on read. Daemon detaches and stores its PID in `.pipemd/.daemon.pid`. |
-| `pmd stop` | **Kills daemon:** Safely removes all pipes and cleans up the PID file. |
-| `pmd restart` | **Stop + start:** Reloads `config.yml` (use after editing config). |
-| `pmd status` | **System health:** Shows active daemon PID, watched files, active pipes, and recent log lines. |
-| `pmd run` | **One-shot render:** Renders the resolved template to `stdout` or a file (`-o`). No daemon required — ideal for CI and pre-commit hooks. |
-| `pmd refresh` | **Sync scripts:** Pulls newer bundled scripts into `.pipemd/scripts/`, offers newly added ones (e.g. **Crew Activity**), and rewrites `config.yml`. |
-| `pmd doctor` | **Diagnose:** Checks for `mkfifo`, stale PIDs, missing scripts, and config drift. |
-| `pmd crew` | **Multi-harness coordination:** Register agents, claim files, surface conflicts (see below). |
-| `pmd uninstall` | **Clean removal:** Restores the original context file and strips PipeMD artifacts. |
+- **Universal compatibility** — Claude Code, Gemini CLI, OpenCode, Cursor, Aider. If it can read Markdown, it works.
+- **Architecture maps** — Live Mermaid dependency graphs for 7 ecosystems. The AI gets an instant mental model of your project.
+- **Smart Context Injection** — Hooks deliver scoped, file-specific context on every tool call, not just at session start.
+- **Crew coordination** — Multiple agents working the same repo see each other's file claims and get conflict warnings in real time.
+- **Bidirectional write-back** — AI edits outside `<!-- pmd: -->` blocks persist to disk. The agent can tune its own context.
+- **Prompt cache optimized** — Static rules at the top, volatile data at the bottom. Your LLM prefix cache stays warm.
+- **Non-destructive setup** — Existing `AGENTS.md` content is preserved to `.pipemd/base.md`. Nothing gets overwritten.
+- **Self-improving** — Scripts and templates are plain text in `.pipemd/`. Ask your AI to edit its own context harness.
 ---
-## 👥 Crew: Coordinating Parallel Agents
-When several AI harnesses work the same repo at once (e.g. OpenCode with 8
-sub-agents plus a Claude CLI session), they edit blind to each other. PipeMD
-Crew turns the live context file into a shared awareness layer.
-The model is **Harness → Coordinator → sub-agents**: one coordinator per
-harness, with PipeMD as the neutral meta-coordinator that renders the union.
+## Commands
 | Command | Description |
 |---------|-------------|
-| `pmd crew join` | Register this agent (`--role coordinator\|worker`, `--label`). |
-| `pmd crew claim <file…>` | Mark files as being worked on (`--note "<task>"`). |
-| `pmd crew release <file…>` | Release claims (`--all` for everything). |
-| `pmd crew note "<text>"` | Post the current task/status. |
-| `pmd crew status` | Show the live crew tree. |
-| `pmd crew leave` | Deregister this agent. |
-| `pmd crew install-hooks` | Auto-wire harness hooks so edits self-report. |
-**Two signal layers.** *Passive* (always on, zero cooperation): observed git
-churn and running harness processes. *Active* (opt-in): the `pmd crew` CLI,
-fired automatically by `pmd crew install-hooks`:
-| Harness | Events | Wired into |
-|---------|---------|------------|
-| Claude Code | `SessionStart` → join, `PreToolUse` → heartbeat, `PostToolUse` → claim, `SubagentStart/Stop` → worker lifecycle, `SessionEnd` → leave, `statusLine` → live PipeMD statusline | `.claude/settings.json` |
-| OpenCode | `tool.execute.before` → heartbeat, `tool.execute.after` → claim, `session.idle` → keep-alive | `.opencode/plugin/pmd-crew.js` |
-| Gemini CLI | `BeforeTool` → heartbeat, `AfterTool` → claim, `SessionStart`/`AfterAgent` → live PipeMD statusline via hook `systemMessage` (v0.26+) | `.gemini/settings.json` |
-| Cursor / Aider / others | no edit-event API | injected Coordination Protocol text |
-The crew block (`<!-- pmd: crew -->`) is rendered into every harness's context
-file, so a `⚠️ CONFLICT` — two agents claiming the same file — appears for
-everyone within one broadcast cycle. Add it via `pmd refresh` (select **Crew
-Activity**) or pick it during `pmd init`.
-**Claude Code statusline.** OpenCode gets a live TUI sidebar panel; Claude Code
-has no pluggable panel, so `install-hooks` instead registers a `statusLine` that
-renders the same dev-side state — daemon up/down, crew session count, passive
-agents, file conflicts, context size, injection counts — on a single line at the
-bottom of the Claude Code UI. It is invoked automatically by the harness on every
-update; a pre-existing custom `statusLine` is never overwritten. Preview it any
-time with `pmd statusline --plain`.
+| `pmd init` | Interactive setup. Detects ecosystem + harnesses, scaffolds everything. Use `--headless` for CI. |
+| `pmd start` | Spawn the daemon. Creates named pipes and serves context on read. |
+| `pmd stop` | Kill the daemon. Removes pipes and cleans up. |
+| `pmd restart` | Stop + start. Reloads config after edits. |
+| `pmd status` | Daemon health: PID, active pipes, recent log lines. |
+| `pmd run` | One-shot render to stdout or file (`-o`). No daemon needed — ideal for CI. |
+| `pmd refresh` | Pull newer bundled scripts. Add newly available blocks without re-init. |
+| `pmd doctor` | Diagnose: `mkfifo`, stale PIDs, missing scripts, config drift. |
+| `pmd crew` | Multi-agent coordination: join, claim files, surface conflicts. See below. |
+| `pmd uninstall` | Clean removal. Restores original context file. |
 ---
-## 🏗️ What Gets Generated?
+## What Gets Generated
-PipeMD keeps your root directory pristine. Everything lives in `.pipemd/`.
+Everything lives in `.pipemd/`. Your root directory stays clean.
-```text
+```
 your-project/
 ├── .pipemd/
-│   ├── config.yml           # ✅ Committed — pipe routing + script definitions
-│   ├── base.md              # ✅ Committed — agent's own instructions (prepended to context)
-│   ├── template.md          # ✅ Committed — 📝 edit this! The static wrapper for your context.
-│   ├── scripts/             # ✅ Committed — Bash/Python/Node data-gathering scripts
-│   │   ├── architecture/    #   🏗️ Architecture map (Mermaid graph TD)
-│   │   ├── project/         #   Project structure, deps, todos
-│   │   ├── git/             #   Git state scripts
+│   ├── config.yml           # Committed — script definitions + pipe routing
+│   ├── base.md              # Committed — your custom AI instructions
+│   ├── template.md          # Committed — edit this! Tags + static content
+│   ├── injection.yml        # Committed — injection rules (active/expert mode)
+│   ├── scripts/             # Committed — data-gathering scripts by category
+│   │   ├── architecture/    #   Mermaid dependency graphs
+│   │   ├── project/         #   Tree, deps, TODOs
+│   │   ├── git/             #   Git state
 │   │   ├── quality/         #   Type checking, linting, tests
-│   │   └── crew/            #   Crew coordination block
-│   ├── injection.yml       # ✅ Committed — Smart injection rules (active/expert mode)
-│   ├── cache/              # (Gitignored) Per-source render cache for injection
-│   │   ├── sources/        #   Cached command outputs with TTL
-│   │   ├── validation/     #   Per-file validation results
-│   │   └── injected/       #   Per-session dedup records
-│   ├── live/                # (Gitignored) Ephemeral named pipes
-│   ├── crew/                # (Gitignored) Per-agent coordination ledger (JSON)
-│   ├── daemon.log           # (Gitignored) Daemon activity log
-│   └── .daemon.pid          # (Gitignored) Running daemon's PID
-├── AGENTS.md                # (Gitignored) 🏴‍☠️ The Named Pipe. The AI reads this.
-└── .gitignore               # Updated automatically by `pmd init`
+│   │   └── crew/            #   Crew coordination
+│   ├── cache/              # Gitignored — render cache for injection
+│   ├── live/                # Gitignored — ephemeral named pipes
+│   └── crew/                # Gitignored — per-agent coordination ledger
+├── AGENTS.md                # Gitignored — the named pipe your AI reads
+└── .gitignore               # Updated automatically by pmd init
 ```
-> Only `config.yml`, `base.md`, `template.md`, and `scripts/` are committed —
-> everything your team needs to reproduce the harness, and nothing ephemeral.
+Only `config.yml`, `base.md`, `template.md`, `injection.yml`, and `scripts/` are committed — everything your team needs, nothing ephemeral.
 ---
-## 🎯 The Template (`.pipemd/template.md`)
+## Configuration
-This is your source of truth. Edit it, commit it, share it with your team. Use `<!-- pmd: command_name -->` to tell the daemon where to inject live data.
+### The Template (`.pipemd/template.md`)
-The served context file is composed of two parts: **base instructions** (from `.pipemd/base.md`) and the **rendered template**. They are separated by `---` + `<!-- pmd-context -->`. AI edits above the separator go back to `base.md`; edits in the template section outside `<!-- pmd: -->` blocks go back to `template.md`.
+Your source of truth. Use `<!-- pmd: command_name -->` tags where you want live data injected.
 ```markdown
-# 🏴‍☠️ AI Context — powered by PipeMD
-> **🤖 PipeMD Context File**
->
-> This file is maintained by PipeMD. It refreshes automatically.
->
-> - Content inside `<!-- pmd: -->` blocks is **read-only** — the daemon overwrites it every cycle.
-> - Everything else is **yours to edit**. Edits persist via bidirectional write-back.
-> - Edits above `<!-- pmd-context -->` route to `.pipemd/base.md`. Edits below it route to `.pipemd/template.md`.
-> - For full details, read `.pipemd/AI_SETUP_PIPEMD.md`.
-## 🏗️ Architecture
-<!-- pmd: arch -->
-```
+# AI Context — powered by PipeMD
-```
+## Architecture
+<!-- pmd: arch -->
 <!-- /pmd -->
-## 📁 Project Structure
+## Project Structure
 <!-- pmd: tree -->
 <!-- /pmd -->
-## 📝 TODOs
-<!-- pmd: todos -->
-<!-- /pmd -->
 ---
-## 🚨 Volatile State
+## Volatile State
 <!-- pmd: diff-stat -->
 <!-- /pmd -->
 ```
-*(Notice how volatile data like `diff-stat` is placed at the bottom? This ensures your LLM Prompt Cache hits for the top 90% of the document!)*
----
+Volatile data at the bottom keeps your LLM prompt cache warm.
-## ⚙️ Configuration (`config.yml`)
+### Config (`config.yml`)
-The `config.yml` connects the `pmd:` tags in your template to the actual scripts that fetch the data.
+Connects template tags to the scripts that fetch the data.
 ```yaml
 version: "1.0"
-# ⚠️ Security Warning: PipeMD executes the commands below exactly as written.
-# Do not run PipeMD in an untrusted repository.
-# Optional: Base instructions file, prepended to the served context.
-# AI edits to the base section are written back here.
 base: ".pipemd/base.md"
 commands:
   arch: "bash .pipemd/scripts/architecture/arch.sh"
   tree: "bash .pipemd/scripts/project/tree.sh"
   diff-stat: "bash .pipemd/scripts/git/diff-stat.sh"
-  todos: "bash .pipemd/scripts/project/find-todos.sh"
 pipes:
-  - file: "AGENTS.md"               # The file the AI Agent reads
-    render: ".pipemd/template.md"   # The template to populate
+  - file: "AGENTS.md"
+    render: ".pipemd/template.md"
 ```
-### Shared Scripts
-Because `.pipemd/scripts/` is committed to git, your whole team gets the exact same context harness. Drop any language script in there (`.sh`, `.py`, `.js`) to pull test results, type-check errors, or database schemas.
+> **Security:** PipeMD executes commands from `config.yml` as-is. Do not run in untrusted repositories.
 ---
-## 🤖 For AI Agents
-If you are an AI agent reading a PipeMD context file, here is the contract:
-**Reading.** The file you read (`CLAUDE.md`, `AGENTS.md`, …) is a *live render*.
-Prefer the data inside `<!-- pmd: -->` blocks over running your own shell
-commands — it is current as of the moment you opened the file.
+## Crew: Multi-Agent Coordination
-**Editing.** The file is split by a `<!-- pmd-context -->` separator:
+When multiple AI agents work the same repo, PipeMD Crew gives them shared awareness — file claims, conflict detection, and status broadcasts — rendered into every agent's context file.
-| Where you edit | Where it persists | Notes |
-|---|---|---|
-| Above the separator | `.pipemd/base.md` | Your own rules and instructions. |
-| Below it, *outside* `<!-- pmd: -->` blocks | `.pipemd/template.md` | Section headers, notes, checkboxes. |
-| *Inside* a `<!-- pmd: -->` block | **nowhere** | Overwritten every refresh cycle — never edit here. |
-**Self-improvement.** Because the harness is plain text, you can tune your own
-context: add/remove `<!-- pmd: -->` blocks in `.pipemd/template.md`, change
-which scripts run in `.pipemd/config.yml`, or adjust the token profile. See
-`.pipemd/AI_SETUP_PIPEMD.md` (scaffolded into every project) for the full guide.
-**Working alongside other agents.** If a **Crew Activity** block is present,
-read it before editing — it lists which files other agents hold. A
-`⚠️ CONFLICT` line means another agent claimed a file you are about to touch;
-treat it as blocking. Announce your own work with `pmd crew claim <file>` and
-`pmd crew note "<task>"` (or let the installed hooks do it automatically).
+```bash
+pmd crew join --role coordinator --label "Claude"
+pmd crew claim src/auth.ts --note "refactoring login"
+pmd crew note "rewriting the auth middleware"
+pmd crew release src/auth.ts
+pmd crew leave
+```
-**Smart Injection.** If the project uses Active or Expert delivery mode, PipeMD hooks inject fresh context into your working memory on every tool call. You'll see messages like `[pmd:crew-locks → src/foo.ts]` before edits and `[pmd:validate-file → src/foo.ts]` after edits. This data is:
+| Command | Description |
+|---------|-------------|
+| `pmd crew join` | Register this agent (`--role`, `--label`) |
+| `pmd crew claim <file>` | Mark files as being worked on |
+| `pmd crew release <file>` | Release claims (`--all` for everything) |
+| `pmd crew note "<text>"` | Post current task/status |
+| `pmd crew status` | Show live crew tree |
+| `pmd crew leave` | Deregister this agent |
+| `pmd crew install-hooks` | Auto-wire harness hooks for self-reporting |
-- **Scoped**: you only see context relevant to the file you're about to touch
-- **Deduplicated**: repeated unchanged data is silently skipped
-- **Cache-backed**: hook latency is under 5ms
+Crew hooks are available for Claude Code, OpenCode, and Gemini CLI — agents automatically report their activity without manual commands.
 ---
-## 🔒 Safety & Edge Cases Handled
-> **⚠️ Security Warning:** PipeMD executes the commands in `config.yml` exactly as written. Do not run PipeMD in an untrusted repository.
-Building a background daemon that streams live data into AI systems requires aggressive safety guardrails. PipeMD includes:
+## Known Limitations
-*   **10-Second Timeouts:** No runaway `grep` commands hanging your AI. If a script stalls, it gets killed.
-*   **Isolated Rendering:** Built on `Promise.allSettled`. If your `test-summary.sh` fails, the error is rendered *in-place* inside the markdown file, and the rest of the document loads perfectly.
-*   **EPIPE Catching:** If Claude Code closes the stream mid-read to save tokens, PipeMD safely catches the `EPIPE` disconnect without crashing the daemon.
-*   **Stale PID Recovery:** If your machine forcefully reboots, `pmd start` instantly detects the dead process, cleans up the old pipes, and starts fresh.
+### FIFO (Named Pipe) Read Errors with Some Agents
----
+Agents backed by Effect.js (e.g. OpenCode) may fail to read pipe-mode context files with errors like:
-## 🧑‍💻 For Developers
+```
+Unknown: FileSystem.readAlloc (30)
+```
-PipeMD is strict TypeScript, **ESM-only** (imports use `.js` extensions,
-`NodeNext` resolution), built with `tsup`, and targets Node.js 18+.
+**Root cause:** These agents use Effect.js's `FileSystem.readAlloc`, which expects regular file semantics (seekable, known size). PipeMD's named pipes are FIFOs — stream-oriented, unseekable, and `stat()` reports size 0. When the agent passes `limit`/`offset`, Effect.js tries to `seek()` on the FIFO and fails.
-### Build & test
+**Mitigation:** The PipeMD OpenCode plugin automatically detects FIFO reads and redirects them to a regular temp file rendered by `pmd run`. This should resolve the error for most setups. Make sure your plugin is up to date (`pmd crew install-hooks` or `pmd init`).
-```bash
-pnpm install       # Install dependencies
-pnpm build         # Production build → dist/ (run before any e2e test)
-pnpm dev           # Watch mode — rebuilds on change
-tsc --noEmit       # Type-check only
-pnpm test          # Full suite: unit → e2e → bidir → scripts → arch → compose → crew
-pnpm test:unit     # reverseInject logic (pure Node, no build needed)
-pnpm test:crew     # Crew coordination lifecycle (needs build)
-```
+**Fallback workaround:** If the plugin fix doesn't cover your case, switch the affected pipe to legacy mode in `.pipemd/config.yml`:
-There is no test framework: unit tests use `node:assert`, e2e tests are Bash
-scripts with custom assertion helpers in `tests/`.
-### Source layout
-```text
-src/
-├── index.ts            # CLI entry — Commander program, registers all commands
-├── config.ts           # PipeConfig type + DEFAULT_CONFIG
-├── commands/            # One file per command: init, start, stop, restart,
-│                        #   status, run, refresh, doctor, uninstall, crew
-└── core/
-    ├── daemon.ts        # Daemon loop — pipe mode (mkfifo) + legacy mode (chokidar)
-    ├── injector.ts      # Renders <!-- pmd: --> blocks; reverseInject write-back
-    ├── cache.ts            # Per-source render cache with TTL + invalidation
-    ├── injection-types.ts  # Injection config schema, types, defaults
-    ├── injection-engine.ts # Rules engine — resolves sources, dedup, truncation
-    ├── dedup.ts            # Per-session dedup — skips unchanged content
-    ├── detect.ts        # Ecosystem auto-detection (Node, Python, Rust, …)
-    ├── detectHarness.ts # AI-harness detection (Claude Code, OpenCode, …)
-    ├── crew.ts          # Crew ledger, conflict detection, block rendering
-    ├── hooks.ts         # Per-harness hook installers (crew + injection)
-    ├── actions.ts       # start/stop/cleanup logic
-    └── logger.ts        # File logger → .pipemd/daemon.log
-scripts/                 # Bundled Bash library, by ecosystem & category
-templates/               # Per-ecosystem Markdown templates
-tests/                   # e2e-*.sh suites + test-reverse-inject.mjs + fixtures/
+```yaml
+pipes:
+  - file: AGENTS.md
+    render: .pipemd/template.md
+    mode: legacy   # writes a regular file instead of a FIFO
 ```
-### The render pipeline
+Legacy mode writes a real file to disk, so agents read it normally. You lose zero-disk-write semantics, but context stays live.
-1. `daemon.ts` reads `.pipemd/template.md` and finds `<!-- pmd: name -->` tags.
-2. `injector.ts` runs each tag's command (from `config.commands`) concurrently
-   via `Promise.allSettled`, with a 10 s timeout per command.
-3. Rendered blocks replace the tags; `base.md` is prepended with the
-   `<!-- pmd-context -->` separator.
-4. The composed Markdown is served on the named pipe (or written in legacy mode)
-   to every harness's context file.
-5. AI edits flow back: `reverseInject` de-renders `pmd` blocks and persists
-   edits to `base.md` / `template.md`.
+**Tracking:** If you hit this, please comment on or open an issue so we can track which agents are affected.
-### Smart injection pipeline (Active/Expert mode)
+---
-1. Harness hook fires (e.g., Claude Code `PreToolUse:Edit` on `src/foo.ts`)
-2. Hook calls `pmd inject --trigger before-edit --file src/foo.ts`
-3. Injection engine loads rules from `injection.yml`
-4. For each matching rule, runs the source resolver (crew-locks, file-errors, git-context...)
-5. Each resolver reads from the render cache (sub-5ms)
-6. Dedup layer checks: skip if content unchanged since last injection
-7. Payloads printed to stdout → agent sees them as hook output
-8. For after-edit triggers: async validation (eslint + tsc) runs in background, cached for next call
+## Contributing
-PRs welcome — see `CLAUDE.md` for conventions and gotchas, `SPEC.md` for the
-full specification.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for build instructions, source layout, and architecture details.
-## 📜 License
+## License
-**ISC License** © Ivann Rudrauf
+ISC License — see [LICENSE](./LICENSE).