# Emu > Stop burning API tokens. 9 algorithmic engines for real-time context optimization, infinite-loop detection, and smart prompt compression. - **Type:** MCP server - **Install:** `agentstack add mcp-enchanter-ai-emu` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [enchanter-ai](https://agentstack.voostack.com/s/enchanter-ai) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [enchanter-ai](https://github.com/enchanter-ai) - **Source:** https://github.com/enchanter-ai/emu ## Install ```sh agentstack add mcp-enchanter-ai-emu ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Emu > An @enchanter-ai product — algorithm-driven, agent-managed, self-learning. The context health platform that learns what wastes your tokens — and stops it. **3 plugins. 9 algorithms. 4 agents. Honest numbers.** > 40 minutes into a session, Emu told me Claude had been editing and reverting > the same file for 12 minutes. I didn't notice. It did. ## TL;DR **In plain English:** Some sessions burn 200k tokens to ship twelve lines. Emu tells you while you can still steer out — not after the context dies and you start over. **Technically:** A1 Markov Drift Detection classifies turn sequences into READ_LOOP / EDIT_REVERT / TEST_FAIL_LOOP patterns against a 5-turn cooldown window; A2 Linear Runway Forecasting estimates remaining turns to compaction with a ±CI band. Context savings are recorded per strategy in `metrics.jsonl` and accumulated cross-session via A7 Exponential Strategy Averaging — every advisory cites observed pattern, not inferred intent. --- ## Origin **Emu** takes its name from **Alex's Mobs** — a flightless bird that stands tall on the open plain and uses its long-range vision to spot threats on the horizon long before they arrive. Emu watches your session the same way: eyes on the token flow, flagging the runway edge before you hit it. The question this plugin answers: *What did I spend?* ## Who this is for - Developers who've watched a session burn through context on re-reads, revert loops, or verbose tool output — and want an objective readout instead of a gut feeling. - Teams that need honest numbers (runway with a ±CI, drift with a specific pattern) for retrospectives, not a marketing dashboard. - Privacy-conscious users — everything Emu observes stays local; there is no outbound network code (see [PRIVACY.md](PRIVACY.md)). Not for: - Centralized-observability teams who need a cloud dashboard — Emu is machine-local by design. - Sessions where context burn is obviously the smaller problem than code correctness — reach for Crow or Lich first, then Emu. ## Contents - [How It Works](#how-it-works) - [What Makes Emu Different](#what-makes-emu-different) - [The Full Lifecycle](#the-full-lifecycle) - [Install](#install) - [Quickstart](#quickstart) - [3 Plugins, 4 Agents, 9 Algorithms](#3-plugins-4-agents-9-algorithms) - [What You Get Per Session](#what-you-get-per-session) - [Roadmap](#roadmap) - [The Science Behind Emu](#the-science-behind-emu) - [Commands](#commands) - [Compression Rules (15)](#compression-rules-15) - [vs Everything Else](#vs-everything-else) - [Agent Conduct (11 Modules)](#agent-conduct-11-modules) - [Architecture](#architecture) - [Acknowledgments](#acknowledgments) - [Versioning & release cadence](#versioning--release-cadence) - [Contributing](#contributing) - [Citation](#citation) - [License](#license) ## How It Works Emu splits into three plugins that each own one lifecycle phase. **token-saver** fires on `PreToolUse` to compress verbose Bash output (A3), block duplicate file reads (A5), and return deltas on changed re-reads (A6). **context-guard** fires on `PostToolUse` to forecast runway (A2) and detect drift patterns (A1). **state-keeper** fires on `PreCompact` to write an atomic checkpoint (A4). Across sessions, A7 accumulates per-strategy success rates. The diagram below shows this flow. Source: [docs/assets/pipeline.mmd](docs/assets/pipeline.mmd) · Regeneration command in [docs/assets/README.md](docs/assets/README.md). Three plugins. Three lifecycle phases. No overlap. No dependencies between plugins. ## What Makes Emu Different ### Drift Alert Catches Claude spinning in circles — in real time, not after the fact: ``` ⚠️ Drift Alert: src/auth.ts read 4× without changes. Claude may be stuck re-reading without progress. → Reframe the problem or /emu:checkpoint before /compact. ``` Three patterns: **read loops**, **edit-revert cycles**, **test fail loops**. 5-turn cooldown between alerts to avoid noise. ### Token Runway Not "43% context used." Not "$0.12 spent." Just: **"~8 turns until compaction."** ``` RUNWAY FORECAST (Algorithm A2: Linear Runway Forecasting) Point estimate: ~14 turns remaining 95% CI: [8, 20] turns Confidence: MEDIUM (CV=0.31) Velocity: 4,200 tokens/turn avg (sigma=1,302) ``` ### Per-Tool Analytics See exactly where your tokens go: ``` TOOL ANALYTICS (this session) Read: 42 calls, ~18,400 tokens (34%) Bash: 28 calls, ~14,200 tokens (26%) Write: 15 calls, ~11,800 tokens (22%) ``` ### Output Efficiency Configurable terse mode that cuts output token waste without losing information. Four levels: off / lite / full / ultra. Code stays verbose — only prose gets lean. ### Delta Mode Re-reading a changed file? Emu shows only what changed instead of the full file. Re-reading an unchanged file? Blocked — with a preview and elapsed time. ### Self-Learning Emu accumulates strategy success rates across sessions. After each report, it logs which compression rules fired, which drift patterns recurred, and which interventions worked — then adjusts its internal model via exponential moving average. ### The Receipt `/emu:report` shows exact savings per feature, drift alerts fired, turns remaining, and accumulated learnings. Conservative methodology. We don't inflate numbers. ## The Full Lifecycle Every turn cycles through the same path. Tool calls hit `PreToolUse` (token-saver), then execute, then hit `PostToolUse` (context-guard). When context approaches full, `PreCompact` fires and state-keeper writes `checkpoint.md` before the wipe. On resume, the restorer agent reads the checkpoint back and the session continues without manual re-briefing. Source: [docs/assets/lifecycle.mmd](docs/assets/lifecycle.mmd) · Regeneration command in [docs/assets/README.md](docs/assets/README.md). Every tool call flows through the same pipeline. When context fills up, state-keeper saves a checkpoint before the wipe, and the restorer agent brings it back autonomously. ## Install Emu ships as 3 plugins cooperating across PreToolUse / PostToolUse / PreCompact. One meta-plugin — `full` — lists all three as dependencies, so a single install pulls in the whole platform. **In Claude Code** (recommended): ``` /plugin marketplace add enchanter-ai/emu /plugin install full@emu ``` Claude Code resolves the dependency list and installs all 3 plugins. Verify with `/plugin list`. **Want to cherry-pick?** Individual plugins are still installable by name — e.g. `/plugin install emu-context-guard@emu` if you only want the drift/runway dashboard. The three lifecycle phases are designed to cooperate, though, so `full@emu` is the path we recommend. **Via shell** (also installs `shared/*.sh` locally so hooks work offline): ```bash bash Source: [docs/assets/state-flow.mmd](docs/assets/state-flow.mmd) · Regeneration command in [docs/assets/README.md](docs/assets/README.md). ``` state-keeper/state/ ├── checkpoint.md # Pre-compaction snapshot (branch, files, instructions) ├── remember.md # User-flagged context (/emu:checkpoint items) └── metrics.jsonl # checkpoint_saved events token-saver/state/ └── metrics.jsonl # bash_compressed, duplicate_blocked, delta_read events context-guard/state/ ├── metrics.jsonl # turn events — now include "skill" field (A8) ├── skill-metrics.jsonl # A8 — rich per-skill events (only when a skill is active) ├── active-skills.json # A8 — live scope stack (invocation-id keyed) └── .session # A9 — per-worktree session id (gitignored) $XDG_STATE_HOME/emu// # A9 — cross-worktree global └── skill-metrics-global..jsonl # per-PID shard; readers glob + merge $XDG_DATA_HOME/emu// # A9 — long-lived learnings └── learnings.json # A7 strategy rates; migrated from local ``` ## Roadmap Tracked in [docs/ROADMAP.md](docs/ROADMAP.md) and the shared [ecosystem map](docs/ecosystem.md). For upcoming work specific to Emu, see issues tagged [roadmap](https://github.com/enchanter-ai/emu/labels/roadmap). ## The Science Behind Emu Nine named algorithms. Each one referenced in code, agents, and reports. ### A1. Markov Drift Detection Pattern-matching finite automaton over tool call sequences. States: `PRODUCTIVE`, `READ_LOOP`, `EDIT_REVERT`, `TEST_FAIL_LOOP`. Transitions on tool name + file hash + exit code. 5-turn cooldown between alerts. = theta; else 0"> Where θ = 3 (configurable via `EMU_DRIFT_READ_THRESHOLD`). ### A2. Linear Runway Forecasting Estimates turns until compaction from a sliding window of token velocities. Where C_max = 200,000 tokens and t̄_w is the windowed mean of recent turns. ### A3. Shannon Compression Reduces output $O$ to $O'$ preserving information density above threshold $\theta$: = theta · H(O); theta = 1.0 code, 0.7 tests, 0.3 logs"> 15 pattern-matched rules for input compression. Extensions: - **Shannon Output Compression** — prose terse mode (4 levels) - **Temporal Decay Compression** — age-based result stubbing ### A4. Atomic State Serialization Write-validate-rename protocol for checkpoint persistence. validate(tmp) -> rename(tmp, target)"> 50KB bound. Atomic `mkdir` locking (never `flock`). ### A5. Content-Addressable Dedup SHA-256 hash + TTL cache for read deduplication. = TTL"> TTL = 600s. Block unchanged, allow after expiry. ### A6. Delta-Read Telemetry Extension of A5. Tracks when changed files are re-read within TTL and emits telemetry: When a file is re-read after modification within the TTL window, the hook logs a `delta_read` event recording file path, full line count, and diff line count. Diff generation (unified format with context) is deferred to Phase 2; current implementation is telemetry-only. ### A7. Exponential Strategy Averaging Exponential moving average (EMA) over compression strategy success rates and drift frequencies across sessions. Uses EMA with α=0.3 to blend current-session metrics into historical rates for compression rules, drift patterns, and velocity. Detects dormant rules, chronic drift patterns, and velocity trends. Persisted to `learnings.json` after each report. ### A8. Skill-Scoped Attribution Every tool call is attributed to the currently-active skill (or `manual` if none is registered). Skills register a scope at entry, unregister at exit; the stack supports nesting so a parent skill that invokes a child skill still has correct parent/child lineage on every event. Where $S$ is the stack of active skills (LIFO), $s_{\text{top}}$ is the most recent, and $\text{TTL} = 3600\text{s}$ (configurable via `EMU_SKILL_TTL`). Scopes are keyed by 16-hex-char invocation ids — not PIDs — so entries survive PID reuse (systemd `InvocationID` pattern). Eviction on every read: stale entries (dead PID or expired TTL) are purged before the "current" scope is returned. Emitted as `skill-metrics.jsonl` alongside `metrics.jsonl`. `/emu:analytics` surfaces the per-skill breakdown. ### A9. Worktree Session Graph Concurrent Claude Code sessions across multiple git worktrees of the same repo are unified into one view by the root-commit hash: The root commit is stable across clones, forks, renames, and worktree paths — basename-of-toplevel is not. Cross-worktree events land in `$XDG\_STATE\_HOME/emu/\langle repo\_id\rangle/`, sharded per-PID (`skill-metrics-global.\langle pid\rangle.jsonl`) to avoid concurrent-append interleaving on filesystems without atomicity guarantees (Windows, NFS). Readers glob all shards and merge by `ts`: `/emu:report` renders a WORKTREE OVERVIEW section when ≥ 2 worktrees have written. `/emu:report --global` forces the unified view across every session recorded in the global dir. Learnings (A7) also migrate to `$XDG_DATA_HOME/emu//learnings.json` — the data dir per XDG spec — so cross-session accumulation survives cache wipes and spans every worktree without symlinks. ## Commands | Command | Plugin | What | |---------|--------|------| | `/emu:report` | context-guard | Full session dashboard. `--global` for unified cross-worktree view (A9). | | `/emu:runway` | context-guard | Quick turns-until-compaction check | | `/emu:analytics` | context-guard | Per-tool + per-skill token breakdown (A8) | | `/emu:doctor` | context-guard | Diagnostic self-check for all plugins | | `/emu:checkpoint [text]` | state-keeper | Save context that survives compaction | | `/emu:checkpoint-show` | state-keeper | Display most recent automatic checkpoint | ## Compression Rules (15) | Pattern | Action | |---------|--------| | npm/yarn/pnpm test, vitest, jest | `tail -n 40` | | pytest, python -m unittest | filter pass/fail summary | | go test | filter PASS/FAIL lines | | mvn/gradle test | filter BUILD + test summary | | dotnet build/test | filter pass/fail summary | | npm/yarn/pnpm install | filter errors/warnings | | cargo build/test | filter errors/warnings | | make | filter errors or "Build succeeded" | | docker build | filter layer summaries + image ID | | terraform plan | filter Plan summary | | eslint | filter error count + first errors | | tsc | filter TS errors | | git log (verbose) | `--oneline -20` | | find (no head) | `head -n 30` | | cat (>100 lines) | `head -n 80` + line count | Bypass: prefix with `FULL:` to skip compression. ## vs Everything Else | | Emu | Caveman | Cozempic | context-mode | token-optimizer | |---|---|---|---|---|---| | Drift detection | real-time, 3 patterns | — | — | — | — | | Turn forecast | Runway + 95% CI | — | threshold only | — | — | | Output reduction | 4 modes | 65% prose cut | — | — | — | | Input compression | 15 rules | — | 18 strategies | — | — | | Delta mode | diff on re-read | — | — | — | delta mode | | Per-skill + per-tool analytics | /emu:analytics (A8) | — | — | per-tool only | waste dashboard | | Cross-worktree unified view | /emu:report --global (A9) | — | — | — | — | | Tool result aging | age-based alerts | — | 3-tier stubbing | — | — | | Savings proof | /emu:report | — | session report | ctx_stats | quality score | | Compaction survival | checkpoint.md | — | team state | SQLite | checkpoints | | Self-learning | learnings.json | — | — | — | — | | Agents | 4 (Haiku) | — | — | — | — | | Dependencies | bash + jq | — | Python | Node.js + MCP | Node.js | Combined: 30-45% token reduction. Not 70%. Honest numbers. Plus the only tool that catches Claude going in circles — and learns from it. ## Agent Conduct (11 Modules) Every skill inherits a reusable behavioral contract from [shared/](shared/) — loaded once into [CLAUDE.md](CLAUDE.md), applied across all plugins. This is how Claude *acts* inside Emu: deterministic, surgical, verifiable. Not a suggestion; a contract. | Module | What it governs | |--------|-----------------| | [discipline.md](../vis/packages/core/conduct/discipline.md) | Coding conduct: think-first, simplicity, surgical edits, goal-driven loops | | [context.md](../vis/packages/core/conduct/context.md) | Attention-budget hygiene, U-curve placement, checkpoint protocol | | [verification.md](../vis/packages/core/conduct/verification.md) | Independent checks, baseline snapshots, dry-run for destructive ops | | [delegation.md](../vis/packages/core/conduct/delegation.md) | Subagent contracts, tool whitelisting, parallel vs. serial rules | | [failure-modes.md](../vis/packages/core/conduct/failure-modes.md) | 14-code taxonomy for accumulated-learning logs | | [tool-use.md](../vis/packages/core/conduct/tool-use.md) | Tool-choice hygiene, error payload contract, parallel-dispatch rules | | [skill-authoring.md](../vis/packages/skills/conduct/skill-authoring.md) | SKILL.md frontmatter discipline, discovery test | | [hooks.md](../vis/packages/core/conduct/hooks.md) | Advisory-only hooks, injection over denial, fail-open | | [precedent.md](../vis/packages/core/conduct/precedent.md) | Log self-observed failures to `state/precedent-log.md`; consult before risky steps | | [tier-sizing.md](../vis/packages/core/conduct/tier-sizi … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [enchanter-ai](https://github.com/enchanter-ai) - **Source:** [enchanter-ai/emu](https://github.com/enchanter-ai/emu) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-enchanter-ai-emu - Seller: https://agentstack.voostack.com/s/enchanter-ai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.