Skip to main content
Can’t find your issue? Ask in the Discord or open a GitHub issue.

​
No models in the picker

Your API key isn’t set. Pick one: 
soulforge --set-key anthropic sk-ant-...
# or export it and restart your terminal:
export ANTHROPIC_API_KEY=sk-ant-...
Check what’s configured: 
soulforge --list-providers

​
Getting rate-limited (429)

Bump retry settings in ~/.soulforge/config.json: 
{
  "retry": {
    "maxAttempts": 5,
    "baseDelayMs": 3000
  }
}
Delays double each attempt. maxAttempts: 5 with baseDelayMs: 3000 gives ~3s, 6s, 12s, 24s, 48s between retries.

​
Icons show as boxes or ??

You don’t have a Nerd Font. Install one and set it as your terminal font. Or run /setup inside SoulForge to install one for you. If you can’t install fonts, disable the icons: 
/font nerd

​
LSP isn’t working

Open /lsp status. If your language server isn’t attached: 
/lsp install
Picks from the Mason registry and installs into ~/.soulforge/lsp-servers/. Restart SoulForge after installing.

​
Neovim not found

SoulForge needs Neovim >= 0.11. Run /setup to install it, or: 
brew install neovim        # macOS
sudo apt install neovim    # Debian/Ubuntu
sudo pacman -S neovim      # Arch
If nvim isn’t on your PATH, set nvimPath in ~/.soulforge/config.json.

​
Editor panel is garbled

Your terminal needs true color. Most modern terminals have it; some need: 
export COLORTERM=truecolor
in your shell profile.

​
Context is full / “too many tokens”

/compact
Runs compaction immediately. Or switch to a larger model (Ctrl+L). To compact automatically at a lower threshold, edit config: 
{
  "compaction": {
    "triggerThreshold": 0.6
  }
}

​
Copilot: 401 / token expired

Your Copilot token was rotated. Copy it again from your IDE: 
soulforge --set-key copilot $(jq -r '."github.com".oauth_token' \
  ~/.config/github-copilot/apps.json)
See Copilot setup for details.

​
Hearth: “daemon unreachable”

The daemon isn’t running: 
soulforge hearth start
Leave it running in a terminal (or install as a service with soulforge hearth install --now). Check with soulforge hearth doctor.

​
Hearth: bot isn’t responding

Run the diagnostic: 
soulforge hearth doctor
Common causes:
  • Token missing from keychain — re-run soulforge hearth login.
  • Chat not paired — run /hearth pair and DM the bot with the code.
  • Your identity isn’t in the allowlist — the daemon drops unknown senders silently.

​
Agent is slow

Switch to a faster model with Ctrl+L (Haiku, Flash, Ollama) or tune the task router — use a fast model for spark and compact, reserve the strong one for ember.

​
Forgot a session

soulforge --headless --chat            # browse by timestamp
Or open /session history inside SoulForge. Sessions live in ~/.soulforge/sessions/.

​
Windows: pasting an image does nothing

Ctrl+V with a screenshot on the clipboard may silently do nothing. Two separate causes on Windows:
  1. Windows Terminal eats the paste. Its bracketed-paste mode emits an empty sequence for image clipboards, so the image bytes never reach SoulForge. Embedded Neovim / Vim keymaps can also swallow Ctrl+V first.
  2. PowerShell can’t be reached. The clipboard read shells out to PowerShell; if neither powershell nor pwsh is on PATH, the read fails.
Try, in order:
  • Press Alt+V instead of Ctrl+V — it bypasses the bracketed-paste / Vim-keymap interception.
  • Make sure Windows PowerShell 5.1 is on PATH: C:\Windows\System32\WindowsPowerShell\v1.0.
  • Check /errors inside SoulForge — a failed clipboard read leaves a clipboard breadcrumb there.
If neither works (the Windows Terminal bug is upstream), save the screenshot to a file and reference the path — the agent reads it with soul_vision: 
look at C:\Users\me\Desktop\bug.png and tell me what's wrong
Drop this helper in your PowerShell profile to capture the clipboard image to a file in one command: 
function Save-ClipboardImage {
    param([string]$Path = "$env:TEMP\sf-paste.png")
    Add-Type -AssemblyName System.Windows.Forms, System.Drawing
    $img = [System.Windows.Forms.Clipboard]::GetImage()
    if ($img) {
        $img.Save($Path, [System.Drawing.Imaging.ImageFormat]::Png)
        Write-Host "Saved: $Path — paste this path into SoulForge."
    } else { Write-Host "No image on clipboard." }
}
Set-Alias cpimg Save-ClipboardImage -Force
Run cpimg, then reference the printed path in your prompt.

​
Windows: command not found after install

PATH updates don’t apply to the shell that ran the installer. Open a brand-new PowerShell or Windows Terminal window. If you used the portable ZIP, make sure the extract folder is on your PATH or call soulforge.exe by full path. The deps/ folder must stay next to soulforge.exe. See the Windows section of installation for the full feature matrix.

​
Still stuck?

  • GitHub Issues
  • Run /diagnose inside SoulForge for a health check — LSP, tree-sitter, semantic indexing, provider status.
  • /status shows the full system dashboard.