SF

The evolution of Singularity Forge — now a standalone autonomous repo operator.

SF is a standalone autonomous repo operator with direct programmatic control over the agent harness. It clears context between tasks, injects exactly the right files at dispatch time, manages git branches, tracks cost and tokens, detects stuck loops, recovers from crashes, and auto-advances through an entire milestone without human intervention.

Forge is the product. The Unified Operation Kernel (UOK) is the internal runtime kernel. Core behavior is governed by purpose-driven TDD and the eight PDD fields: purpose, consumer, contract, failure boundary, evidence, non-goals, invariants, and assumptions.

We sharpen Forge against the best external ideas we can find — Claude Code and Codex for ergonomics, Aider and gsd-2 for execution, Plandex for workflow structure — but those are reference inputs, not the destination. Forge stays focused on autonomous single-repo execution. ACE Coder is the separate multi-repo and large-scale path.

State a purpose. Walk away. Come back to built, verified software with clean git history.

SF runs as a server; humans drive it from the web app. The CLI/headless surface is the machine and automation substrate (autonomous workers, RPC, CI) — not a human surface. The TUI has been removed.

Supported platforms: Linux x86-64 / Linux arm64. macOS support removed 2026-05-17 per operator direction.

SF now provisions a managed RTK binary on supported Linux and Windows installs to compress shell-command output in bash, bash_job, bash_background, and verification flows. SF forces RTK_TELEMETRY_DISABLED=1 for all managed invocations. Set SF_RTK_DISABLED=1 to disable the integration.

Node runtime: SF targets Node.js 26.1+. Use the repo .mise.toml, .node-version, or .nvmrc pins when developing from source.

---

What's New in v2.71

External Tooling

• External MCP tool configs — SF can connect to project-local MCP tool servers for third-party services and local integrations.
• Stream ordering preserved — external tool output now renders in the correct order, including MCP tool calls surfaced by model/runtime adapters.
• Multi-round discuss questions — new-project discuss phase supports multi-round questioning with structured question gates.

Model Selection Hardening

• Unconfigured models blocked — models without a configured provider are filtered from selection surfaces, preventing dispatch failures.
• Provider readiness required — saved default model selection now verifies the provider is ready before accepting it.
• Session override honored — /sf model selection persists as a session override across all dispatch phases.
• Minimal context guard — model override logic is skipped in minimal command contexts where it doesn't apply.

Auto-Mode Resilience

• Credential cooldown recovery — autonomous mode survives transient 429 rate-limit responses with structured cooldown errors and a bounded retry budget.
• Fire-and-forget autonomous start — autonomous startup is detached from active turns to prevent blocking.
• Scoped forensics — stuck-loop forensics are now scoped to auto sessions only, preventing false positives in interactive use.

Provider Fixes

• Full OAuth login URLs — OAuth login URLs are now displayed in full instead of being truncated.
• MiniMax bearer auth — MiniMax Anthropic API requests use proper bearer authentication.
• Case-insensitive tool rendering — renderable tool matching is now case-insensitive, fixing missed tool output.
• Machine-surface idle timeout — idle timeout is kept off during interactive tool execution in sf headless.

Reliability & Internals

• TOCTOU file locking — race conditions in event log and custom workflow graph file locking are fixed with proper atomic lock acquisition.
• State derive refactor — deriveStateFromDb god function extracted into composable, testable helpers.
• Windows portability — hardened cross-platform portability across runtime, tooling, and CI.
• Model routing transparency — dynamic routing is skipped for interactive dispatches; model changes are always shown in the banner.
• Capability-aware routing (ADR-004) — full implementation of capability scoring, before_model_select hook, and task metadata extraction.
• Multi-model provider strategy (ADR-005) — infrastructure for multi-provider model selection wired into live paths.
• Anti-fabrication guardrails — discuss prompts enforce turn-taking to prevent fabricated user responses.
• Milestone worktree cleanup — merged worktree cleanup uses the milestone branch instead of generic lookups.
• Tool cache control — cache_control breakpoints added to tool definitions for improved prompt caching.

See the full Changelog for details on every release.

Previous highlights (v2.70 and earlier)

