solo-founder-os 0.27.4

Shared base library for the Solo Founder OS agent stack — Source/MetricSample, baseline w/ rotation, HTTP retry, Anthropic client, notifiers (ntfy/Telegram/Slack), brief composer, testing helpers.

solo-founder-os

English | 中文

The 6-layer self-evolving agent stack a one-person company actually runs. Local-first. Zero cloud infra. Sub-$0.06/week autonomous spend.

What it does

Solo Founder OS is the shared library + CLI suite that runs the 11-agent indie-founder stack. Five things no other agent platform does together:

1. Reads plain Python agents. No SDK injection. Agents write JSONL/markdown to ~/.<agent>/; SFOS tails those files. No re-instrumentation.
2. Closes the L1↔L4↔L5↔L6 self-improving loop end-to-end. Reflexion logs feed an evolver that opens PR-gated proposals; an eval judge surfaces quality drift; a council deliberates on severe drops; the council's conclusions flow back into the evolver's Haiku prompt. All on cron.
3. Local-first observability. sfos-ui is a Streamlit dashboard reading the same JSONL files — no Phoenix instance, no Langfuse Docker, no LangSmith account.
4. Cron-aware, not request-aware. Built for agents that wake up Sunday morning, not real-time chatbots. Avoids the alert-fatigue anti-pattern.
5. Solo-founder framing. "What needs you today" inbox, not enterprise team/project hierarchy.

Quick start

pip install 'solo-founder-os[anthropic,ui]'

# Schedule the weekly self-improvement loop on launchd:
sfos-cron install   # pre-flight will refuse if SFOS isn't pip-installed
# Sun 08:00  sfos-eval         judge skills with Sonnet
# Sun 08:30  sfos-council      multi-perspective on severe drift
# Sun 09:00  sfos-evolver      Haiku synthesizes PR proposals
# Sun 09:30  sfos-retro        cross-agent weekly digest

# Open the local dashboard:
sfos-ui
# → http://localhost:8501

# Sync state across machines via git:
sfos-sync init [e-mail]:you/sfos-state.git
sfos-sync push

That's it. No accounts. No cloud. Cost ceiling $0.06/week.

Production install (from source)

Until PyPI Trusted Publishing is configured per repo, install editable from your local clone:

git clone https://github.com/alex-jb/solo-founder-os.git ~/Desktop/solo-founder-os
cd ~/Desktop/solo-founder-os
pip install --user -e '.[anthropic,ui]'

pip install -e matters: launchd's neutral CWD won't see a dev tree otherwise. sfos-cron install runs a sterile-import pre-flight that refuses to write plists when this hasn't been done. Pass --ensure-pip-install to make it auto-fix:

sfos-cron install --ensure-pip-install

If your stack agents' console scripts (e.g. payments-agent, vc-outreach-agent) don't appear on PATH after install, the binaries landed in ~/Library/Python/<version>/bin/ which most shells don't include. Easiest fix:

ln -s ~/Library/Python/3.9/bin/payments-agent ~/.local/bin/
# (repeat per agent, or symlink the whole dir)

The 6-layer self-improving loop

L1  Reflexion         ─┐  log_outcome(agent, task, FAILED, signal)
L2  Supervisor        ─┤  launchd cron driver
L3  Skills            ─┤  record_example(skill, inputs, output)
L4  Evolver           ─┼─→  Haiku synthesizes PR proposals from
L5  Council           ─┤    L1 patterns + L6 drift, with L5 council
L6  Eval (Sonnet)     ─┘    deliberation injected as prompt context

Every Sunday morning the loop runs:

1. 08:00 — sfos-eval judges the last 5 record_example rows per skill using a 5-axis Sonnet rubric (clarity / specificity / voice / accuracy / completeness). Persists per-skill scores. Detects drift > 0.5 vs prior week.
2. 08:30 — sfos-council --auto-from-drift convenes a BUG_TRIAGE meeting (3 perspectives + 1 synthesis) for any skill whose mean dropped

   0.7. Saves notes to council-meetings/.

3. 09:00 — sfos-evolver scans reflexion logs for ≥3× recurring failure patterns AND reads L6 drift signals. For each, it asks Haiku for a concrete fix. If the L5 council deliberated on this skill, the synthesis is injected into the Haiku prompt as additional context — the patch reflects multi-angle reasoning, not one-shot guess. Output: markdown artifacts in evolver-proposals/ (PR-gated; never auto-merged).
4. 09:30 — sfos-retro walks every agent's reflexion / preference / skill data and produces ONE markdown digest answering: who's running, what's each failing at most, which skills are bubbling up, which variants are winning their bandits.

Costs: ~$0.04/week for evals + ~$0.01/week for evolver + ~$0.005/week for council meetings (when drift is severe). Total <$0.06/week.

ICPL preference learning through the Inbox

