{"_id":"@burnmydays/signaf","_rev":"2-f1ee215ed49378cc07bce3e148fcfc8c","name":"@burnmydays/signaf","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@burnmydays/signaf","version":"0.1.0","keywords":["sigrank","signa","agent","cascade","taste","steering-efficiency","token-efficiency"],"license":"CC-BY-NC-4.0","_id":"@burnmydays/signaf@0.1.0","maintainers":[{"name":"burnmydays","email":"burnmydays@proton.me"}],"homepage":"https://signalaf.com","bugs":{"url":"https://github.com/SunrisesIllNeverSee/signa/issues"},"bin":{"signaf":"src/index.mjs"},"dist":{"shasum":"b63b1635105bf21f4d18cc78ac5f4ee208df0eea","tarball":"https://registry.npmjs.org/@burnmydays/signaf/-/signaf-0.1.0.tgz","fileCount":37,"integrity":"sha512-Yj4HFo0wRVjZv7wVnxeOpWT13f3K/hH6VHu9Ye3JbIcAqesvswkDvTUno4tYjSlREj4reHErW516fI2GW/Zgzg==","signatures":[{"sig":"MEUCIQDLQf15Bfc+0AdwIYo04j01Dc/FAL6vIBHlLD4bDPY8yQIgSRWRvrMgeErBXPuw8U/P6t5coOOYFPMYeSLzjTRXG5w=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":350528},"main":"src/index.mjs","type":"module","engines":{"node":">=18"},"gitHead":"aa600c8c79ff5ca7a0b4b8cd810a145ef45fe92a","scripts":{"test":"node --test test/","start":"node src/index.mjs"},"_npmUser":{"name":"burnmydays","email":"burnmydays@proton.me"},"repository":{"url":"git+https://github.com/SunrisesIllNeverSee/signa.git","type":"git"},"_npmVersion":"11.12.1","description":"signaf — interactive token-cascade agent. Reads your session logs locally, computes the cascade + Steering Efficiency, builds a taste profile, and coaches you on token efficiency.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/signaf_0.1.0_1783698514149_0.39994562520386445","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Archived. Use 'npx sigrank' instead — https://signalaf.com"}},"time":{"created":"2026-07-10T15:48:34.029Z","modified":"2026-09-04T19:46:55.216Z","0.1.0":"2026-07-10T15:48:34.281Z"},"bugs":{"url":"https://github.com/SunrisesIllNeverSee/signa/issues"},"license":"CC-BY-NC-4.0","homepage":"https://signalaf.com","keywords":["sigrank","signa","agent","cascade","taste","steering-efficiency","token-efficiency"],"repository":{"url":"git+https://github.com/SunrisesIllNeverSee/signa.git","type":"git"},"description":"signaf — interactive token-cascade agent. Reads your session logs locally, computes the cascade + Steering Efficiency, builds a taste profile, and coaches you on token efficiency.","maintainers":[{"name":"burnmydays","email":"burnmydays@proton.me"}],"readme":"# signaf — token-cascade coach\n\n<div align=\"center\">\n\n[![license](https://img.shields.io/badge/license-CC--BY--NC--4.0-blue.svg?style=flat-square)](./LICENSE)\n[![platform](https://img.shields.io/badge/platform-node-grey.svg?style=flat-square)](https://nodejs.org)\n[![live](https://img.shields.io/badge/site-signalaf.com-gold.svg?style=flat-square)](https://signalaf.com)\n[![MCP](https://img.shields.io/badge/MCP-12%20tools-purple.svg?style=flat-square)](https://modelcontextprotocol.io)\n\n</div>\n\n**Interactive token-cascade agent.** Reads your AI coding session logs locally, computes the yield cascade (Υ, SNR, Leverage, Velocity), builds a behavioral taste profile, measures your Appropriate Steering Index (ASI), and coaches you on token efficiency.\n\nEverything stays local. Nothing leaves your machine.\n\n→ **[signalaf.com](https://signalaf.com)**\n\n---\n\n## The SigRank ecosystem\n\nsignaf is one of three pieces:\n\n| Repo                                                                  | What it is                                                                                                                              | Install                              |\n| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |\n| **[sigrank-mcp](https://github.com/SunrisesIllNeverSee/sigrank-mcp)** | The instrument — extracts 4 token pillars, computes the cascade, submits to the leaderboard. MCP server + TUI dashboard.                | `npx sigrank`                        |\n| **[sigrank-app](https://github.com/SunrisesIllNeverSee/sigrank-app)** | The leaderboard — signalaf.com. Privacy-preserving operator profiles, class tiers, board rankings.                                      | [signalaf.com](https://signalaf.com) |\n| **[signaf](https://github.com/SunrisesIllNeverSee/signa)** (this repo) | The coach — reads all 3 signal layers from your logs, builds a taste profile, measures ASI, coaches you on what your tokens were worth. | `npx signaf`             |\n\n**sigrank-mcp** is the calorie counter. **signaf** is the metabolic panel.\n\n---\n\n## Table of Contents\n\n- [The SigRank ecosystem](#the-sigrank-ecosystem)\n- [What this is](#what-this-is)\n- [Install](#install)\n- [Quick start](#quick-start)\n- [The REPL](#the-repl)\n- [MCP server mode](#mcp-server-mode)\n- [Skills](#skills)\n- [Appropriate Steering Index (ASI)](#appropriate-steering-index-asi)\n- [The taste profile](#the-taste-profile)\n- [The taste → cascade bridge](#the-taste--cascade-bridge)\n- [Privacy](#privacy)\n- [File layout](#file-layout)\n- [Architecture](#architecture)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## What this is\n\n`signaf` reads the same session logs that `sigrank-mcp`'s `tokenpull` reads — but instead of just extracting four token pillars, it reads **all three signal layers**:\n\n- **Layer 1 (metadata):** tool distribution, file edit counts, edit sizes, reject/error rates\n- **Layer 2 (structural):** correction loops, convergence patterns, session shape\n- **Layer 3 (content):** user feedback directives — distilled into preferences, not retained (opt-in)\n\nFrom these layers it computes:\n\n- The **cascade** (Υ, SNR, Leverage, Velocity, class) — the efficiency metrics\n- **Appropriate Steering Index (ASI)** — 8 dimensions measuring whether your interventions were the RIGHT ones, not just how often you accepted\n- A **behavioral taste profile** — 5 dimensions: steering signature, iteration fingerprint, workflow rhythm, cascade personality, correction taxonomy\n\nThen it coaches you: diagnose weak pillars, simulate changes, suggest improvements, track trends, set goals, analyze costs, detect anomalies, and run the full self-improvement cycle.\n\n---\n\n## Install\n\n```bash\nnpx signaf                 # no install needed\n# or install globally:\nnpm install -g signaf\nsignaf --help\n```\n\nRequires Node.js ≥ 18.\n\n---\n\n## Quick start\n\n```bash\n# 1. Start the interactive REPL (auto-scans on first run)\nsignaf\n\n# 2. Or run one-shot commands\nsignaf scan                 # Read logs, compute everything, save\nsignaf diagnose             # \"How am I doing?\"\nsignaf simulate input -50%  # \"What if I cut my input in half?\"\nsignaf suggest              # \"What should I do differently?\"\nsignaf taste                # \"What's my taste profile?\"\nsignaf asi                  # \"How well do I steer?\"\nsignaf bridge               # \"Connect my behavior to my cascade\"\nsignaf goal transmitter     # \"How do I hit TRANSMITTER?\"\nsignaf cost                 # \"How much did I spend?\"\nsignaf compare transmitter  # \"How do I compare to TRANSMITTER avg?\"\nsignaf self-improve         # Full cycle: diagnose → suggest → actions\nsignaf watch                # Background daemon (auto-scan on log changes)\n\n# 3. Or expose signaf as MCP tools for your AI agent\nsignaf --mcp                # starts stdio MCP server (12 tools)\n```\n\n---\n\n## The REPL\n\n```bash\n$ signa\n\nsignaf — interactive token-cascade agent. Type \"help\" for commands.\n\nsigna> how am I doing today?\n═══ DIAGNOSE ═══\nClass: POWER  ·  Υ 283.17  ·  SNR 0.522  ·  Leverage 259.3×  ·  Velocity 1.092\n...\n\nsigna> what should I do differently?\n═══ SUGGEST ═══\n1. Increase output by 19.43M (→ 42.79M)\n   impact: Υ 283.17 → 518.64 (83.2% gain)\n...\n\nsigna> simulate input -50%\n═══ SIMULATE ═══\nBase:    Υ 283.17  ·  POWER\nProjected: Υ 1,132.66  ·  ARCHITECT+\nDelta:   ↑ 849.49 (300.0%)\nClass change: POWER → ARCHITECT+\n...\n\nsigna> quit\n```\n\n### LLM mode (optional)\n\nThe REPL works without an LLM — it pattern-matches input to skills directly. For conversational responses, enable the Claude API adapter:\n\n```bash\n# Set your API key\nexport ANTHROPIC_API_KEY=sk-ant-...\n\n# Or in ~/.signa/settings.json:\n{ \"llm\": \"claude\" }\n```\n\nWhen enabled, signaf sends only computed **metrics** (class, yield, pillars, ASI dimensions, taste dimensions) to Claude for conversational formatting. No session logs, no code, no message content. Default mode (stub) sends nothing — zero API calls, zero data leaves.\n\n---\n\n## MCP server mode\n\n`signaf --mcp` starts a stdio MCP server that exposes 12 tools. Your AI agent (Claude Code, Cursor, Windsurf) can call them through MCP. You bring your own LLM; signaf provides the skills.\n\n```json\n// In .mcp.json:\n{\n  \"mcpServers\": {\n    \"signaf\": {\n      \"command\": \"signaf\",\n      \"args\": [\"--mcp\"]\n    }\n  }\n}\n```\n\n| MCP tool         | What it does                               |\n| ---------------- | ------------------------------------------ |\n| `signa_scan`     | Read logs, compute cascade + ASI + taste   |\n| `signa_diagnose` | Pillar-level audit + issue detection       |\n| `signa_simulate` | Project Υ/class delta from a pillar change |\n| `signa_suggest`  | Ranked recommendations with impact         |\n| `signa_taste`    | 5-dimension behavioral taste profile       |\n| `signa_asi`      | 8-dimension Appropriate Steering Index     |\n| `signa_bridge`   | Taste → cascade coaching insights          |\n| `signa_cost`     | Token-to-cost analysis + cache savings     |\n| `signa_goal`     | Path to a target class                     |\n| `signa_compare`  | Head-to-head vs class benchmark            |\n| `signa_track`    | Metrics over time from history             |\n| `signa_anomaly`  | Detect metric drops                        |\n\nContext is cached for 60 seconds to avoid re-reading logs on every tool call. All data stays local.\n\n---\n\n## Skills\n\n| Skill          | Trigger                        | What it does                                                      |\n| -------------- | ------------------------------ | ----------------------------------------------------------------- |\n| `scan`         | \"scan\", \"refresh\"              | Read logs, compute cascade + ASI + taste profile, save to history |\n| `diagnose`     | \"how am I doing\", \"audit\"      | Pillar-level audit: which pillar is weak, why                     |\n| `simulate`     | \"simulate\", \"what if\"          | Project Υ/class delta from a hypothetical pillar change           |\n| `suggest`      | \"suggest\", \"what should I do\"  | Ranked recommendations with simulated impact                      |\n| `track`        | \"track\", \"am I improving\"      | Metrics over time from local history                              |\n| `taste`        | \"taste\", \"profile\"             | Show your behavioral taste profile (5 dimensions)                 |\n| `asi`          | \"asi\", \"steering\"              | Show your Appropriate Steering Index (8 dimensions)               |\n| `bridge`       | \"bridge\", \"connect\"            | Taste → cascade coaching insights                                 |\n| `goal`         | \"goal\", \"how do I hit\"         | Path to a target class (TRANSMITTER, ARCHITECT, etc.)             |\n| `cost`         | \"cost\", \"how much\"             | Token-to-cost analysis (Claude pricing)                           |\n| `anomaly`      | \"anomaly\", \"did anything drop\" | Detect metric drops, pinpoint when                                |\n| `self-improve` | \"self-improve\", \"coach\"        | Full cycle: diagnose → suggest → simulate → next actions          |\n| `compare`      | \"compare\", \"vs\"                | Head-to-head vs class average                                     |\n| `watch`        | \"watch\", \"daemon\"              | Background daemon: auto-scan on .jsonl changes                    |\n\n---\n\n## Appropriate Steering Index (ASI)\n\nASI measures whether your interventions were the RIGHT ones, not just how often you accepted. Based on Anthropic's autonomy research.\n\n**8 dimensions:**\n\n1. **Acceptance rate** — fraction of turns used as-is\n2. **Correction rate** — fraction of turns you re-edited\n3. **Rejection rate** — fraction of turns explicitly rejected\n4. **Correction precision** — how targeted your corrections were (single-file vs scattered)\n5. **Intervention timing** — how long you let the agent work before intervening\n6. **Reliance slope** — trend of your acceptance rate over the session (stable/improving/declining)\n7. **Over-correction index** — fraction of corrections that were potentially unnecessary\n8. **Under-steering index** — fraction of turns where you should have intervened but didn't\n\nEach dimension reports a confidence level (high/medium/low) based on sample size.\n\n**Why ASI, not just SE?** SE v1 (the legacy metric) measured acceptance rate — a high SE just means you said \"yes\" a lot. ASI measures whether your \"yes\" was the right call. An SE of 0.99 can correspond to an ASI of 0.686 — revealing that 49% of corrections were potentially unnecessary.\n\n---\n\n## The taste profile\n\nSaved at `~/.signa/taste-profile.json`. Generated from your last 30 days of logs. **Behavioral, not content-based** — 5 dimensions:\n\n1. **Steering signature** — your ASI dimensions + SE legacy\n2. **Iteration fingerprint** — which files you iterate on, loop depth, convergence patterns\n3. **Workflow rhythm** — tool distribution, investigate-to-edit ratio, workflow style\n4. **Cascade personality** — pillar distribution tendencies (cache-hoarder, input-minimizer, output-light, high-leverage)\n5. **Correction taxonomy** — what you correct (design vs logic vs config), categorized by file type\n\n**Layer 3 (content-based) is opt-in.** Use `signaf taste --deep` or pass `{ deepTaste: true }` to the MCP tool. Raw content is not retained — only distilled preferences.\n\nThe profile is **operator-owned**: you can read it, edit it, share it, or delete it. It never leaves your machine by default.\n\n---\n\n## The taste → cascade bridge\n\nThe bridge connects your behavioral taste profile to your cascade performance, generating coaching insights unique to SigRank. No other tool can do this — it requires both the taste profile AND the cascade formula.\n\nExample insights:\n\n- **\"Bash-heavy workflow\"** (high severity) — you run a lot of Bash commands, which tend to reset context. Impact: lower cache reads → lower leverage → lower Υ. Recommendation: batch your commands.\n- **\"Diverging file loops\"** (high severity) — you're iterating on files without converging. Impact: high input, low output per turn. Recommendation: stop the loop and give explicit taste guidance.\n- **\"Output-light personality\"** (high severity) — your output-to-input ratio is low. Impact: low velocity → low Υ. Recommendation: ask the agent for complete implementations, not pieces.\n\n---\n\n## Privacy\n\nEverything stays local. The agent reads all three signal layers from your logs, builds the taste profile, computes metrics — all on-device. Nothing is transmitted.\n\n**MCP server mode:** All computation happens locally. The MCP server only exposes computed results to your AI agent via stdio. No data is sent to any server.\n\n**LLM mode (optional):** When enabled, signaf sends only computed **metrics** (class, yield, pillars, ASI dimensions, taste dimensions) to Claude for conversational formatting. No session logs, no code, no message content. Default mode (stub) sends nothing.\n\n---\n\n## File layout\n\n```\n~/.signa/\n  taste-profile.json   — your taste profile (regenerated on each scan)\n  history.json         — cascade metrics over time (append-only, capped at 1000)\n  settings.json        — codename, platform, log root path, llm config\n```\n\n---\n\n## Architecture\n\n```\nsigna/\n  src/\n    index.mjs           — entry: CLI dispatch + REPL boot + --mcp flag\n    repl.mjs            — interactive chat loop (readline, pattern-matches to skills)\n    mcp-server.mjs      — MCP server: 12 tools, stdio transport, 60s context cache\n    logreader.mjs       — rich session-log reader (all 3 signal layers)\n    cascade.mjs         — Υ/SNR/Leverage/Velocity/class + simulate + cost (pure math)\n    store.mjs           — local JSON persistence (~/.signa/)\n    watch.mjs           — daemon: auto-scan on .jsonl change\n    taste/\n      extractor.mjs     — extract taste signal from logs (3 layers, Layer 3 opt-in)\n      profile.mjs       — build + save + load taste profile\n      se.mjs            — Steering Efficiency (SE v1) + Appropriate Steering Index (ASI v2)\n      bridge.mjs        — taste → cascade coaching insights\n    skills/\n      index.mjs         — all 13 skills (diagnose, simulate, suggest, taste, asi, etc.)\n    llm/\n      stub.mjs          — LLM interface (delegates to claude.mjs when configured)\n      claude.mjs        — Claude API adapter (operator brings own key, metrics-only)\n```\n\n---\n\n## Brainstorm\n\nThis agent was built from the [SigRank brainstorm package](https://signalaf.com). The brainstorm stays untouched — this is the build that came out of it. See `PLAN.md` for the build plan.\n\n---\n\n## Contributing\n\nContributions welcome. signaf is built in the open.\n\n- Report bugs via [GitHub Issues](https://github.com/SunrisesIllNeverSee/signa/issues)\n- PRs: fork → branch → tests pass → open PR against `main`\n- See the [SigRank ecosystem](#the-sigrank-ecosystem) section for how this repo relates to the others\n\n---\n\n## License\n\nCC-BY-NC-4.0 — see [`LICENSE`](./LICENSE).\n","readmeFilename":"README.md"}