Skip to main content
Glama

SigRank CLI & MCP

Read your local AI usage, inspect the token cascade, and optionally publish a signed snapshot to the SigRank leaderboard on SignalAF.

npx sigrank

npm CI License: MIT

Website · Quickstart · MCP setup · Tool and adapter reference · Privacy

What it does

  • Reads usage metadata from supported local AI session logs.

  • Shows input, output, cache-write, and cache-read counts across available time windows.

  • Calculates Yield, Leverage, Velocity, SNR, and 10xDEV locally.

  • Provides a terminal dashboard and MCP tools for AI clients.

  • Submits signed telemetry only when you choose to publish.

This evaluates observable token-processing patterns, not model quality, work quality, productivity, or business outcomes. An adapter may estimate a pillar when its source does not expose it separately; those limitations are documented in the adapter reference.

Related MCP server: MCP Monitor

Get started

Requires Node.js 20 or later. No global install is required.

Explore locally

npx sigrank                       # interactive dashboard in a terminal
npx sigrank board --once          # public leaderboard, one-shot
npx sigrank board --window 7d --once

The dashboard includes Dashboard, Trends, Compare, Board, Watch, and Connect tabs. Use 1–6 or the arrow keys to switch, R to refresh, and Q to quit.

Publish your own snapshot

  1. Sign in at signalaf.com and create a connect code in Settings.

  2. Enroll this device, then inspect the dry-run payload.

  3. Submit when you are ready to publish.

npx sigrank enroll
npx sigrank submit --dry-run
npx sigrank submit

Enrollment binds a device signing key to your operator account. The private key stays on your device. The server verifies and re-scores submitted telemetry; a local preview is not a guaranteed public rank.

For repeated use, an optional global installation provides the same commands:

npm install -g sigrank
sigrank

Connect an MCP client

Add this server to your client's MCP configuration:

{
  "mcpServers": {
    "sigrank": {
      "command": "npx",
      "args": ["-y", "sigrank"]
    }
  }
}

The entry point automatically runs an MCP stdio server when launched without a terminal. MCP tool names are called by the client; they are not shell commands.

Task

Tools

Inspect local usage

tokenpull, rank_windows, tokenpull_compare

Calculate from supplied counts

rank_paste, get_sigrank_standard_record

Read public results

get_leaderboard, get_operator, discover_peers

Explore possible changes

diagnose_cascade, simulate_change, suggest_improvements

Enroll and submit

enroll, submit_verified

For the full list, arguments, and adapter paths, see the CLI and MCP reference. Publishing through submit_verified requires confirm: true; dry_run: true inspects the payload without publishing.

Command guide

Command

Purpose

sigrank

Open the terminal dashboard

sigrank board --once

Print the public leaderboard

sigrank compare --platform codex

Audit token counts across available local sources

sigrank watch --window 7d

Watch local usage updates

sigrank enroll

Bind a device using a connect code

sigrank submit --dry-run

Inspect a signed submission without sending it

sigrank submit

Publish a verified submission

sigrank proxy

Start the optional loopback usage proxy

sigrank --help

Show the current command reference

Optional usage proxy

Some clients do not persist all provider-reported usage in their session files. sigrank proxy can capture usage from compatible Anthropic or OpenAI API traffic when a client supports a custom API base URL.

The proxy is off by default and binds only to loopback. It forwards provider-bound request/response content and credentials in memory, but does not persist their content. Its local usage log contains token counts and metadata. See the privacy contract before using it.

How measurement works

Four token pillars feed the calculation:

Yield (Υ) = (cache_read × output) / input²
Leverage  = cache_read / input
Velocity  = output / input
SNR       = output / (input + output)
10xDEV    = log₁₀(Leverage)

This package distributes the Upsilon measurement engine through the sigrank CLI/MCP compatibility command. SigRank is the public leaderboard and proof surface on SignalAF. TTEOP defines the protocol semantics; MO§ES™ is the governance framework.

The implementation delegates canonical calculations through token-cascade to tteop-spec. See the TTEOP implementation profile and protocol compatibility notes.

