@scottymade/mana 1.1.2 → 1.2.1

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 +202 -83
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
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">
2
+ <a href="https://devmana.ai">
3
+ <img src="docs/mana-promo.png" alt="Mana - Boss-Tier AI. Minion-Tier Costs. Save 50-70% on AI Coding API Costs" width="800">
4
+ </a>
3
5
  </p>
4
6
 
5
7
  <p align="center">
@@ -13,7 +15,7 @@
13
15
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg" alt="Platforms">
14
16
  </a>
15
17
  <a href="https://devmana.ai">
16
- <img src="https://img.shields.io/badge/Claude%20Code-MCP%20Server-purple.svg" alt="Claude Code MCP Server">
18
+ <img src="https://img.shields.io/badge/AI%20Coding%20Agent-MCP%20Server-purple.svg" alt="Mana AI Coding Agent MCP Server">
17
19
  </a>
18
20
  <a href="https://github.com/scottymade/mana/blob/main/LICENSE">
19
21
  <img src="https://img.shields.io/github/license/scottymade/mana" alt="License">
@@ -22,9 +24,9 @@
22
24
 
23
25
  ---
24
26
 
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!
27
+ <a href="https://devmana.ai">MANA</a> intercepts bloated tool responses and routes them through lightweight models benchmarked for task accuracy. File reads, bash outputs, search results, and MCP calls — all optimized before reaching your AI coding agent, saving 50-70% on API costs. Your agent keeps its full power for the boss fights — architecture, debugging, code generation. The minion work gets handled for a fraction of the cost.
26
28
 
27
- **Result: 2x the coding sessions with no change to your workflow.**
29
+ **Result: Same AI intelligence. 50-70% less spend. No change to your workflow.**
28
30
 
29
31
  ---
30
32
 
@@ -34,52 +36,40 @@ MANA optimizes the token-heavy tool outputs that eat through your Claude limits.
34
36
 
35
37
  ### File Operations Are Mana Vampires
36
38
 
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.
39
+ Your AI agent 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
40
 
39
41
  ### Bash Commands Siphon Mana on Every Cast
40
42
 
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.
43
+ You run `npm run test`. Your AI agent 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
44
 
43
45
  ### Directory Searches Burn Through Reserves
44
46
 
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.
47
+ Your AI agent 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
48
 
47
49
  ### It's a Wipe. Pull the Combat Log — Here's What Killed You.
48
50
 
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 |
51
+ | 70-90% | MCP bloat | 2-3x |
52
+ |--------|-----------|------|
53
+ | of tokens go to tool bloat — not your actual work | unfiltered API calls draining mana on every lookup | faster bleed in large codebases |
52
54
 
53
- **You're not bad at token management. The trash mobs wiped your mana before you even reached the boss.**
55
+ **You're not bad at token management. The debuff was running before you even started coding.**
54
56
 
55
57
  ---
56
58
 
57
59
  ## How It Works
58
60
 
59
- **What If You Had a Mana Regen Buff Running 24/7?**
61
+ **Reclaim Your Mana Pool**
60
62
 
61
- **_That's Mana._**
63
+ You don't need a bigger mana pool. You need to stop the drain on the one you have.
62
64
 
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.
65
+ Mana saves 50-70% of your budget from going to bloated tool responses, unfiltered MCP calls, and brute-force file searches — routing the low-level work to optimized models so you stop paying boss rates for minion work.
64
66
 
65
- - Claude's full intelligence on architecture & code
66
- - Trash mobs handled by leaner models
67
+ - Your AI agent's full intelligence on architecture & code
68
+ - Minion work routed to minion-tier models
67
69
  - Your existing workflow, unchanged
68
70
  - Same firepower, at a fraction of the mana cost
69
71
 
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
- ```
72
+ Your AI coding agent keeps its full power for architecture, debugging, and code generation — the actual boss fights. Mana just stops it from burning spell slots on everything else.
83
73
 
84
74
  **Smart Routing** — Every tool action routes to a lightweight model benchmarked as the most accurate for that specific job.
85
75
 
@@ -87,108 +77,237 @@ flowchart TB
87
77
 
88
78
  **Compounding Savings** — Leaner responses mean leaner context. Savings stack with every turn. Longer sessions, fewer tokens burned.
89
79
 
90
- ### Mana Pool: Doubled
80
+ ### Your API Budget, Stretched 2-3x Further
91
81
 
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** |
82
+ | Monthly API Spend | Estimated Waste | With Mana |
83
+ |-------------------|-----------------|-----------|
84
+ | $600/mo | ~$420 goes to bloat | **Save $300-420/mo** |
85
+ | $1,500/mo | ~$1,050 goes to bloat | **Save $750-1,050/mo** |
86
+ | $2,500/mo | ~$1,750 goes to bloat | **Save $1,250-1,750/mo** |
97
87
 
98
- **Same Claude intelligence. Double the hours. A fraction of the price!**
88
+ **Same AI intelligence. 50-70% less spend. No change to your workflow.**
99
89
 
100
90
  ---
101
91
 
102
- ## Quick Start
92
+ ## Mana Dashboard
103
93
 
104
- ### Step 1: Install MANA
94
+ <p align="center">
95
+ <a href="https://waitlist.devmana.ai">
96
+ <img src="docs/mana-dashboard.png" alt="Mana Dashboard" width="800">
97
+ </a>
98
+ </p>
99
+
100
+ ---
101
+
102
+ ## Quick Start
105
103
 
106
104
  ```bash
