@proxysoul/soulforge 2.0.0 → 2.1.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.
Files changed (5) hide show
  1. package/README.md +48 -62
  2. package/dist/index.js +24177 -14916
  3. package/dist/workers/intelligence.worker.js +24 -4
  4. package/dist/workers/io.worker.js +35 -10
  5. package/package.json +9 -8
package/README.md CHANGED
@@ -1,3 +1,7 @@
1
+ <p align="center">
2
+ <a href="https://paypal.me/waeru"><img src="https://img.shields.io/badge/%E2%9A%94%EF%B8%8F_Fuel_the_Forge-PayPal-9B30FF.svg?style=for-the-badge&logo=paypal&logoColor=white" alt="Fuel the Forge" /></a>
3
+ </p>
4
+
1
5
  <h1 align="center">SoulForge</h1>
2
6
 
3
7
  <p align="center">
@@ -13,9 +17,6 @@
13
17
  <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f472b6.svg" alt="Bun" /></a>
14
18
  </p>
15
19
 
16
- <p align="center">
17
- <em>Built by <a href="https://github.com/proxysoul">proxySoul</a></em>
18
- </p>
19
20
 
20
21
  <p align="center">
21
22
  <img src="assets/main-1.png" alt="SoulForge — Graph-Powered Code Intelligence" width="900" />
@@ -23,6 +24,21 @@
23
24
 
24
25
  ---
25
26
 
