@scottymade/mana 1.0.0 → 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.
- package/README.md +209 -27
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,53 +1,235 @@
|
|
|
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">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
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
|
-
|
|
23
|
+
---
|
|
6
24
|
|
|
7
|
-
|
|
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
|
+
---
|
|
101
|
+
|
|
102
|
+
## Quick Start
|
|
103
|
+
|
|
104
|
+
### Step 1: Install MANA
|
|
8
105
|
|
|
9
106
|
```bash
|
|
10
107
|
npm install -g @scottymade/mana
|
|
11
108
|
```
|
|
12
109
|
|
|
13
|
-
|
|
110
|
+
Get your API key at [devmana.ai](https://devmana.ai) → **Settings** → **API Keys**
|
|
14
111
|
|
|
15
|
-
|
|
112
|
+
### Step 2: Add MCP Server
|
|
16
113
|
|
|
17
|
-
|
|
114
|
+
**2a. Project only** (run from your project root):
|
|
18
115
|
|
|
19
|
-
|
|
116
|
+
```bash
|
|
117
|
+
claude mcp add -s project mana -- mana --api-key=YOUR_API_KEY
|
|
118
|
+
```
|
|
20
119
|
|
|
21
|
-
|
|
120
|
+
**2b. Global** (run from anywhere, applies to all projects):
|
|
22
121
|
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
"mcpServers": {
|
|
26
|
-
"mana": {
|
|
27
|
-
"command": "mana",
|
|
28
|
-
"args": ["--api-key=YOUR_API_KEY"]
|
|
29
|
-
}
|
|
30
|
-
}
|
|
31
|
-
}
|
|
122
|
+
```bash
|
|
123
|
+
claude mcp add -s user mana -- mana --api-key=YOUR_API_KEY
|
|
32
124
|
```
|
|
33
125
|
|
|
34
|
-
|
|
126
|
+
> **Note:** Project-level configs override global. You can mix and match (e.g., global MCP server + per-project instructions).
|
|
127
|
+
|
|
128
|
+
### Step 3: Add Claude Instructions
|
|
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
|
|
35
139
|
|
|
36
|
-
|
|
140
|
+
**3a. Project only** (run from your project root):
|
|
37
141
|
|
|
38
142
|
```bash
|
|
39
|
-
|
|
40
|
-
curl -fsSL https://raw.githubusercontent.com/scottymade/mana/main/instructions/CLAUDE_INSTRUCTIONS.md >> .claude/CLAUDE.md
|
|
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
|
|
41
144
|
```
|
|
42
145
|
|
|
43
|
-
|
|
146
|
+
**3b. Global** (run from anywhere, applies to all projects):
|
|
147
|
+
|
|
148
|
+
```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
|
|
150
|
+
```
|
|
151
|
+
|
|
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
|
+
---
|
|
44
224
|
|
|
45
|
-
|
|
225
|
+
## Support
|
|
46
226
|
|
|
47
|
-
|
|
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/)
|
|
48
230
|
|
|
49
|
-
|
|
231
|
+
---
|
|
50
232
|
|
|
51
233
|
## License
|
|
52
234
|
|
|
53
|
-
Apache
|
|
235
|
+
Apache 2.0 - See [LICENSE](LICENSE) for details.
|