Privacy

Local inspection does not publish your usage. Signed submissions include the four pillars plus account/device identifiers, signature, platform/version information, counts, and report metadata. Enrollment also sends a device label.

Prompt text, response text, source code, repository contents, and local file paths are not part of the ranked submission payload. The optional proxy's transient handling of content is separate from what is persisted or submitted.

Read the full payload and privacy details, and use submit --dry-run to inspect what would be sent.

Development

git clone https://github.com/SunrisesIllNeverSee/sigrank-mcp.git
cd sigrank-mcp
npm install
npm test
npm run test:packaged

Run node index.mjs in a terminal for the dashboard, or configure the checked-out entry point in an MCP client. Release versions are managed by the repository's explicit publishing workflow; a documentation commit does not publish an npm release.

  • sigrank-app — SignalAF website, profiles, public API, and leaderboard.

  • token-cascade — measurement implementation consumed by this package.

  • TTEOP — protocol specification and semantics.

Contributing and security

See the contributing guide. Open bugs in GitHub Issues; report vulnerabilities privately through the security policy.

License

MIT.

Available Tools

25 tools
diagnose_cascadeA
Read-onlyIdempotent

Analyzes your token cascade and diagnoses where you're leaking efficiency. Takes your 4 pillars (input/output/cacheCreate/cacheRead) and produces a ranked list of efficiency leaks with severity (critical/warning/info), findings, and recommendations. Checks: cache leverage (are you rereading what you wrote?), velocity (are you generating enough output per input?), SNR (is your signal drowning in noise?), cache creation ratio (are you over-committing?), input bloat (is fresh input too high?), and 10xDEV (is the full cascade compounding?). Each finding includes an estimated Υ impact. Pure local math — no network, no submission. Use this BEFORE simulate_change to understand what's wrong, then use simulate_change to test fixes. Accepts the same input formats as rank_paste (JSON or 4 whitespace numbers).

Inputs: text (required). Returns: cascade, pillars, summary, diagnosis

discover_peersA
Read-only

Discovers mentors, peers, and complementary operators for YOUR operator on the SigRank leaderboard. Uses your enrolled device identity — no codename needed. Finds operators you should learn from: (1) Mentors — 1-2 class tiers above you with similar cascade shapes, including the specific pillar delta that explains the yield gap (e.g. '12× your cache reads'). (2) Peers — same class tier, ranked by yield proximity. (3) Complementary — operators whose strength is your weakness. Use this after submit_verified to find who to learn from, then chain into self_improve with the mentor's pillar deltas as context. Requires enrollment (npx sigrank-mcp enroll). Intent: DISCOVER_PEERS.

Inputs: n, platform. Returns: cta, peers, mentors, summary, +2 more

enrollA
Idempotent

Bind THIS device to your SigRank operator so your signed token runs cascade to the live board. Paste the key from signalaf.com → Settings → "New key" (or "Generate connect code"). On first run it generates + stores a local ed25519 keypair (~/.sigrank-mcp/identity.json); only the PUBLIC key is ever sent. By enrolling you agree to the SignalAF Terms of Service (signalaf.com/terms) and Privacy Policy (signalaf.com/privacy). Need a new key? Click "New key" at signalaf.com → Settings, then paste it here.

Inputs: code (required), device_label. Returns: reason, status, codename, device_id, +2 more

get_leaderboardA
Read-only

Fetches the live public SigRank leaderboard from signalaf.com. Reads all ranked operators sorted by yield (Υ = Cache Reads × Output / Input²) and returns an array of operator summaries. Each entry contains: codename (public display name), yield (Υ, the headline efficiency metric), leverage ratio (Cr/I = cache reads divided by input), velocity (O/I = output divided by input), class tier (one of 24 experience stages: 8 tiers × 3 sub-stages, e.g. ARCH+ I, REFINER II, IGNITER III), and rank position (integer, 1-based). Returns an empty array if no operators have submitted yet. Use this to see where operators stand overall, to find specific codenames for get_operator lookups, or to display the current rankings. Do NOT use this to check your own rank if you already know your codename — use get_operator instead for a single-operator profile with per-window breakdowns. After calling this, follow up with get_operator to get detailed metrics for any operator of interest.

