> ## Documentation Index
> Fetch the complete documentation index at: https://soulforge.proxysoul.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> A bird's-eye view of the SoulForge architecture.

SoulForge is three things talking to each other:

1. **A live code graph** — every file, symbol, and import, ranked by importance. Updated as you work.
2. **An agent loop** — reads, edits, tests, commits. Can dispatch parallel sub-agents.
3. **Your Neovim** — embedded. The agent edits through the same editor you use.

## The agents

| Agent         | Runs                                             | Model                  |
| ------------- | ------------------------------------------------ | ---------------------- |
| **Forge**     | The one talking to you. Orchestrates everything. | Your active model      |
| **⚡ Spark**   | Read-only research (grep, read, analyze).        | `taskRouter.spark`     |
| **🔥 Ember**  | Code edits and refactors. Own context window.    | `taskRouter.ember`     |
| **WebSearch** | Multi-step web research with citations.          | `taskRouter.webSearch` |

Configure which model each one uses in [the task router](/recipes/task-router).

## What the agents share

When Forge dispatches multiple sub-agents in parallel, they coordinate through a shared bus:

* **File cache** — first reader caches; others reuse.
* **Tool cache** — read-only tool results shared across agents and dispatches.
* **Edit lock** — concurrent writes to the same file are serialized.
* **Findings** — one agent's discovery reaches the others at their next step.

Result: N agents don't re-read the same files N times.

## Code intelligence, layered

Operations (go-to-definition, rename, diagnostics…) try the best backend first, fall back if it fails:

| Tier | Backend     | Used for                                     |
| ---- | ----------- | -------------------------------------------- |
| 1    | LSP         | precise types, workspace rename, diagnostics |
| 2    | ts-morph    | TypeScript/JavaScript AST ops                |
| 2    | tree-sitter | 33+ languages — outlines, imports            |
| 3    | regex       | universal fallback                           |

LSP runs via Neovim when the editor is open, via standalone servers otherwise. The agent always has it.

## System prompt

Every turn, the prompt is assembled from: mode, project info, git context, the Soul Map, your memory, forbidden files, active skills. The Soul Map (built by the repo-map engine) is personalized per-turn — files you just edited or referenced get boosted.

See [the Soul Map](/concepts/repo-map) for ranking details, [memory](/tools/memory) for cross-session knowledge, [compound tools](/concepts/compound-tools) for the one-call tools, [code intelligence](/concepts/intelligence) for the backend router.