sigrank 1.0.46 → 1.0.48
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/MCP_SERVER_DESCRIPTION.md +3 -3
- package/README.md +90 -424
- package/manifest.json +1 -1
- package/package.json +1 -1
- package/presentation/cli.mjs +4 -77
- package/presentation/tui-themes.mjs +43 -28
- package/presentation/tui.mjs +958 -268
- package/resources/privacy-model.md +4 -4
- package/tools/watch-tokenpull.mjs +14 -3
package/README.md
CHANGED
|
@@ -1,272 +1,65 @@
|
|
|
1
|
-
# SigRank
|
|
1
|
+
# SigRank CLI & MCP
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
> The `sigrank` package reads local AI session logs, derives your token cascade,
|
|
5
|
-
> and publishes to the board at [signalaf.com](https://signalaf.com).
|
|
6
|
-
> _Four token counts only. Never prompts or code._
|
|
7
|
-
|
|
8
|
-
<div align="center">
|
|
9
|
-
|
|
10
|
-
<p><img src="./.github/assets/og-card.png" alt="SigRank SignalAF — AI operator evaluation and token cascade efficiency leaderboard" width="800"></p>
|
|
11
|
-
|
|
12
|
-
**SignalAF is the brand. SigRank proves. MO§ES™ governs.**
|
|
13
|
-
|
|
14
|
-
SigRank evaluates observable AI operator token-processing patterns—not AI model quality, cognition, work quality, employee productivity, or business value.
|
|
15
|
-
|
|
16
|
-
[](https://www.npmjs.com/package/sigrank)
|
|
17
|
-
[](https://github.com/SunrisesIllNeverSee/sigrank-mcp/actions/workflows/ci.yml)
|
|
18
|
-
[](https://github.com/SunrisesIllNeverSee/sigrank-mcp/actions/workflows/codeql.yml)
|
|
19
|
-
[](https://github.com/SunrisesIllNeverSee/sigrank-mcp/actions/workflows/dependency-audit.yml)
|
|
20
|
-
[](https://github.com/SunrisesIllNeverSee/sigrank-mcp/network/dependencies)
|
|
21
|
-
[](./LICENSE)
|
|
22
|
-
[](https://nodejs.org)
|
|
23
|
-
[](https://signalaf.com)
|
|
24
|
-
[](https://glama.ai/mcp/servers/SunrisesIllNeverSee/sigrank-mcp)
|
|
25
|
-
[](https://lightnow.ai/servers/io.github.SunrisesIllNeverSee/sigrank-mcp)
|
|
26
|
-
|
|
27
|
-
</div>
|
|
28
|
-
|
|
29
|
-
<p align="center">
|
|
30
|
-
<a href="https://www.npmjs.com/package/sigrank"><img src="https://img.shields.io/badge/$%20npx%20sigrank-gold?style=for-the-badge&logo=npm&logoColor=white&labelColor=1a1a1a&color=daa520" alt="npx sigrank" /></a>
|
|
31
|
-
</p>
|
|
32
|
-
|
|
33
|
-
## Table of Contents
|
|
34
|
-
|
|
35
|
-
- [SignalAF product architecture](#signalaf-product-architecture)
|
|
36
|
-
- [Quickstart](#quickstart--3-steps-to-the-board)
|
|
37
|
-
- [Install from GitHub](#install-from-github)
|
|
38
|
-
- [Install via Smithery](#install-via-smithery)
|
|
39
|
-
- [Commands](#commands)
|
|
40
|
-
- [MCP Server mode](#mcp-server-mode)
|
|
41
|
-
- [Cascade math](#cascade-math)
|
|
42
|
-
- [Token Pillars](#token-pillars--sources)
|
|
43
|
-
- [Platform adapters](#platform-adapters)
|
|
44
|
-
- [Privacy](#privacy)
|
|
45
|
-
- [Env vars](#env-vars)
|
|
46
|
-
- [Dev / test](#dev--test)
|
|
47
|
-
- [File map](#file-map)
|
|
48
|
-
- [Contributing](#contributing)
|
|
49
|
-
- [License](#license)
|
|
50
|
-
|
|
51
|
-
| The board | Your operator profile |
|
|
52
|
-
| :-----------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------: |
|
|
53
|
-
| [](https://signalaf.com/board/all) | [](https://signalaf.com) |
|
|
54
|
-
| Every operator ranked by **Υ Yield** — the architecture of the cascade, not raw spend | Cascade layer, class, and fingerprint — derived from four token counts |
|
|
55
|
-
|
|
56
|
-
> **Run [`sigrank enroll`](#sign-in--submit) then [`sigrank submit`](#sign-in--submit) to get ranked and claim your public profile at [signalaf.com](https://signalaf.com).**
|
|
57
|
-
|
|
58
|
-
---
|
|
59
|
-
|
|
60
|
-
## SignalAF product architecture
|
|
61
|
-
|
|
62
|
-
```text
|
|
63
|
-
MO§ES™ governance → SignalAF brand → SigRank leaderboard → Upsilon engine
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
| Repo | What it is | Install |
|
|
67
|
-
|------|-----------|---------|
|
|
68
|
-
| **[sigrank-mcp](https://github.com/SunrisesIllNeverSee/sigrank-mcp)** (this repo) | SigRank's on-device scanner — extracts four token pillars, computes locally, and optionally submits to the board. | `npx sigrank` |
|
|
69
|
-
| **[sigrank-app](https://github.com/SunrisesIllNeverSee/sigrank-app)** | SignalAF web app — the SigRank leaderboard, operator profiles, and proof surface. | [signalaf.com](https://signalaf.com) |
|
|
70
|
-
| **[bestuser-router-mcp](https://github.com/SunrisesIllNeverSee/bestuser-router-mcp)** | The intent layer — routes "who is the best AI user?" queries to SigRank SignalAF's leaderboard. MCP server for AI assistants. | `npx bestuser-router-mcp` |
|
|
71
|
-
| **[sigarena](https://github.com/SunrisesIllNeverSee/sigarena)** | The satellite — public LLM operator evals at sigeconomy.com. Read-only leaderboard, SEO/AEO surface. | [sigeconomy.com](https://sigeconomy.com) |
|
|
72
|
-
| **[sigrank-vscode](https://github.com/SunrisesIllNeverSee/sigrank-vscode)** | The IDE extension — see your cascade metrics inline in VS Code. | `code --install-extension sigrank.sigrank` |
|
|
73
|
-
| **[fundscore](https://github.com/SunrisesIllNeverSee/fundscore)** | The repo scorer — investor-readiness scoring for GitHub repos. CLI + MCP server. | `npx fundscore` |
|
|
74
|
-
|
|
75
|
-
### Also in the MO§ES™ suite
|
|
76
|
-
|
|
77
|
-
| Site | What it is |
|
|
78
|
-
| ---- | ---------- |
|
|
79
|
-
| **[SIGNOMY](https://signomy.xyz)** | Governed AI agent marketplace where ranked agents form teams, fill slots, run missions, and earn revenue under constitutional protocol. Agents are free. Operators pay. |
|
|
80
|
-
| **[MO§ES](https://mos2es.com)** | Constitutional governance and methodology — the law governing SignalAF, SigRank, and the Upsilon measurement engine. |
|
|
81
|
-
|
|
82
|
-
## Quickstart — 3 steps to the board
|
|
3
|
+
Read your local AI usage, inspect the token cascade, and optionally publish a signed snapshot to the [SigRank leaderboard on SignalAF](https://signalaf.com).
|
|
83
4
|
|
|
84
5
|
```bash
|
|
85
|
-
|
|
86
|
-
npm install -g sigrank
|
|
87
|
-
|
|
88
|
-
# 2. Sign in (paste a connect code from signalaf.com → Settings → New key)
|
|
89
|
-
sigrank enroll
|
|
90
|
-
|
|
91
|
-
# 3. Submit your cascade to the board
|
|
92
|
-
sigrank submit
|
|
93
|
-
|
|
94
|
-
# (cautious? see exactly what would be sent — four counts + a signature — sending nothing)
|
|
95
|
-
sigrank submit --dry-run
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
That's it. sigrank reads your local AI session logs on-device, derives your token cascade (Υ Yield, Leverage, Velocity, 10xDEV), and publishes to [signalaf.com](https://signalaf.com). No paste, no transcript content — what leaves your machine is limited to the four token pillars plus the identifiers listed under [Privacy](#privacy).
|
|
99
|
-
|
|
100
|
-
Or just explore without signing in:
|
|
101
|
-
|
|
102
|
-
```bash
|
|
103
|
-
sigrank # launches the full tabbed TUI (dashboard, compare, board, watch)
|
|
104
|
-
npx sigrank board --once # print the live leaderboard once
|
|
105
|
-
bunx sigrank board --once # same, via Bun (faster startup if you have it)
|
|
6
|
+
npx sigrank
|
|
106
7
|
```
|
|
107
8
|
|
|
108
|
-
|
|
9
|
+
[](https://www.npmjs.com/package/sigrank)
|
|
10
|
+
[](https://github.com/SunrisesIllNeverSee/sigrank-mcp/actions/workflows/ci.yml)
|
|
11
|
+
[](./LICENSE)
|
|
109
12
|
|
|
110
|
-
|
|
111
|
-
git clone https://github.com/SunrisesIllNeverSee/sigrank-mcp.git
|
|
112
|
-
cd sigrank-mcp
|
|
113
|
-
npm install
|
|
13
|
+
**[Website](https://signalaf.com) · [Quickstart](#get-started) · [MCP setup](#connect-an-mcp-client) · [Tool and adapter reference](./docs/CLI-MCP-REFERENCE.md) · [Privacy](#privacy)**
|
|
114
14
|
|
|
115
|
-
|
|
116
|
-
node index.mjs # TUI (if TTY)
|
|
117
|
-
node cli.mjs board --once # leaderboard one-shot
|
|
15
|
+
## What it does
|
|
118
16
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
17
|
+
- Reads usage metadata from supported local AI session logs.
|
|
18
|
+
- Shows input, output, cache-write, and cache-read counts across available time windows.
|
|
19
|
+
- Calculates Yield, Leverage, Velocity, SNR, and 10xDEV locally.
|
|
20
|
+
- Provides a terminal dashboard and MCP tools for AI clients.
|
|
21
|
+
- Submits signed telemetry only when you choose to publish.
|
|
123
22
|
|
|
124
|
-
|
|
125
|
-
**Site:** [signalaf.com](https://signalaf.com)
|
|
126
|
-
**npm:** [sigrank](https://www.npmjs.com/package/sigrank)
|
|
127
|
-
**Smithery:** [smithery.ai/servers/burnmydays/sigrank](https://smithery.ai/servers/burnmydays/sigrank)
|
|
128
|
-
**Glama:** [glama.ai/mcp/servers/SunrisesIllNeverSee/sigrank-mcp](https://glama.ai/mcp/servers/SunrisesIllNeverSee/sigrank-mcp)
|
|
23
|
+
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](./docs/CLI-MCP-REFERENCE.md#platform-adapters).
|
|
129
24
|
|
|
130
|
-
|
|
25
|
+
## Get started
|
|
131
26
|
|
|
132
|
-
|
|
27
|
+
Requires **Node.js 20 or later**. No global install is required.
|
|
133
28
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
### Smithery CLI
|
|
29
|
+
### Explore locally
|
|
137
30
|
|
|
138
31
|
```bash
|
|
139
|
-
#
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
# Connect to SigRank SignalAF (downloads the MCPB bundle locally)
|
|
143
|
-
smithery mcp add burnmydays/sigrank --id sigrank
|
|
144
|
-
|
|
145
|
-
# List available tools
|
|
146
|
-
smithery tool list sigrank
|
|
147
|
-
|
|
148
|
-
# Call a tool
|
|
149
|
-
smithery tool call sigrank get_leaderboard '{}'
|
|
150
|
-
smithery tool call sigrank rank_paste '{"text": "1000000 500000 50000 800000"}'
|
|
32
|
+
npx sigrank # interactive dashboard in a terminal
|
|
33
|
+
npx sigrank board --once # public leaderboard, one-shot
|
|
34
|
+
npx sigrank board --window 7d --once
|
|
151
35
|
```
|
|
152
36
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
1. Go to [smithery.ai/servers/burnmydays/sigrank](https://smithery.ai/servers/burnmydays/sigrank)
|
|
156
|
-
2. Click **Install**
|
|
157
|
-
3. Smithery handles the rest — no manual config editing
|
|
37
|
+
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.
|
|
158
38
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
## Commands
|
|
162
|
-
|
|
163
|
-
```
|
|
164
|
-
⊙ SigRank SignalAF CLI v1.0.37
|
|
165
|
-
|
|
166
|
-
Default (no args)
|
|
167
|
-
sigrank unified dashboard: cascade + token pillars + board
|
|
168
|
-
|
|
169
|
-
Commands
|
|
170
|
-
enroll sign in: paste a connect code (get one at signalaf.com → Settings)
|
|
171
|
-
submit publish your verified runs to the board (sign in first)
|
|
172
|
-
board live leaderboard (refreshes every 30s)
|
|
173
|
-
board --window 7d board for a specific window (7d, 30d, 90d, all)
|
|
174
|
-
board --once print once and exit
|
|
175
|
-
compare raw pillar audit: tokenpull vs ccusage vs token-dash vs tokscale
|
|
176
|
-
compare --platform codex compare for a specific platform
|
|
177
|
-
tui full tabbed TUI: Dashboard / Trends / Compare / Board / Watch / Connect
|
|
178
|
-
tui --platform codex TUI with a different default platform
|
|
179
|
-
watch live tune meter — ALL active platforms × all windows, every 30s
|
|
180
|
-
watch --platform codex watch only one platform (optional filter)
|
|
181
|
-
watch --window 7d watch only one window (optional filter)
|
|
182
|
-
proxy opt-in local Anthropic/OpenAI usage proxy
|
|
183
|
-
proxy --port 9000 run the proxy on a custom loopback port
|
|
184
|
-
|
|
185
|
-
Options
|
|
186
|
-
--window 7d · 30d · 90d · all (default: 30d for board; all windows for watch)
|
|
187
|
-
--platform claude · codex · amp · gemini · opencode · goose · …
|
|
188
|
-
--refresh poll interval in seconds (default: 30)
|
|
189
|
-
--once print once and exit (board only)
|
|
190
|
-
--port proxy port (default: 8787)
|
|
191
|
-
|
|
192
|
-
For AI clients (not typeable)
|
|
193
|
-
In a piped/non-TTY context, sigrank is an MCP stdio server.
|
|
194
|
-
AI clients (Claude, Cursor, …) call its tools automatically — these are
|
|
195
|
-
NOT shell commands. Humans use the commands above.
|
|
196
|
-
|
|
197
|
-
Examples
|
|
198
|
-
sigrank # unified dashboard
|
|
199
|
-
sigrank board # live leaderboard
|
|
200
|
-
sigrank compare # pillar audit (claude)
|
|
201
|
-
sigrank compare --platform codex
|
|
202
|
-
sigrank watch --window 7d --refresh 60
|
|
203
|
-
sigrank board --window all --once
|
|
204
|
-
```
|
|
39
|
+
### Publish your own snapshot
|
|
205
40
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
persist it in their local session files. SigRank SignalAF can capture those
|
|
210
|
-
provider-reported counts through a manually started loopback proxy:
|
|
41
|
+
1. Sign in at [signalaf.com](https://signalaf.com) and create a connect code in Settings.
|
|
42
|
+
2. Enroll this device, then inspect the dry-run payload.
|
|
43
|
+
3. Submit when you are ready to publish.
|
|
211
44
|
|
|
212
45
|
```bash
|
|
213
|
-
sigrank
|
|
214
|
-
sigrank
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
Then point a compatible tool's API base URL at the displayed local URL. The
|
|
218
|
-
first release supports Anthropic Messages (`/v1/messages`), OpenAI Chat
|
|
219
|
-
Completions (`/v1/chat/completions`), and OpenAI Responses (`/v1/responses`).
|
|
220
|
-
The tool must support a custom API base URL; this is not guaranteed for every
|
|
221
|
-
desktop client.
|
|
222
|
-
|
|
223
|
-
The proxy is **off by default**: it opens no port and observes no traffic unless
|
|
224
|
-
you explicitly run `sigrank proxy`. It binds only to loopback and stops when the
|
|
225
|
-
command exits. Request and response content, API keys, and tool calls are
|
|
226
|
-
forwarded transiently but never written to disk. Only usage metadata is appended
|
|
227
|
-
to `~/.sigrank-mcp/proxy-sessions.jsonl` (directory `0700`, file `0600`).
|
|
228
|
-
|
|
229
|
-
Anthropic and OpenAI calls are currently grouped under one `proxy` platform row.
|
|
230
|
-
For streamed Chat Completions, SigRank SignalAF sets OpenAI's
|
|
231
|
-
`stream_options.include_usage=true` so the provider includes the final usage
|
|
232
|
-
chunk; response chunks are still forwarded immediately.
|
|
233
|
-
|
|
234
|
-
### The TUI is the whole app
|
|
235
|
-
|
|
236
|
-
Launch it and sign in inside it:
|
|
237
|
-
|
|
238
|
-
```
|
|
239
|
-
npx sigrank
|
|
46
|
+
npx sigrank enroll
|
|
47
|
+
npx sigrank submit --dry-run
|
|
48
|
+
npx sigrank submit
|
|
240
49
|
```
|
|
241
50
|
|
|
242
|
-
|
|
51
|
+
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.
|
|
243
52
|
|
|
244
|
-
|
|
245
|
-
| ------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
|
246
|
-
| **Dashboard** | `1` | Cascade table (all platforms × windows + combined) · Υ sparklines · token composition bars · mini board |
|
|
247
|
-
| **Trends** | `2` | Every metric across windows — sub-views: You / Platform / Field |
|
|
248
|
-
| **Compare** | `3` | 4-source pillar audit (tokenpull vs ccusage vs token-dash vs tokscale) · delta % · cascade metrics per source · cache read bar chart |
|
|
249
|
-
| **Board** | `4` | Full leaderboard with all fields · `[W]` cycles window (7d/30d/90d/all) |
|
|
250
|
-
| **Watch** | `5` | In-TUI landing panel · `[Enter]` launches the live watcher (big numbers + pillar bars + Υ trend, auto-refreshes 30s) |
|
|
251
|
-
| **Connect** | `6` | Sign in / switch device — paste a connect code from signalaf.com → Settings. Then `[S]` submits. |
|
|
252
|
-
|
|
253
|
-
### Sign in + submit
|
|
53
|
+
For repeated use, an optional global installation provides the same commands:
|
|
254
54
|
|
|
255
55
|
```bash
|
|
256
|
-
|
|
257
|
-
sigrank
|
|
258
|
-
sigrank submit --dry-run # inspect the exact signed payload without sending anything
|
|
56
|
+
npm install -g sigrank
|
|
57
|
+
sigrank
|
|
259
58
|
```
|
|
260
59
|
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
---
|
|
264
|
-
|
|
265
|
-
## MCP Server mode
|
|
60
|
+
## Connect an MCP client
|
|
266
61
|
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
Add to `.mcp.json` or equivalent:
|
|
62
|
+
Add this server to your client's MCP configuration:
|
|
270
63
|
|
|
271
64
|
```json
|
|
272
65
|
{
|
|
@@ -279,211 +72,84 @@ Add to `.mcp.json` or equivalent:
|
|
|
279
72
|
}
|
|
280
73
|
```
|
|
281
74
|
|
|
282
|
-
|
|
75
|
+
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.
|
|
283
76
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
}
|
|
292
|
-
```
|
|
77
|
+
| Task | Tools |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| Inspect local usage | `tokenpull`, `rank_windows`, `tokenpull_compare` |
|
|
80
|
+
| Calculate from supplied counts | `rank_paste`, `get_sigrank_standard_record` |
|
|
81
|
+
| Read public results | `get_leaderboard`, `get_operator`, `discover_peers` |
|
|
82
|
+
| Explore possible changes | `diagnose_cascade`, `simulate_change`, `suggest_improvements` |
|
|
83
|
+
| Enroll and submit | `enroll`, `submit_verified` |
|
|
293
84
|
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
| Tool | Args | What |
|
|
297
|
-
| ------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
298
|
-
| `rank_paste(text)` | `{input, output, cacheCreate, cacheRead}` JSON or 4 whitespace-delimited numbers | Scores token pillars → Υ Yield / SNR / Leverage / Velocity / 10xDEV / Class + prose narration card |
|
|
299
|
-
| `get_leaderboard()` | `{window?}` | Live board from signalaf.com — sorted by Υ Yield |
|
|
300
|
-
| `get_operator(codename)` | `{codename}` | One operator's live profile |
|
|
301
|
-
| `submit_paste(text, codename)` | `{text, codename?}` | Rank locally then POST to board. Omit codename for preview-only |
|
|
302
|
-
| `tokenpull(platform?)` | `{platform?}` | On-device local reader: scans local logs → 4-window cascade. Zero paste, token-only |
|
|
303
|
-
| `tokenpull_submit(codename, window?)` | `{codename?, window?}` | `tokenpull` → publish to board. Omit codename for preview |
|
|
304
|
-
| `tokenpull_compare(platform?)` | `{platform?}` | All four sources side-by-side: tokenpull + ccusage + token-dash + tokscale. Returns pillars, cascade metrics, and delta % vs tokenpull per window |
|
|
305
|
-
| `rank_windows` | `{platform?, window?}` | Multi-window cascade from local logs |
|
|
306
|
-
| `get_sigrank_standard_record` | `{input, output, cache_write?, cache_read?}` | Builds the portable `sigrank/0.1-draft` compatibility record (legacy alias under TTEOP authority) — canonical cascade, computed locally |
|
|
307
|
-
| `discover_peers` | `{codename?}` | Find mentors, peers, and complementary operators on the leaderboard |
|
|
308
|
-
| `watch_tokenpull` | `{platform?, interval_s?}` | One cascade snapshot per call (interval_s advisory) |
|
|
309
|
-
| `submit_verified` | `{window?, platform?, dry_run?}` | THE ranked path: builds + ed25519-signs Schema 1.0 snapshots and POSTs them. `platform:'multi'` sums all active platforms. `dry_run:true` returns the exact payload unsent |
|
|
310
|
-
| `enroll` | `{code, device_label?}` | Bind this device with a connect code from signalaf.com → Settings |
|
|
311
|
-
| `diagnose_cascade` | `{text?}` | Diagnoses where your token cascade is leaking efficiency — ranked findings with severity + estimated Υ impact |
|
|
312
|
-
| `simulate_change` | `{text?, changes}` | Prescriptive "what if" — test proposed pillar changes and see the exact Υ delta + class change before committing |
|
|
313
|
-
| `suggest_improvements` | `{text?}` | Generates ranked, simulated improvement suggestions — tests strategies and returns them sorted by Υ yield impact |
|
|
314
|
-
| `self_improve` | `{text?}` | One-click optimize: diagnoses, suggests, and simulates the best change in a single call |
|
|
315
|
-
| `tokscale_breakdown(threshold?)` | `{threshold?}` | Per-model token breakdown across platforms (models under threshold → "other") |
|
|
316
|
-
| `tokscale_market_share()` | `{}` | AI tool market share: each tool's % of tokens/cost/messages, ranked. From local tokscale data |
|
|
317
|
-
| `tokscale_developer_profile()` | `{}` | Per-developer usage profile across all detected tools: model mix, pillars, sessions, workspace count (no names). Paths redacted |
|
|
318
|
-
| `tokscale_model_trends()` | `{}` | Model adoption over time: per-model first/last seen, active days, month-by-month adoption curve |
|
|
319
|
-
| `tokscale_cost_analysis()` | `{}` | Cost per developer per model: cost_per_million_tokens, cost_per_message, share_cost, client rollup |
|
|
320
|
-
| `tokscale_device_profile()` | `{}` | Device fingerprinting: installed tools, session counts, active days, day-of-week distribution, concurrency. Paths redacted |
|
|
321
|
-
| `tokscale_mcp_usage()` | `{}` | MCP server usage: detected servers, detection window, active days |
|
|
322
|
-
| `tokscale_competitive_intel(target)` | `{target}` | Competitive intelligence for any AI tool: rank, model mix, cost efficiency, share vs all competitors |
|
|
323
|
-
|
|
324
|
-
Intent tools (`get_best_operator`, `compare_self`, `compare_operators`, `describe_power_user`, `optimize_efficiency`) moved to [bestuser-router-mcp](https://github.com/SunrisesIllNeverSee/bestuser-router-mcp) — `npx bestuser-router-mcp`.
|
|
325
|
-
|
|
326
|
-
---
|
|
327
|
-
|
|
328
|
-
## Cascade math
|
|
85
|
+
For the full list, arguments, and adapter paths, see the [CLI and MCP reference](./docs/CLI-MCP-REFERENCE.md). Publishing through `submit_verified` requires `confirm: true`; `dry_run: true` inspects the payload without publishing.
|
|
329
86
|
|
|
330
|
-
|
|
331
|
-
Υ Yield = (cache_read × output) / input² (TTEOP canonical)
|
|
332
|
-
SNR = output / (input + output) (display alias for output_fraction)
|
|
333
|
-
Leverage = cache_read / input (TTEOP canonical)
|
|
334
|
-
Velocity = output / input (TTEOP canonical)
|
|
335
|
-
10xDEV = log₁₀(leverage) (display alias for log_leverage)
|
|
336
|
-
```
|
|
87
|
+
## Command guide
|
|
337
88
|
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
89
|
+
| Command | Purpose |
|
|
90
|
+
| --- | --- |
|
|
91
|
+
| `sigrank` | Open the terminal dashboard |
|
|
92
|
+
| `sigrank board --once` | Print the public leaderboard |
|
|
93
|
+
| `sigrank compare --platform codex` | Audit token counts across available local sources |
|
|
94
|
+
| `sigrank watch --window 7d` | Watch local usage updates |
|
|
95
|
+
| `sigrank enroll` | Bind a device using a connect code |
|
|
96
|
+
| `sigrank submit --dry-run` | Inspect a signed submission without sending it |
|
|
97
|
+
| `sigrank submit` | Publish a verified submission |
|
|
98
|
+
| `sigrank proxy` | Start the optional loopback usage proxy |
|
|
99
|
+
| `sigrank --help` | Show the current command reference |
|
|
344
100
|
|
|
345
|
-
|
|
101
|
+
### Optional usage proxy
|
|
346
102
|
|
|
347
|
-
|
|
103
|
+
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.
|
|
348
104
|
|
|
349
|
-
The
|
|
105
|
+
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](./docs/CLI-MCP-REFERENCE.md#privacy) before using it.
|
|
350
106
|
|
|
351
|
-
|
|
352
|
-
| ----------------- | ------------------------------------------------------------------------------ | --------------------- |
|
|
353
|
-
| `tokenpull` | On-device JSONL scanner (canon source) | claude, codex, amp, … |
|
|
354
|
-
| `ccusage` | `ccusage <platform> daily --json` CLI (bundled) | claude, codex |
|
|
355
|
-
| `token-dashboard` | `~/.claude/token-dashboard.db` SQLite ([Nate's](https://github.com/nateherkai/token-dashboard)) | claude only |
|
|
356
|
-
| `tokscale` | `tokscale models --json` CLI (bundled, falls back to `~/tokscale_report.json`) | claude, codex |
|
|
107
|
+
## How measurement works
|
|
357
108
|
|
|
358
|
-
|
|
109
|
+
Four token pillars feed the calculation:
|
|
359
110
|
|
|
360
|
-
```
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
111
|
+
```text
|
|
112
|
+
Yield (Υ) = (cache_read × output) / input²
|
|
113
|
+
Leverage = cache_read / input
|
|
114
|
+
Velocity = output / input
|
|
115
|
+
SNR = output / (input + output)
|
|
116
|
+
10xDEV = log₁₀(Leverage)
|
|
364
117
|
```
|
|
365
118
|
|
|
366
|
-
|
|
367
|
-
- **Alpha** = 2.0 default (when no Claude data)
|
|
368
|
-
- Owner-stated average: 7:1:2 (cache:input:output) → input/output ≈ 0.5
|
|
369
|
-
|
|
370
|
-
Verifier numbers (ccusage/tokscale for codex) show **raw uncached input** (`input_tokens − cached`) — a different field than the estimated input above. The discrepancy is expected and explained inline in the dashboard.
|
|
371
|
-
|
|
372
|
-
---
|
|
373
|
-
|
|
374
|
-
## Platform adapters
|
|
375
|
-
|
|
376
|
-
All adapters are token-only (no message content, no cost fields, no credentials). The table below is regenerated from the adapter file headers in `adapters/index.mjs` + `adapters/tokenpull.mjs` so the path, pillar shape, and notes match the actual code (a prior revision had drifted on Qwen/Codex/Copilot).
|
|
377
|
-
|
|
378
|
-
| Platform | Path | Pillar shape & notes |
|
|
379
|
-
| ------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
380
|
-
| Claude Code | ✅ `~/.claude/projects` (recursive, incl. `subagents/`) | Native 4-pillar; dedup by `(session_id, message_id)` — final snapshot wins |
|
|
381
|
-
| Codex | ✅ `~/.codex/sessions` (+ `archived_sessions`) | `input_tokens` incl. cached → `input` + `cacheCreate` split window-level via `io_ratio`; `cacheRead` native (`cached_input_tokens`); `reasoning_output`→output; verified vs ccusage (~1%) |
|
|
382
|
-
| Devin CLI | ✅ `~/.local/share/devin/cli/sessions.db` | SQLite; native 4-pillar from `metadata.metrics` (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens`); `input_tokens` is fresh (excludes cache) |
|
|
383
|
-
| Amp | ✅ `~/.local/share/amp/threads` | Native 4-pillar; per-message |
|
|
384
|
-
| Kimi | ✅ `~/.kimi/sessions` | Native 4-pillar; `StatusUpdate` lines only |
|
|
385
|
-
| pi-agent | ✅ `~/.pi/agent/sessions` | Native 4-pillar; per-message JSONL |
|
|
386
|
-
| oh-my-pi (`omp`) | ✅ `~/.omp/agent/sessions` (recursive, incl. nested subagent transcripts) | Native 4-pillar from `.message.usage` on `type:"message"` entries (`cacheWrite`→`cacheCreate`); **`reasoningTokens` is already inside `output`** — never added, or it double-counts; `usage.cost` reuses the same four key names for USD floats and is dropped; dedup by (session header `id`, entry `id`). Separate harness from pi-agent |
|
|
387
|
-
| OpenClaw | ✅ `~/.openclaw` | Native 4-pillar; per-message JSONL |
|
|
388
|
-
| Droid | ✅ `~/.factory/sessions/*.settings.json` | Native 4-pillar; `thinking_tokens`→output |
|
|
389
|
-
| Codebuff | ✅ `~/.config/manicode` | Native 4-pillar; `chat-messages.json` |
|
|
390
|
-
| Hermes | ✅ `~/.hermes/state.db` | Native 4-pillar; SQLite; `reasoning_tokens`→output |
|
|
391
|
-
| Kilo | ✅ `~/.local/share/kilo/kilo.db` | Native 4-pillar; SQLite |
|
|
392
|
-
| Qwen | ✅ `~/.qwen/projects` | Estimated (`cacheCreate=0` — no field in logs); `cacheRead` from `cachedContentTokenCount`; `thoughtsTokenCount`→output |
|
|
393
|
-
| Goose | ✅ `~/.local/share/goose/sessions/sessions.db` (or `$GOOSE_PATH_ROOT/data/sessions/sessions.db`) | Estimated (`cacheCreate=cacheRead=0` — no cache fields); reasoning = `total−input−output`→output; cumulative-column dedup by session id |
|
|
394
|
-
| Gemini CLI | ✅ `~/.gemini/tmp` | Estimated (`cacheCreate=0`); `cacheRead` from `cached` field; `thought`→output; `input` = `input−cached` (fresh) |
|
|
395
|
-
| GitHub Copilot CLI | ✅ `~/.copilot/otel` | Native 4-pillar (OTel spans: `llm.token_count.{prompt,completion,cache_creation,cache_read}`); requires `COPILOT_OTEL_ENABLED=true` + `COPILOT_OTEL_EXPORTER_TYPE=file` set **before** session start |
|
|
396
|
-
| OpenCode | ⚠️ `~/.local/share/opencode` | Data gap — logs store `cost:0` and derive tokens via LiteLLM at runtime; raw token counts not persisted. No pillars readable with current format |
|
|
397
|
-
| SigRank SignalAF proxy | ✅ `~/.sigrank-mcp/proxy-sessions.jsonl` | Opt-in native 4-pillar usage reported by Anthropic/OpenAI; same-timestamp records keep the last call; OpenAI cached input is separated from fresh input |
|
|
398
|
-
| Other (user JSON) | ✅ `$SIGRANK_OTHER_PATH` | User-supplied JSON `{ "windows": { "all": {input,output,cacheCreate,cacheRead} } }`; all-time only (no timestamps) |
|
|
399
|
-
| Cursor | 🔜 | Chat log path TBD |
|
|
400
|
-
| Windsurf | 🔜 | Session logs at `~/.codeium/windsurf/` |
|
|
401
|
-
|
|
402
|
-
`estimated=true` means one or more pillars are derived, not native. The server re-scores all submitted pillars authoritatively; local preview Υ is indicative only.
|
|
403
|
-
|
|
404
|
-
---
|
|
119
|
+
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.
|
|
405
120
|
|
|
406
|
-
|
|
121
|
+
The implementation delegates canonical calculations through `token-cascade` to `tteop-spec`. See the [TTEOP implementation profile](./TTEOP-IMPLEMENTATION-PROFILE.md) and [protocol compatibility notes](./docs/PROTOCOL-COMPATIBILITY.md).
|
|
407
122
|
|
|
408
|
-
|
|
409
|
-
- **MCP safety rails.** The `enroll` tool refuses to re-bind a device that is already enrolled (re-enroll from the CLI), and `submit_verified` requires `confirm: true` to publish (not needed with `dry_run`). `tokscale_developer_profile` returns workspace counts only, never workspace or project names.
|
|
410
|
-
- **Token-only persistence and submission.** Local-log adapters read usage metadata only. The optional proxy necessarily handles provider-bound request and response bytes in memory, but never persists their content; it writes only token counts, model/backend metadata, and timestamps. Only token telemetry is submitted to SigRank SignalAF.
|
|
411
|
-
- **Local by default.** `tokenpull` reads only the selected or detected adapter paths on your device (e.g. `~/.claude/projects` for Claude, `~/.codex` for Codex, plus additional paths for Amp, Devin, Gemini, Goose, and other supported platforms). Numbers stay on your machine unless you explicitly submit with a codename.
|
|
412
|
-
- **Background tooling excluded.** Memory plugins, observers, summarizers (e.g. `claude-mem`, `mem0`, `observer-sessions`) are filtered from both Claude and Codex reads. `subagents/` are kept — they represent real operator work.
|
|
413
|
-
- **Board reads are anonymous.** No account needed to browse, compare, or watch.
|
|
414
|
-
- **Ranked submissions are signed, not trusted.** `sigrank submit` requires a one-time `enroll` (device-bound ed25519 key — the private key never leaves your machine). Verify what's sent with `sigrank submit --dry-run`: the payload is four token counts, ratios, and a signature.
|
|
415
|
-
|
|
416
|
-
---
|
|
123
|
+
## Privacy
|
|
417
124
|
|
|
418
|
-
|
|
125
|
+
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.
|
|
419
126
|
|
|
420
|
-
|
|
421
|
-
| ----------------------- | ---------------------- | ---------------------------- |
|
|
422
|
-
| `SIGRANK_API_BASE` | `https://signalaf.com` | Override the board host (https required; http only for loopback) |
|
|
423
|
-
| `SIGRANK_DEVICE_LABEL` | `sigrank <version> · <platform>` | Optional device label sent at enroll |
|
|
424
|
-
| `SIGRANK_FETCH_TIMEOUT` | `10000` | Board API fetch timeout (ms) |
|
|
127
|
+
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.
|
|
425
128
|
|
|
426
|
-
|
|
129
|
+
Read the [full payload and privacy details](./docs/CLI-MCP-REFERENCE.md#privacy), and use `submit --dry-run` to inspect what would be sent.
|
|
427
130
|
|
|
428
|
-
##
|
|
131
|
+
## Development
|
|
429
132
|
|
|
430
133
|
```bash
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
134
|
+
git clone https://github.com/SunrisesIllNeverSee/sigrank-mcp.git
|
|
135
|
+
cd sigrank-mcp
|
|
136
|
+
npm install
|
|
137
|
+
npm test
|
|
138
|
+
npm run test:packaged
|
|
434
139
|
```
|
|
435
140
|
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
-
|
|
441
|
-
-
|
|
442
|
-
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
-
|
|
447
|
-
- `enroll` posts identity (public key only), maps 201 enrolled + 410 code_invalid
|
|
448
|
-
- `submit_verified` signs Schema 1.0, server-verifiable
|
|
449
|
-
- `simulate_change` relative + absolute deltas, quadratic penalty, JSON input
|
|
450
|
-
- Hardening: div-by-zero guards, parsePillars warnings, fetch timeout, EXCLUDE_TOOLING regex, narrate safety
|
|
451
|
-
- `sign.test.mjs` ed25519 round-trip + canonical 926-byte payload parity
|
|
452
|
-
|
|
453
|
-
---
|
|
454
|
-
|
|
455
|
-
## File map
|
|
456
|
-
|
|
457
|
-
| File | Responsibility |
|
|
458
|
-
| --------------- | ----------------------------------------------------------------------- |
|
|
459
|
-
| `index.mjs` | Entry point — TTY detection, routes to CLI or MCP server |
|
|
460
|
-
| `proxy.mjs` | Opt-in loopback Anthropic/OpenAI proxy and usage capture |
|
|
461
|
-
| `cli.mjs` | CLI commands: board, compare, watch, enroll, submit, help |
|
|
462
|
-
| `tui.mjs` | Full tabbed TUI: Dashboard / Trends / Compare / Board / Watch / Connect |
|
|
463
|
-
| `cascade.mjs` | Cascade facade — delegates to `@sigrank/cascade` → `tteop-spec` (Υ, SNR, leverage, velocity, 10xDEV, class) |
|
|
464
|
-
| `tokenpull.mjs` | On-device log scanner — Claude, Codex, multi-platform |
|
|
465
|
-
| `adapters.mjs` | Platform adapter registry (16+ platforms) |
|
|
466
|
-
| `tools.mjs` | MCP tool table + dispatcher |
|
|
467
|
-
| `connect.mjs` | Connect-code enrollment + device identity |
|
|
468
|
-
| `keystore.mjs` | Local key management (paste-keys, not API keys) |
|
|
469
|
-
| `submit.mjs` | Verified submit flow (signs + POSTs to board) |
|
|
470
|
-
| `sign.mjs` | Schema 1.0 signing (X-Agent-Signature) |
|
|
471
|
-
| `narrate.mjs` | Deterministic prose narration card |
|
|
472
|
-
| `preflight.mjs` | Plausibility checks (Benford, bounds, anomaly detection) |
|
|
473
|
-
| `test.mjs` | Unit tests (no external deps) |
|
|
474
|
-
| `sign.test.mjs` | ed25519 signing + canon parity test |
|
|
475
|
-
|
|
476
|
-
---
|
|
477
|
-
|
|
478
|
-
## Contributing
|
|
479
|
-
|
|
480
|
-
Contributions welcome. SigRank SignalAF MCP is built in the open.
|
|
481
|
-
|
|
482
|
-
- [Contributing guide](./.github/CONTRIBUTING.md)
|
|
483
|
-
- [Security policy](https://github.com/SunrisesIllNeverSee/sigrank-mcp/security/policy)
|
|
484
|
-
- Report bugs via [GitHub Issues](https://github.com/SunrisesIllNeverSee/sigrank-mcp/issues)
|
|
485
|
-
- PRs: fork → branch → `node test.mjs` passes → open PR against `main`
|
|
141
|
+
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.
|
|
142
|
+
|
|
143
|
+
## Related projects
|
|
144
|
+
|
|
145
|
+
- [sigrank-app](https://github.com/SunrisesIllNeverSee/sigrank-app) — SignalAF website, profiles, public API, and leaderboard.
|
|
146
|
+
- [token-cascade](https://www.npmjs.com/package/token-cascade) — measurement implementation consumed by this package.
|
|
147
|
+
- [TTEOP](https://github.com/SunrisesIllNeverSee/otep-spec) — protocol specification and semantics.
|
|
148
|
+
|
|
149
|
+
## Contributing and security
|
|
150
|
+
|
|
151
|
+
See the [contributing guide](./.github/CONTRIBUTING.md). Open bugs in [GitHub Issues](https://github.com/SunrisesIllNeverSee/sigrank-mcp/issues); report vulnerabilities privately through the [security policy](https://github.com/SunrisesIllNeverSee/sigrank-mcp/security/policy).
|
|
486
152
|
|
|
487
153
|
## License
|
|
488
154
|
|
|
489
|
-
MIT
|
|
155
|
+
[MIT](./LICENSE).
|
package/manifest.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json",
|
|
3
3
|
"manifest_version": "0.4",
|
|
4
4
|
"name": "sigrank",
|
|
5
|
-
"version": "1.0.
|
|
5
|
+
"version": "1.0.48",
|
|
6
6
|
"description": "Ranks AI coding operators by token cascade efficiency (Yield = cache_read \u00d7 output / input\u00b2). 25 tools including SigRank Standard record, yield calculation, local token usage pulls, signed submission, and tokscale-powered analytics (market share, developer profiles, model trends, cost analysis, device profiles, MCP usage, competitive intelligence). Privacy-first: runs locally, only four token counts leave the machine.",
|
|
7
7
|
"author": {
|
|
8
8
|
"name": "SunrisesIllNeverSee",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sigrank",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.48",
|
|
4
4
|
"author": "SunrisesIllNeverSee (https://github.com/SunrisesIllNeverSee)",
|
|
5
5
|
"description": "Upsilon measurement engine distributed through the sigrank CLI/MCP compatibility package, with SigRank public leaderboard tools.",
|
|
6
6
|
"mcpName": "io.github.SunrisesIllNeverSee/sigrank-mcp",
|