27
+ ## Table of Contents
28
+
29
+ - [Why SoulForge?](#why-soulforge)
30
+ - [How it compares](#how-it-compares)
31
+ - [Installation](#installation)
32
+ - [Usage](#usage)
33
+ - [Providers](#providers)
34
+ - [Configuration](#configuration)
35
+ - [Documentation](#documentation)
36
+ - [Roadmap](#roadmap)
37
+ - [Inspirations](#inspirations)
38
+ - [License](#license)
39
+
40
+ ---
41
+
26
42
  ## Why SoulForge?
27
43
 
28
44
  Every AI coding tool starts blind. The agent reads files, greps around, slowly pieces together what your codebase looks like. You're paying for the agent to figure out what you already know.
@@ -33,67 +49,20 @@ SoulForge doesn't work that way. On startup, it builds a **live dependency graph
33
49
 
34
50
  | | |
35
51
  |---|---|
36
- | **Live Soul Map** | The agent already knows where every symbol lives, what imports what, and which files are most important. No wasted tokens reading files just to orient itself. |
37
- | **Surgical reads** | Instead of reading entire files, the agent pulls exactly the function or class it needs by name. A 500-line file becomes a 20-line symbol extraction. The Soul Map provides line numbers and signatures, so the agent always knows precisely what to ask for. |
38
- | **Zero-cost compaction** | When conversations get long, SoulForge compacts context by replaying structured state it already tracked (files touched, decisions made, errors hit) without making an LLM call. Other tools spend thousands of tokens summarizing. SoulForge does it for free. |
39
- | **Shared agent cache** | When multiple agents work in parallel, the first one to read a large file caches it. Others get a compact stub with symbol names and line ranges instead of the full content. Hundreds of lines become four. |
52
+ | **[Live Soul Map](docs/repo-map.md)** | A SQLite-backed graph of every file, symbol, import, and export — ranked by PageRank, enriched with git co-change history, updated in real-time. The agent already knows where everything lives and how far an edit will ripple. No wasted tokens orienting itself. |
53
+ | **[Surgical reads](docs/architecture.md)** | Instead of reading entire files, the agent extracts exactly the function or class it needs by name via a 4-tier intelligence chain (LSP → ts-morph → tree-sitter → regex) across 30 languages. A 500-line file becomes a 20-line symbol extraction. |
54
+ | **[Zero-cost compaction](docs/compaction.md)** | State extraction runs as the conversation happens: files touched, decisions made, errors hit. When context gets long, it compacts instantly from this pre-built state. No LLM call, no latency, no cost. |
55
+ | **[Multi-agent dispatch](docs/agent-bus.md)** | Parallelize work across explore, code, and web search agents. The first agent to read a large file caches it — others get a compact stub with symbol names and line ranges. Edit coordination prevents conflicts. |
56
+ | **[Multi-tab coordination](docs/cross-tab-coordination.md)** | Run concurrent sessions with different models and modes per tab. Agents see what other tabs are editing, get warnings on contested files, and git operations coordinate automatically. |
57
+ | **[Compound tools](docs/compound-tools.md)** | `read` batches files in parallel with surgical extraction. `multi_edit` applies changes atomically. `rename_symbol`, `move_symbol`, `rename_file` are compiler-guaranteed and cross-file. `project` auto-detects lint/test/build across 23 ecosystems. |
40
58
  | **Mix-and-match models** | You choose which model handles which job. Put Opus on planning, Sonnet on coding, Haiku on search and cleanup. Or use one model for everything. The task router gives you full control. |
41
59
  | **Prompt caching** | The Soul Map is stable across turns, so it stays cached. On Anthropic, that means the bulk of the system prompt costs a fraction of what it would otherwise. |
42
60
 
43
- ---
44
-
45
- ## What makes SoulForge different
46
-
47
- <table>
48
- <tr>
49
- <td width="50%">
50
-
51
- ### Live Soul Map
52
- A SQLite-backed graph of your entire codebase: files, symbols, imports, exports. Ranked by PageRank, enriched with git co-change history, updated in real-time as you edit. The agent knows what's in your project, what depends on what, and where everything lives. Not a static snapshot. It evolves with your code. [Deep dive →](docs/repo-map.md)
53
-
54
- </td>
55
- <td width="50%">
56
-
57
- ### Surgical Reads
58
- The agent doesn't read whole files. It extracts exactly the function, class, or type it needs by name, powered by the Soul Map's symbol index and a 4-tier intelligence chain (LSP → ts-morph → tree-sitter → regex). A 500-line file becomes a 20-line read. Across 30 languages. [Deep dive →](docs/architecture.md)
59
-
60
- </td>
61
- </tr>
62
- <tr>
63
- <td>
64
-
65
- ### Multi-Agent Dispatch
66
- Parallelize work across explore, code, and web search agents. When one agent reads a large file, others get a compact stub with symbol names and line ranges instead of re-reading the full content. Edit coordination prevents conflicts. [Deep dive →](docs/agent-bus.md)
67
-
68
- </td>
69
- <td>
70
-
71
- ### Zero-Cost Compaction
72
- State extraction runs as the conversation happens: files touched, decisions made, errors hit. All tracked deterministically. When context gets long, it compacts instantly from this pre-built state. No LLM call, no latency, no cost. [Deep dive →](docs/compaction.md)
73
-
74
- </td>
75
- </tr>
76
- <tr>
77
- <td>
78
-
79
- ### Multi-Tab Coordination
80
- Run multiple sessions side by side with different models and modes per tab. Agents see what other tabs are editing, get warnings on contested files, and git operations coordinate across tabs automatically. [Deep dive →](docs/cross-tab-coordination.md)
81
-
82
- </td>
83
- <td>
84
-
85
- ### Compound Tools
86
- `read` batches multiple files in parallel with surgical symbol extraction. `multi_edit` applies multiple edits to a file atomically (all-or-nothing). `rename_symbol`, `move_symbol`, `rename_file`, `refactor` are compiler-guaranteed and cross-file. `project` auto-detects lint/test/build across 23 ecosystems. [Deep dive →](docs/compound-tools.md)
87
-
88
- </td>
89
- </tr>
90
- </table>
91
-
92
61
  ### And also
93
62
 
94
63
  - **Lock-in mode.** Hides agent narration during work, shows only tool activity and the final answer. Toggle via `/lock-in` or config.
95
64
  - **Embedded Neovim.** Your actual config, plugins, and LSP servers. The AI works through the same editor you use. [Deep dive →](docs/architecture.md)
96
- - **10 providers.** Anthropic, OpenAI, Google, xAI, Ollama, OpenRouter, LLM Gateway, Vercel AI Gateway, Proxy, and any OpenAI-compatible API. [Deep dive →](docs/provider-options.md)
65
+ - **12 providers.** Anthropic, OpenAI, Google, xAI, GitHub Copilot, GitHub Models, Ollama, OpenRouter, LLM Gateway, Vercel AI Gateway, Proxy, and any OpenAI-compatible API.
97
66
  - **Task router.** Assign different models to different jobs. Spark agents (explore/investigate) and ember agents (code edits) can each use different models. You pick what goes where. [Deep dive →](docs/architecture.md)
98
67
  - **Code execution (Smithy).** Sandboxed code execution via Anthropic's `code_execution` tool. The agent can run Python to process data, do calculations, or batch tool calls programmatically.
99
68
  - **User steering.** Type while the agent works. Messages queue up and reach the agent at the next step. [Deep dive →](docs/steering.md)
@@ -118,7 +87,7 @@ Run multiple sessions side by side with different models and modes per tab. Agen
118
87
  | **Task routing** | Per-task model assignment (spark, ember, web search, verify, desloppify, compact) | Single model | Single model | Per-agent model | Single model |
119
88
  | **Compound tools** | `read` (batch + surgical), `multi_edit` (atomic), `rename_symbol`, `move_symbol`, `rename_file`, `refactor`, `project` | Rename via LSP | — | — | — |
120
89
  | **Editor** | Embedded Neovim (your config, your plugins) | No editor | No editor | No editor | No editor |
121
- | **Providers** | 10 + custom OpenAI-compatible | Anthropic only | Multi-model | OpenAI only | 100+ LLMs |
90
+ | **Providers** | 12 + custom OpenAI-compatible | Anthropic only | Multi-model | OpenAI only | 100+ LLMs |
122
91
  | **License** | BSL 1.1 (source-available) | Proprietary | Proprietary | Apache 2.0 | Apache 2.0 |
123
92
 
124
93
  > *Competitor features verified as of March 29, 2026. [Let us know](https://github.com/ProxySoul/soulforge/issues) if something's changed.*
@@ -170,6 +139,7 @@ git clone https://github.com/ProxySoul/soulforge.git && cd soulforge && bun inst
170
139
  ./scripts/bundle.sh # macOS ARM64
171
140
  ./scripts/bundle.sh x64 # Intel Mac
172
141
  ./scripts/bundle.sh x64 linux # Linux x64
142
+ ./scripts/bundle.sh x64-baseline linux # Linux x64 (older CPUs without AVX)
173
143
  ./scripts/bundle.sh arm64 linux # Linux ARM64
174
144
  cd dist/bundle/soulforge-*/ && ./install.sh
175
145
  ```
@@ -214,9 +184,16 @@ soulforge --headless --mode architect # Read-only analysis
214
184
  soulforge --headless --diff "fix the bug" # Show changed files
215
185
  ```
216
186
 
217
- **Modes:** default (full agent), auto (no questions), architect (read-only), socratic, challenge, plan
187
+ | Mode | Description |
188
+ |------|-------------|
189
+ | `default` | Full agent with all tools |
190
+ | `auto` | Executes immediately, no questions |
191
+ | `architect` | Read-only analysis and review |
192
+ | `socratic` | Guided learning through questions |
193
+ | `challenge` | Pushes back on your assumptions |
194
+ | `plan` | Planning mode, no code changes |
218
195
 
219
- [Full CLI reference →](docs/headless.md) · [All 86 slash commands →](docs/commands-reference.md)
196
+ [Full CLI reference](docs/headless.md)
220
197
 
221
198
  ---
222
199
 
@@ -229,12 +206,18 @@ soulforge --headless --diff "fix the bug" # Show changed files
229
206
  | [**OpenAI**](https://platform.openai.com/) | `OPENAI_API_KEY` |
230
207
  | [**Google**](https://aistudio.google.com/) | `GOOGLE_GENERATIVE_AI_API_KEY` |
231
208
  | [**xAI**](https://console.x.ai/) | `XAI_API_KEY` |
209
+ | [**GitHub Copilot**](https://github.com/features/copilot) | OAuth token from IDE ([setup](docs/copilot-provider.md)) |
210
+ | [**GitHub Models**](https://github.com/marketplace/models) | `GITHUB_MODELS_API_KEY` (PAT with `models:read`) |
232
211
  | [**Ollama**](https://ollama.ai) | Auto-detected |
233
212
  | [**OpenRouter**](https://openrouter.ai) | `OPENROUTER_API_KEY` |
234
213
  | [**Vercel AI Gateway**](https://vercel.com/ai-gateway) | `AI_GATEWAY_API_KEY` |
235
214
  | [**Proxy**](https://github.com/router-for-me/CLIProxyAPI) | `PROXY_API_KEY` |
236
215
  | **Custom** | Any OpenAI-compatible API |
237
216
 
217
+ **GitHub Copilot**: Sign in via your IDE (VS Code, JetBrains), copy `oauth_token` from `~/.config/github-copilot/apps.json`, save with `/keys` or `--set-key copilot`. [Full setup guide](docs/copilot-provider.md).
218
+
219
+ **GitHub Models**: Free playground API with per-token billing. Create a fine-grained PAT with `models:read` scope. Lower rate limits than Copilot.
220
+
238
221
  Add custom providers in config, no code changes:
239
222
 
240
223
  ```json
@@ -249,7 +232,7 @@ Add custom providers in config, no code changes:
249
232
  }
250
233
  ```
251
234
 
252
- [Provider options →](docs/provider-options.md) · [Custom providers →](docs/headless.md#custom-providers)
235
+ [Custom providers](docs/headless.md#custom-providers) · [Provider options](docs/provider-options.md)
253
236
 
254
237
  ---
255
238
 
@@ -293,6 +276,9 @@ See [GETTING_STARTED.md](GETTING_STARTED.md) for the full config reference.
293
276
  | [Commands](docs/commands-reference.md) | All 86 slash commands |
294
277
  | [Steering](docs/steering.md) | Mid-stream user input |
295
278
  | [Provider Options](docs/provider-options.md) | Thinking modes, context management |
279
+ | [Copilot Provider](docs/copilot-provider.md) | Setup, legal review |
280
+ | [Cross-Tab Coordination](docs/cross-tab-coordination.md) | Multi-tab file claims, git coordination |
281
+ | [Themes](docs/themes.md) | 24 themes, custom themes, hot reload |
296
282
  | [Prompt System](docs/prompt-system.md) | Per-family prompts, mode overlays |
297
283
  | [Getting Started](GETTING_STARTED.md) | First launch walkthrough |
298
284
  | [Contributing](CONTRIBUTING.md) | Dev setup, PR guidelines |
@@ -317,7 +303,7 @@ The intelligence layer is being extracted into reusable packages:
317
303
 
318
304
  - **[Aider](https://github.com/Aider-AI/aider)**: tree-sitter repo maps with PageRank. SoulForge adds cochange analysis, blast radius, clone detection, and live updates.
319
305
  - **[Everything Claude Code](https://github.com/affaan-m/everything-claude-code)**: enforce behavior with code, not prompts. Our schema validation, pre-commit gates, and auto-enrichment patterns come from this thinking.
320
- - **[Vercel AI SDK](https://sdk.vercel.ai)**: the multi-provider abstraction that makes 10 providers possible.
306
+ - **[Vercel AI SDK](https://sdk.vercel.ai)**: the multi-provider abstraction that makes 12 providers possible.
321
307
  - **[Neovim](https://neovim.io)**: embedded via msgpack-RPC. Your config and muscle memory shouldn't be a compromise.
322
308
 
323
309
  ---