autonomous-flow-daemon 1.1.0 → 1.6.0

package/README.md

@@ -9,16 +9,12 @@
   <a href="https://github.com/dotoricode/autonomous-flow-daemon">
     <img src="demo.gif" width="850" alt="afd demo" style="border-radius: 12px; box-shadow: 0 20px 40px rgba(0,0,0,0.4);">
   </a>
-  <br>
-  <br>
-  <b>🛡️ Immortal Context Flow:</b> 
-  <em>"afd restores critical config files with <b>near-zero latency</b>, ensuring your AI workflow remains unbroken and cost-efficient."</em>
 </p>
 
 ---
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.1.0-blue?style=flat-square" alt="version" />
+  <img src="https://img.shields.io/badge/version-1.6.0-blue?style=flat-square" alt="version" />
   <a href="https://www.npmjs.com/package/autonomous-flow-daemon"><img src="https://img.shields.io/npm/v/autonomous-flow-daemon?style=flat-square&logo=npm&color=cb0000" alt="npm" /></a>
   <img src="https://img.shields.io/badge/runtime-Bun-f472b6?style=flat-square&logo=bun" alt="Bun" />
   <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT" />
@@ -33,49 +29,76 @@
 
 ## Why afd?
 
-> [afd] 🛡️ AI agent deleted '.claudeignore' | 🩹 Self-healed in 184ms | Context preserved.
+> [afd] AI agent deleted '.claudeignore' | Self-healed in 184ms | Context preserved.
 
-You're deep in flow. Your AI agent makes a wrong move — deletes a config, corrupts a hook file, wipes a `.cursorrules`. Without `afd`, you stop everything, diagnose the breakage, manually fix it: **30 minutes gone**.
+Your AI agent deletes a config, corrupts a hook file, wipes `.cursorrules`. Without `afd`, you stop everything, diagnose the breakage, manually fix it: **30 minutes gone**.
 
-With `afd`, the daemon noticed in 10ms, restored the file in 184ms, and logged it silently. **You never even saw it happen.**
+With `afd`, the daemon noticed in 10ms, restored the file in 184ms, and logged it silently. **You never even saw it happen.** Running as a native Bun daemon, it consumes < 0.1% CPU and ~40MB RAM — zero interference with your workflow.
 
 | Situation | Without afd | With afd |
 |:----------|:------------|:---------|
 | AI deletes `.claudeignore` | 30 min manual fix | **0.2s auto-heal** |
 | Hook file corrupted | Re-inject hooks, restart session | **Silent background repair** |
 | `git checkout` triggers 50 file events | AI goes haywire | **Mass-event suppressor kicks in** |
-| New team member, missing context | Tribal knowledge required | **`afd sync` vaccines the setup** |
+| AI reads 8 large files (114KB) | ~28,600 tokens consumed | **~1,700 tokens via hologram (94% saved)** |
 
 ---
 
-## 🚀 Zero-Interference Promise
+## Key Features
 
-We built `afd` to protect your flow, not to slow it down.
-
-* **No Performance Hit:** Running as a native background daemon via Bun, `afd` consumes **< 0.1% CPU** and **~40MB RAM**.
-* **Seamless Recovery:** With **sub-millisecond healing**, files are restored before Claude Code can even register a missing context error.
-* **Non-Invasive:** `afd` observes file system events from the OS layer. It never intercepts or modifies Claude Code's internal execution or API calls.
+| Feature | What it does |
+|:--------|:-------------|
+| **S.E.A.M Auto-Heal** | Detects file deletion/corruption and restores it in < 270ms |
+| **Hologram Extraction** | Serves 80-93% lighter file skeletons to AI agents via MCP, slashing token costs |
+| **Smart File Reader** | `afd_read` — small files served raw, large files auto-compressed; supports line-range reads |
+| **Workspace Map** | `afd://workspace-map` — full file tree + export signatures in one call |
+| **Hologram L1** | Import-aware compression — only imported symbols get full signatures (85%+ savings) |
+| **Quarantine Zone** | Backs up corrupted files to `.afd/quarantine/` before restoring |
+| **Self-Evolution** | Analyzes quarantined failures and writes prevention rules to `afd-lessons.md` |
+| **Mistake History** | PreToolUse hook injects past mistakes as warnings before file edits |
+| **Double-Tap Heuristic** | Delete once = auto-heal; delete again within 30s = respected as intent |
+| **Vaccine Network** | Export learned antibodies via `afd sync` for cross-project immunity |
+| **MCP Integration** | `afd mcp install` auto-registers the daemon as an MCP server |
+| **HUD Defense Counter** | Status bar shows defense count + reason summary at a glance |
 
 ---
 