105
+ # 1. Install
107
106
  npm install -g @scottymade/mana
107
+
108
+ # 2. Setup (auto-detects your platforms, prompts for API key)
109
+ mana setup
108
110
  ```
109
111
 
110
112
  Get your API key at [devmana.ai](https://devmana.ai) → **Settings** → **API Keys**
111
113
 
112
- ### Step 2: Add MCP Server
114
+ That's it. `mana setup` detects which AI coding platforms you have installed, configures MCP + prompt injection for each one, and you're ready to go.
113
115
 
114
- **2a. Project only** (run from your project root):
116
+ ### Supported Platforms
115
117
 
116
- ```bash
117
- claude mcp add -s project mana -- mana --api-key=YOUR_API_KEY
118
+ Claude Code, OpenAI Codex, OpenCode, Cursor, Windsurf, GitHub Copilot, JetBrains AI, Cline, Roo Code, Continue.dev, Zed, Trae IDE, and Aider.
119
+
120
+ ### Restart your editor and start saving tons of Mana!
121
+
122
+ ---
123
+
124
+ ## Verify It's Working
125
+
126
+ After setup, ask your agent to read a file:
127
+
128
+ ```
129
+ Read the package.json file and tell me what dependencies this project uses.
118
130
  ```
119
131
 
120
- **2b. Global** (run from anywhere, applies to all projects):
132
+ You should see output like:
121
133
 
122
- ```bash
123
- claude mcp add -s user mana -- mana --api-key=YOUR_API_KEY
134
+ ```
135
+ read_optimized [EXTRACT] -> 1,247 tokens saved (72% reduction) [1,732 -> 485]
124
136
  ```
125
137
 
126
- > **Note:** Project-level configs override global. You can mix and match (e.g., global MCP server + per-project instructions).
138
+ If you see token savings in the output, MANA is working.
127
139
 
128
- ### Step 3: Add Claude Instructions
140
+ ---
129
141
 
130
- #### Manual Install
142
+ ## What `mana setup` Does
131
143
 
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:
144
+ For each detected platform, `mana setup` handles two things automatically:
133
145
 
134
- **3a. Project only:** Prepend to `CLAUDE.md` in your project root
146
+ 1. **Prompt initialization** — Installs instructions that teach the AI to use MANA's optimized tools (`read_optimized`, `bash_optimized`, `search_optimized`, etc.) instead of native tools
147
+ 2. **MCP registration** — Registers the MANA MCP server so your platform can call MANA MCP sub-servers and their tools
135
148
 
136
- **3b. Global:** Prepend to `~/.claude/CLAUDE.md`
149
+ Each platform has its own config format and file paths — `mana setup` handles all of it. Run `mana setup --uninstall` to cleanly remove everything.
137
150
 
138
- #### Automatic Install
151
+ ---
139
152
 
140
- **3a. Project only** (run from your project root):
153
+ ## How to Update MANA
141
154
 
142
155
  ```bash
