# singularity-forge — Index

*Generated: 2026-05-11 | Commit: see `git rev-parse HEAD` | Commands: see WORKFLOWS.md*

## What this repo is

SF (Singularity Forge) is a standalone autonomous repo operator CLI built on the [Pi SDK](https://github.com/badlogic/pi-mono). It compiles purpose into software via a Purpose-to-Software Compiler model (ADR-0000). One command (`sf`) runs an LLM-powered agent that plans, implements, tests, commits, and advances through milestones autonomously.

**Version:** 2.75.3  
**Package:** `singularity-forge` on npm  
**Bin:** `sf`  
**Node:** 26.1+ required (`.mise.toml`, `.nvmrc`, `.node-version` pin)  

## How to run it

```bash
npm install -g singularity-forge@latest
sf                # interactive TUI
sf headless ...   # machine surface (JSON I/O)
```

Dev from source:
```bash
npm install
npm run build          # full build (packages + web)
npm run build:core     # packages + tsc + resources only
npm run dev            # hot reload
npm run copy-resources # rebuild dist/resources/ (extension JS/prompts)
```

## Where to start

| Goal | Start here |
|------|-----------|
| Understand the product | `README.md`, `VISION.md`, `ARCHITECTURE.md` |
| Understand SF's architecture decisions | `docs/adr/` |
| Understand spec-first TDD doctrine | `docs/SPEC_FIRST_TDD.md` |
| Understand the runtime state model | `.sf/PROJECT.md`, `AGENTS.md` |
| Find a subsystem | `SUBSYSTEMS.md` |
| Build/test commands | `WORKFLOWS.md` |
| Understand SF autonomous mode | `src/resources/extensions/sf/` |
| Understand the Pi SDK packages | `packages/` |

## Key files

- `src/loader.ts` — CLI entry point (`dist/loader.js`, bin `sf`)
- `src/headless-context.ts` — headless context loading + auto-bootstrap
- `src/resources/extensions/sf/` — SF autonomous mode extension (compile via `copy-resources`)
- `packages/coding-agent/` — Pi agent core (tools, models, sessions, settings)
- `packages/ai/` — LLM provider adapters
- `packages/tui/` — Terminal UI
- `packages/daemon/` — Background daemon process
- `.sf/sf.db` — canonical structured state (SQLite, `node:sqlite`)