-## ✨ Key Features (v1.1.0)
+## Token Savings — Real Measured Data
 
-| Feature | What it does |
-|:--------|:-------------|
-| **🛡️ S.E.A.M Auto-Heal** | Detects file deletion and restores it in < 270ms — before your AI agent notices |
-| **🔍 Smart Discovery** | Automatically scans for AI-context files (`.claude/`, `.cursorrules`, `.mcp.json`, etc.) — zero config required |
-| **🏥 Boastful Doctor** | Real-time value tracking: saved tokens, time, and cost — with witty feedback after every heal |
-| **🌐 Auto-Localization** | Seamlessly switches between Korean and English based on your system locale. Or set it: `afd lang ko` |
-| **🧬 Double-Tap Heuristic** | Distinguishes accidents from intent — delete once, afd heals it; delete again within 30s, afd respects your decision |
-| **💉 Vaccine Network** | Export learned antibodies via `afd sync` for cross-project, cross-team immunity |
-| **📊 Hologram Extraction** | Serves 80%+ lighter file skeletons to AI agents, slashing token costs |
+The hologram system is afd's biggest value driver for AI-assisted development. Here's what we measured in a real session:
+
+### Session Snapshot (measured during a real coding session)
+
+| Metric | Value |
+|:-------|:------|
+| Hologram requests | 8 calls |
+| Target files total size | ~114.5 KB (8 files, avg 14.3 KB each) |
+| Original token cost | ~28,600 tokens |
+| After hologram compression | ~1,700 tokens |
+| **Tokens saved** | **~26,900 tokens (94% reduction)** |
+
+### How It Scales
+
+```
+Session tokens (at ctx ~15%):  ~150,000  ████████████████
+Tokens saved by hologram:       ~26,900  ██░░░░░░░░░░░░░░  (18% of session)
+```
+
+At ctx 50%+, file reads dominate the token budget. Without hologram, reading 8 large files costs ~28.6K tokens each time. With hologram, **each file costs 1/16th** of its original footprint — and the gap widens with every repeated read.
+
+### Three Layers of Token Optimization
+
+| Layer | Tool | Savings | How |
+|:------|:-----|:--------|:----|
+| **L0 Hologram** | `afd_hologram` | 80%+ | Strip function bodies, keep type signatures |
+| **L1 Hologram** | `afd_hologram` + `contextFile` | 85%+ | Filter to only imported symbols |
+| **Smart Reader** | `afd_read` | Auto | Files < 10KB raw, >= 10KB auto-hologram |
+| **Workspace Map** | `afd://workspace-map` | N/A | Entire project structure in one call |
 
 ---
 
 ## The One-Command Experience
 
-> **Zero-Config. Total Protection.**
-
 ```bash
 npx @dotoricode/afd start
 ```
@@ -86,27 +109,24 @@ Or install locally:
 bun link && afd start
 ```
 
-That's it. One command. `afd` takes over from here:
+That's it. `afd` takes over from here:
 
-- **Auto-Injection** — Installs `PreToolUse` hooks into Claude Code silently. No manual config editing.
-- **Sense (Watcher)** — 10ms real-time monitoring of critical configs: `.claude/`, `CLAUDE.md`, `.cursorrules`, `.claudeignore`, `.gitignore`.
-- **Auto-Heal** — Silent background repair of missing or corrupted files using the **S.E.A.M cycle**. You won't even notice it happened.
+- **Auto-Injection** — Installs `PreToolUse` hooks into Claude Code silently.
+- **Sense (Watcher)** — 10ms real-time monitoring of critical configs.
+- **Auto-Heal** — Silent background repair using the S.E.A.M cycle.
 
 ```
 $ afd start