143
- { curl -fsSL https://raw.githubusercontent.com/scottymade/mana/main/instructions/CLAUDE_INSTRUCTIONS.md; echo ""; echo "---"; echo ""; cat CLAUDE.md 2>/dev/null; } > CLAUDE.md.tmp && mv CLAUDE.md.tmp CLAUDE.md
156
+ npm update -g @scottymade/mana
144
157
  ```
145
158
 
146
- **3b. Global** (run from anywhere, applies to all projects):
159
+ The update automatically refreshes the MANA prompt across all configured platforms. Restart your editor to use the new version.
160
+
161
+ **Check your current version:**
147
162
 
148
163
  ```bash
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
164
+ npm list -g @scottymade/mana
150
165
  ```
151
166
 
152
- > **Note:** These commands prepend MANA instructions to existing files. Your existing CLAUDE.md content will be preserved below the MANA instructions.
153
-
154
167
  ---
155
168
 
156
- ### Restart Claude Code and start saving tons of Mana!
169
+ ## Your Spellbook — Optimized Versions of Internal Tools
157
170
 
158
- 1. Restart Claude Code in your project
159
- 2. Run `/mcp` to verify MANA is connected
171
+ *Every adventurer needs the right gear. These are your upgraded spell slots.*
160
172
 
161
- ---
173
+ MANA swaps out your AI's clunky default tools for lean, optimized versions. Same spells, fraction of the mana cost. Your assistant learns them automatically from the prompt `mana setup` installs — no workflow changes, no new incantations to memorize.
162
174
 
163
- ## Verify It's Working
175
+ ### The Arsenal
164
176
 
165
- After setup, ask Claude to read a file:
177
+ | Spell | Replaces | What It Actually Does |
178
+ |-------|----------|----------------------|
179
+ | `read_optimized` | Native file read | Reads a 3,000-line file, returns only the 40 lines you needed |
180
+ | `read_optimized_batch` | Multiple file reads | Raids multiple files in one cast. Efficient looting. |
181
+ | `bash_optimized` | Native shell execution | Runs a command, strips the noise from the output |
182
+ | `search_optimized` | Native grep/glob | Searches your codebase without burning a spell slot per miss |
183
+ | `list_directory_optimized` | Native directory listing | Maps the dungeon without drawing every brick |
184
+ | `git_optimized` | Native git commands | Git log, diff, status — compressed to what matters |
166
185
 
167
- ```
168
- Read the package.json file and tell me what dependencies this project uses.
169
- ```
186
+ ### Spell Modifiers (Action Types)
170
187
 
171
- You should see output like:
188
+ Each tool call carries an `action_type` — think of it as choosing between a cantrip and a full spell slot:
172
189
 
190
+ | Modifier | When To Use | Mana Cost |
191
+ |----------|------------|-----------|
192
+ | `EXTRACT` | "Find the database config in this file" | Low — surgical extraction, returns only the hit |
193
+ | `SUMMARIZE` | "What does this 500-line file do?" | Low — heavy compression, key points only |
194
+ | `CHECK` | "Does this file import React?" | Minimal — yes/no, costs almost nothing |
195
+ | `DEBUG_LOGS` | "Why is this test failing?" | Low — zeroes in on errors and stack traces |
196
+ | `READ_FULL` | "I need every single line" | Full price — no optimization. The Wish spell of reads. Used sparingly. |
197
+
198
+ ---
199
+
200
+ ### Binding Your Familiars — MCP Sub-Server Setup
201
+
202
+ Wizard plan users can setup MCP sub-servers that live behind our Mana optization. MCPs you already use — GitLab, Brave Search, database tools, custom scripts, whatever's in your party. Instead of each agent spawning and managing them separately, MANA runs them all behind a single daemon. Your AI talks to MANA, MANA talks to your sub-servers, and every response that flows back gets the same token optimization treatment. One connection. All your tools. Leaner output on everything.
203
+
204
+ Create a config file at `~/.mana/mcp-servers.json` (global) or `.mana-mcp.json` (per-project):
205
+
206
+ ```json
207
+ {
208
+ "mcpServers": {
209
+ "gitlab": {
210
+ "command": "npx",
211
+ "args": ["-y", "@modelcontextprotocol/server-gitlab"],
212
+ "env": { "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxx" }
213
+ },
214
+ "brave-search": {
215
+ "command": "npx",
216
+ "args": ["-y", "@modelcontextprotocol/server-brave-search"],
217
+ "env": { "BRAVE_API_KEY": "BSA..." }
218
+ },
219
+ "time": {
220
+ "command": "python",
221
+ "args": ["-m", "mcp_server_time", "--local-timezone=America/New_York"]
222
+ }
223
+ }
224
+ }
173
225
  ```
174
- read_optimized [EXTRACT] -> 1,247 tokens saved (72% reduction) [1,732 -> 485]
226
+
227
+ Each familiar entry supports:
228
+
229
+ | Field | Type | Description |
230
+ |-------|------|-------------|
231
+ | `command` | string | The incantation to summon it (e.g., `npx`, `python`, `node`) |
232
+ | `args` | string[] | Spell components |
233
+ | `env` | object | Environment variables passed to the sub-server |
234
+ | `cwd` | string | Working directory for the sub-server |
235
+ | `transport` | `"stdio"` \| `"streamable-http"` | Transport type (default: `stdio`) |
236
+ | `url` | string | URL for `streamable-http` transport (remote familiars) |
237
+ | `enabled` | boolean | Set to `false` to bench a familiar without unbinding it |
238
+
239
+ ### Remote Familiars (Streamable HTTP)
240
+
241
+ For remote/hosted MCP servers — summon from across the planes:
242
+
243
+ ```json
244
+ {
245
+ "mcpServers": {
246
+ "my-remote-server": {
247
+ "transport": "streamable-http",
248
+ "url": "https://my-mcp-server.example.com/mcp"
249
+ }
250
+ }
251
+ }
175
252
  ```
176
253
 
177
- If you see token savings in the output, MANA is working.
254
+ ### Config Priority
255
+
256
+ Configs load in priority order (highest first). Think of it as spell slot override rules:
257
+
258
+ 1. `--mcp-config=<path>` — CLI flag (DM override)
259
+ 2. `.mana-mcp.json` — Project directory (dungeon-specific)
260
+ 3. `~/.mana/mcp-servers.json` — Home directory (character sheet)
261
+
262
+ ### Commanding Your Familiars
263
+
264
+ Sub-server tools are discoverable through three meta-spells:
265
+
266
+ | Meta-Spell | What It Does |
267
+ |------------|-------------|
268
+ | `mana_list_tools` | Survey all available familiar abilities |
269
+ | `mana_describe_tool` | Inspect a specific ability's full schema |
270
+ | `mana_call_tool` | Command a familiar to act |
271
+
272
+ Tools are namespaced as `server/tool_name` (e.g., `gitlab/create_issue`, `brave-search/web_search`).
273
+
274
+ ### Hot-Swapping Mid-Combat
275
+
276
+ Edit your config file and changes are picked up automatically. Or run `mana reload` manually. Either way:
277
+
278
+ - **Summoned** — New familiars connect and their abilities become available
279
+ - **Dismissed** — Removed familiars disconnect cleanly
280
+ - **Rebound** — Changed familiars reconnect with the new config
281
+ - **Unbothered** — Unchanged familiars keep their existing connections
282
+
283
+ No daemon restart. No editor restart. Swap your loadout without leaving the dungeon.
178
284
 
179
285
  ---
180
286
 
181
- ## What the Instructions File Does
287
+ ## The Archmage's Summon Circle — MCP Multiplexer
288
+
289
+ *Archmage Tier only. For those who command more than one familiar.*
290
+
291
+ Most devs juggle multiple MCP servers — GitLab, Brave Search, custom tools — each configured separately in every editor. That's like attuning to each magic item one at a time during combat.
182
292
 
183
- The `CLAUDE.md` file teaches Claude to:
293
+ MANA's multiplexer lets you **summon all your MCP servers through a single daemon**. Configure once, use everywhere. And every response that flows through gets the same token optimization treatment.
184
294
 
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
295
+ ### Why Go Archmage?
189
296
 
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.**
297
+ - **One config, all platforms** — Define your familiars once, summon them from any editor
298
+ - **Token optimization on everything** — Sub-server responses get compressed too. No wasted mana.
299
+ - **Auto-resurrect** — If a sub-server dies mid-fight, MANA raises it automatically
300
+ - **Hot-swap** — Add or remove sub-servers without restarting anything. Swap gear mid-dungeon.
301
+ - **Shared connections** — Multiple editors tap the same sub-server pool. Party-wide buffs.
191
302
 
303
+ ### Summoning the Daemon
304
+
305
+ ```bash
306
+ mana start # Summon the daemon (checks Archmage attunement)
307
+ mana status # Scry daemon status, PID, uptime
308
+ mana reload # Hot-reload sub-server config without restart
309
+ mana stop # Dismiss the daemon
310
+ ```
192
311
  ---
193
312
 
194
313
  ## Troubleshooting
@@ -204,16 +323,16 @@ npm install -g @scottymade/mana
204
323
  which mana
205
324
  ```
206
325
 
207
- ### Claude isn't using MANA tools
326
+ ### AI assistant isn't using MANA tools
208
327
 
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
328
+ 1. Run `mana setup` again to verify configuration
329
+ 2. Restart your editor after setup
330
+ 3. Check that MANA tools appear in your platform's MCP/tool list
212
331
 
213
332
  ### "Invalid API key" error
214
333
 
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
334
+ 1. Create a new API key in the Dashboard [app.devmana.ai](https://app.devmana.ai)
335
+ 2. Run `mana setup` again with the correct key
217
336
  3. Ensure the key hasn't been revoked
218
337
 
219
338
  ### API Usage
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scottymade/mana",
3
- "version": "1.1.2",
3
+ "version": "1.2.1",
4
4
  "description": "MANA - LLM Token Usage Optimizer for Claude Code",
5
5
  "keywords": [
6
6
  "claude",