Home / Quickstart
Get running in minutes

Quickstart

Install Sentigent, seed a plan, drive it with real claude -p laps, and read the FAP receipt. No cloud setup required. Everything runs locally.

Prerequisites: Python 3.11+, uv or pip, and claude CLI installed and authenticated (claude --version should work). Ollama is optional — only needed for the local CloneResolver push-vs-ask path.

Install

Install with uv (recommended) or plain pip.

terminal 
# recommended
uv pip install sentigent

# or with pip
pip install sentigent

Sentigent is local-first. No API keys required for the loop driver itself. Your plans, decisions, and FAP data stay on your machine in a local SQLite brain.

Seed a plan

Give the loop driver a goal. It creates a durable state file that survives session ends, crashes, and reboots. This is the VISION.md equivalent encoded into the loop's state.

terminal 
python -m sentigent.operator.loop_driver start \
  --goal "Ship feature X with passing tests"

# output:
loop_id: loop_83cc8641
state:   ~/.sentigent/loops/loop_83cc8641.json
status:  pending

The loop_id is your handle for this plan. Use it in all subsequent commands. The state file is atomic — a partial write never corrupts it.

Drive it

Start the loop. Each lap spawns a fresh claude -p subprocess over exactly one step, then runs the verify gate (your project's tests/lint/typecheck) before marking it done. The loop persists state atomically after every lap — safe to kill at any point.

terminal 
python -m sentigent.operator.loop_driver drive loop_83cc8641 --execute

# each lap prints:
[lap 1/? ] running step: write test scaffold
[lap 1/? ] verify gate: pytest tests/ ... PASSED (19 tests)
[lap 1/? ] step verified — persisting next step
[lap 2/? ] running step: implement loop_driver.start()
...
--execute flag: without it, the loop runs in dry-run mode — it plans and verifies but does not spawn real claude -p subprocesses. Use dry-run to inspect the plan before committing to execution.

Flags reference

FlagDefaultDescription
--execute off Spawn real claude -p subprocesses. Required for live runs.
--max-laps 50 Hard cap on laps per drive call. Loop halts cleanly at ceiling.
--guardrails auto Path(s) to guardrail YAML packs. Auto-discovers guardrails/ in project root.
--no-progress-halt 3 Halt if the same verify failure repeats N times in a row. Prevents burn loops.

Resume after any interruption

The loop stores the next queued step atomically before each lap ends. If the session ends, your machine restarts, or you manually kill the process — just run drive again with the same loop_id. It picks up exactly where it left off.

terminal 
# session ended, machine restarted — resume seamlessly
python -m sentigent.operator.loop_driver drive loop_83cc8641 --execute

resuming loop_83cc8641 at step 4/7 (3 verified, 0 asks)

Read the honest scoreboard

When the loop finishes (or at any point during a run), print the FAP receipt. It aggregates across all loops you've run — distance, fidelity, autonomy, and the headline FAP for each.

terminal 
python -m sentigent.operator.loop_driver receipt
SENTIGENT LOOP RECEIPT — Faithful Autonomous Progress across runs
────────────────────────────────────────────────────────────
loop              FAP  dist   fid  auto  asks  goal
loop_83cc8641   100%  100%  100%  100%     0  Write a pytest suite for loop_driver
────────────────────────────────────────────────────────────
1 loop  ·  1 completed  ·  mean FAP 100%  ·  paged you 0×

Every number in the receipt was logged by the loop itself during execution. Nothing is inferred or estimated. See the FAP doc for the full metric definitions.

Using from Claude Code (MCP)

The loop driver is also exposed over MCP so it's callable from inside a Claude Code session without switching to a terminal. The same durable state file backs both interfaces — starting a loop via MCP and driving it via CLI (or vice versa) works transparently.

claude code session 
# from inside a Claude Code session, call the MCP tools directly:

operator_start(goal="Ship feature X with passing tests")
# → { loop_id: "loop_83cc8641", status: "pending" }

operator_status(loop_id="loop_83cc8641")
# → { step: 3, total: 7, verified: 2, asks: 0, fap: 0.28 }

operator_resume(loop_id="loop_83cc8641")
# → drives the next lap inline

Adding guardrails

Drop a YAML file in guardrails/ in your project root. The loop driver picks it up automatically on the next drive call. See the Guardrails doc for the full format and available actions.

guardrails/my-org.yaml 
rules:
  - id: no-force-push
    match: "push --force|push -f"
    scope: bash
    action: block
    severity: critical

  - id: prod-deploy-gate
    match: "deploy --prod|kubectl apply"
    scope: bash
    action: approve
    severity: high

What to try next

← Guardrails Back to home →