• External MCP integrations (v2.68) — project-local MCP configs connect SF to external tools; SF workflow is no longer exposed as MCP
• Contextual tips system (v2.68) — the web app surfaces contextual tips based on workflow state
• Structured questions — interactive prompts stay inside SF's direct runtime flow
• Tiered Context Injection (M005) — relevance-scoped context with 65%+ token reduction
• Resilient transient error recovery — defers to Core RetryHandler and fixes cmdCtx race conditions
• Anthropic subscription routing — auto-routed through Claude Code CLI provider with proper display names
• 5-wave state machine hardening — critical data integrity fixes across atomic writes, event log reconciliation, session recovery
• Discussion gate enforcement — mechanical enforcement with fail-closed behavior
• Slice-level parallelism — dependency-aware parallel dispatch within a milestone
• Persistent notification panel — web panel, widget, and API for real-time notifications
• MCP client integrations — external tool servers can be discovered and used from SF sessions
• Ollama extension — first-class local LLM support via Ollama, with dynamic routing enabled by default
• Discord bot & daemon — dedicated daemon package, Discord bot, and headless text mode with tool calls
• Capability-aware model routing (ADR-004) — capability scoring, before_model_select hook, and task metadata extraction
• VS Code sidebar redesign — SCM provider, checkpoints, diagnostics panel, activity feed, workflow controls, session forking
• Real-time worker monitoring — live parallel-worker progress in the web app
• Codebase map — automatic codebase map injection for fresh agent contexts
• --resume flag — resume previous sessions from the CLI
• Concurrent invocation guard — prevents overlapping autonomous mode runs
• VS Code integration — status bar, file decorations, bash terminal, session tree, conversation history, and code lens
• Skills overhaul — 30+ skill packs covering major frameworks, databases, and cloud platforms
• Single-writer state engine — disciplined state transitions with machine guards and TOCTOU hardening
• DB-backed planning tools — atomic Postgres-backed tool calls for state transitions
• Declarative workflow engine — YAML workflows through auto-loop
• Doctor: worktree lifecycle checks — validates worktree health, detects orphans, consolidates cleanup

---

Documentation

Full documentation is in the docs/ directory:

User Guides

• Getting Started — install, first run, basic usage
• [Autonomous Mode](./docs/user-docs/autonomous mode.md) — autonomous execution deep-dive
• Configuration — all preferences, models, git, and hooks
• Custom Models — add custom providers (Ollama, vLLM, LM Studio, proxies)
• Token Optimization — profiles, context compression, complexity routing
• Cost Management — budgets, tracking, projections
• Git Strategy — worktree isolation, branching, merge behavior
• Parallel Orchestration — run multiple milestones simultaneously
• Working in Teams — unique IDs, shared artifacts
• Skills — bundled skills, discovery, custom authoring
• Commands Reference — all commands and keyboard shortcuts
• Troubleshooting — common issues, doctor, forensics, recovery
• Visualizer — workflow visualizer with stats and discussion status
• Remote Questions — route decisions to Slack or Discord when human input is needed
• Dynamic Model Routing — complexity-based model selection and budget pressure
• Web Interface — browser-based project management and real-time progress
• Migration from v1 — .planning → .sf migration
• Docker Sandbox — run SF autonomous mode in an isolated Docker container

Developer Docs

• Architecture — system design and dispatch pipeline
• CI/CD Pipeline — three-stage promotion pipeline (Dev → Test → Prod)
• Pipeline Simplification (ADR-003) — merged research into planning, mechanical completion
• VS Code Extension — chat participant, sidebar dashboard, RPC integration

---

How It Works

SF structures 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

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

The Loop

Each slice flows through phases automatically:

Plan (with integrated research) → Execute (per task) → Complete → Reassess Roadmap → Next Slice
                                                                                      ↓ (all slices done)
                                                                              Validate Milestone → Complete Milestone

Plan scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). Execute runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. Complete writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. Reassess checks if the roadmap still makes sense given what was learned. Validate Milestone runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.

/sf autonomous — The Main Event

This is what makes SF different. Run it, walk away, come back to built software.

/sf autonomous