Inputs: no named parameters. Returns: operators

get_operatorA
Read-only

Fetches one operator's live profile from the SigRank board by their codename. Reads the operator's current submission data from signalaf.com and returns their detailed metrics: yield (Υ), leverage ratio (Cr/I), velocity (O/I), class tier (one of 24 experience stages: 8 tiers × 3 sub-stages, e.g. ARCH+ I, REFINER II, IGNITER III), rank position (integer, 1-based), and per-window breakdowns for each time range (7d, 30d, 90d, all-time) with the four canonical pillars (input, output, cacheCreate, cacheRead) per window. Returns an error if the codename is not found on the board. Use this to look up any operator who has submitted to the board — codenames are public and visible on the leaderboard. Do NOT use this to browse all operators — use get_leaderboard for that. After calling this, you can use simulate_change to model what would happen if the operator adjusted their token mix.

Inputs: codename (required). Returns: rank, class, yield_, batched, +4 more

get_sigrank_standard_recordA
Read-onlyIdempotent

Build Upsilon's portable sigrank/0.1-draft compatibility record from available token telemetry. Input and output are required; unavailable cache telemetry remains null. Computes the canonical cascade locally through token-cascade and returns Yield, Leverage, Velocity, SNR, and 10xDEV. Upsilon is the measurement product; SigRank is the public leaderboard. No data is submitted or persisted.

Inputs: input (required), output (required), tool, model, +4 more. Returns: spec, source, metrics, protocol, +4 more

rank_pasteA
Read-onlyIdempotent

Computes the SigRank yield cascade from a paste of token counts. Parses the input, runs the full cascade math locally (no network calls), and returns: yield (Υ, the headline efficiency metric, Υ = Cache Reads × Output / Input²), snr (signal-to-noise ratio), leverage (Cr/I = cache reads divided by input), velocity (O/I = output divided by input), dev10x (10xDEV score), class (operator experience stage — 24 stages = 8 tiers × 3 sub-stages I/II/III, e.g. ARCH+ I, REFINER II, IGNITER III, or UNCLASSED for empty input), mode (detected working mode), and a deterministic prose "card" summarizing the result in plain English. Accepts two input formats: (1) JSON object {"input":N,"output":N,"cacheCreate":N,"cacheRead":N} or (2) four whitespace-separated numbers in order: input output cacheCreate cacheRead. Returns an error if the input is malformed or has negative values. Use this for a quick one-off ranking without submitting to the board. Do NOT use this to submit your score — use submit_paste instead, which both ranks and publishes. Do NOT use this if you want to rank all four time windows at once — use rank_windows for that. After calling this, use submit_paste to publish the result if you want to appear on the leaderboard.

Inputs: text (required). Returns: snr, card, mode, class, +6 more

rank_windowsA
Read-onlyIdempotent

Rank all four time windows (7d/30d/90d/all-time) in one call from a dashboard paste — paste the full table from ccusage, tokscale, or the Claude Max usage dashboard and get the cascade (Υ, SNR, Leverage, Velocity, 10xDEV, class, card) for each window. Each window is parsed and scored independently. Named keys required (input/output/cacheCreate/cacheRead); positional order is NOT safe here (dashboards list cache_read before cache_create — see WINDOWED_PROFILES gotcha). Omit windows you don't have — partial input is allowed (1–4 windows). Does NOT submit to the board; use tokenpull_submit for a local zero-paste preview, or submit_verified to publish via the enrolled-device path.

Inputs: 7d, 30d, 90d, all, +1 more. Returns: windows

self_improveA
Read-onlyIdempotent

