Key Concepts
Understanding these concepts will help you get the most out of System 0.
Instances
An instance is a named analysis session with its own state, history, and configuration. Think of it as a dedicated analyst assigned to one target. Targets can be directories, URLs, APIs, or any accessible resource. You can have many instances running simultaneously on different targets.
# Create an instance targeting a codebase
s0 init my-audit --goal 'Find security issues'
# Target a URL
s0 init site-audit --goal 'Analyze site structure' --target https://example.com
# Each instance lives at ~/.system0/instances/<name>/Execution Modes
Modes control how much autonomy the system has. Graduate from safe to autonomous at your own pace.
| Mode | Finds Issues | Plans Fixes | Executes Fixes | Risk Level |
|---|---|---|---|---|
| observe | Yes | No | No | Zero |
| suggest | Yes | Yes (with risk scores) | No | Zero |
| supervised | Yes | Yes | After approval | Controlled |
| auto | Yes | Yes | Yes (with safety rails) | Managed |
Passes and Cycles
A pass (or cycle) is one complete analyze-discover-grow loop. Each pass:
- Selects an analysis angle
- Examines the target
- Collects findings and gaps
- Creates new analysis angles from gaps
- Plans and executes fixes (if mode allows)
More passes = deeper, broader analysis. The system discovers new angles with each pass, so later passes often catch subtler issues.
Findings
A finding is an issue discovered during analysis. Each finding has:
- Severity: 0.0 to 1.0 (higher = more critical)
- Description: What the issue is
- Location: Where it was found
- Evidence: Supporting context
Only findings above the severity-threshold (default: 0.6) trigger fix planning.
Gaps
A gap is something the system could not evaluate. Gaps become new analysis angles in the next pass. This is how the system grows: it discovers its own blind spots and fills them.
Dimensions
A dimension is an analysis angle the system uses to examine targets. The system starts with one seed dimension and grows from there. Over time, effective dimensions get more attention while less productive ones fade.
Maturity Gates
The system prevents premature action with two gates:
- min-passes (default: 2): No fix planning until at least this many passes have run
- min-dimensions (default: 3): No auto-execution until at least this many analysis dimensions exist
This ensures the system has built sufficient understanding before taking action.
Budget Hierarchy
Four independent spending ceilings:
| Level | Default | Scope |
|---|---|---|
| Per-pass | $10.00 | Single analysis cycle |
| Per-action | $5.00 | Single fix action |
| Session | $50.00 | One daemon session |
| Lifetime | $500.00 | Total instance spend |
The Ledger
Every event is recorded in an append-only ledger (ledger.jsonl). This is the immutable history of everything the system has done: findings, gaps, plans, actions, verifications. It cannot be edited, only appended to. This provides a complete audit trail for any analysis.
Worktree Isolation
In auto and supervised modes, System 0 creates an isolated git worktree for its changes. This means:
- Your main branch is never checked out or modified
- All changes happen on a dedicated
s0/<name>branch - You can merge back with
s0 mergewhen ready - Or discard the worktree entirely
Offspring (Hatch / Hatch0)
Instances can create offspring for focused sub-analyses:
- hatch: Evolved offspring that inherit the parent's analysis coverage. Picks up where the parent left off.
- hatch0: Pristine offspring that start from scratch. A clean-slate analysis with no inherited assumptions.