@proxysoul/soulforge 2.9.5 โ 2.10.0
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 +113 -450
- package/dist/index.js +4083 -3853
- package/dist/workers/intelligence.worker.js +157 -108
- package/dist/workers/io.worker.js +27 -4
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -25,221 +25,156 @@
|
|
|
25
25
|
|
|
26
26
|
<img src="assets/features.svg" width="800" />
|
|
27
27
|
|
|
28
|
+
<br/>
|
|
29
|
+
|
|
30
|
+
<a href="https://www.star-history.com/?repos=ProxySoul%2Fsoulforge&type=date&legend=top-left">
|
|
31
|
+
<picture>
|
|
32
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=ProxySoul/soulforge&type=date&theme=dark&legend=top-left" />
|
|
33
|
+
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=ProxySoul/soulforge&type=date&legend=top-left" />
|
|
34
|
+
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=ProxySoul/soulforge&type=date&legend=top-left" width="700" />
|
|
35
|
+
</picture>
|
|
36
|
+
</a>
|
|
37
|
+
|
|
28
38
|
</div>
|
|
29
39
|
|
|
30
40
|
<img src="assets/separator.svg" width="100%" height="8" />
|
|
31
41
|
|
|
32
|
-
##
|
|
42
|
+
## The agent that already knows your codebase
|
|
33
43
|
|
|
34
44
|
Every AI coding tool starts blind. It reads files, greps around, slowly builds a mental model of your codebase. You wait. You pay. The agent is doing orientation work, not real work.
|
|
35
45
|
|
|
36
|
-
SoulForge already knows.
|
|
46
|
+
SoulForge already knows. It builds a **live dependency graph** on startup and keeps it updated as you work. The agent knows which files matter, what depends on what, and how far an edit will ripple before it writes a single line.
|
|
47
|
+
|
|
48
|
+
**Result: ~2x fewer steps, ~2x lower cost on the same tasks.** The agent spends time on real work, not figuring out where things are.
|
|
37
49
|
|
|
38
50
|
<img src="assets/separator.svg" width="100%" height="8" />
|
|
39
51
|
|
|
40
|
-
|
|
52
|
+
## What makes it different
|
|
41
53
|
|
|
42
54
|
<table>
|
|
43
55
|
<tr>
|
|
44
56
|
<td width="50%" valign="top">
|
|
45
|
-
<h4
|
|
46
|
-
<p>
|
|
57
|
+
<h4>โก Live Soul Map</h4>
|
|
58
|
+
<p>Graph of every file, symbol, and import, ranked by importance, enriched with git history, updated in real-time. The agent never wastes a turn orienting itself. <a href="docs/repo-map.md">Learn more</a></p>
|
|
47
59
|
</td>
|
|
48
60
|
<td width="50%" valign="top">
|
|
49
|
-
<h4
|
|
50
|
-
<p>
|
|
61
|
+
<h4>๐ช Surgical reads</h4>
|
|
62
|
+
<p>Extracts exactly the function or class it needs by name. A 500-line file becomes a 20-line extraction. 33 languages supported. <a href="docs/architecture.md">Learn more</a></p>
|
|
51
63
|
</td>
|
|
52
64
|
</tr>
|
|
53
65
|
<tr>
|
|
54
66
|
<td valign="top">
|
|
55
|
-
<h4
|
|
56
|
-
<p>
|
|
67
|
+
<h4>๐ค Multi-agent dispatch</h4>
|
|
68
|
+
<p>Parallel explore, code, and web search agents with shared cache. One agent's discovery reaches others instantly. <a href="docs/agent-bus.md">Learn more</a></p>
|
|
57
69
|
</td>
|
|
58
70
|
<td valign="top">
|
|
59
|
-
<h4
|
|
60
|
-
<p>
|
|
71
|
+
<h4>๐ฐ Instant compaction</h4>
|
|
72
|
+
<p>Context state is tracked as the conversation happens. When it gets long, compaction fires instantly, often with zero LLM cost. <a href="docs/compaction.md">Learn more</a></p>
|
|
61
73
|
</td>
|
|
62
74
|
</tr>
|
|
63
75
|
<tr>
|
|
64
76
|
<td valign="top">
|
|
65
|
-
<h4
|
|
66
|
-
<p>
|
|
77
|
+
<h4>๐ง 4-tier code intelligence</h4>
|
|
78
|
+
<p>LSP, ts-morph, tree-sitter, regex fallback chain. Dual LSP backend, works with or without the editor open. <a href="docs/architecture.md">Learn more</a></p>
|
|
67
79
|
</td>
|
|
68
80
|
<td valign="top">
|
|
69
|
-
<h4
|
|
70
|
-
<p><code>
|
|
81
|
+
<h4>๐ง Compound tools</h4>
|
|
82
|
+
<p><code>rename_symbol</code>, <code>move_symbol</code>, <code>refactor</code>, <code>project</code>. Compiler-guaranteed, one call does the complete job. <a href="docs/compound-tools.md">Learn more</a></p>
|
|
71
83
|
</td>
|
|
72
84
|
</tr>
|
|
73
85
|
<tr>
|
|
74
86
|
<td valign="top">
|
|
75
|
-
<h4
|
|
76
|
-
<p>Opus
|
|
87
|
+
<h4>๐ฏ Mix-and-match models</h4>
|
|
88
|
+
<p>Opus for planning, Sonnet for coding, Haiku for cleanup. 20 providers built-in. Task router gives full control.</p>
|
|
77
89
|
</td>
|
|
78
90
|
<td valign="top">
|
|
79
|
-
<h4
|
|
80
|
-
<p>
|
|
91
|
+
<h4>๐ Embedded Neovim</h4>
|
|
92
|
+
<p>Your config, your plugins, your LSP servers. The AI edits through the same editor you use.</p>
|
|
81
93
|
</td>
|
|
82
94
|
</tr>
|
|
83
95
|
</table>
|
|
84
96
|
|
|
85
|
-
<br/>
|
|
86
|
-
|
|
87
|
-
<details>
|
|
88
|
-
<summary><strong>More features</strong></summary>
|
|
89
|
-
<br/>
|
|
90
|
-
|
|
91
97
|
<table>
|
|
92
98
|
<tr>
|
|
93
|
-
<td width="
|
|
94
|
-
<
|
|
95
|
-
</
|
|
96
|
-
|
|
97
|
-
<td
|
|
98
|
-
<
|
|
99
|
-
</
|
|
100
|
-
|
|
101
|
-
<td><strong>19 providers</strong></td>
|
|
102
|
-
<td>Anthropic, OpenAI, Google, xAI, Groq, DeepSeek, Mistral, Bedrock, Fireworks, MiniMax, Copilot, GitHub Models, Ollama, LM Studio, OpenRouter, LLM Gateway, Vercel AI Gateway, Proxy, any OpenAI-compatible.</td>
|
|
103
|
-
</tr>
|
|
104
|
-
<tr>
|
|
105
|
-
<td><strong>Task router</strong></td>
|
|
106
|
-
<td>Per-job model assignment. Spark agents and ember agents each get their own model. <a href="docs/architecture.md">More</a></td>
|
|
107
|
-
</tr>
|
|
108
|
-
<tr>
|
|
109
|
-
<td><strong>Code execution</strong></td>
|
|
110
|
-
<td>Sandboxed Python via Anthropic's <code>code_execution</code> tool. Process data, calculations, batch tool calls.</td>
|
|
111
|
-
</tr>
|
|
112
|
-
<tr>
|
|
113
|
-
<td><strong>User steering</strong></td>
|
|
114
|
-
<td>Type while the agent works. Messages queue and arrive at the next step. <a href="docs/steering.md">More</a></td>
|
|
115
|
-
</tr>
|
|
116
|
-
<tr>
|
|
117
|
-
<td><strong>Skills + gates</strong></td>
|
|
118
|
-
<td>Installable skills for domain work. Destructive actions need confirmation. Auto mode for full autonomy.</td>
|
|
119
|
-
</tr>
|
|
120
|
-
<tr>
|
|
121
|
-
<td><strong>MCP servers</strong></td>
|
|
122
|
-
<td>Connect to any <a href="https://modelcontextprotocol.io">Model Context Protocol</a> server. stdio, HTTP, SSE transports. Auto-reconnect, bounded concurrency, tool namespacing. <a href="docs/mcp.md">More</a></td>
|
|
123
|
-
</tr>
|
|
124
|
-
<tr>
|
|
125
|
-
<td><strong>Inline images</strong></td>
|
|
126
|
-
<td>Pixel-perfect images, animated GIFs, and video-to-GIF inline in chat via <code>soul_vision</code>. Kitty graphics protocol with Unicode placeholders. Supports local files, URLs, and code execution output. <a href="#inline-image-support">See terminal support</a></td>
|
|
127
|
-
</tr>
|
|
128
|
-
<tr>
|
|
129
|
-
<td><strong>4-tier intelligence</strong></td>
|
|
130
|
-
<td>LSP, ts-morph, tree-sitter, regex. 33 languages. Dual LSP: Neovim bridge when the editor is open, standalone servers when it's not. <a href="docs/architecture.md">More</a></td>
|
|
99
|
+
<td width="50%" valign="top">
|
|
100
|
+
<h4>๐ MCP servers</h4>
|
|
101
|
+
<p>Connect to any <a href="https://modelcontextprotocol.io">Model Context Protocol</a> server. stdio, HTTP, SSE transports. Auto-reconnect, namespaced tools. <a href="docs/mcp.md">Learn more</a></p>
|
|
102
|
+
</td>
|
|
103
|
+
<td width="50%" valign="top">
|
|
104
|
+
<h4>๐ช Lifecycle hooks</h4>
|
|
105
|
+
<p>13 hook events (PreToolUse, PostToolUse, SessionStart, etc.). Claude Code compatible, drop in your existing <code>.claude/settings.json</code> hooks. <a href="docs/hooks.md">Learn more</a></p>
|
|
106
|
+
</td>
|
|
131
107
|
</tr>
|
|
132
108
|
<tr>
|
|
133
|
-
<td
|
|
134
|
-
<
|
|
109
|
+
<td valign="top">
|
|
110
|
+
<h4>๐งฉ Skills</h4>
|
|
111
|
+
<p>Installable domain-specific capabilities with approval gates. Browse and install from the community registry with <code>Ctrl+S</code>.</p>
|
|
112
|
+
</td>
|
|
113
|
+
<td valign="top">
|
|
114
|
+
<h4>๐ Multi-tab</h4>
|
|
115
|
+
<p>Up to 5 concurrent sessions with per-tab models, file claims, and git coordination. <a href="docs/cross-tab-coordination.md">Learn more</a></p>
|
|
116
|
+
</td>
|
|
135
117
|
</tr>
|
|
136
118
|
</table>
|
|
137
119
|
|
|
138
|
-
|
|
139
|
-
|
|
120
|
+
<details>
|
|
121
|
+
<summary><strong>Even more</strong></summary>
|
|
140
122
|
<br/>
|
|
141
123
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
124
|
+
- **User steering** type while the agent works, messages inject mid-stream. [More](docs/steering.md)
|
|
125
|
+
- **Lock-in mode** hides narration, shows only tool activity and final answer
|
|
126
|
+
- **Inline images** pixel-perfect images and animated GIFs in chat via Kitty graphics protocol
|
|
127
|
+
- **24 themes** Catppuccin, Dracula, Gruvbox, Nord, Tokyo Night, and more. Custom themes with hot reload. [More](docs/themes.md)
|
|
128
|
+
- **Code execution** sandboxed Python for data processing and calculations
|
|
129
|
+
- **100 slash commands** [Full reference](docs/commands-reference.md)
|
|
145
130
|
|
|
131
|
+
</details>
|
|
132
|
+
|
|
133
|
+
<br/>
|
|
146
134
|
<img src="assets/separator.svg" width="100%" height="8" />
|
|
147
135
|
|
|
148
|
-
### Inline image support
|
|
149
136
|
|
|
150
|
-
|
|
137
|
+
## Get started
|
|
151
138
|
|
|
152
|
-
|
|
139
|
+
macOS and Linux. First launch offers to install Neovim and Nerd Fonts if missing.
|
|
153
140
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
<th width="140">Terminal</th>
|
|
158
|
-
<th width="120">Static images</th>
|
|
159
|
-
<th width="120">Animated GIF</th>
|
|
160
|
-
<th width="120">Video to GIF</th>
|
|
161
|
-
<th>Method</th>
|
|
162
|
-
<th>Notes</th>
|
|
163
|
-
</tr>
|
|
164
|
-
</thead>
|
|
165
|
-
<tbody>
|
|
166
|
-
<tr>
|
|
167
|
-
<td><strong>Kitty</strong></td>
|
|
168
|
-
<td>Pixel-perfect</td>
|
|
169
|
-
<td>Animated</td>
|
|
170
|
-
<td>Animated</td>
|
|
171
|
-
<td>Kitty graphics protocol + Unicode placeholders</td>
|
|
172
|
-
<td>Kitty โค 0.37 only โ see note above</td>
|
|
173
|
-
</tr>
|
|
174
|
-
<tr>
|
|
175
|
-
<td><strong>Ghostty</strong></td>
|
|
176
|
-
<td>Pixel-perfect</td>
|
|
177
|
-
<td>Static frame</td>
|
|
178
|
-
<td>Static frame</td>
|
|
179
|
-
<td>Kitty graphics protocol + Unicode placeholders</td>
|
|
180
|
-
<td>Animation not yet implemented (<a href="https://github.com/ghostty-org/ghostty/discussions/5218">#5218</a>)</td>
|
|
181
|
-
</tr>
|
|
182
|
-
<tr>
|
|
183
|
-
<td><strong>Konsole</strong></td>
|
|
184
|
-
<td>chafa / half-block</td>
|
|
185
|
-
<td>Static frame</td>
|
|
186
|
-
<td>Static frame</td>
|
|
187
|
-
<td>Terminal art (chafa, built-in half-block)</td>
|
|
188
|
-
<td>Has Kitty graphics but no Unicode placeholders (<a href="https://invent.kde.org/utilities/konsole/-/merge_requests/594">MR #594</a>)</td>
|
|
189
|
-
</tr>
|
|
190
|
-
<tr>
|
|
191
|
-
<td><strong>iTerm2</strong></td>
|
|
192
|
-
<td>chafa / half-block</td>
|
|
193
|
-
<td>Static frame</td>
|
|
194
|
-
<td>Static frame</td>
|
|
195
|
-
<td>Terminal art (chafa, built-in half-block)</td>
|
|
196
|
-
<td>Has Kitty graphics but no Unicode placeholders (<a href="https://github.com/gnachman/iTerm2/commit/4fe5b21">commit</a>)</td>
|
|
197
|
-
</tr>
|
|
198
|
-
<tr>
|
|
199
|
-
<td><strong>WezTerm</strong></td>
|
|
200
|
-
<td>chafa / half-block</td>
|
|
201
|
-
<td>Static frame</td>
|
|
202
|
-
<td>Static frame</td>
|
|
203
|
-
<td>Terminal art (chafa, built-in half-block)</td>
|
|
204
|
-
<td>No Unicode placeholders (<a href="https://github.com/wezterm/wezterm/issues/986">#986</a>)</td>
|
|
205
|
-
</tr>
|
|
206
|
-
<tr>
|
|
207
|
-
<td><strong>Warp</strong></td>
|
|
208
|
-
<td>chafa / half-block</td>
|
|
209
|
-
<td>Static frame</td>
|
|
210
|
-
<td>Static frame</td>
|
|
211
|
-
<td>Terminal art (chafa, built-in half-block)</td>
|
|
212
|
-
<td>No Unicode placeholders (<a href="https://github.com/warpdotdev/Warp/issues/6210">#6210</a>)</td>
|
|
213
|
-
</tr>
|
|
214
|
-
<tr>
|
|
215
|
-
<td><strong>Alacritty</strong></td>
|
|
216
|
-
<td>chafa / half-block</td>
|
|
217
|
-
<td>Static frame</td>
|
|
218
|
-
<td>Static frame</td>
|
|
219
|
-
<td>Terminal art (chafa, built-in half-block)</td>
|
|
220
|
-
<td>No graphics protocol</td>
|
|
221
|
-
</tr>
|
|
222
|
-
<tr>
|
|
223
|
-
<td><strong>Others</strong></td>
|
|
224
|
-
<td>Half-block art</td>
|
|
225
|
-
<td>Static frame</td>
|
|
226
|
-
<td>Static frame</td>
|
|
227
|
-
<td>Built-in half-block ANSI art</td>
|
|
228
|
-
<td>Any truecolor terminal works</td>
|
|
229
|
-
</tr>
|
|
230
|
-
</tbody>
|
|
231
|
-
</table>
|
|
141
|
+
```bash
|
|
142
|
+
brew tap proxysoul/tap && brew install soulforge
|
|
143
|
+
```
|
|
232
144
|
|
|
233
|
-
<
|
|
234
|
-
<
|
|
145
|
+
<details>
|
|
146
|
+
<summary><strong>Other install methods</strong></summary>
|
|
235
147
|
<br/>
|
|
236
|
-
Install <a href="https://github.com/hpjansson/chafa"><code>chafa</code></a> for higher quality terminal art on non-pixel terminals. Install <a href="https://github.com/FFmpeg/FFmpeg"><code>ffmpeg</code></a> for animated GIF, video conversion, and format support. Install <a href="https://github.com/yt-dlp/yt-dlp"><code>yt-dlp</code></a> to display videos from URLs.
|
|
237
|
-
</sub>
|
|
238
148
|
|
|
149
|
+
**Bun (global):**
|
|
239
150
|
```bash
|
|
240
|
-
|
|
151
|
+
bun install -g @proxysoul/soulforge
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
**Prebuilt binary:**
|
|
155
|
+
```bash
|
|
156
|
+
# Download from https://github.com/ProxySoul/soulforge/releases/latest
|
|
157
|
+
tar xzf soulforge-*.tar.gz && cd soulforge-*/ && ./install.sh
|
|
241
158
|
```
|
|
242
159
|
|
|
160
|
+
**Build from source:**
|
|
161
|
+
```bash
|
|
162
|
+
git clone https://github.com/ProxySoul/soulforge.git && cd soulforge && bun install
|
|
163
|
+
bun run dev
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
</details>
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
soulforge # launch, pick a model with Ctrl+L
|
|
170
|
+
soulforge --set-key anthropic sk-ant-... # save a key
|
|
171
|
+
soulforge --headless "your prompt here" # non-interactive
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
See [GETTING_STARTED.md](GETTING_STARTED.md) for a full walkthrough, or the [full docs](docs/README.md) for everything.
|
|
175
|
+
|
|
176
|
+
<img src="assets/separator.svg" width="100%" height="8" />
|
|
177
|
+
|
|
243
178
|
## How it compares
|
|
244
179
|
|
|
245
180
|
<table>
|
|
@@ -248,7 +183,6 @@ brew install ffmpeg chafa yt-dlp
|
|
|
248
183
|
<th width="160"></th>
|
|
249
184
|
<th>SoulForge</th>
|
|
250
185
|
<th>Claude Code</th>
|
|
251
|
-
<th>Copilot CLI</th>
|
|
252
186
|
<th>Codex CLI</th>
|
|
253
187
|
<th>Aider</th>
|
|
254
188
|
</tr>
|
|
@@ -256,81 +190,43 @@ brew install ffmpeg chafa yt-dlp
|
|
|
256
190
|
<tbody>
|
|
257
191
|
<tr>
|
|
258
192
|
<td><strong>Codebase awareness</strong></td>
|
|
259
|
-
<td>Live
|
|
193
|
+
<td>Live dependency graph with ranking</td>
|
|
260
194
|
<td>File reads + grep</td>
|
|
261
|
-
<td>None</td>
|
|
262
195
|
<td>MCP plugins</td>
|
|
263
196
|
<td>Tree-sitter + PageRank</td>
|
|
264
197
|
</tr>
|
|
265
198
|
<tr>
|
|
266
199
|
<td><strong>Cost optimization</strong></td>
|
|
267
|
-
<td>
|
|
200
|
+
<td>Surgical reads + instant compaction + shared cache + model mixing</td>
|
|
268
201
|
<td>Auto-compaction</td>
|
|
269
|
-
<td>Context window mgmt</td>
|
|
270
202
|
<td>Server-side compaction</td>
|
|
271
203
|
<td>-</td>
|
|
272
204
|
</tr>
|
|
273
205
|
<tr>
|
|
274
206
|
<td><strong>Code intelligence</strong></td>
|
|
275
|
-
<td>4-tier
|
|
207
|
+
<td>4-tier fallback, dual LSP, 33 languages</td>
|
|
276
208
|
<td>LSP via plugins</td>
|
|
277
|
-
<td>LSP (VS Code)</td>
|
|
278
209
|
<td>MCP-based LSP</td>
|
|
279
210
|
<td>Tree-sitter AST</td>
|
|
280
211
|
</tr>
|
|
281
212
|
<tr>
|
|
282
213
|
<td><strong>Multi-agent</strong></td>
|
|
283
|
-
<td>Parallel dispatch
|
|
214
|
+
<td>Parallel dispatch with shared cache</td>
|
|
284
215
|
<td>Subagents + Teams</td>
|
|
285
|
-
<td>Subagents + Fleet</td>
|
|
286
216
|
<td>Multi-agent v2</td>
|
|
287
217
|
<td>Single</td>
|
|
288
218
|
</tr>
|
|
289
219
|
<tr>
|
|
290
|
-
<td><strong>Multi-tab</strong></td>
|
|
291
|
-
<td>Per-tab models, file claims, cross-tab git coordination</td>
|
|
292
|
-
<td>-</td>
|
|
293
|
-
<td>-</td>
|
|
294
|
-
<td>-</td>
|
|
295
|
-
<td>-</td>
|
|
296
|
-
</tr>
|
|
297
|
-
<tr>
|
|
298
|
-
<td><strong>Task routing</strong></td>
|
|
299
|
-
<td>Per-task model (spark, ember, web search, verify, desloppify, compact)</td>
|
|
300
|
-
<td>Single model</td>
|
|
301
|
-
<td>Single model</td>
|
|
302
|
-
<td>Per-agent model</td>
|
|
303
|
-
<td>Single model</td>
|
|
304
|
-
</tr>
|
|
305
|
-
<tr>
|
|
306
|
-
<td><strong>Compound tools</strong></td>
|
|
307
|
-
<td><code>read</code> batch+surgical, <code>multi_edit</code> atomic, <code>rename_symbol</code>, <code>move_symbol</code>, <code>refactor</code>, <code>project</code></td>
|
|
308
|
-
<td>Rename via LSP</td>
|
|
309
|
-
<td>-</td>
|
|
310
|
-
<td>-</td>
|
|
311
|
-
<td>-</td>
|
|
312
|
-
</tr>
|
|
313
|
-
<tr>
|
|
314
|
-
<td><strong>MCP support</strong></td>
|
|
315
|
-
<td>Built-in: stdio, HTTP, SSE. Auto-reconnect, namespaced tools</td>
|
|
316
|
-
<td>MCP client</td>
|
|
317
|
-
<td>MCP client</td>
|
|
318
|
-
<td>MCP-based</td>
|
|
319
|
-
<td>-</td>
|
|
320
|
-
</tr>
|
|
321
|
-
<tr>
|
|
322
220
|
<td><strong>Editor</strong></td>
|
|
323
|
-
<td>Embedded Neovim (your config
|
|
324
|
-
<td>No</td>
|
|
221
|
+
<td>Embedded Neovim (your config)</td>
|
|
325
222
|
<td>No</td>
|
|
326
223
|
<td>No</td>
|
|
327
224
|
<td>No</td>
|
|
328
225
|
</tr>
|
|
329
226
|
<tr>
|
|
330
227
|
<td><strong>Providers</strong></td>
|
|
331
|
-
<td>
|
|
228
|
+
<td>20 + custom</td>
|
|
332
229
|
<td>Anthropic only</td>
|
|
333
|
-
<td>Multi-model</td>
|
|
334
230
|
<td>OpenAI only</td>
|
|
335
231
|
<td>100+ LLMs</td>
|
|
336
232
|
</tr>
|
|
@@ -338,272 +234,39 @@ brew install ffmpeg chafa yt-dlp
|
|
|
338
234
|
<td><strong>License</strong></td>
|
|
339
235
|
<td>BSL 1.1</td>
|
|
340
236
|
<td>Proprietary</td>
|
|
341
|
-
<td>Proprietary</td>
|
|
342
237
|
<td>Apache 2.0</td>
|
|
343
238
|
<td>Apache 2.0</td>
|
|
344
239
|
</tr>
|
|
345
240
|
</tbody>
|
|
346
241
|
</table>
|
|
347
242
|
|
|
348
|
-
<sub>Verified
|
|
349
|
-
|
|
350
|
-
<img src="assets/separator.svg" width="100%" height="8" />
|
|
351
|
-
|
|
352
|
-
## Installation
|
|
353
|
-
|
|
354
|
-
macOS and Linux. First launch checks for prerequisites and offers to install Neovim and Nerd Fonts.
|
|
355
|
-
|
|
356
|
-
### Homebrew (recommended)
|
|
357
|
-
|
|
358
|
-
```bash
|
|
359
|
-
brew tap proxysoul/tap
|
|
360
|
-
brew install soulforge
|
|
361
|
-
```
|
|
362
|
-
|
|
363
|
-
<details>
|
|
364
|
-
<summary><strong>Bun (global)</strong></summary>
|
|
365
|
-
<br/>
|
|
366
|
-
|
|
367
|
-
```bash
|
|
368
|
-
curl -fsSL https://bun.sh/install | bash
|
|
369
|
-
bun install -g @proxysoul/soulforge
|
|
370
|
-
soulforge
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
</details>
|
|
374
|
-
|
|
375
|
-
<details>
|
|
376
|
-
<summary><strong>Prebuilt binary</strong></summary>
|
|
377
|
-
<br/>
|
|
378
|
-
|
|
379
|
-
Download from [Releases](https://github.com/ProxySoul/soulforge/releases/latest):
|
|
380
|
-
|
|
381
|
-
```bash
|
|
382
|
-
tar xzf soulforge-*.tar.gz && cd soulforge-*/ && ./install.sh
|
|
383
|
-
```
|
|
384
|
-
|
|
385
|
-
Installs to `~/.soulforge/`, adds to PATH.
|
|
243
|
+
<sub>Verified April 2026. <a href="https://github.com/ProxySoul/soulforge/issues">Report inaccuracies.</a></sub>
|
|
386
244
|
|
|
387
|
-
</details>
|
|
388
|
-
|
|
389
|
-
<details>
|
|
390
|
-
<summary><strong>Self-contained bundle</strong></summary>
|
|
391
|
-
<br/>
|
|
392
|
-
|
|
393
|
-
Ships Neovim 0.11, ripgrep, fd, lazygit, tree-sitter grammars, Nerd Font symbols. Zero system deps.
|
|
394
|
-
|
|
395
|
-
```bash
|
|
396
|
-
git clone https://github.com/ProxySoul/soulforge.git && cd soulforge && bun install
|
|
397
|
-
./scripts/bundle.sh # macOS ARM64
|
|
398
|
-
./scripts/bundle.sh x64 # Intel Mac
|
|
399
|
-
./scripts/bundle.sh x64 linux # Linux x64
|
|
400
|
-
./scripts/bundle.sh x64-baseline linux # Linux x64 (older CPUs)
|
|
401
|
-
./scripts/bundle.sh arm64 linux # Linux ARM64
|
|
402
|
-
cd dist/bundle/soulforge-*/ && ./install.sh
|
|
403
|
-
```
|
|
404
|
-
|
|
405
|
-
</details>
|
|
406
|
-
|
|
407
|
-
<details>
|
|
408
|
-
<summary><strong>Build from source</strong></summary>
|
|
409
|
-
<br/>
|
|
410
|
-
|
|
411
|
-
Requires [Bun](https://bun.sh) >= 1.0 and [Neovim](https://neovim.io) >= 0.11.
|
|
412
|
-
|
|
413
|
-
```bash
|
|
414
|
-
git clone https://github.com/ProxySoul/soulforge.git && cd soulforge && bun install
|
|
415
|
-
bun run dev # development mode
|
|
416
|
-
# or
|
|
417
|
-
bun run build && bun link && soulforge
|
|
418
|
-
```
|
|
419
|
-
|
|
420
|
-
</details>
|
|
421
|
-
|
|
422
|
-
### Quick start
|
|
423
|
-
|
|
424
|
-
```bash
|
|
425
|
-
soulforge # launch, pick a model with Ctrl+L
|
|
426
|
-
soulforge --set-key anthropic sk-ant-... # save a key
|
|
427
|
-
soulforge --headless "your prompt here" # non-interactive
|
|
428
|
-
```
|
|
429
|
-
|
|
430
|
-
See [GETTING_STARTED.md](GETTING_STARTED.md) for a full walkthrough.
|
|
431
245
|
|
|
432
246
|
<img src="assets/separator.svg" width="100%" height="8" />
|
|
433
247
|
|
|
434
|
-
##
|
|
248
|
+
## 20 providers
|
|
435
249
|
|
|
436
|
-
|
|
437
|
-
soulforge # TUI
|
|
438
|
-
soulforge --headless "prompt" # stream to stdout
|
|
439
|
-
soulforge --headless --json "prompt" # structured JSON
|
|
440
|
-
soulforge --headless --chat # multi-turn
|
|
441
|
-
soulforge --headless --model provider/model # override model
|
|
442
|
-
soulforge --headless --mode architect # read-only
|
|
443
|
-
soulforge --headless --diff "fix the bug" # show changed files
|
|
444
|
-
```
|
|
250
|
+
Anthropic ยท OpenAI ยท Google ยท xAI ยท Groq ยท DeepSeek ยท Mistral ยท Bedrock ยท Fireworks ยท MiniMax ยท Codex ยท Copilot ยท GitHub Models ยท Ollama ยท LM Studio ยท OpenRouter ยท LLM Gateway ยท Vercel AI Gateway ยท Proxy ยท **any OpenAI-compatible API**
|
|
445
251
|
|
|
446
|
-
|
|
447
|
-
<thead><tr><th width="140">Mode</th><th>What it does</th></tr></thead>
|
|
448
|
-
<tbody>
|
|
449
|
-
<tr><td><code>default</code></td><td>Full agent, all tools</td></tr>
|
|
450
|
-
<tr><td><code>auto</code></td><td>Executes immediately, no questions</td></tr>
|
|
451
|
-
<tr><td><code>architect</code></td><td>Read-only analysis and review</td></tr>
|
|
452
|
-
<tr><td><code>socratic</code></td><td>Guided learning through questions</td></tr>
|
|
453
|
-
<tr><td><code>challenge</code></td><td>Pushes back on assumptions</td></tr>
|
|
454
|
-
<tr><td><code>plan</code></td><td>Planning only, no code changes</td></tr>
|
|
455
|
-
</tbody>
|
|
456
|
-
</table>
|
|
252
|
+
Set a key and go: `soulforge --set-key anthropic sk-ant-...` or `export ANTHROPIC_API_KEY=sk-ant-...`
|
|
457
253
|
|
|
458
|
-
[
|
|
459
|
-
|
|
460
|
-
<img src="assets/separator.svg" width="100%" height="8" />
|
|
461
|
-
|
|
462
|
-
## Providers
|
|
463
|
-
|
|
464
|
-
<table>
|
|
465
|
-
<thead><tr><th width="200">Provider</th><th>Setup</th></tr></thead>
|
|
466
|
-
<tbody>
|
|
467
|
-
<tr><td><a href="https://llmgateway.io/?ref=6tjJR2H3X4E9RmVQiQwK"><strong>LLM Gateway</strong></a></td><td><code>LLM_GATEWAY_API_KEY</code></td></tr>
|
|
468
|
-
<tr><td><a href="https://console.anthropic.com/"><strong>Anthropic</strong></a></td><td><code>ANTHROPIC_API_KEY</code></td></tr>
|
|
469
|
-
<tr><td><a href="https://platform.openai.com/"><strong>OpenAI</strong></a></td><td><code>OPENAI_API_KEY</code></td></tr>
|
|
470
|
-
<tr><td><a href="https://aistudio.google.com/"><strong>Google</strong></a></td><td><code>GOOGLE_GENERATIVE_AI_API_KEY</code></td></tr>
|
|
471
|
-
<tr><td><a href="https://console.x.ai/"><strong>xAI</strong></a></td><td><code>XAI_API_KEY</code></td></tr>
|
|
472
|
-
<tr><td><a href="https://console.groq.com/"><strong>Groq</strong></a></td><td><code>GROQ_API_KEY</code></td></tr>
|
|
473
|
-
<tr><td><a href="https://platform.deepseek.com/"><strong>DeepSeek</strong></a></td><td><code>DEEPSEEK_API_KEY</code></td></tr>
|
|
474
|
-
<tr><td><a href="https://console.mistral.ai/"><strong>Mistral</strong></a></td><td><code>MISTRAL_API_KEY</code></td></tr>
|
|
475
|
-
<tr><td><a href="https://aws.amazon.com/bedrock/"><strong>Amazon Bedrock</strong></a></td><td><code>AWS_ACCESS_KEY_ID</code> + <code>AWS_SECRET_ACCESS_KEY</code> + <code>AWS_REGION</code></td></tr>
|
|
476
|
-
<tr><td><a href="https://fireworks.ai/"><strong>Fireworks</strong></a></td><td><code>FIREWORKS_API_KEY</code></td></tr>
|
|
477
|
-
<tr><td><a href="https://platform.minimaxi.com/"><strong>MiniMax</strong></a></td><td><code>MINIMAX_API_KEY</code></td></tr>
|
|
478
|
-
<tr><td><a href="https://github.com/features/copilot"><strong>GitHub Copilot</strong></a></td><td>OAuth token from IDE (<a href="docs/copilot-provider.md">setup</a>)</td></tr>
|
|
479
|
-
<tr><td><a href="https://github.com/marketplace/models"><strong>GitHub Models</strong></a></td><td><code>GITHUB_MODELS_API_KEY</code> (PAT with <code>models:read</code>)</td></tr>
|
|
480
|
-
<tr><td><a href="https://ollama.ai"><strong>Ollama</strong></a></td><td>Auto-detected</td></tr>
|
|
481
|
-
<tr><td><a href="https://lmstudio.ai"><strong>LM Studio</strong></a></td><td>Auto-detected</td></tr>
|
|
482
|
-
<tr><td><a href="https://openrouter.ai"><strong>OpenRouter</strong></a></td><td><code>OPENROUTER_API_KEY</code></td></tr>
|
|
483
|
-
<tr><td><a href="https://vercel.com/ai-gateway"><strong>Vercel AI Gateway</strong></a></td><td><code>AI_GATEWAY_API_KEY</code></td></tr>
|
|
484
|
-
<tr><td><a href="https://github.com/router-for-me/CLIProxyAPI"><strong>Proxy</strong></a></td><td><code>PROXY_API_KEY</code></td></tr>
|
|
485
|
-
<tr><td><strong>Custom</strong></td><td>Any OpenAI-compatible API</td></tr>
|
|
486
|
-
</tbody>
|
|
487
|
-
</table>
|
|
488
|
-
|
|
489
|
-
<details>
|
|
490
|
-
<summary><strong>Provider notes</strong></summary>
|
|
491
|
-
<br/>
|
|
492
|
-
|
|
493
|
-
**Amazon Bedrock** uses AWS IAM credentials. Set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` (defaults `us-east-1`). Supports `AWS_SESSION_TOKEN` for temporary creds.
|
|
494
|
-
|
|
495
|
-
**GitHub Copilot**: sign in via IDE, copy `oauth_token` from `~/.config/github-copilot/apps.json`, save with `/keys` or `--set-key copilot`. [Full guide](docs/copilot-provider.md).
|
|
496
|
-
|
|
497
|
-
**GitHub Models**: free playground API, per-token billing. Fine-grained PAT with `models:read`. Lower rate limits than Copilot.
|
|
498
|
-
|
|
499
|
-
**Ollama**: auto-detected at `localhost:11434`. Override with `OLLAMA_HOST`.
|
|
500
|
-
|
|
501
|
-
**LM Studio**: auto-detected at `localhost:1234`. Override with `LM_STUDIO_URL`. Optional auth via `LM_API_TOKEN`.
|
|
502
|
-
|
|
503
|
-
</details>
|
|
504
|
-
|
|
505
|
-
Custom providers via config:
|
|
506
|
-
|
|
507
|
-
```json
|
|
508
|
-
{
|
|
509
|
-
"providers": [{
|
|
510
|
-
"id": "my-provider",
|
|
511
|
-
"name": "My Provider",
|
|
512
|
-
"baseURL": "https://api.example.com/v1",
|
|
513
|
-
"envVar": "MY_PROVIDER_API_KEY",
|
|
514
|
-
"models": ["model-a", "model-b"]
|
|
515
|
-
}]
|
|
516
|
-
}
|
|
517
|
-
```
|
|
518
|
-
|
|
519
|
-
[Custom providers](docs/headless.md#custom-providers) / [Provider options](docs/provider-options.md)
|
|
520
|
-
|
|
521
|
-
<img src="assets/separator.svg" width="100%" height="8" />
|
|
522
|
-
|
|
523
|
-
## Configuration
|
|
524
|
-
|
|
525
|
-
Layered: global (`~/.soulforge/config.json`) + project (`.soulforge/config.json`).
|
|
526
|
-
|
|
527
|
-
```json
|
|
528
|
-
{
|
|
529
|
-
"defaultModel": "anthropic/claude-sonnet-4-6",
|
|
530
|
-
"thinking": { "mode": "adaptive" },
|
|
531
|
-
"repoMap": true,
|
|
532
|
-
"taskRouter": {
|
|
533
|
-
"spark": "anthropic/claude-sonnet-4-6",
|
|
534
|
-
"ember": "anthropic/claude-opus-4-6",
|
|
535
|
-
"webSearch": "anthropic/claude-haiku-4-5",
|
|
536
|
-
"desloppify": "anthropic/claude-haiku-4-5",
|
|
537
|
-
"compact": "google/gemini-2.0-flash"
|
|
538
|
-
},
|
|
539
|
-
"instructionFiles": ["soulforge", "claude", "cursorrules"]
|
|
540
|
-
}
|
|
541
|
-
```
|
|
542
|
-
|
|
543
|
-
Drop a `SOULFORGE.md` in your project root for conventions, architecture notes, preferences. Also reads `CLAUDE.md`, `.cursorrules`, `AGENTS.md`. Toggle via `/instructions`.
|
|
544
|
-
|
|
545
|
-
See [GETTING_STARTED.md](GETTING_STARTED.md) for the full config reference.
|
|
254
|
+
[Provider setup guide](docs/headless.md#provider-management) ยท [Custom providers](docs/headless.md#custom-providers)
|
|
546
255
|
|
|
547
256
|
<img src="assets/separator.svg" width="100%" height="8" />
|
|
548
257
|
|
|
549
258
|
## Documentation
|
|
550
259
|
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
<tr><td><a href="docs/project-tool.md">Project Tool</a></td><td>25+ ecosystems, pre-commit checks, monorepo discovery</td></tr>
|
|
562
|
-
<tr><td><a href="docs/mcp.md">MCP Servers</a></td><td>Model Context Protocol integration, transports, configuration, lifecycle</td></tr>
|
|
563
|
-
<tr><td><a href="docs/compaction.md#mempalace-integration">MemPalace</a></td><td>Persistent memory via <a href="https://github.com/milla-jovovich/mempalace">MemPalace</a>. Compaction auto-saves to knowledge graph, agent diary, semantic search</td></tr>
|
|
564
|
-
<tr><td><a href="docs/commands-reference.md">Commands</a></td><td>All 86 slash commands</td></tr>
|
|
565
|
-
<tr><td colspan="2"><strong>Usage</strong></td></tr>
|
|
566
|
-
<tr><td><a href="docs/headless.md">Headless Mode</a></td><td>CLI flags, JSON/JSONL output, CI/CD integration</td></tr>
|
|
567
|
-
<tr><td><a href="docs/steering.md">Steering</a></td><td>Mid-stream user input</td></tr>
|
|
568
|
-
<tr><td><a href="docs/cross-tab-coordination.md">Cross-Tab Coordination</a></td><td>Multi-tab file claims, git coordination</td></tr>
|
|
569
|
-
<tr><td colspan="2"><strong>Config</strong></td></tr>
|
|
570
|
-
<tr><td><a href="docs/provider-options.md">Provider Options</a></td><td>Thinking modes, context management</td></tr>
|
|
571
|
-
<tr><td><a href="docs/themes.md">Themes</a></td><td>24 themes, custom themes, hot reload</td></tr>
|
|
572
|
-
<tr><td><a href="docs/prompt-system.md">Prompt System</a></td><td>Per-family prompts, mode overlays</td></tr>
|
|
573
|
-
<tr><td><a href="docs/copilot-provider.md">Copilot Provider</a></td><td>Setup, legal review</td></tr>
|
|
574
|
-
<tr><td colspan="2"><strong>Start</strong></td></tr>
|
|
575
|
-
<tr><td><a href="GETTING_STARTED.md">Getting Started</a></td><td>First launch walkthrough</td></tr>
|
|
576
|
-
<tr><td><a href="CONTRIBUTING.md">Contributing</a></td><td>Dev setup, PR guidelines</td></tr>
|
|
577
|
-
</tbody>
|
|
578
|
-
</table>
|
|
579
|
-
|
|
580
|
-
<img src="assets/separator.svg" width="100%" height="8" />
|
|
581
|
-
|
|
582
|
-
## Roadmap
|
|
583
|
-
|
|
584
|
-
Extracting the intelligence layer into reusable packages:
|
|
585
|
-
|
|
586
|
-
- **`@soulforge/intelligence`** : graph intelligence, tools, agent orchestration as a library
|
|
587
|
-
- **`@soulforge/mcp`** : Soul Map tools as MCP servers for Claude Code, Cursor, Copilot, any MCP client
|
|
588
|
-
- **`sf --headless`** : shipped. [Docs](docs/headless.md)
|
|
589
|
-
- **MCP servers** : shipped. Connect to any MCP server. [Docs](docs/mcp.md)
|
|
590
|
-
|
|
591
|
-
<table>
|
|
592
|
-
<thead><tr><th width="120">Status</th><th>Item</th></tr></thead>
|
|
593
|
-
<tbody>
|
|
594
|
-
<tr><td><strong>In progress</strong></td><td>Repo map visualization, GitHub CLI integration, dispatch worktrees, <a href="https://agentclientprotocol.com/">ACP</a></td></tr>
|
|
595
|
-
<tr><td><strong>Planned</strong></td><td>Monorepo graph support, benchmarks, orchestrated workflows (planner > TDD > reviewer > security)</td></tr>
|
|
596
|
-
</tbody>
|
|
597
|
-
</table>
|
|
598
|
-
|
|
599
|
-
<img src="assets/separator.svg" width="100%" height="8" />
|
|
600
|
-
|
|
601
|
-
## Inspirations
|
|
602
|
-
|
|
603
|
-
- **[Aider](https://github.com/Aider-AI/aider)** : tree-sitter repo maps with PageRank. SoulForge adds cochange, blast radius, clone detection, live updates.
|
|
604
|
-
- **[Everything Claude Code](https://github.com/affaan-m/everything-claude-code)** : enforce behavior with code, not prompts.
|
|
605
|
-
- **[Vercel AI SDK](https://sdk.vercel.ai)** : multi-provider abstraction.
|
|
606
|
-
- **[Neovim](https://neovim.io)** : embedded via msgpack-RPC. Your config and muscle memory intact.
|
|
260
|
+
| | |
|
|
261
|
+
|---|---|
|
|
262
|
+
| **[Architecture](docs/architecture.md)** | System overview, agent tiers, intelligence router |
|
|
263
|
+
| **[Repo Map](docs/repo-map.md)** | Graph ranking, co-change analysis, blast radius |
|
|
264
|
+
| **[Commands](docs/commands-reference.md)** | All 100 slash commands |
|
|
265
|
+
| **[Headless Mode](docs/headless.md)** | CLI flags, JSON output, CI/CD |
|
|
266
|
+
| **[Configuration](docs/README.md)** | Config files, task router, custom providers |
|
|
267
|
+
| **[Themes](docs/themes.md)** | 24 themes, custom themes, hot reload |
|
|
268
|
+
| **[MCP Servers](docs/mcp.md)** | Model Context Protocol integration |
|
|
269
|
+
| **[Copilot Provider](docs/copilot-provider.md)** | Setup and legal review |
|
|
607
270
|
|
|
608
271
|
<img src="assets/separator.svg" width="100%" height="8" />
|
|
609
272
|
|
|
@@ -614,5 +277,5 @@ Extracting the intelligence layer into reusable packages:
|
|
|
614
277
|
<br/>
|
|
615
278
|
|
|
616
279
|
<div align="center">
|
|
617
|
-
<sub>Built by <a href="https://github.com/proxysoul">proxySoul</a></sub>
|
|
280
|
+
<sub>Open-sourced March 30, 2026. Built by <a href="https://github.com/proxysoul">proxySoul</a></sub>
|
|
618
281
|
</div>
|