Runs the full self-improvement cycle in one call: (1) gets your current token pillars — either from the provided text or by running tokenpull on your local logs, (2) diagnoses where you're leaking efficiency (diagnose_cascade), (3) generates ranked improvement suggestions (suggest_improvements), (4) simulates the top suggestion (simulate_change), and (5) returns the complete cycle: diagnosis + suggestions + the simulated impact of the best change. This is the 'one-click optimize' tool — call it at the end of a session to see what to improve next time. If you provide pillars in text, it skips the tokenpull step. If you omit text, it runs tokenpull first (requires local ccusage logs). Pure local math — no network, no submission. The scope parameter adds mode detection (BUILD/EDIT/DEBUG/MAINTAIN/IDLE) and scoped analysis: 'daily' (default — current behavior + mode), 'weekly' (compound into weekly snapshots + report artifact), 'trend' (30d/90d trajectory analysis).

Inputs: text, scope, window. Returns: mode, trend, advice, report, +8 more

simulate_changeA
Read-onlyIdempotent

The first PRESCRIPTIVE SigRank tool — 'what if I changed my token mix?' Takes your current 4 pillars (input/output/cacheCreate/cacheRead) and one or more proposed changes, runs the canonical cascade on BOTH the current and simulated values, and returns the exact Υ Yield delta, class change, and per-metric diffs. This is the 'show me the payoff before I do the work' primitive: no network, no submission, pure local math. Use it to answer 'would increasing my cache-read by 50k tokens actually move my class?' before you change your workflow. Accepts the current pillars as JSON or 4 numbers (same as rank_paste) plus a changes object with any of the 4 pillar names mapped to new absolute values OR relative deltas (e.g. {cacheRead: '+50000'} or {input: 800000}).

Inputs: text (required), changes (required). Returns: current, simulated, yield_delta, class_change, +1 more

submit_pasteA
Read-onlyIdempotent

Ranks a paste of token counts locally and shows the cascade result (yield, leverage, velocity, class, card). This is a PREVIEW-ONLY tool — it does not publish to the board. The board's /api/v1/ingest-paste endpoint now requires an authenticated Supabase session, which MCP tools do not carry. To publish to the leaderboard, use submit_verified (which signs and posts to /api/v1/snapshots via the enrolled-device path) or submit directly through the signalaf.com web UI. Use this when you have token counts from ccusage or a dashboard and want to see your score instantly. Do NOT use this if you want to pull your local usage automatically — use tokenpull_submit for the zero-paste flow. Do NOT use this for multi-window dashboard pastes — use rank_windows to rank them first.

Inputs: text (required), codename. Returns: reason, status, preview, server_response

submit_verifiedA
Idempotent

Publish your LOCAL token runs to the SigRank board as a VERIFIED operator — the enrolled, signed path. Reads your pillars (tokenpull), builds the canonical Schema 1.0 snapshot per window, ed25519-signs it with your device key, and POSTs to /api/v1/snapshots. Requires npx sigrank-mcp enroll first (a bound device). Only signed submissions from a trusted device rank on the board. Token-only; the private key never leaves your machine. Publishing requires confirm: true (ask the user first); pass dry_run:true to inspect the exact signed payload without publishing and without confirm.

Inputs: window, confirm, dry_run, platform. Returns: reason, status, preview, server_response

suggest_improvementsA
Read-onlyIdempotent

Generates ranked, simulated improvement suggestions for your token cascade. Takes your 4 pillars, tests multiple improvement strategies (increase cache reads, reduce fresh input, increase output, optimize cache creation), simulates each with the canonical cascade engine, and returns them ranked by Υ yield impact. Each suggestion includes: the action, which pillar to change, how much to change it, the projected Υ after the change, the yield delta, the projected class tier, and a rationale. Also returns the single highest-impact change (best_single_change). Pure local math — no network, no submission. Use this after diagnose_cascade to get actionable next steps, then use simulate_change to fine-tune before committing. Accepts the same input formats as rank_paste.

Inputs: text (required). Returns: suggestions, current_class, current_yield, best_single_change

tokenpullA
Read-only

Pull your LOCAL token usage from the platform's session logs and rank it across the four windows (7d/30d/90d/all-time) with the cascade — zero paste. Token-only: reads usage counts not message content. The numbers stay on your machine unless you submit them. Some platforms may have partial data (estimated=true when cacheCreate isn't available) or a dataGap note when the log format doesn't expose raw token counts.

