Solo Founder Os

solo-founder-os

English | [中文](README.zh-CN.md)

> 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.

[](LICENSE) [](https://pypi.org/project/solo-founder-os/) [](#)

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](#the-stack-11-agents-7-canonical-layers). Five things no other agent platform does together:

1. Reads plain Python agents. No SDK injection. Agents write JSONL/markdown

to ~/./; SFOS tails those files. No re-instrumentation.

1. 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.

1. Local-first observability. sfos-ui is a Streamlit dashboard

reading the same JSONL files — no Phoenix instance, no Langfuse Docker, no LangSmith account.

1. Cron-aware, not request-aware. Built for agents that wake up Sunday

morning, not real-time chatbots. Avoids the alert-fatigue anti-pattern.

1. 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 ~/./ 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

Not sure which agents to install first? All 11 agents on day one is overwhelming. Fork into an audience track first:

• [Indie hacker](docs/ONBOARDING-BY-AUDIENCE.md#track-1-indie-hacker) — marketing + funnel + cost-audit + vc-outreach (4 agents)
• [OSS maintainer](docs/ONBOARDING-BY-AUDIENCE.md#track-2-oss-maintainer) — build-quality + marketing + bilingual-sync + customer-support (4 agents)
• [Freelance dev](docs/ONBOARDING-BY-AUDIENCE.md#track-3-freelance-dev) — payments + customer-support + cost-audit + marketing (4 agents)
• [Research lab](docs/ONBOARDING-BY-AUDIENCE.md#track-4-research-lab) — customer-discovery + bilingual-sync + build-quality + marketing + funnel (5 agents)

Or install the shared library and run sfos-doctor to get a per-agent recommendation:

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 git@github.com: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//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.

1. 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/.

1. 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).

1. 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 **/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 -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 ~/./ 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 ~/./ 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 .

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: alex-jb
• Source: alex-jb/solo-founder-os
• License: MIT
• Homepage: https://vibexforge.com

Install and usage instructions live in the source repository linked above.