-  🛡️ Daemon started (pid 4812, port 52413)
-  🛡️ Smart Discovery: Watching 7 AI-context targets
-  Targets: .claude/, CLAUDE.md, .cursorrules, .claudeignore, .gitignore, mcp-config.json, .mcp.json
+  Daemon started (pid 4812, port 52413)
+  Smart Discovery: Watching 7 AI-context targets
   Hook injected into .claude/hooks.json
 ```
 
-> You type `afd start`. Then you forget about it. That's the entire UX.
-
 ---
 
 ## The S.E.A.M Cycle
 
-The intelligence inside `afd`. Every file event flows through four stages:
+Every file event flows through four stages:
 
 ```mermaid
 graph LR
@@ -123,177 +143,88 @@ graph LR
 | Stage | What Happens | Speed |
 |:------|:-------------|:------|
 | **Sense** | Chokidar watcher detects `add`, `change`, `unlink` events | < 10ms |
-| **Extract** | Immune engine runs 3 built-in health checks (IMM-001..003) | < 5ms |
-| **Adapt** | Matches symptom to stored antibody in SQLite (WAL mode) | < 1ms |
+| **Extract** | Generates hologram (type skeleton) & runs health checks | < 5ms |
+| **Adapt** | Matches symptom to antibody, quarantines corrupted state | < 1ms |
 | **Mutate** | Applies RFC 6902 JSON-Patch to restore the file | < 25ms |
 
 > Full cycle: **< 270ms** from file deletion to full recovery.
 
-### Watch Targets
-
-These files are monitored in real-time. Immune files (IMM-*) are automatically restored on deletion:
-
-| Target | Type | Antibody | Auto-Restore |
-|:-------|:-----|:---------|:-------------|
-| `.claude/` | Directory | IMM-002 (`hooks.json`) | ✅ |
-| `CLAUDE.md` | File | IMM-003 | ✅ |
-| `.claudeignore` | File | IMM-001 | ✅ |
-| `.cursorrules` | File | — | Event logging only |
-| `.gitignore` | File | — | Event logging only |
-| `mcp-config.json` | File | — | 🔍 Smart Discovery |
-| `.mcp.json` | File | — | 🔍 Smart Discovery |
-| `.ai/` | Directory | — | 🔍 Smart Discovery |
-| `.windsurfrules` | File | — | 🔍 Smart Discovery |
-
-> Antibodies are **auto-seeded on startup** with each file's current content, and **refreshed on every change** — so restores always reflect the latest version.
->
-> 🔍 **Smart Discovery** scans for 12+ known AI-config patterns at startup (< 0.1ms) and adds any found files to the active watch list automatically.
-
 ---
 
 ## Commands
 