Inputs: platform. Returns: card, note, window, cascade, +6 more

tokenpull_compareA
Read-only

Pull token usage from ALL four local sources in parallel — tokenpull (JSONL canon), ccusage CLI, token-dashboard SQLite, and tokscale report — and return them side-by-side with delta % vs tokenpull as the baseline. Also computes the cascade (Υ, SNR, Leverage, class) for each source so you can see how each verifier scores. Useful for validating your numbers before submitting, or understanding discrepancies between tools. Claude only for token-dash; codex and others use tokenpull + ccusage + tokscale. Token-only, on-device.

Inputs: platform. Returns: sources, platform

tokenpull_submitA
Read-onlyIdempotent

Pull your LOCAL token usage from session logs and compute the cascade per window — the zero-paste preview flow. Reads the four canonical pillars (input, output, cacheCreate, cacheRead) per window from your local logs and computes yield, leverage, velocity, class, and card. This is a PREVIEW-ONLY tool — it does not publish to the board. The board's /api/v1/ingest-paste endpoint now requires an authenticated Supabase session, which MCP tools do not carry. To publish to the leaderboard, use submit_verified (which signs and posts to /api/v1/snapshots via the enrolled-device path) or submit directly through the signalaf.com web UI. Token-only — no prompt content is read or transmitted.

Inputs: window, codename, platform. Returns: reason, status, preview, server_response

tokscale_breakdownA
Read-only

Show a per-model breakdown of your token usage across all platforms detected by tokscale. Models under the threshold (default 1%) are lumped into 'other' to keep the display clean. Useful for seeing which models you actually use per platform (e.g. claude-opus-4-8 76%, claude-sonnet-4-6 11%, other 0.3%). Returns { platform: [{ model, input, output, cacheRead, cacheCreate, pct }] }.

Inputs: threshold. Returns: platforms

tokscale_competitive_intelA
Read-only

Competitive intelligence for any AI tool company. Pass a target tool (by tokscale client slug like 'claude', 'codex', 'devin-cli' or canonical platform name like 'devin', 'other') and get: the target's rank by tokens among all detected tools, its full profile (tokens, cost, model mix, cache_read_pct, cost_per_million_tokens, market share), and a head-to-head comparison against every competitor (each competitor's tokens, cost, model_count, share, cost_per_million_tokens). Returns market_totals for context. If the target is not found, lists all detected clients. Use this to benchmark one AI tool against its competitors on this machine. All data is local — this is your own usage, not aggregate market data.

Inputs: target (required). Returns: error, found, target, competitors, +3 more

tokscale_cost_analysisA
Read-only

Cost analysis per developer per model from your local tokscale data. Returns a per-client × per-model cost breakdown with cost_per_million_tokens, cost_per_message, and share_cost. Includes a per-client cost rollup and totals: total_cost, total_tokens, avg_cost_per_million_tokens, most_expensive_model, cheapest_per_token. Use this to see exactly where your AI spend goes — which tools and models cost the most and which give the best value per token. Do NOT use this for market share — use tokscale_market_share for that.

Inputs: no named parameters. Returns: error, totals, entries, client_rollup

tokscale_developer_profileA
Read-only

Per-developer usage profile across all 20+ AI tools detected by tokscale on this machine. For each tool: model mix (per-model tokens/cost/messages/performance), token pillars (input/output/cache_read/cache_write/reasoning), cache_read_pct, session count, scan path (redacted to ~), workspace breakdown, and headless support flag. Returns a summary with tool_count, total_cost, dominant_tool. All filesystem paths are redacted (home dir → ~). Use this to understand your full AI tool footprint — which tools you use, which models per tool, and how your usage is distributed. Do NOT use this for cost-only analysis — use tokscale_cost_analysis for that.

Inputs: no named parameters. Returns: error, tools, summary

tokscale_device_profileA
Read-only

