@scottymade/mana 1.0.1 → 1.0.2

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.
Files changed (2) hide show
  1. package/README.md +188 -8
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,103 @@
1
- # @scottymade/mana
1
+ <p align="center">
2
+ <img src="docs/mana-promo.png" alt="Mana - Double Your Claude Code Usage for 1/3 the Price" width="800">
3
+ </p>
2
4
 
3
- MANA - LLM Token Usage Optimizer for Claude Code
5
+ <p align="center">
6
+ <a href="https://github.com/scottymade/mana/releases">
7
+ <img src="https://img.shields.io/github/v/release/scottymade/mana" alt="Version">
8
+ </a>
9
+ <a href="https://www.npmjs.com/package/@scottymade/mana">
10
+ <img src="https://img.shields.io/npm/v/@scottymade/mana" alt="npm">
11
+ </a>
12
+ <a href="https://github.com/scottymade/mana/releases">
13
+ <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg" alt="Platforms">
14
+ </a>
15
+ <a href="https://devmana.ai">
16
+ <img src="https://img.shields.io/badge/Claude%20Code-MCP%20Server-purple.svg" alt="Claude Code MCP Server">
17
+ </a>
18
+ <a href="https://github.com/scottymade/mana/blob/main/LICENSE">
19
+ <img src="https://img.shields.io/github/license/scottymade/mana" alt="License">
20
+ </a>
21
+ </p>
4
22
 
5
- Optimizes token-heavy tool outputs, saving 50-80% on every operation. Double your Claude Code usage.
23
+ ---
24
+
25
+ MANA optimizes the token-heavy tool outputs that eat through your Claude limits. File reads, command outputs, search results - they all get intelligently routed and compressed before reaching Claude, saving 50-80% of tokens on every operation. Keeping your context lean and keeping you coding longer without hitting usage caps!
26
+
27
+ **Result: 2x the coding sessions with no change to your workflow.**
28
+
29
+ ---
30
+
31
+ ## Your Mana Bar Has a Hole In It
32
+
33
+ *Debuff effect: Token bleed on every tool call. Here's how it stacks:*
34
+
35
+ ### File Operations Are Mana Vampires
36
+
37
+ Claude Code reads an entire component file. 2,847 lines. Only 40 were relevant to your query. That's 2,800+ wasted tokens per file op. One trash mob just ate your spell slots.
38
+
39
+ ### Bash Commands Siphon Mana on Every Cast
40
+
41
+ You run `npm run test`. Claude gets back 5,000 tokens - suite names, timing breakdowns, coverage reports. You just needed to know: is the build alive? Mana bar blinked red for a pulse check.
42
+
43
+ ### Directory Searches Burn Through Reserves
44
+
45
+ Claude casts Locate Object to find a file. Miss. Recasts with new keywords. Miss. Third cast, broader search. Nothing batched. That's 3x the tokens for one file path.
46
+
47
+ ### It's a Wipe. Pull the Combat Log — Here's What Killed You.
48
+
49
+ | 50-80% | 6-12h | 2-3x |
50
+ |--------|-------|------|
51
+ | of tokens go to tool bloat - not your actual work | actual grinding (from 25h) | faster bleed in large codebases |
52
+
53
+ **You're not bad at token management. The trash mobs wiped your mana before you even reached the boss.**
54
+
55
+ ---
56
+
57
+ ## How It Works
58
+
59
+ **What If You Had a Mana Regen Buff Running 24/7?**
60
+
61
+ **_That's Mana._**
62
+
63
+ We route Claude tool calls through our custom MCP server. When Claude Code reads a 3,000-line file, Mana intercepts the bloated response, routes it through more optimized models to extract only what's relevant to your quest, then sends the filtered result back.
64
+
65
+ - Claude's full intelligence on architecture & code
66
+ - Trash mobs handled by leaner models
67
+ - Your existing workflow, unchanged
68
+ - Same firepower, at a fraction of the mana cost
69
+
70
+ Claude still handles your architecture decisions, writing clean & concise code, complex debugging, and code reviews—the actual boss fights. It just stops wasting magic on tool outputs that didn't need Claude-level intelligence in the first place.
71
+
72
+ ```mermaid
73
+ flowchart TB
74
+ USER[Your Prompt] --> CLAUDE[Claude]
75
+ CLAUDE --> |read_optimized| MANA[MANA MCP Server]
76
+ CLAUDE --> |bash_optimized| MANA
77
+ CLAUDE --> |search_optimized| MANA
78
+ MANA --> |Raw Content| API[MANA Optimization API]
79
+ API --> |Compressed| MANA
80
+ MANA --> |50-80% fewer tokens| CLAUDE
81
+ CLAUDE --> RESPONSE[Claude's Response]
82
+ ```
83
+
84
+ **Smart Routing** — Every tool action routes to a lightweight model benchmarked as the most accurate for that specific job.
85
+
86
+ **Lean Processing** — Optimized models handle the heavy lifting—reading files, parsing bash outputs, extracting precise answers.
87
+
88
+ **Compounding Savings** — Leaner responses mean leaner context. Savings stack with every turn. Longer sessions, fewer tokens burned.
89
+
90
+ ### Mana Pool: Doubled
91
+
92
+ | Plan | Before | With Mana |
93
+ |------|--------|-----------|
94
+ | Claude Pro | 25 hours | **50 hours** |
95
+ | Claude Max $100 | 125 hours | **250 hours** |
96
+ | Claude Max $200 | 500 hours | **1000 hours** |
97
+
98
+ **Same Claude intelligence. Double the hours. A fraction of the price!**
99
+
100
+ ---
6
101
 
