Skip to main content

​
5-minute setup

1

Install SoulForge

# macOS (Apple Silicon)
curl -fsSL https://github.com/ProxySoul/soulforge/releases/latest/download/soulforge-darwin-arm64.tar.gz | tar xz
sudo mv soulforge-darwin-arm64 /usr/local/bin/soulforge
Or via Homebrew: brew tap proxysoul/tap && brew install soulforgeSee Installation for all methods.
2

Set an API key

export ANTHROPIC_API_KEY=sk-ant-...
# Or use --set-key to save to your OS keychain:
soulforge --set-key anthropic sk-ant-...
3

Launch and select a model

soulforge
On first launch, SoulForge checks for Neovim and Nerd Fonts and offers to install them if missing. Press Ctrl+L to open the model picker. Claude Sonnet 4 is a good default.
4

Send your first prompt

Type a message in the input box and press Enter:
> explain the project structure
SoulForge scans your codebase on startup (repo map), so the AI already understands your file layout, imports, and key symbols.
5

Explore features

  • Open the editor: Ctrl+E to toggle the embedded Neovim panel
  • Git menu: Ctrl+G for commit, push, pull, stash
  • Browse commands: Type / or press Ctrl+K for the command palette
  • Switch modes: Ctrl+D to cycle through default, auto, architect, socratic, challenge
  • Plan mode: /plan refactor the auth module for research-first structured planning
  • Skills: Ctrl+S to browse and install community skills

​
Key shortcuts

KeyAction
Ctrl+LSelect LLM model
Ctrl+EToggle editor panel
Ctrl+GGit menu
Ctrl+KCommand palette
Ctrl+SSkills browser
Ctrl+TNew tab
Ctrl+WClose tab
Ctrl+DCycle forge mode
Ctrl+XAbort generation

​
The interface

+-------------------------------------------------+
|  SoulForge | tokens | context | git | model     |  <- header
|                                                 |
|  Chat messages appear here                      |  <- chat area
|  Tool calls show in real time                   |
|                                                 |
|  > type here...                                 |  <- input
|  ^X Stop  ^D Mode  ^E Editor  ^G Git  ^L LLM   |  <- footer
+-------------------------------------------------+
Header shows token usage, context budget, git branch, and active model. Chat area renders messages with markdown, syntax-highlighted code blocks, and live tool call progress. Input box accepts natural language or slash commands (type / to see them).

​
Task router

Use /router to assign different models to different tasks:
SlotModelPurpose
PlanningOpusArchitecture decisions
CodingSonnetFile edits
ExplorationHaikuRead-only research
Web SearchHaikuSearch queries
TrivialHaikuSmall tasks

​
Headless mode

Run SoulForge without the TUI for scripting and CI/CD: 
# Inline prompt
soulforge --headless "explain the auth middleware"

# JSON output
soulforge --headless --json "list all TODO comments"

# Event stream
soulforge --headless --events "refactor the store"

# Interactive chat
soulforge --headless --chat
See Headless mode for the full reference.

​
Next steps