[WIP] Nancy

Process supervisor for Claude Code CLI sessions. Nancy is a plain Rust binary — not a Claude Code session itself. It spawns claude -p processes and manages them via hooks, stream parsing, and token tracking.

Prerequisites

• Rust (stable, 2021 edition)
• Claude Code CLI installed and authenticated (claude on PATH)
• curl (used by hook commands; ships with macOS)
• FMM (optional) — Frontmatter Matters for codebase intelligence

Build

cargo build --release

The binary is at ./target/release/nancyr.

Run

# From any project directory:
nancyr "your prompt here"

# With options:
nancyr --limit 100000 --warn 60 --deny 90 --report "fix the auth bug"

# Via cargo:
RUST_LOG=nancy=info cargo run -- "your prompt here"

What Nancy does

1. FMM codebase scan — reads .fmm sidecar files from the project to build a structural map (exports, imports, LOC). Injected into the prompt so Claude Code starts with understanding.
2. Session journal — reads recent sessions from .nancy/sessions/ for continuity across runs. Previous task outcomes feed into the next prompt.
3. Hook server — starts on a random localhost port, writes hooks config to .claude/settings.local.json
4. Spawns claude -p — with stream-json output, piped through Nancy's stream parser
5. Real-time token tracking — every tool call triggers a PreToolUse hook:
   • < 70% — allow silently
   • 70–95% — allow, inject warning via systemMessage
   • > 95% — deny the tool, forcing Claude to wrap up
6. Session report — optionally generates an MDX report in .nancy/reports/
7. Cleanup — restores .claude/settings.local.json to its pre-Nancy state

CLI Options

nancyr [OPTIONS] <PROMPT>...

Arguments:
  <PROMPT>...              The task prompt for Claude Code

Options:
      --limit <LIMIT>      Token budget limit [default: 200000]
      --warn <WARN>        Warning threshold percentage [default: 70]
      --deny <DENY>        Deny threshold percentage [default: 95]
      --claude <CLAUDE>    Path to the claude binary [default: claude]
  -C, --dir <DIR>          Working directory
      --no-fmm             Disable FMM codebase analysis
      --no-journal         Disable session journaling
      --report             Generate an MDX session report
  -h, --help               Print help
  -V, --version            Print version

Test

# Unit tests (66 tests, no Claude CLI needed):
cargo test

# Quick smoke test (requires authenticated Claude CLI):
RUST_LOG=nancy=info cargo run -- "What is 2+2? Answer in one word."

# Smoke test with report:
RUST_LOG=nancy=info cargo run -- --report "What is 2+2? Answer in one word."

Architecture

Crate	Role
nancy-core	Domain types, traits, state machines, error types. No I/O.
nancy-driver	Stream-json parser for claude -p stdout.
nancy-monitor	Hook server (axum), token budget tracking, statusline parsing.
nancy-brain	Prompt compiler, FMM codebase analysis, MDX report generation.
nancy-cli	Entry point. Supervisor loop, session journal, CLI.
nancy-runtime	Runtime trait + ProcessRuntime impl.

Intelligence Layer

FMM Codebase Map

If the project has FMM sidecar files (.fmm), Nancy reads them to build a structural map of the codebase. This map is injected into the compiled prompt, giving Claude Code instant understanding of the project:

Codebase structure (via FMM sidecars):

  src/auth.rs (180 loc)
    exports: AuthMiddleware, JwtConfig, verify_token
    imports: axum, jsonwebtoken

  src/routes.rs (320 loc)
    exports: api_router, health_check
    imports: axum, serde

Summary: 12 files, 45 exports, 2800 total LOC

Run fmm generate in your project to create/update sidecars.

Session Journal

Nancy persists session outcomes in .nancy/sessions/ as JSON. Before each session, it reads recent entries and injects continuity context:

Recent sessions in this project:
- [2026-02-18T21:40:27] task-1: "Fix the auth bug" → Success, 3 turns, $0.45
  Output: Fixed JWT validation in auth middleware...

This gives Claude Code awareness of what's already been done.

MDX Reports

With --report, Nancy generates rich MDX files in .nancy/reports/ with YAML frontmatter, metrics tables, tool usage breakdowns, and session output. Compatible with Next.js, Astro, or any MDX pipeline.

Configuration

Setting	Flag	Default	Description
Token limit	--limit	200,000	Total input+output token budget
Warn threshold	--warn	70%	Inject systemMessage warning
Deny threshold	--deny	95%	Block all tool use
Claude binary	--claude	claude	Path to Claude Code CLI
Working dir	-C	cwd	Project directory
FMM	--no-fmm	enabled	Codebase structure analysis
Journal	--no-journal	enabled	Session persistence
Report	--report	disabled	MDX report generation

How hooks work

Nancy registers as a PreToolUse hook via .claude/settings.local.json. When Claude Code is about to use a tool, it runs the hook command which curls Nancy's HTTP server. Nancy checks the token budget and returns a JSON response that Claude Code reads:

Claude Code                          Nancy
    |                                  |
    |-- PreToolUse stdin JSON -------->|
    |   (via curl -d @-)               |
    |                                  |-- check TokenBudget
    |                                  |
    |<-- JSON response (stdout) -------|
    |   {hookSpecificOutput:           |
    |     {permissionDecision:"allow"},|
    |    systemMessage:"...warning"}   |
    |                                  |

PostToolUse additionalContext does not work for injecting context visible to Claude. That's why Nancy uses PreToolUse with systemMessage.