singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
singularity-forge/docs/user-docs/getting-started.md
Mikael Hugo 3960e42b26 docs: align sf purpose doctrine and docs
2026-05-06 00:38:36 +02:00

7.8 KiB
Raw Blame History

Getting Started with SF

SF is a purpose-to-software compiler. It turns bounded intent into PDD contracts, researches missing context, writes failing tests or executable evidence first, implements the smallest satisfying change, verifies, and records what happened. This guide walks you through installing and running SF on Linux.

Prerequisites

Requirement Minimum Recommended
Node.js 24.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 Linux instructions below.

Install on 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 v24.x or higher
git --version    # should print 2.20+

Step 3 — Install SF:

npm install -g singularity-forge

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 singularity-forge

Docker on Linux

Downloads: Docker Engine

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

Step 1 — Install Docker Engine.

Step 2 — Clone the SF repo:

git clone https://github.com/singularity-ng/singularity-forge.git
cd singularity-forge/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 autonomous "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.

Autonomous Mode — /sf autonomous

Type /sf autonomous and walk away. SF researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete. /sf autonomous remains available as a short alias.

/sf autonomous

See Autonomous Mode for full details.

Recommended Workflow: Two Terminals

Run autonomous mode in one terminal, steer from another.

Terminal 1 — let it build:

sf
/sf autonomous

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 (singularity-forge) 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 singularity-forge

Or from within a session:

/sf update

Quick Troubleshooting

Problem Fix
command not found: sf Add npm global bin to PATH
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 24+)

For more, see Troubleshooting.

Next Steps