@scottymade/mana 1.2.0 → 1.2.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 +127 -88
  2. package/package.json +3 -3
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-api-spend.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
+ <a href="https://devmana.ai">MANA</a> 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. <a href="https://devmana.ai">MANA</a> 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,107 +77,157 @@ 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 <a href="https://devmana.ai">MANA</a> |
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
- ```
118
+ Claude Code, OpenAI Codex, OpenCode, Cursor, Windsurf, GitHub Copilot, JetBrains AI, Cline, Roo Code, Continue.dev, Zed, Trae IDE, and Aider.
119
119
 
120
- **2b. Global** (run from anywhere, applies to all projects):
120
+ ### Restart your editor and start saving tons of Mana!
121
121
 
122
- ```bash
123
- claude mcp add -s user mana -- mana --api-key=YOUR_API_KEY
124
- ```
122
+ ---
125
123
 
126
- > **Note:** Project-level configs override global. You can mix and match (e.g., global MCP server + per-project instructions).
124
+ ## Verify It's Working
127
125
 
128
- ### Step 3: Add Claude Instructions
126
+ After setup, ask your agent to read a file:
129
127
 
130
- #### Manual Install
128
+ ```
129
+ Read the package.json file and tell me what dependencies this project uses.
130
+ ```
131
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:
132
+ You should see output like:
133
133
 
134
- **3a. Project only:** Prepend to `CLAUDE.md` in your project root
134
+ ```
135
+ read_optimized [EXTRACT] -> 1,247 tokens saved (72% reduction) [1,732 -> 485]
136
+ ```
135
137
 
136
- **3b. Global:** Prepend to `~/.claude/CLAUDE.md`
138
+ If you see token savings in the output, <a href="https://devmana.ai">MANA</a> is working.
137
139
 
138
- #### Automatic Install
140
+ ---
139
141
 
140
- **3a. Project only** (run from your project root):
142
+ ## How to Update MANA
141
143
 
142
144
  ```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
145
+ npm update -g @scottymade/mana
144
146
  ```
145
147
 
146
- **3b. Global** (run from anywhere, applies to all projects):
148
+ The update automatically refreshes the <a href="https://devmana.ai">MANA</a> prompt across all configured platforms. Restart your editor to use the new version.
149
+
150
+ **Check your current version:**
147
151
 
148
152
  ```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
153
+ npm list -g @scottymade/mana
150
154
  ```
151
155
 
152
- > **Note:** These commands prepend MANA instructions to existing files. Your existing CLAUDE.md content will be preserved below the MANA instructions.
153
-
154
156
  ---
155
157
 
156
- ### Restart Claude Code and start saving tons of Mana!
158
+ ## Mana Optimization Core: Your Spellbook — Optimized Versions of Internal Tools
157
159
 
158
- 1. Restart Claude Code in your project
159
- 2. Run `/mcp` to verify MANA is connected
160
+ *Your spellbook just got enchanted. Same incantations, at a fraction of the casting cost.*
160
161
 
161
- ---
162
+ <a href="https://devmana.ai">MANA</a> swaps out your AI's clunky default tools for lean, optimized versions. Same AI tool call power, at fraction of the API cost.
162
163
 
163
- ## Verify It's Working
164
+ ### The Arsenal
164
165
 
165
- After setup, ask Claude to read a file:
166
+ | Spell | Replaces | What It Actually Does |
167
+ |-------|----------|----------------------|
168
+ | `read_optimized` | Native file read | Reads a 3,000-line file, returns only the 40 lines you needed |
169
+ | `read_optimized_batch` | Multiple file reads | Raids multiple files in one cast. Efficient looting at scale. |
170
+ | `bash_optimized` | Native shell execution | Runs a command, strips the noise from the output |
171
+ | `search_optimized` | Native grep/glob | Locally indexed semantic code searches without burning API costs on fails lookups |
172
+ | `list_directory_optimized` | Native directory listing | Maps the dungeon without drawing every brick |
173
+ | `git_optimized` | Native git commands | Git log, diff, status — compressed to what matters |
166
174
 
167
- ```
168
- Read the package.json file and tell me what dependencies this project uses.
175
+ ---
176
+
177
+ ### Mana MCP Call Optimization: Rally Your Familiars
178
+
179
+ *Every wizard knows — a loyal familiar doesn't just follow orders. It filters the noise so you can focus on the completing your cast at full power.*
180
+
181
+ Wizard & Archmage 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, <a href="https://devmana.ai">MANA</a> runs them all behind a single daemon. Your AI talks to <a href="https://devmana.ai">MANA</a>, <a href="https://devmana.ai">MANA</a> 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.
182
+
183
+ Create a config file at `~/.mana/mcp-servers.json` (global) or `.mana-mcp.json` (per-project):
184
+
185
+ ```json
186
+ {
187
+ "mcpServers": {
188
+ "gitlab": {
189
+ "command": "npx",
190
+ "args": ["-y", "@modelcontextprotocol/server-gitlab"],
191
+ "env": { "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxx" }
192
+ },
193
+ "brave-search": {
194
+ "command": "npx",
195
+ "args": ["-y", "@modelcontextprotocol/server-brave-search"],
196
+ "env": { "BRAVE_API_KEY": "BSA..." }
197
+ },
198
+ "time": {
199
+ "command": "python",
200
+ "args": ["-m", "mcp_server_time", "--local-timezone=America/New_York"]
201
+ }
202
+ }
203
+ }
169
204
  ```