-Everything you need. Nothing you don't.
-
-| Command | Essence | Intelligence Inside |
-|:--------|:--------|:--------------------|
-| `afd start` | **Ignite** | Daemon spawn + Smart Discovery + Hook injection |
-| `afd fix` | **Diagnose** | Symptom detection & Antibody learning |
-| `afd score` | **Vitals** | Localized health dashboard & Value metrics |
-| `afd sync` | **Federate** | Vaccine payload export for cross-project immunity |
-| `afd lang` | **Localize** | Switch display language (`afd lang ko` / `afd lang en`) |
-| `afd stop` | **Quarantine** | Shift summary & Graceful shutdown |
-
-### Quick Reference
-
-```bash
-afd start      # Start daemon, inject hooks, begin watching
-afd fix        # Scan for issues, auto-patch, learn antibodies
-afd score      # Full diagnostic dashboard (localized)
-afd sync       # Export antibodies to .afd/global-vaccine-payload.json
-afd lang ko    # Switch to Korean / afd lang en for English
-afd stop       # Shift summary + graceful shutdown
-```
-
----
-
-## Dashboard: `afd score`
-
-```
-┌──────────────────────────────────────────────┐
-│  afd score — Daemon Diagnostics              │
-├──────────────────────────────────────────────┤
-│  Ecosystem    : Claude Code                  │
-├──────────────────────────────────────────────┤
-│  Uptime       : 1h 23m                       │
-│  Events       : 156                          │
-│  Files Found  : 8                            │
-├──────────────────────────────────────────────┤
-│  Immune System                               │
-│  ──────────────────────────────              │
-│  Antibodies   : 7                            │
-│  Level        : Fortified                    │
-│  Auto-healed  : 3 background events          │
-├──────────────────────────────────────────────┤
-│  📈 Value Delivered                          │
-│  ──────────────────────────────              │
-│  Tokens saved : ~2.9K                        │
-│  Time saved   : ~40 min                      │
-│  Cost saved   : ~$0.01                       │
-├──────────────────────────────────────────────┤
-│  🗣️ The immune system holds. Another day,   │
-│     another heal. 💪                         │
-└──────────────────────────────────────────────┘
-```
-
-> The dashboard is fully localized. Run `afd lang ko` and every label switches to Korean.
+| Command | What it does |
+|:--------|:-------------|
+| `afd start` | Daemon spawn + Smart Discovery + Hook injection + MCP registration |
+| `afd stop` | Shift summary report & graceful shutdown (`--clean` to remove hooks & MCP) |
+| `afd score` | Health dashboard with evolution & hologram metrics |
+| `afd fix` | Symptom detection with hologram context & antibody learning |
+| `afd sync` | Vaccine payload export/import (`--push`, `--pull`, `--remote <url>`) |
+| `afd restart` | Stop + start in one command |
+| `afd status` | Quick health check — daemon, hooks, MCP, defenses |
+| `afd doctor` | Comprehensive health analysis with auto-fix recommendations |
+| `afd evolution` | Analyze quarantined failures & generate prevention rules |
+| `afd mcp install` | Register afd as MCP server in project + global config |
+| `afd vaccine` | List, search, install, publish community antibodies |
+| `afd lang` | Switch display language (`afd lang ko` / `afd lang en`) |
 
 ---
 
 ## Advanced Intelligence
 
-### Double-Tap Heuristic (Immune Tolerance)
+### Double-Tap Heuristic
 
 `afd` distinguishes **accidents** from **intent**:
 
 ```
-$ rm .claudeignore            # First tap → afd heals it silently
-$ rm .claudeignore            # Second tap within 30s → "You meant it."
-  [afd] 🫡 Antibody IMM-001 retired. Double-tap detected. Standing down.
+$ rm .claudeignore            # First tap -> afd heals it silently
+$ rm .claudeignore            # Second tap within 30s -> "You meant it."
+  [afd] Antibody IMM-001 retired. Double-tap detected. Standing down.
 ```
 
 | Scenario | Response |
 |:---------|:---------|
 | Single delete (accident) | Auto-heal + record first tap |
 | Re-delete within 30s (intent) | Antibody goes dormant, deletion respected |
-| Re-delete after 30s | Fresh first tap, heals again |
 | 3+ deletes in 1s (git checkout) | Mass-event detected, all suppression paused |
 
-### Vaccine Network (Team Federation)
-
-Export learned antibodies for your entire team:
+### Vaccine Network
 
 ```bash
-afd sync
-# → .afd/global-vaccine-payload.json
+afd sync              # Export to .afd/global-vaccine-payload.json
+afd sync --push       # Push vaccines to remote
+afd sync --pull       # Pull vaccines from remote
 ```
 
-The payload is sanitized (no absolute paths, no secrets) and portable. Drop it into any project, and `afd` inherits the immunity.
-
-### Hologram Extraction
+The payload is sanitized (no absolute paths, no secrets) and portable.
 