Device fingerprinting: profiles this machine's AI tool footprint — which AI tools are installed, where their session logs live (paths redacted to ~), how many sessions and messages each has, when the machine was active (daily activity + day-of-week distribution), session concurrency, and longest continuous session. Combines tokscale clients + graph data. All filesystem paths are redacted so no local username leaks. Use this to audit your own machine's AI tool installation and activity pattern. This is local-only — it profiles the current machine, not remote devices.

Inputs: no named parameters. Returns: error, summary, activity, sessions, +4 more

tokscale_market_shareA
Read-only

Complete AI tool market share analysis from your local tokscale data. Aggregates per-model usage by client (AI tool) and computes each tool's share of total tokens, cost, and messages. Returns each tool ranked by token share, with share_tokens / share_cost / share_messages percentages and a totals rollup. All data is read locally from tokscale's scan of your session logs — no network calls, no PII. Use this to see which AI coding tools dominate your workflow by volume, spend, or activity. Do NOT use this for per-model detail — use tokscale_developer_profile for that.

Inputs: no named parameters. Returns: error, tools, totals

tokscale_mcp_usageA
Read-only

MCP server usage patterns from your local tokscale data. Reports which MCP servers tokscale detected on this machine, the detection window, and active days in that window. tokscale currently exposes detected MCP servers as a set (not per-session attribution), so the report notes the detection window. Use this to see which MCP servers are active on your machine. If no servers are detected, the response explains that MCP server tracking requires a tokscale version that records per-session MCP attribution.

Inputs: no named parameters. Returns: note, error, servers, server_count, +2 more

watch_tokenpullA
Idempotent

One poll per call: pulls your local token logs and returns the current cascade for the watched window — the tool never blocks or loops. Re-call at your desired cadence to watch for changes (interval_s is advisory only and echoed back as poll_interval_s). With submit:true AND confirm:true (and an enrolled device) each call may also sign + publish the watched window to the public board, rate-limited to once per 5 min per platform+window. Publishing requires confirm: true (ask the user first); default is preview-only (no submit).

Inputs: submit, window, confirm, platform, +1 more. Returns: card, note, window, cascade, +6 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 25 tools

    Disambiguation3/5

    The set has several overlapping families: rank_paste/submit_paste both rank pasted counts, tokenpull/tokenpull_submit both pull local usage, and get_sigrank_standard_record overlaps with cascade-ranking tools. The descriptions are unusually detailed and explicitly say when not to use a tool, which prevents total confusion, but an agent still faces real misselection risk among the near-duplicate preview/pull/paste tools.

    Naming Consistency3/5

    Names are consistently snake_case, but the convention is mixed: some use domain prefixes (tokscale_*, tokenpull*), some use get_* resource lookup, some use verb phrases (rank_paste, submit_verified), and some are composite actions (self_improve, discover_peers). It remains readable, but there is no single predictable verb_noun pattern across the set.

    Tool Count3/5

    At 25 tools, the surface is heavy for a single MCP server even though the domain is broad: local token analytics, leaderboard access, submission, diagnosis, and tokscale profiling. Many analytics and cascade tools earn their place individually, but consolidation of the preview/pull/rank variants would improve scoping.

    Completeness4/5

    The domain lifecycle is largely covered: enrollment, local token pull, multi-source comparison, ranking/simulation/diagnosis, leaderboard and operator lookup, verified submission, peer discovery, and extensive tokscale analytics. Minor gaps remain around submission management or richer operator search, but core workflows have no obvious dead ends.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to interact with the AI-Archive platform for research paper discovery through semantic search, paper submission and management, peer review with structured scoring, and citation generation in multiple formats.
      54
      21 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An observability tool for agentic AI pipelines that intercepts MCP and Python tool calls to provide real-time metrics, session replays, and alerts via a local dashboard. It enables centralized monitoring of multiple MCP servers through multiplexer and proxy modes without requiring changes to existing agent code.
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to rate each other, track interaction outcomes, and compute trust scores, with features like submitting ratings, getting reputation profiles, leaderboards, and trust computation.
      11 npm
      MIT