170
205
 
171
- You should see output like:
206
+ ### Context Savings for Each MCP Server Added
172
207
 
173
- ```
174
- read_optimized [EXTRACT] -> 1,247 tokens saved (72% reduction) [1,732 -> 485]
175
- ```
208
+ Similar to how Claude Code only reveals the tool definitions and schemas as they're needed, we also only show the names and descriptions of the subservers to the AI so your session saves a ton of context.
209
+
210
+ Your AI has the ability to look into the details of the tools as needed, and can load schemas to invoke the correct tool calls and use as it normally would:
176
211
 
177
- If you see token savings in the output, MANA is working.
212
+ | Meta-Spell | What It Does |
213
+ |------------|-------------|
214
+ | `mana_list_tools` | Survey all available familiar abilities |
215
+ | `mana_describe_tool` | Inspect a specific ability's full schema |
216
+ | `mana_call_tool` | Command a familiar to act |
217
+
218
+ No bloat upfront. Full power on demand. The more MCP servers you add, the more context you save — and the more room your AI has to focus on the boss fights.
178
219
 
179
220
  ---
180
221
 
181
- ## What the Instructions File Does
222
+ ## The Archmage's Summon Circle — MCP Multiplexer
223
+
224
+ *Archmage Tier only. For those who command an army of AI Agents ready to serve.*
182
225
 
183
- The `CLAUDE.md` file teaches Claude to:
226
+ Every agent you spin up spawns its own instance of every MCP server available to it. Run five agents in parallel with six MCP servers each, and that's thirty separate processes eating RAM and grinding your system to a crawl. Task performance tanks. Completion times balloon. Your army of agents becomes a bottleneck instead of a force multiplier.
184
227
 
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
228
+ Mana's multiplexer lets you summon all your MCP servers through a single daemon. Configure once, use everywhere. Every agent shares the same server instances — slashing RAM usage while still getting the full Mana token optimization treatment on every response that flows through.
189
229
 
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.**
230
+ More agents. Less overhead. If you're running the kind of parallel workflows that bring most systems to their knees, this is how you scale without sacrifice.
191
231
 
192
232
  ---
193
233
 
@@ -204,16 +244,16 @@ npm install -g @scottymade/mana
204
244
  which mana
205
245
  ```
206
246
 
207
- ### Claude isn't using MANA tools
247
+ ### AI assistant isn't using MANA tools
208
248
 
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
249
+ 1. Run `mana setup` again to verify configuration
250
+ 2. Restart your editor after setup
251
+ 3. Check that <a href="https://devmana.ai">MANA</a> tools appear in your platform's MCP/tool list
212
252
 
213
253
  ### "Invalid API key" error
214
254
 
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
255
+ 1. Create a new API key in the Dashboard [app.devmana.ai](https://app.devmana.ai)
256
+ 2. Run `mana setup` again with the correct key
217
257
  3. Ensure the key hasn't been revoked
218
258
 
219
259
  ### API Usage
@@ -226,10 +266,9 @@ Check your API usage on your [Mana Dashboard](https://app.devmana.ai/)
226
266
 
227
267
  - **Documentation**: [GitHub](https://github.com/scottymade/mana/)
228
268
  - **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/)
230
269
 
231
270
  ---
232
271
 
233
272
  ## License
234
273
 
235
- Apache 2.0 - See [LICENSE](LICENSE) for details.
274
+ Proprietary / EULA - See [LICENSE](LICENSE) for details.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@scottymade/mana",
3
- "version": "1.2.0",
4
- "description": "MANA - LLM Token Usage Optimizer for Claude Code",
3
+ "version": "1.2.2",
4
+ "description": "MANA - LLM Token Optimization",
5
5
  "keywords": [
6
6
  "claude",
7
7
  "claude-code",
@@ -10,7 +10,7 @@
10
10
  "llm"
11
11
  ],
12
12
  "author": "ScottyMade <hi@scottymadellc.com>",
13
- "license": "Apache-2.0",
13
+ "license": "SEE LICENSE IN LICENSE",
14
14
  "homepage": "https://devmana.ai",
15
15
  "repository": {
16
16
  "type": "git",