-When AI agents request file context, `afd` serves **token-efficient skeletons** — stripping comments and function bodies while preserving the full type signature:
+### Self-Evolution
 
+```bash
+afd evolution
 ```
-Original:  2,450 chars → Hologram: 380 chars (84% savings)
-```
-
-This keeps your AI agent's context window lean without losing structural understanding.
-
----
-
-## Status Line
 
-Real-time daemon status in Claude Code's status bar:
-
-```
-🛡️ afd: OFF                              # Daemon not running
-🛡️ afd: ON                               # Running, no heals
-🛡️ afd: ON 🩹1                            # 1 auto-heal event
-🛡️ afd: ON | 🩹 3 Healed | last: IMM-003  # Detailed view
-```
+Analyzes quarantined failures and writes prevention rules to `afd-lessons.md`. AI agents read this before editing immune-critical files — turning past failures into future prevention.
 
 ---
 
-## Plugin / MCP Setup
-
-`afd` can be registered as a **Model Context Protocol (MCP) server** inside Claude Code, allowing the daemon to start automatically when Claude Code launches.
+## MCP Setup
 
-### Automatic (recommended)
+`afd` provides four MCP tools and one resource:
 
-Add to your Claude Code MCP config (`~/.claude/mcp.json` or project-level `.mcp.json`):
+| MCP Tool | Purpose |
+|:---------|:--------|
+| `afd_read` | Smart file reader — raw for small files, auto-hologram for large, optional line ranges |
+| `afd_hologram` | Token-efficient type skeleton of any TS/JS file (80%+ savings) |
+| `afd_diagnose` | Health diagnosis with symptoms and hologram context |
+| `afd_score` | Runtime stats: uptime, heals, hologram savings |
 
-```json
-{
-  "mcpServers": {
-    "afd": {
-      "command": "bun",
-      "args": ["run", "src/cli.ts", "start"]
-    }
-  }
-}
-```
-
-### Manual
+| MCP Resource | Purpose |
+|:-------------|:--------|
+| `afd://workspace-map` | Full file tree with export signatures in one call |
 
 ```bash
-afd start   # starts daemon in background, injects hooks
-```
-
-Once registered, Claude Code will display the live status line:
-
-```
-🛡️ afd: ON | 🩹 3 Healed | last: IMM-003
+afd mcp install    # Registers in .mcp.json + ~/.claude.json
 ```
 
 ---
@@ -307,7 +238,6 @@ Once registered, Claude Code will display the live status line:
 | Watching | **Chokidar** | Cross-platform, battle-tested file watcher |
 | Patching | **RFC 6902 JSON-Patch** | Deterministic, composable file mutations |
 | CLI | **Commander.js** | Standard, zero-surprise command parsing |
-| i18n | **Built-in engine** | Zero-dependency locale switching in 0.01ms |
 
 ---
 
@@ -327,11 +257,10 @@ npx @dotoricode/afd start
 
 - **Bun** >= 1.0
 - **OS**: Windows, macOS, Linux
-- **Target**: Claude Code, Cursor (ecosystem auto-detected)
+- **Target**: Claude Code, Cursor, Windsurf, Codex (ecosystem auto-detected)
 
 ---
 
 ## License
 
 MIT
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autonomous-flow-daemon",
-  "version": "1.1.0",
+  "version": "1.6.0",
   "description": "Zero-config immunity for AI coding workflows. Self-heals broken configs in < 270ms.",
   "type": "module",
   "bin": {
@@ -26,14 +26,20 @@
     "dev-tools"
   ],
   "scripts": {
-    "start": "bun run src/cli.ts start",
-    "dev": "bun run src/cli.ts",
+    "dev": "bun --watch src/cli.ts",
+    "score": "bun src/cli.ts score",
+    "start": "bun src/cli.ts start",
     "test": "bun test"
   },
   "dependencies": {
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.2",
+    "web-tree-sitter": "^0.26.8"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "optionalDependencies": {
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-typescript": "^0.23.2"
+  }
 }