Autonomous mode is governed by the Unified Operation Kernel (UOK), not by the LLM or a loose file loop. UOK reads canonical project state, records each run in the DB-backed ledger, projects runtime files for query/UI, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, autonomous mode reconciles the UOK ledger and projections before dispatching the next unit. Use /sf autonomous; there is no separate /sf auto mode.

What happens under the hood:

1. Fresh session per unit — Every task, every research phase, every planning step gets a clean 200k-token context window. No accumulated garbage. No "I'll be more concise now."

2. Context pre-loading — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files.

3. Git isolation — When git.isolation is set to worktree or branch, each milestone runs on its own milestone/<MID> branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is worktree, configurable via preferences.

4. Crash recovery — A lock file tracks the current unit. If the session dies, the next /sf autonomous reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator state is persisted to disk with PID liveness detection, so multi-worker sessions survive crashes too. Through the machine surface, crashes trigger automatic restart with exponential backoff (default 3 attempts).

5. Provider error recovery — Transient provider errors (rate limits, 500/503 server errors, overloaded) resume automatically after a delay. Permanent errors (auth, billing) pause for manual review. The model fallback chain retries transient network errors before switching models.

6. Stuck detection — A sliding-window detector identifies repeated dispatch patterns (including multi-unit cycles). On detection, it retries once with a deep diagnostic. If it fails again, autonomous mode stops with the exact file it expected.

7. Timeout supervision — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout pauses autonomous mode. Recovery steering nudges the LLM to finish durable output before giving up.

8. Cost tracking — Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause autonomous mode before overspending.

9. Adaptive replanning — After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing.

