187 lines
5.3 KiB
Text
187 lines
5.3 KiB
Text
---
|
|
title: "Getting started"
|
|
description: "Install SF, configure your LLM provider, and run your first autonomous session."
|
|
---
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install -g singularity-forge
|
|
```
|
|
|
|
Requires Node.js 22+ and Git.
|
|
|
|
<Note>
|
|
**`command not found: sf`?** Your shell may not have npm's global bin directory in `$PATH`. Run `npm prefix -g` to find it, then add `$(npm prefix -g)/bin` to your PATH. See [troubleshooting](/guides/troubleshooting) for details.
|
|
</Note>
|
|
|
|
SF checks for updates every 24 hours. Update in-session with `/sf update`.
|
|
|
|
## First launch
|
|
|
|
```bash
|
|
sf
|
|
```
|
|
|
|
On first launch, a setup wizard walks you through:
|
|
|
|
1. **LLM provider** — 20+ providers (Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, Amazon Bedrock, Azure, and more). OAuth handles Claude Max and Copilot subscriptions automatically; otherwise paste an API key.
|
|
2. **Tool API keys** (optional) — Brave Search, Context7, Jina, Slack, Discord. Press Enter to skip any.
|
|
|
|
Re-run the wizard anytime:
|
|
|
|
```bash
|
|
sf config
|
|
```
|
|
|
|
### Set up API keys
|
|
|
|
For non-Anthropic models, you may need a search API key. Run `/sf config` to set keys globally — they're saved to `~/.sf/agent/auth.json` and apply to all projects.
|
|
|
|
### Set up MCP servers
|
|
|
|
To connect SF to local or external MCP servers, add project-local config in `.mcp.json` or `.sf/mcp.json`. See [configuration](/guides/configuration) for examples. Use `/sf mcp` to verify connectivity.
|
|
|
|
### Offline mode
|
|
|
|
SF works fully offline with local models (Ollama, vLLM, LM Studio). Configure a [custom model](/guides/custom-models) and SF handles the rest — no internet connection required.
|
|
|
|
## Choose a model
|
|
|
|
SF auto-selects a default model after login. Switch anytime:
|
|
|
|
```
|
|
/model
|
|
```
|
|
|
|
Or configure per-phase models in [preferences](/guides/configuration).
|
|
|
|
## Two ways to work
|
|
|
|
<Tabs>
|
|
<Tab title="Step mode">
|
|
Type `/sf` inside a session. SF executes one unit at a time, pausing between each with a wizard showing what completed and what's next.
|
|
|
|
- **No `.sf/` directory** → starts a discussion 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
|
|
</Tab>
|
|
<Tab title="Auto mode">
|
|
Type `/sf autonomous` and walk away. SF autonomously researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete.
|
|
|
|
```
|
|
/sf autonomous
|
|
```
|
|
|
|
See [auto mode](/guides/auto-mode) for the full details.
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## Two terminals, one project
|
|
|
|
The recommended workflow: auto mode in one terminal, steering from another.
|
|
|
|
**Terminal 1 — let it build:**
|
|
|
|
```bash
|
|
sf
|
|
/sf autonomous
|
|
```
|
|
|
|
**Terminal 2 — steer while it works:**
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Project structure
|
|
|
|
SF organizes work into a hierarchy:
|
|
|
|
```
|
|
Milestone → a shippable version (4-10 slices)
|
|
Slice → one demoable vertical capability (1-7 tasks)
|
|
Task → one context-window-sized unit of work
|
|
```
|
|
|
|
All state lives on disk in `.sf/`:
|
|
|
|
<Accordion title="Directory structure">
|
|
```
|
|
.sf/
|
|
PROJECT.md — what the project is right now
|
|
REQUIREMENTS.md — requirement contract (active/validated/deferred)
|
|
DECISIONS.md — append-only architectural decisions
|
|
KNOWLEDGE.md — cross-session rules, patterns, and lessons
|
|
RUNTIME.md — runtime context: API endpoints, env vars, services
|
|
STATE.md — quick-glance status
|
|
milestones/
|
|
M001/
|
|
M001-ROADMAP.md — slice plan with risk levels and dependencies
|
|
M001-CONTEXT.md — scope and goals from discussion
|
|
slices/
|
|
S01/
|
|
S01-PLAN.md — task decomposition
|
|
S01-SUMMARY.md — what happened
|
|
S01-UAT.md — human test script
|
|
tasks/
|
|
T01-PLAN.md
|
|
T01-SUMMARY.md
|
|
```
|
|
</Accordion>
|
|
|
|
## Resume a session
|
|
|
|
```bash
|
|
sf --continue # or sf -c
|
|
```
|
|
|
|
Resumes the most recent session. To pick from all saved sessions:
|
|
|
|
```bash
|
|
sf sessions
|
|
```
|
|
|
|
## VS Code extension
|
|
|
|
SF is also available as a VS Code extension (publisher: FluxLabs). It provides:
|
|
|
|
- **`@sf` chat participant** — talk to the agent in VS Code Chat
|
|
- **Sidebar dashboard** — connection status, model info, token usage, quick actions
|
|
- **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
|
|
|
|
```bash
|
|
sf --web
|
|
```
|
|
|
|
A browser-based dashboard with real-time progress and multi-project support. See [web interface](/guides/web-interface) for details.
|
|
|
|
## Troubleshooting
|
|
|
|
### `sf` runs `git svn dcommit` instead of SF
|
|
|
|
The [oh-my-zsh git plugin](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/git) defines `alias sf='git svn dcommit'`.
|
|
|
|
**Option 1** — Remove the alias in `~/.zshrc` (after the `source $ZSH/oh-my-zsh.sh` line):
|
|
|
|
```bash
|
|
unalias sf 2>/dev/null
|
|
```
|
|
|
|
**Option 2** — Use the alternative binary name:
|
|
|
|
```bash
|
|
sf-cli
|
|
```
|
|
|
|
Both `sf` and `sf-cli` point to the same binary.
|