7
102
  ## Quick Start
8
103
 
@@ -28,8 +123,20 @@ claude mcp add -s project mana -- mana --api-key=YOUR_API_KEY
28
123
  claude mcp add -s user mana -- mana --api-key=YOUR_API_KEY
29
124
  ```
30
125
 
126
+ > **Note:** Project-level configs override global. You can mix and match (e.g., global MCP server + per-project instructions).
127
+
31
128
  ### Step 3: Add Claude Instructions
32
129
 
130
+ #### Manual Install
131
+
132
+ Copy the contents of [CLAUDE_INSTRUCTIONS.md](https://github.com/scottymade/mana/blob/main/instructions/CLAUDE_INSTRUCTIONS.md) and **prepend** it to the beginning of your CLAUDE.md file:
133
+
134
+ **3a. Project only:** Prepend to `CLAUDE.md` in your project root
135
+
136
+ **3b. Global:** Prepend to `~/.claude/CLAUDE.md`
137
+
138
+ #### Automatic Install
139
+
33
140
  **3a. Project only** (run from your project root):
34
141
 
35
142
  ```bash
@@ -42,14 +149,87 @@ claude mcp add -s user mana -- mana --api-key=YOUR_API_KEY
42
149
  { curl -fsSL https://raw.githubusercontent.com/scottymade/mana/main/instructions/CLAUDE_INSTRUCTIONS.md; echo ""; echo "---"; echo ""; cat ~/.claude/CLAUDE.md 2>/dev/null; } > ~/.claude/CLAUDE.md.tmp && mv ~/.claude/CLAUDE.md.tmp ~/.claude/CLAUDE.md
43
150
  ```
44
151
 
45
- ### Step 4: Restart Claude Code
152
+ > **Note:** These commands prepend MANA instructions to existing files. Your existing CLAUDE.md content will be preserved below the MANA instructions.
153
+
154
+ ---
155
+
156
+ ### Restart Claude Code and start saving tons of Mana!
157
+
158
+ 1. Restart Claude Code in your project
159
+ 2. Run `/mcp` to verify MANA is connected
160
+
161
+ ---
162
+
163
+ ## Verify It's Working
164
+
165
+ After setup, ask Claude to read a file:
166
+
167
+ ```
168
+ Read the package.json file and tell me what dependencies this project uses.
169
+ ```
170
+
171
+ You should see output like:
172
+
173
+ ```
174
+ read_optimized [EXTRACT] -> 1,247 tokens saved (72% reduction) [1,732 -> 485]
175
+ ```
176
+
177
+ If you see token savings in the output, MANA is working.
178
+
179
+ ---
180
+
181
+ ## What the Instructions File Does
182
+
183
+ The `CLAUDE.md` file teaches Claude to:
184
+
185
+ - Use `read_optimized` instead of the native `Read` tool
186
+ - Use `bash_optimized` instead of the native `Bash` tool
187
+ - Use `search_optimized` instead of `Glob` and `Grep`
188
+ - Use `list_directory_optimized` for directory listings
189
+
190
+ Without this file, Claude will use its built-in tools and you won't get any token savings. **This step is required for MANA to work.**
191
+
192
+ ---
193
+
194
+ ## Troubleshooting
195
+
196
+ ### "Command not found" error
197
+
198
+ Make sure the npm package is installed globally:
199
+
200
+ ```bash
201
+ npm install -g @scottymade/mana
202
+
203
+ # Verify it's in PATH
204
+ which mana
205
+ ```
206
+
207
+ ### Claude isn't using MANA tools
208
+
209
+ 1. Verify `CLAUDE.md` exists (project root or `~/.claude/CLAUDE.md` for global)
210
+ 2. Restart Claude Code after making changes
211
+ 3. Check that the instructions appear in Claude's context
212
+
213
+ ### "Invalid API key" error
214
+
215
+ 1. Verify your key at [devmana.ai/settings](https://devmana.ai/settings)
216
+ 2. Re-run the `claude mcp add` command with the correct key
217
+ 3. Ensure the key hasn't been revoked
218
+
219
+ ### API Usage
220
+
221
+ Check your API usage on your [Mana Dashboard](https://app.devmana.ai/)
222
+
223
+ ---
46
224
 
47
- Run `/mcp` to verify MANA is connected.
225
+ ## Support
48
226
 
49
- ## Documentation
227
+ - **Documentation**: [GitHub](https://github.com/scottymade/mana/)
228
+ - **Issues**: [GitHub Issues](https://github.com/scottymade/mana/issues)
229
+ - **Bugs, Feedback and Feature Requests** can be sent via the chat feature in your [Mana Dashboard](https://app.devmana.ai/)
50
230
 
51
- Full documentation at [github.com/scottymade/mana](https://github.com/scottymade/mana)
231
+ ---
52
232
 
53
233
  ## License
54
234
 
55
- Apache-2.0
235
+ Apache 2.0 - See [LICENSE](LICENSE) for details.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scottymade/mana",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "MANA - LLM Token Usage Optimizer for Claude Code",
5
5
  "keywords": [
6
6
  "claude",