10. Verification enforcement — Configure shell commands (npm run lint, npm run test, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Auto-discovered checks from package.json run in advisory mode — they log warnings but don't block on pre-existing errors. Configurable via verification_commands, verification_auto_fix, and verification_max_retries preferences.

11. Milestone validation — After all slices complete, a validate-milestone gate compares roadmap success criteria against actual results before sealing the milestone.

12. Escape hatch — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just /sf autonomous to resume from disk state.

/sf and /sf next — Assisted Mode

By default, /sf runs in assisted mode: the same UOK-governed dispatch loop as autonomous mode, but it pauses between units with a wizard showing what completed and what's next. You advance one step at a time, review the output, and continue when ready.

• No .sf/ directory → Start a new project. Discussion flow captures your vision, constraints, and preferences.
• Milestone exists, no roadmap → Discuss or research the milestone.
• Roadmap exists, slices pending → Plan the next slice, execute one task, or switch to autonomous mode.
• Mid-task → Resume from where you left off.

/sf next is an explicit alias for assisted mode. You can switch from assisted mode to autonomous mode mid-session via the wizard.

Assisted mode pauses after each unit. Autonomous mode continues until policy, evidence, budget, blockers, or completion stops it.

---

Getting Started

Run SF and open the web app

SF is a server. Humans interact with it entirely through the web app — there is no human CLI or TUI.

# From source (dev): starts the server and prints the web URL + access token
npm run sf:server -- --port 4000 --host 127.0.0.1
# → http://127.0.0.1:4000/#token=...

In production SF runs as a deployed server (the sf-server pod), reached at its web URL behind your ingress/SSO. Either way, open the printed URL in a browser — everything below happens in the web app.

Connect a provider

In the web app, connect an LLM provider — 20+ supported (Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, and more). Subscription providers use OAuth; others take an API key. SF auto-selects a default model and is provider-agnostic — switch or mix models per phase from the UI.

Work with it

From the web app you point SF at a repo and choose how much autonomy to hand it — the same UOK lifecycle and crash-recovery model underneath either way:

• Assisted — SF executes one unit of work at a time, pausing between each so you see what completed and what's next. No project yet? It starts the discussion flow. Roadmap exists? It plans or executes the next step.
• Autonomous — walk away. SF researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete, fresh context window per task. Watch live progress and steer (discuss decisions, check status, queue the next milestone) from the same web UI while it runs — your input is picked up at the next phase boundary without stopping the run.

Machine surface — CI, automation, workers

sf headless is SF's machine surface — the same SF flow without any UI, for CI pipelines, cron jobs, parent processes, the autonomous/RPC workers, and scripted automation. It is not a human surface: it's a surface, not run control, not a permission profile, and not an output format.

# Run autonomous mode in CI
sf headless --timeout 600000 autonomous

# Create and execute a milestone end-to-end
sf headless new-milestone --context spec.md --autonomous

# One unit at a time (cron-friendly)
sf headless next

# Instant JSON snapshot (no LLM, ~50ms)
sf headless query

# Stream structured events as JSONL
sf headless --output-format stream-json autonomous

# Force a specific pipeline phase
sf headless dispatch plan

The machine surface handles prompts according to the configured run control and permission profile, detects completion, and exits with structured codes: 0 complete, 1 error/timeout, 10 blocked, 11 cancelled, and 12 reload. Auto-restarts on crash with exponential backoff. Use sf headless query for instant, machine-readable state inspection — returns phase, next dispatch preview, and parallel worker costs as a single JSON object without spawning an LLM session. Use --output-format json for one batch result object, --output-format stream-json for event JSONL, and the default text output for human logs. Pair with remote questions to route decisions to Slack or Discord when human input is needed.

Multi-session orchestration — the machine surface supports file-based IPC in .sf/parallel/ for coordinating multiple SF workers across milestones. Build orchestrators that spawn, monitor, and budget-cap a fleet of SF workers.

Terminology: SF has one flow engine. The web app (the human surface), the CLI/headless machine surface, editor adapters, and the autonomous/RPC workers are entrypoints around that flow. ACP/RPC/stdio/HTTP are protocols. text, json, and stream-json are output formats. Manual, assisted, and autonomous are run-control modes. Restricted, normal, trusted, and unrestricted are permission profiles. See SF operating model, a generated human export from .sf working state and source evidence.

First launch

On first run, SF launches a branded setup wizard that walks you through LLM provider selection (OAuth or API key), then optional tool API keys (Brave Search, Context7, Jina, Slack, Discord). Every step is skippable — press Enter to skip any. If you have an existing Pi installation, your provider credentials (LLM and tool keys) are imported automatically. Run sf config anytime to re-run the wizard.

Commands

Command	What it does
/sf	Assisted mode — executes one unit at a time, pauses between each
/sf next	Explicit assisted mode (same as bare /sf)
/sf autonomous	Autonomous mode — researches, plans, executes, commits, repeats
/sf quick	Execute a quick task with SF guarantees, skip planning overhead
/sf stop	Stop autonomous mode gracefully
/sf steer	Hard-steer plan documents during execution
/sf discuss	Discuss architecture and decisions (works alongside autonomous mode)
/sf rethink	Conversational project reorganization
/sf mcp	External MCP server status and connectivity
/sf status	Progress dashboard
/sf queue	Queue future milestones (safe during autonomous mode)
/sf prefs	Model selection, timeouts, budget ceiling
/sf migrate	Migrate a v1 .planning directory to .sf format
/sf help	Categorized command reference for all SF subcommands
/sf mode	Switch workflow mode (solo/team) with coordinated defaults
/sf forensics	Full-access SF debugger for autonomous mode failure investigation
/sf cleanup	Archive phase directories from completed milestones
/sf doctor	Runtime health checks — issues surface across widget, visualizer, and reports
/sf keys	API key manager — list, add, remove, test, rotate, doctor
/sf logs	Browse activity, debug, and metrics logs
/sf export --html	Generate HTML report for current or completed milestone
/worktree (/wt)	Git worktree lifecycle — create, switch, merge, remove
/voice	Toggle real-time speech-to-text (Linux)
/exit	Graceful shutdown — saves session state before exiting
/kill	Kill SF process immediately
/clear	Start a new session (alias for /new)
Ctrl+Alt+G	Toggle dashboard overlay
Ctrl+Alt+V	Toggle voice transcription
Ctrl+Alt+B	Show background shell processes
Alt+V	Paste clipboard image
sf config	Re-run the setup wizard (LLM provider + tool keys)
sf update	Update SF to the latest version
sf headless [cmd]	Machine surface for /sf commands (CI, cron, scripts)
sf headless query	Instant machine snapshot — JSON state, next dispatch, costs (no LLM)
sf --continue (-c)	Resume the most recent session for the current directory
sf --worktree (-w)	Launch an isolated worktree session for the active milestone
sf sessions	Interactive session picker — browse and resume any saved session

---

What SF Manages For You

Context Engineering

Every dispatch is carefully constructed. The LLM never wastes tool calls on orientation.

Artifact	Purpose
PROJECT.md	Living doc — what the project is right now
DECISIONS.md	Append-only register of architectural decisions
KNOWLEDGE.md	Cross-session rules, patterns, and lessons learned
RUNTIME.md	Runtime context — API endpoints, env vars, services (v2.39)
STATE.md	Quick-glance dashboard — always read first
M001-ROADMAP.md	Milestone plan with slice checkboxes, risk levels, dependencies
M001-CONTEXT.md	User decisions from the discuss phase
M001-RESEARCH.md	Codebase and ecosystem research
S01-PLAN.md	Slice task decomposition with must-haves
T01-PLAN.md	Individual task plan with verification criteria
T01-SUMMARY.md	What happened — YAML frontmatter + narrative
S01-UAT.md	Human test script derived from slice outcomes

SF's working spec/state model is .sf-native. If an inherited repo has SPEC.md, BASE_SPEC.md, or product spec docs, SF treats them as external evidence and projects useful facts into .sf/PROJECT.md, .sf/REQUIREMENTS.md, milestones, slices, tasks, decisions, and evidence. New work should not create a second root-level spec system. Every milestone, slice, and task plan starts with its purpose before implementation details.

Git Strategy

Branch-per-milestone with sequential task commits and squash merge. Fully automated.

main:
  docs(M001/S04): workflow documentation and examples
  fix(M001/S03): bug fixes and doc corrections
  feat(M001/S02): API endpoints and middleware
  feat(M001/S01): data model and type system

milestone/M001 (deleted after merge):
  feat(S01/T03): file writer with round-trip fidelity
  feat(S01/T02): markdown parser for plan files
  feat(S01/T01): core types and interfaces

One squash commit per milestone on main (or whichever branch you started from). The worktree is torn down after merge. Git bisect works. Individual milestones are revertable. Commit messages are generated from task summaries — no more generic "complete task" messages.

Verification

Every task has must-haves — mechanically checkable outcomes:

• Truths — Observable behaviors ("User can sign up with email")
• Artifacts — Files that must exist with real implementation, not stubs
• Key Links — Imports and wiring between artifacts

The verification ladder: static checks → command execution → behavioral testing → human review (only when the agent genuinely can't verify itself).

Dashboard

Ctrl+Alt+G or /sf status opens a real-time overlay showing:

• Current milestone, slice, and task progress
• Autonomous mode elapsed time and phase
• Per-unit cost and token breakdown by phase, slice, and model
• Cost projections based on completed work
• Completed and in-progress units

HTML Reports

After a milestone completes, SF auto-generates a self-contained HTML report in .sf/reports/. Each report includes project summary, progress tree, slice dependency graph (SVG DAG), cost/token metrics with bar charts, execution timeline, changelog, and knowledge base sections. No external dependencies — all CSS and JS are inlined, printable to PDF from any browser.

An auto-generated index.html shows all reports with progression metrics across milestones.

• Automatic — generated after milestone completion (configurable via auto_report preference)
• Manual — run /sf export --html anytime

---

Configuration

Preferences

SF preferences live in ~/.sf/PREFERENCES.md (global) or .sf/PREFERENCES.md (project). Manage with /sf prefs.

---
version: 1
models:
  research: claude-sonnet-4-6
  planning:
    model: claude-opus-4-6
    fallbacks:
      - openrouter/z-ai/glm-5
      - openrouter/minimax/minimax-m2.5
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6
skill_discovery: suggest
auto_supervisor:
  soft_timeout_minutes: 20
  idle_timeout_minutes: 10
  hard_timeout_minutes: 30
budget_ceiling: 50.00
unique_milestone_ids: true
verification_commands:
  - npm run lint
  - npm run test
auto_report: true
---

Key settings:

Setting	What it controls
models.*	Per-phase model selection — string for a single model, or {model, fallbacks} for automatic failover
skill_discovery	auto / suggest / off — how SF finds and applies skills
auto_supervisor.*	Timeout thresholds for autonomous mode supervision
budget_ceiling	USD ceiling — autonomous mode pauses when reached
uat_dispatch	Enable automatic UAT runs after slice completion
always_use_skills	Skills to always load when relevant
skill_rules	Situational rules for skill routing
skill_staleness_days	Skills unused for N days get deprioritized (default: 60, 0 = disabled)
unique_milestone_ids	Uses unique milestone names to avoid clashes when working in teams of people
git.isolation	worktree (default), branch, or none — enable worktree or branch isolation for milestone work
git.manage_gitignore	Set false to prevent SF from modifying .gitignore
verification_commands	Array of shell commands to run after task execution (e.g., ["npm run lint", "npm run test"])
verification_auto_fix	Auto-retry on verification failures (default: true)
verification_max_retries	Max retries for verification failures (default: 2)
phases.require_slice_discussion	Pause autonomous mode before each slice for human discussion review
auto_report	Auto-generate HTML reports after milestone completion (default: true)

Agent Instructions

Place an AGENTS.md file in any directory to provide persistent behavioral guidance for that scope. Pi core loads AGENTS.md automatically (with CLAUDE.md as a fallback) at both user and project levels. Use these files for coding standards, architectural decisions, domain terminology, or workflow preferences.

Note: The legacy agent-instructions.md format (~/.sf/agent-instructions.md and .sf/agent-instructions.md) is deprecated and no longer loaded. Migrate any existing instructions to AGENTS.md or CLAUDE.md.

Debug Mode

Start SF with sf --debug to enable structured JSONL diagnostic logging. Debug logs capture dispatch decisions, state transitions, and timing data for troubleshooting autonomous mode issues.

Token Optimization

SF includes a coordinated token optimization system that reduces usage by 40-60% on cost-sensitive workloads. Set a single preference to coordinate model selection, phase skipping, and context compression:

token_profile: budget # or balanced (default), quality

Profile	Savings	What It Does
budget	40-60%	Cheap models, skip research/reassess, minimal context inlining
balanced	10-20%	Default models, skip slice research, standard context
quality	0%	All phases, all context, full model power

Complexity-based routing automatically classifies tasks as simple/standard/complex and routes to appropriate models. Simple docs tasks get Haiku; complex architectural work gets Opus. The classification is heuristic (sub-millisecond, no LLM calls) and learns from outcomes via a persistent routing history.

Budget pressure graduates model downgrading as you approach your budget ceiling — 50%, 75%, and 90% thresholds progressively shift work to cheaper tiers.

See the full Token Optimization Guide for details.

Bundled Tools

SF ships with 24 extensions, all loaded automatically:

Extension	What it provides
SF	Core workflow engine, autonomous mode, commands, dashboard
Browser Tools	Playwright-based browser with form intelligence, intent-ranked element finding, semantic actions, PDF export, session state persistence, network mocking, device emulation, structured extraction, visual diffing, region zoom, test code generation, and prompt injection detection
Search the Web	Brave Search, Tavily, or Jina page extraction
Google Search	Gemini-powered web search with AI-synthesized answers
Context7	Up-to-date library/framework documentation
Bash Background	Long-running process management with readiness detection
Bash Jobs	Background bash commands with job tracking and cancellation
Subagent	Delegated tasks with isolated context windows
GitHub	Full-suite GitHub issues and PR management via /gh command
MCP Client	Client-side connections to external MCP tool servers via @modelcontextprotocol/sdk; SF does not expose its workflow as MCP
Voice	Real-time speech-to-text transcription (Linux — Ubuntu 22.04+)
Slash Commands	Custom command creation
Ask User Questions	Structured user input with single/multi-select
Secure Env Collect	Masked secret collection without manual .env editing
Remote Questions	Route decisions to Slack/Discord when human input is needed in headless/CI mode
Universal Config	Discover and import MCP servers and rules from other AI coding tools
AWS Auth	Automatic Bedrock credential refresh for AWS-hosted models
Ollama	First-class local LLM support via Ollama
Claude Code CLI	External provider extension for Claude Code CLI
cmux	Claude multiplexer integration — desktop notifications, sidebar metadata, visual subagent splits
GitHub Sync	Auto-sync milestones to GitHub Issues, PRs, and Milestones
LSP	Language Server Protocol — diagnostics, definitions, references, hover, rename
TTSR	Tool-triggered system rules — conditional context injection based on tool usage

Bundled Agents

Five specialized subagents for delegated work:

Agent	Role
Scout	Fast codebase recon — returns compressed context for handoff
Researcher	Web research — finds and synthesizes current information
Worker	General-purpose execution in an isolated context window
JavaScript Pro	JavaScript-specialized execution and debugging
TypeScript Pro	TypeScript-specialized execution and debugging

---

Working in teams

The best practice for working in teams is to ensure unique milestone names across all branches (by using unique_milestone_ids) and checking in the right .sf/ artifacts to share valuable context between teammates.

Suggested .gitignore setup

# ── SF: Runtime / Ephemeral (per-developer, per-session) ──────────────────
# Crash detection sentinel — PID lock, written per autonomous mode session
.sf/auto.lock
# Autonomous mode dispatch tracker — prevents re-running completed units (includes archived per-milestone files)
.sf/completed-units*.json
# State manifest — workflow state for recovery
.sf/state-manifest.json
# Derived state cache — regenerated from plan/roadmap files on disk
.sf/STATE.md
# Per-developer token/cost accumulator
.sf/metrics.json
# Raw JSONL session dumps — crash recovery forensics, auto-pruned
.sf/activity/
# Unit execution records — dispatch phase, timeouts, recovery tracking
.sf/runtime/
# Git worktree working copies
.sf/worktrees/
# Parallel orchestration IPC and worker status
.sf/parallel/
# Daily-rotated event journal — structured event log for forensics
.sf/journal/
# Doctor run history — diagnostic check results
.sf/doctor-history.jsonl
# Workflow event log — structured event stream
.sf/event-log.jsonl
# Generated HTML reports (regenerable via /sf export --html)
.sf/reports/
# Session-specific interrupted-work markers
.sf/milestones/**/continue.md
.sf/milestones/**/*-CONTINUE.md

Unique Milestone Names

Create or amend your .sf/PREFERENCES.md file within the repo to include unique_milestone_ids: true e.g.

---
version: 1
unique_milestone_ids: true
---

With the above .gitignore set up, the .sf/PREFERENCES.md file is checked into the repo ensuring all teammates use unique milestone names to avoid collisions.

Milestone names will now be generated with a 6 char random string appended e.g. instead of M001 you'll get something like M001-ush8s3

Migrating an existing git ignored .sf/ folder

1. Ensure you are not in the middle of any milestones (clean state)
2. Update the .sf/ related entries in your .gitignore to follow the Suggested .gitignore setup section under Working in teams (ensure you are no longer blanket ignoring the whole .sf/ directory)
3. Update your .sf/PREFERENCES.md file within the repo as per section Unique Milestone Names
4. If you want to update all your existing milestones use this prompt in SF: I have turned on unique milestone ids, please update all old milestone ids to use this new format e.g. M001-abc123 where abc123 is a random 6 char lowercase alpha numeric string. Update all references in all .sf file contents, file names and directory names. Validate your work once done to ensure referential integrity.
5. Commit to git

---

Architecture

SF is a TypeScript application that embeds the Pi coding agent SDK.

sf (CLI binary)
  └─ loader.ts          Sets PI_PACKAGE_DIR, SF env vars, dynamic-imports cli.ts
      └─ cli.ts         Wires SDK managers, loads extensions, starts InteractiveMode
          ├─ headless.ts     Headless orchestrator (spawns RPC child, auto-responds, detects completion)
          ├─ onboarding.ts   First-run setup wizard (LLM provider + tool keys)
          ├─ wizard.ts       Env hydration from stored auth.json credentials
          ├─ app-paths.ts    ~/.sf/agent/, ~/.sf/sessions/, auth.json
          ├─ resource-loader.ts  Syncs bundled extensions + agents to ~/.sf/agent/
          └─ src/resources/
              ├─ extensions/sf/    Core SF extension (auto, state, commands, ...)
              ├─ extensions/...     21 supporting extensions
              ├─ agents/            scout, researcher, worker, javascript-pro, typescript-pro
              └─ SF-WORKFLOW.md    Manual bootstrap protocol

Key design decisions:

• pkg/ shim directory — PI_PACKAGE_DIR points here (not project root) to avoid Pi's theme resolution collision with our src/ directory. Contains only piConfig and theme assets.
• Two-file loader pattern — loader.ts sets all env vars with zero SDK imports, then dynamic-imports cli.ts which does static SDK imports. This ensures PI_PACKAGE_DIR is set before any SDK code evaluates.
• Always-overwrite sync — npm update -g takes effect immediately. Bundled extensions and agents are synced to ~/.sf/agent/ on every launch, not just first run.
• State lives in Postgres — canonical structured state and planning rows live in the database configured by SF_DB_URL (see ADR-0082). Repo-local .sf/ holds journals, traces, runtime projections, and generated markdown — not a second planning database. No in-memory state survives across sessions.

---

Requirements

• Node.js ≥ 26.1.0
• An LLM provider — any of the 20+ supported providers (see Use Any Model)
• Git — initialized automatically if missing

Optional:

• Brave Search API key (web research)
• Tavily API key (web research — alternative to Brave)
• Google Gemini API key (web research via Gemini Search grounding)
• Context7 API key (library docs)
• Jina API key (page extraction)

---

Use Any Model

SF isn't locked to one provider. It supports 20+ model providers out of the box and routes per phase — a strong reasoning model for planning, a fast model for research, whatever performs best for execution. Provider-agnostic by design: no model vendor is privileged.

Built-in Providers

Anthropic, Anthropic (Vertex AI), OpenAI, Google (Gemini), OpenRouter, GitHub Copilot, Amazon Bedrock, Azure OpenAI, Google Vertex, Groq, Cerebras, Mistral, xAI, HuggingFace, Vercel AI Gateway, and more.

OAuth / Max Plans

If you have a Claude Max, Codex, or GitHub Copilot subscription, SF can use the corresponding local authenticated runtime/provider adapter directly. Claude Code and Codex are not project MCP dependencies; they are model/runtime routes. Gemini can also route through the Gemini CLI core path where configured.

⚠️ Important: Using OAuth tokens from subscription plans outside their native applications may violate the provider's Terms of Service. In particular:

• Google Gemini — Using Gemini CLI or Antigravity OAuth tokens in third-party tools has resulted in Google account suspensions. This affects your entire Google account, not just the Gemini service. Use a Gemini API key instead.
• Claude Max — Anthropic's ToS may not explicitly permit OAuth use outside Claude's own applications.
• GitHub Copilot — Usage outside GitHub's own tools may be restricted by your subscription terms.

SF supports API key authentication for all providers as the safe alternative. We strongly recommend using API keys over OAuth for Google Gemini.

OpenRouter

OpenRouter gives you access to hundreds of models through a single API key. Use it to run SF with Llama, DeepSeek, Qwen, or anything else OpenRouter supports.

Per-Phase Model Selection

In your preferences (/sf prefs), assign different models to different phases:

models:
  research: openrouter/deepseek/deepseek-r1
  planning:
    model: claude-opus-4-6
    fallbacks:
      - openrouter/z-ai/glm-5
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6

Use expensive models where quality matters (planning, complex execution) and cheaper/faster models where speed matters (research, simple completions). Each phase accepts a simple model string or an object with model and fallbacks — if the primary model fails (provider outage, rate limit, credit exhaustion), SF automatically tries the next fallback. SF tracks cost per-model so you can see exactly where your budget goes.

---

Ecosystem

Project	Description
SF2 Config Utility	Standalone configuration tool for managing SF preferences, providers, and API keys

---

Star History

---

License

MIT License

---

A purpose-to-software compiler.

State a purpose. Walk away. Come back to built, verified software.