The sfos-ui Inbox tab is the canonical HITL approval surface. When you edit a draft before clicking ✅ Approve, the diff is logged as an ICPL (In-Context Preference Learning) pair to ~/.<agent>/preference-pairs.jsonl.

Next time the same agent drafts a similar task, preference_preamble() pulls those pairs as few-shot exemplars in the system prompt. The agent drifts toward your voice without you writing a single new prompt.

Task disambiguation: task field in frontmatter wins; falls back to platform (marketing-agent uses this for X / LinkedIn / Reddit), then kind, then <slug>-draft.

CLI suite

CLI	What it does
sfos-doctor	Health-check all known agent dirs
sfos-supervisor	L2 — find work for agents (auto-trigger)
sfos-evolver	L4 — propose PR-gated patches from reflexion + drift
sfos-council	L5 — multi-agent deliberation; --auto-from-drift mode
sfos-eval	L6 — Sonnet judges record_example rows
sfos-retro	Cross-agent weekly digest
sfos-bus	Cross-terminal markdown broadcast
sfos-inbox	HITL governance rail (CLI alternative to sfos-ui)
sfos-cron install	Schedule the 4-job Sunday loop on launchd
sfos-ui	Local Streamlit dashboard (4 tabs)
sfos-sync	Multi-machine git-based sync of ~/.solo-founder-os/

The stack (11 agents, 7 canonical layers)

Layer	Agent
1. Content / marketing	orallexa-marketing-agent
2. Customer support	customer-support-agent
3. Customer discovery	customer-discovery-agent
4. Customer outreach (cold sales)	customer-outreach-agent
5. Investor outreach	vc-outreach-agent
6. Analytics + cost	funnel-analytics-agent, cost-audit-agent
7. Monetization	payments-agent
(cross-cutting)	build-quality-agent, bilingual-content-sync-agent

Each agent is its own pip package + CLI + optional MCP server. They share this library for HITL queue, Anthropic client, reflexion logging, skill distillation, and the L1–L6 loop primitives.

Test isolation

Set SFOS_TEST_MODE=1 in your test suite's conftest.py:

# tests/conftest.py
import os
os.environ.setdefault("SFOS_TEST_MODE", "1")

This gates log_outcome, record_example, and log_edit from writing to ~/.<agent>/ during pytest. Without it, agent test fixtures pollute production reflexion data and feed false-positive proposals to L4 evolver. (All 8 stack agents already adopt this.)

Privacy

• All state lives in ~/.<agent>/ and ~/.solo-founder-os/.
• sfos-sync ships a default .gitignore that excludes usage.jsonl, cron-logs/, cron/, bandit.sqlite so Stripe-shaped tokens, cost logs, and per-machine state never reach a remote git repo.
• The Anthropic client logs cost (input/output tokens) to usage.jsonl — never the prompt content.
• The L4 evolver's safety gate refuses any patch touching auth, secret, credential, smtp, stripe, billing, anthropic_client, or migrations paths even if Haiku tries to suggest them.

Why these design choices

• Streamlit, not React/FastAPI — research showed solo founders use ~30 min/day across 2 batches; real-time monitoring is alert-fatigue anti-pattern at this volume. st.fragment(run_every="3s") gives "live feel" via local polling, no second process.
• Vertical timeline of file events, not chat-bubble metaphor — SFOS agents communicate ASYNCHRONOUSLY via files. Chat bubbles would misrepresent the architecture.
• Default cron threshold 0.7 for council, 0.5 for evolver — councils cost ~5 Haiku calls each. Stricter trigger keeps weekly autonomous spend under $0.06 even if drift is constantly firing.
• PR-gated, never auto-merged — the evolver writes markdown artifacts for review. Hard whitelist + blocklist on what files can be touched.

Status

v0.26 (2026-05-02). Production loop is live on the maintainer's machine; first auto-fire 2026-05-04 Sunday. 504 tests across the library; 1100+ tests across the full 11-agent stack.

License

MIT. Use freely.

🧩 Part of the Solo Founder OS stack

A growing collection of MIT-licensed agents that share solo-founder-os as their base — Source/MetricSample contracts, HITL queue, AnthropicClient, notifiers, scheduler. Each agent is independently useful; together they cover the full solo-founder workflow.

Agent	What it does
build-quality-agent	Pre-push diff reviewer + local build runner — catches CI-killing changes before they ship
customer-discovery-agent	Reddit pain-point scraper + Claude clustering for product validation
funnel-analytics-agent	Daily brief + real-time alerts across 9 sources (Vercel, GitHub, Supabase, etc.)
vc-outreach-agent	Investor cold email drafter with HITL queue + SMTP sender
cost-audit-agent	Monthly bill audit across 6 providers with dollar-tagged waste findings
bilingual-content-sync-agent	EN ⇄ ZH i18n diff + Claude translate + HITL apply
orallexa-marketing-agent	AI marketing agent for OSS founders — auto-generate platform-specific marketing posts

Each agent's own row is omitted from its README. Install whichever solve real problems for you.