> ## 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.
# SoulForge
> Code-aware terminal AI that works with symbols, not strings.
Most AI coding tools treat your codebase as text. They grep, they paste, they match strings. SoulForge treats code as code. It parses every file on launch, builds a live dependency graph, and addresses your work by symbol and line number. Rename a class, move a function, change a return type, the agent uses AST surgery and LSP rename, not find-and-replace.
Symbol-addressed TypeScript and JavaScript edits via ts-morph. Roots in a 2022 Master's thesis on programmatic JS to TS conversion. Changing a return type costs a handful of tokens.
Workspace rename, definitions, references, call and type hierarchy, diagnostics, code actions, format. Mason installer for 576+ servers from the TUI.
V2 extracts structured state as the conversation happens. When context fills, serialization is instant. Typical sessions compact for free.
Per-model and per-subagent breakdown. Real prices for Claude, OpenAI, Gemini, DeepSeek, Groq, Mistral, Copilot, OpenRouter. Cache-aware. Zero for local models.
Up to 5 tabs per project, each with its own model, mode, session, and checkpoints. Tabs see each other's claimed files and active agents. Git hard-blocks during cross-tab dispatch, you never commit partial changes.
The agent reads a single function by name or jumps via LSP go-to-definition. It navigates the code graph instead of grepping and dumping whole files.
## Start in 60 seconds
```bash Homebrew theme={null}
brew tap proxysoul/tap && brew install soulforge
soulforge
```
```bash One key, every model theme={null}
soulforge --set-key llmgateway sk-...
soulforge
```
```bash Local, no key theme={null}
brew install ollama && ollama pull llama3.3
soulforge
```
Neovim is optional. A Nerd Font is optional. SoulForge prompts to install either on first launch if you want them.
Homebrew, binary, Bun, or source.
Your first five minutes.
Do I need Neovim? Which LLM? How much does it cost?
## Plain-English prompts, real tool calls
```
> rename UserService to AccountService
> move parseConfig from utils.ts to config/parser.ts
> change fetchUser to return Promise
> run tests, fix lint, commit
> research how auth handles refresh tokens
```
Every line above resolves to a single compound tool call. No multi-step orchestration. No guessing commands.
## Why it's different
SQLite graph of every file, symbol, and import. Ranked by PageRank and git co-change. Blast-radius tags show how far an edit ripples. Updates as you work.
65+ surgical operations via ts-morph. Toggle `async`, change a parameter, add a method, rename a class member. Atomic batches with rollback.
Definitions, references, rename, diagnostics, code actions, call and type hierarchy, format, hover. Install servers from Mason's registry inside the TUI (`/lsp install`). Works with or without Neovim open.
Extract one function by name. A 500-line file becomes 20 lines in the prompt. TypeScript, Python, Rust, Go, Java, Kotlin, Scala, Swift, C/C++, Ruby, PHP, Elixir, Zig, Lua, Dart, OCaml, Solidity, Vue, and more.
Live USD cost broken down by model and by subagent. Cache-aware pricing across Anthropic, OpenAI, Google, DeepSeek, Groq, Mistral, Fireworks, Copilot, OpenRouter, and GitHub Models.
Structured state extraction as you go — files touched, decisions, failures, tool results. Compaction serializes instantly and usually skips the LLM pass entirely.
Forge dispatches explore, code, and web-search agents in parallel. One agent's file read is cached for the others. Discoveries propagate across agents within a step.
Different model per task slot: spark for exploration, ember for code, compact for context, verify for review. Cheap work to cheap models. Mix providers freely.
Catppuccin, Dracula, Gruvbox, Tokyo Night, Rose Pine, Kanagawa, Nightfox, Cyberdream, Oxocarbon, and more. Hot-reloaded custom themes from a JSON file.
Every turn is a checkpoint with git tags for file rollback. Sessions save as JSONL; resume by short-id prefix. Undo conversation and files in one keystroke.
Ollama and LM Studio auto-detected. Run Llama, Qwen, DeepSeek, Mistral, whatever you have. Cost tracking skips local models automatically.
Browse, install, enable, disable community skills from the TUI (`Ctrl+S`). Skills resolve from project and global scopes, auto-loaded into the agent prompt.
Hearth exposes your running forge to Telegram or Discord. Approval prompts arrive as inline buttons. Your code never leaves your host. (Experimental — expect rough edges.)
## Providers
21 built-in LLM providers: Anthropic, OpenAI, Google, xAI, Groq, DeepSeek, Mistral, Bedrock, Fireworks, MiniMax, Codex, Copilot, GitHub Models, OpenRouter, OpenCode Zen, OpenCode Go, LLM Gateway, Vercel AI Gateway, Proxy (CLIProxyAPI relay), Ollama, LM Studio. Plus any OpenAI-compatible API via custom providers. See [all providers](/providers/overview).
## Ready?
`brew tap proxysoul/tap && brew install soulforge`
Common questions, short answers.
Need help? [Troubleshooting](/troubleshooting) · [Discord](https://discord.gg/fX4H7GYSMJ) · [GitHub issues](https://github.com/proxysoul/soulforge/issues) · [Blog](https://proxysoul.com/blog/soulforge).