@mauricode/token-derby 3.1.0 → 3.1.3
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/README.md +34 -0
- package/dist/bin.js +381 -66
- package/dist/bin.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -97,10 +97,44 @@ at usage you didn't produce.
|
|
|
97
97
|
|
|
98
98
|
- `~/.token-derby/stable.json` — saved horses
|
|
99
99
|
- `~/.token-derby/active-races/<join-code>.json` — per-race state for rejoin
|
|
100
|
+
- `~/.token-derby/logs/token-derby.log` — debug log (see below)
|
|
101
|
+
|
|
102
|
+
## Debug log
|
|
103
|
+
|
|
104
|
+
Every command appends to a rolling log, so a race that stalls overnight can be
|
|
105
|
+
diagnosed afterwards. The race UI takes over the terminal, which is exactly when
|
|
106
|
+
nothing can be printed to the screen.
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
token-derby logs # print the path of the log file
|
|
110
|
+
token-derby logs --tail 100 # print the last 100 lines (default 50)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The log rolls at 2MB and keeps five files (`token-derby.log` plus `.1`–`.4`), so
|
|
114
|
+
it never exceeds ~10MB. Each environment has its own, next to that environment's
|
|
115
|
+
identity.
|
|
116
|
+
|
|
117
|
+
What the lines mean when a race misbehaves:
|
|
118
|
+
|
|
119
|
+
- `beat.prepare.start` with no `beat.prepare.done` after it — the token scan
|
|
120
|
+
hung, and the poller is still waiting on it.
|
|
121
|
+
- repeated `beat.send.err` with a climbing `next_ms` — the heartbeat is
|
|
122
|
+
reaching the network and failing; `retry` counts the attempts.
|
|
123
|
+
- `scan.timeout` — the scan blew its budget; `reason` names the source that was
|
|
124
|
+
still running.
|
|
125
|
+
|
|
126
|
+
Credentials are never written: identity and horse tokens, request headers and
|
|
127
|
+
bodies are all omitted, and claim tokens and admin codes are masked out of the
|
|
128
|
+
URLs they travel in.
|
|
100
129
|
|
|
101
130
|
## Environment
|
|
102
131
|
|
|
103
132
|
- `TOKEN_DERBY_API_BASE` — override the API base URL (default: `https://token-derby.mauricode.co.uk/api`)
|
|
104
133
|
- `TOKEN_DERBY_HOME` — override the data directory (default: `~/.token-derby`)
|
|
105
134
|
- `TOKEN_DERBY_CLAUDE_DIR` — override the transcripts directory (default: `~/.claude/projects`)
|
|
135
|
+
- `CLAUDE_CONFIG_DIR` — Claude Code's own config override. When set, transcripts are read from `$CLAUDE_CONFIG_DIR/projects`. `TOKEN_DERBY_CLAUDE_DIR` still wins.
|
|
136
|
+
|
|
137
|
+
Token Derby counts usage from this machine's filesystem only. If Claude Code runs
|
|
138
|
+
in a container, over SSH, or on another machine, join the race from there — `join`
|
|
139
|
+
warns before entering a race whose primary model has no transcripts to read.
|
|
106
140
|
- **Top-5 conversations (primary):** a race can be created so that only each racer's **5 most-active conversations per heartbeat** count toward their **primary** model's score (secondaries unaffected). The race creator opts in at `token-derby create` (prompt) or, for organisation-scheduled races, via the "Primary top-5 cap" option on the schedule tab of `token-derby web`. Off by default (every conversation counts).
|