solo-founder-os 0.28.0

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 | 中文

Run your one-person company on YOUR keys, in YOUR language, on YOUR machine. Open-source alternative to closed SaaS agent platforms. 6-layer self-evolving stack. Local-first. Zero cloud infra. Sub-$0.06/week autonomous spend.

Why this exists. Cofounder 2, Devin, Lindy, and the next 10 SaaS agent platforms route your API calls through their billing layer, store your data in their cloud, and ship English-only. SFOS does the opposite: your keys, your disk, your language. 11 Python packages you pip install and import — or just one if you only want marketing-agent. No platform middleman.

The 11-agent stack at a glance

                    ┌──────────────────────────────────────┐
                    │   solo-founder-os (shared library)   │
                    │   eval · council · evolver · retro   │
                    └────────────────┬─────────────────────┘
                                     │
       ┌──────────────────┬──────────┴───────────┬──────────────────┐
       ▼                  ▼                      ▼                  ▼
  ┌─────────┐       ┌─────────┐            ┌─────────┐        ┌─────────┐
  │ marketing│      │customer- │           │  funnel- │       │  cost-  │
  │  agent  │       │discovery │           │analytics │       │  audit  │
  └─────────┘       └─────────┘            └─────────┘        └─────────┘
   distribute        find pain               watch                spend
                                             funnel              guardrail

       ┌──────────────────┬──────────────────────┬──────────────────┐
       ▼                  ▼                      ▼                  ▼
  ┌─────────┐       ┌─────────┐            ┌─────────┐        ┌─────────┐
  │   vc-   │       │customer-│            │payments │        │bilingual│
  │outreach │       │ support │            │  agent  │        │content- │
  └─────────┘       └─────────┘            └─────────┘        │  sync   │
   raise & sell     reply & triage         collect $          └─────────┘
                                                              EN ↔ 中文

       ┌──────────────────┐
       ▼                  ▼
  ┌─────────┐       ┌─────────┐
  │ build-  │       │ vibex-  │
  │ quality │       │publish  │
  └─────────┘       └─────────┘
   pre-push gate    HITL post to 抖音/小红书/B站

7 canonical layers — one agent per canonical solo-founder job: distribute, discover, watch, spend, raise/sell, support, collect, translate, ship-safely, publish. Each runs as its own PyPI package; install only what you need.

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.

What SFOS is not (so you can pick the right tool)

The agent-tooling space is crowded — here's where SFOS sits and where it doesn't.

• Not an agent framework. If you're building a custom multi-agent workflow from scratch, use OpenRath (PyTorch-style Session/Workflow primitives), LangGraph, or CrewAI. SFOS is the application layer — a fixed 11-agent stack you install and run, not primitives you compose into your own runtime. You could build SFOS-on-OpenRath; we just don't, because cron + JSONL files solve our use case without the abstraction tax.
• Not a hosted SaaS. Cofounder 2 and similar take your prompts through their billing layer, store state on their cloud, and (so far) ship English-only. SFOS is the opposite shape: your API key calls Anthropic directly, your ~/.<agent>/ state lives on your laptop, and Chinese-language docs + prompts are first-class.
• Not for teams. No project/seat/role model. The CLI assumes one human approving the HITL queue. Multi-person workflows would need a different governance surface than sfos-inbox.
• Not real-time. Agents wake on Sunday-morning cron and process queued work in batches. If you want sub-second response-loop agents, use a chat-style runtime, not SFOS.

If those constraints fit a one-person company shipping at a sustainable pace, read on.

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 — cron, eval, reflexion, AnthropicClient, HITL queue, notifiers. Each agent is independently useful; together they cover the full one-person company workflow.

🌐 The whole stack is live in production at vibexforge.com.

Agent	What it does
build-quality-agent	Pre-push Claude 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 founder brief + real-time PH-day alerts across 9 sources.
orallexa-marketing-agent	AI marketing agent — submit project once, get platform-native posts for X / Reddit / HN / Dev.to / 小红书 + 7 more. Powers vibexforge.com.
vc-outreach-agent	Cold email drafter — investors (vc mode) or paying customers (customer mode, merged from customer-outreach in v0.9.0). HITL queue + SMTP sender.
cost-audit-agent	Monthly bill audit across 6 providers (Vercel / Anthropic / OpenPanel / HyperDX / Supabase / GitHub Actions) with dollar-tagged waste findings.
bilingual-content-sync-agent	EN ⇄ 中文 i18n diff + Claude translate + HITL apply. Batch API path @ 50% off.
customer-support-agent	Triage user messages → auto-draft replies → HITL queue. Closes the L5 customer-support layer.
payments-agent	Overdue-invoice reminder drafter. Stripe-shaped types + MockProvider fallback + hard money-safety prompt rules.

Each agent's own row is omitted from its README. Install whichever solve real problems for you — pip install <agent-name>.