singularity-forge/docs/user-docs/getting-started.md

Getting Started with SF

SF is an AI coding agent that handles planning, execution, verification, and shipping so you can focus on what to build. This guide walks you through installation on macOS, Windows, and Linux, then gets you running your first session.

---

Prerequisites

Requirement	Minimum	Recommended
Node.js	22.0.0	24 LTS
Git	2.20+	Latest
LLM API key	Any supported provider	Anthropic (Claude)

Don't have Node.js or Git yet? Follow the OS-specific instructions below.

---

Install by Operating System

macOS

Downloads: Node.js | Git | Homebrew

Step 1 — Install Homebrew (skip if you already have it):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 2 — Install Node.js and Git:

brew install node git

Step 3 — Verify dependencies are installed:

node --version   # should print v22.x or higher
git --version    # should print 2.20+

Step 4 — Install SF:

npm install -g sf-run

Step 5 — Set up your LLM provider:

# Option A: Set an environment variable (Anthropic recommended)
export ANTHROPIC_API_KEY="sk-ant-..."

# Option B: Use the built-in config wizard
sf config

To persist the key, add the export line to ~/.zshrc:

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

See Provider Setup Guide for all 20+ supported providers.

Step 6 — Launch SF:

cd ~/my-project   # navigate to any project
sf               # start a session

Step 7 — Verify everything works:

sf --version     # prints the installed version

Inside the session, type /model to confirm your LLM is connected.

Apple Silicon PATH fix: If sf isn't found after install, npm's global bin may not be in your PATH:

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

oh-my-zsh conflict: The oh-my-zsh git plugin defines alias sf='git svn dcommit'. Fix with unalias sf 2>/dev/null in ~/.zshrc, or use sf-cli instead.

---

Windows

Downloads: Node.js | Git for Windows | Windows Terminal

Option A: winget (recommended for Windows 10/11)

Step 1 — Install Node.js and Git:

winget install OpenJS.NodeJS.LTS
winget install Git.Git

Step 2 — Restart your terminal (close and reopen PowerShell or Windows Terminal).

Step 3 — Verify dependencies are installed:

node --version   # should print v22.x or higher
git --version    # should print 2.20+

Step 4 — Install SF:

npm install -g sf-run

Step 5 — Set up your LLM provider:

# Option A: Set an environment variable (current session)
$env:ANTHROPIC_API_KEY = "sk-ant-..."

# Option B: Use the built-in config wizard
sf config

To persist the key permanently, add it via System Settings > Environment Variables, or run:

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User")

See Provider Setup Guide for all 20+ supported providers.

Step 6 — Launch SF:

cd C:\Users\you\my-project   # navigate to any project
sf                           # start a session

Step 7 — Verify everything works:

sf --version     # prints the installed version

Inside the session, type /model to confirm your LLM is connected.

Option B: Manual install

1. Download and install Node.js LTS — check "Add to PATH" during setup
2. Download and install Git for Windows — use default options
3. Open a new terminal, then follow Steps 3-7 above

Windows tips:

• Use Windows Terminal or PowerShell for the best experience. Command Prompt works but has limited color support.
• If sf isn't recognized, restart your terminal. Windows needs a fresh terminal to pick up new PATH entries.
• WSL2 also works — install WSL, then follow the Linux instructions inside your distro.

---

Linux

Downloads: Node.js | Git | nvm

Pick your distro, then follow the steps.

Ubuntu / Debian

Step 1 — Install Node.js and Git:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs git

Fedora / RHEL / CentOS

Step 1 — Install Node.js and Git:

curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo dnf install -y nodejs git

Arch Linux

Step 1 — Install Node.js and Git:

sudo pacman -S nodejs npm git

Using nvm (any distro)

Step 1 — Install nvm, then Node.js:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc   # or ~/.zshrc
nvm install 24
nvm use 24

All distros: Steps 2-7

Step 2 — Verify dependencies are installed:

node --version   # should print v22.x or higher
git --version    # should print 2.20+

Step 3 — Install SF:

npm install -g sf-run

Step 4 — Set up your LLM provider:

# Option A: Set an environment variable (Anthropic recommended)
export ANTHROPIC_API_KEY="sk-ant-..."

# Option B: Use the built-in config wizard
sf config

To persist the key, add the export line to ~/.bashrc (or ~/.zshrc):

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc

See Provider Setup Guide for all 20+ supported providers.

Step 5 — Launch SF:

cd ~/my-project   # navigate to any project
sf               # start a session

Step 6 — Verify everything works:

sf --version     # prints the installed version

Inside the session, type /model to confirm your LLM is connected.

Permission errors on npm install -g? Don't use sudo npm. Fix npm's global directory instead:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g sf-run

---

Docker (any OS)

Downloads: Docker Desktop

Run SF in an isolated sandbox without installing Node.js on your host.

Step 1 — Install Docker Desktop (4.58+ required).

Step 2 — Clone the SF repo:

git clone https://github.com/singularity-forge/sf-run.git
cd sf-2/docker

Step 3 — Create and enter a sandbox:

docker sandbox create --template . --name sf-sandbox
docker sandbox exec -it sf-sandbox bash

Step 4 — Set your API key and run SF:

export ANTHROPIC_API_KEY="sk-ant-..."
sf auto "implement the feature described in issue #42"

See Docker Sandbox docs for full configuration, resource limits, and compose files.

---

After Installation

Choose a Model

SF auto-selects a default model after provider setup. Switch anytime inside a session:

/model

Or configure per-phase models in preferences — see Configuration.

---

Two Ways to Work

Step Mode — /sf

Type /sf inside a session. SF executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next.

• No .sf/ directory — starts a discussion flow to capture your project vision
• Milestone exists, no roadmap — discuss or research the milestone
• Roadmap exists, slices pending — plan the next slice or execute a task
• Mid-task — resume where you left off

Step mode keeps you in the loop, reviewing output between each step.

Auto Mode — /sf auto

Type /sf auto and walk away. SF autonomously researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete.

/sf auto

See Auto Mode for full details.

---

Recommended Workflow: Two Terminals

Run auto mode in one terminal, steer from another.

Terminal 1 — let it build:

sf
/sf auto

Terminal 2 — steer while it works:

sf
/sf discuss    # talk through architecture decisions
/sf status     # check progress
/sf queue      # queue the next milestone

Both terminals read and write the same .sf/ files. Decisions in terminal 2 are picked up at the next phase boundary automatically.

---

How SF Organizes Work

Milestone  →  a shippable version (4-10 slices)
  Slice    →  one demoable vertical capability (1-7 tasks)
    Task   →  one context-window-sized unit of work

The iron rule: a task must fit in one context window. If it can't, it's two tasks.

All state lives on disk in .sf/:

.sf/
  PROJECT.md          — what the project is right now
  REQUIREMENTS.md     — requirement contract
  DECISIONS.md        — append-only architectural decisions
  KNOWLEDGE.md        — cross-session rules and patterns
  STATE.md            — quick-glance status
  milestones/
    M001/
      M001-ROADMAP.md — slice plan with dependencies
      slices/
        S01/
          S01-PLAN.md     — task decomposition
          S01-SUMMARY.md  — what happened

---

VS Code Extension

SF is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "SF" in VS Code extensions:

• @sf chat participant — talk to the agent in VS Code Chat
• Sidebar dashboard — connection status, model info, token usage
• Full command palette — start/stop agent, switch models, export sessions

The CLI (sf-run) must be installed first — the extension connects to it via RPC.

---

Web Interface

SF has a browser-based interface for visual project management:

sf --web

See Web Interface for details.

---

Resume a Session

sf --continue    # or sf -c

Resumes the most recent session for the current directory.

Browse all saved sessions:

sf sessions

---

Updating SF

SF checks for updates every 24 hours and prompts at startup. You can also update manually:

npm update -g sf-run

Or from within a session:

/sf update

---

Quick Troubleshooting

Problem	Fix
command not found: sf	Add npm global bin to PATH (see OS-specific notes above)
sf runs git svn dcommit	oh-my-zsh conflict — unalias sf or use sf-cli
Permission errors on npm install -g	Fix npm prefix (see Linux notes) or use nvm
Can't connect to LLM	Check API key with sf config, verify network access
sf hangs on start	Check Node.js version: node --version (need 22+)

For more, see Troubleshooting.

---

Next Steps

• Auto Mode — deep dive into autonomous execution
• Configuration — model selection, timeouts, budgets
• Commands Reference — all commands and shortcuts
• Provider Setup — detailed setup for every provider
• Working in Teams — multi-developer workflows