Skip to content

Commit 5ffd21b

Browse files
committed
docs(readme): update in-session examples to match the real hook output
The showcase and Quickstart blocks used a stale "⚡ handled by token-ninja" banner, made-up rule ids (git-branch-current, git-log-recent, port-usage, npm-test), and rough token estimates. They also showed conversational NL prompts being intercepted, which the UserPromptSubmit hook rejects under --strict mode. Refresh both blocks with real literal commands users actually type into Claude Code, the hook's actual suppression banner ("⚡ token-ninja handled locally (<rule_id>) · saved ~N tokens"), and token-saved numbers captured from `ninja route --strict` on this repo.
1 parent f77f852 commit 5ffd21b

1 file changed

Lines changed: 55 additions & 34 deletions

File tree

README.md

Lines changed: 55 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -27,23 +27,34 @@ unchanged, uninterrupted.
2727
---
2828

2929
```console
30-
# Inside your Claude Code (or Cursor / Claude Desktop) session — just chat as usual.
31-
# token-ninja watches every shell call the agent tries to make and handles the
32-
# deterministic ones locally, without ever hitting the model.
33-
34-
you › what branch am I on?
35-
ai › (asks token-ninja) git branch --show-current
36-
⚡ ninja handled locally (git-branch-current) · saved ~420 tokens
37-
main
38-
39-
you › how's the test suite doing?
40-
ai › (asks token-ninja) npm test
41-
⚡ ninja handled locally (npm-test) · saved ~480 tokens
42-
Tests 234 passed (234)
43-
44-
you › explain this stack trace: …
45-
ai › (token-ninja: no match — passing through to the model)
46-
…regular model reply…
30+
# Inside your Claude Code session — just chat as usual. When you type a literal
31+
# command, the UserPromptSubmit hook routes it through token-ninja first. If a
32+
# high-confidence rule matches, the command runs locally and its output is
33+
# returned to you — the model is never invoked. Zero input tokens, zero output
34+
# tokens. Anything conversational flows through to Claude untouched.
35+
36+
you › git status
37+
⚡ token-ninja handled locally (git-status) · saved ~424 tokens
38+
39+
On branch main
40+
nothing to commit, working tree clean
41+
42+
you › git branch --show-current
43+
⚡ token-ninja handled locally (git-branch-list) · saved ~416 tokens
44+
45+
main
46+
47+
you › git log --oneline -10
48+
⚡ token-ninja handled locally (git-log-passthrough) · saved ~611 tokens
49+
50+
f77f852 chore(main): release 0.3.0
51+
6932f36 feat(setup): auto-register ninja mcp with Gemini CLI
52+
1b323b2 fix(router): preserve ANSI colors when the hook short-circuits the model
53+
89394ec feat(hook): replace PreToolUse Bash hook with UserPromptSubmit
54+
55+
56+
you › explain why this stack trace is blowing up in production
57+
# No match (conversational) — prompt flows to Claude unchanged.
4758
```
4859

4960
No prefix. No new commands to learn. Keep chatting with `claude`, `codex`,
@@ -134,23 +145,33 @@ skipped safely instead of failing the install.
134145
open your AI tool the way you always do and start chatting:
135146

136147
```console
137-
you › are there any uncommitted changes?
138-
ai ⚡ handled by token-ninja (git-status) · saved ~512 tokens
139-
On branch main
140-
nothing to commit, working tree clean
141-
142-
you › list the recent commits on this branch
143-
ai ⚡ handled by token-ninja (git-log-recent) · saved ~500 tokens
144-
9e1c3b4 feat(setup): auto-register ninja mcp
145-
48f6643 feat(rules): expand coverage with 10 new domains
146-
147-
148-
you › what's using port 3000?
149-
ai ⚡ handled by token-ninja (port-usage) · saved ~438 tokens
150-
node 4812 alice 21u IPv6 *:3000 (LISTEN)
151-
152-
you › why is my React state not updating when I click the button?
153-
ai # No match — token-ninja passes through. The model answers normally.
148+
you › git status
149+
⚡ token-ninja handled locally (git-status) · saved ~424 tokens
150+
151+
On branch main
152+
nothing to commit, working tree clean
153+
154+
you › npm test
155+
⚡ token-ninja handled locally (npm-run-known) · saved ~2,362 tokens
156+
157+
Test Files 20 passed (20)
158+
Tests 268 passed (268)
159+
Duration 4.16s
160+
161+
you › docker ps
162+
⚡ token-ninja handled locally (docker-ps) · saved ~452 tokens
163+
164+
CONTAINER ID IMAGE STATUS NAMES
165+
a7f3c9e21b4d postgres:16 Up 2 hours db
166+
51e2d7f0a8c6 redis:7 Up 2 hours cache
167+
168+
you › git diff
169+
⚡ token-ninja handled locally (git-diff) · saved ~402 tokens
170+
171+
(no changes)
172+
173+
you › why is my React state not updating when I click the button?
174+
# No match (conversational) — token-ninja passes through. The model answers normally.
154175
```
155176

156177
Check how many tokens you've saved at any time:

0 commit comments

Comments
 (0)