Yoak is the harness for your cofounder agent ⸻ the one you talk to when you're searching for a repeatable business. Reinforced context including essays from Paul Graham, textbooks from Steve Blank, and curated interviews with Steve Jobs provide valuable founder level discussion about the most important parts of your startup. Yoak asks the hard questions, tracks what you've actually validated, and won't let you confuse hope for evidence.
Yoak is not a frontier model. It's a cofounder harness around the model you choose (Ollama locally by default, or Claude/GPT/DeepSeek via API). The harness is what makes it Yoak:
- Persistent memory — Lean Canvas, hypotheses, learning journal
- Structured workflows — idea evaluation, customer discovery, validation, pivot decisions
- Encoded frameworks — PG instincts + Blank Customer Development + Jobs taste
- Interfaces — terminal chat, web dashboard, Obsidian export
You interact with Yoak, your cofounder agent. Under the hood, an orchestrator assembles context from your startup's state, calls your configured LLM, and writes what you learn back to SQLite.
| Generic LLM chat | Yoak |
|---|---|
| Forgets your canvas between sessions | Remembers canvas, hypotheses, and journal |
| Gives encouraging advice | Pushback-focused cofounder persona |
| No structured phases | Customer Development workflows with steps |
| You manage the process | Agent routes to workflows and skills automatically |
Every startup begins with untested assumptions. Most founders execute instead of learning — building features nobody wants, scaling before finding fit, ignoring the hard questions.
Yoak encodes three complementary worldviews as the cofounder agent's operating system:
| Layer | Thinker | Role in Yoak |
|---|---|---|
| Instincts | Paul Graham | How to evaluate ideas, recognize what matters, use growth as a compass |
| Methodology | Steve Blank | Customer Development — the structured search for a repeatable business model |
| Taste | Steve Jobs | Product quality, simplicity, starting from the customer experience |
The result is an AI cofounder that asks the questions you're avoiding, challenges your assumptions with frameworks, and keeps you honest about what's validated versus what's hoped for.
Copy and paste this into your terminal:
git clone https://github.com/Schellbach/yoak.git && cd yoak && makeThat's it, one line. It clones the repo, installs everything, and drops you into a conversation with your cofounder agent. The web dashboard starts in the background. No API key needed. First run takes about a minute; every run after is instant.
export ANTHROPIC_API_KEY="sk-ant-..." # or OPENAI_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, ZHIPUAI_API_KEY
make init # picks up the key, lets you switchmake # start chatting (web UI starts in the background)
make chat # go straight to chat (web UI starts in the background)
make serve # start only the web dashboard (foreground)
make canvas # print your Lean Canvas
make hypotheses # list hypotheses
make journal # show your learning journal
make export ARGS="--vault ~/Obsidian/MyVault" # one-way Obsidian export
make init # reconfigure model, project name, etc.
make help # show all commandsThe first time you run make or make chat, Yoak builds the dashboard with npm (Node.js required once) and starts it in the background at http://127.0.0.1:8420. Use make serve if you only want the web UI without terminal chat.
- Python 3.10+
- Ollama (free local AI) is offered during first-run setup.
- Web UI requires Node.js 18+
Yoak is a cofounder agent harness: interfaces and orchestration on top, swappable LLM on the bottom, startup memory in the middle.
┌─────────────────────────────────────────────────────────────────┐
│ INTERFACES │
│ Web Dashboard (React) CLI (Typer) │
└──────────┬───────────────────────────────┬──────────────────────┘
│ │
┌──────────▼───────────────────────────────▼──────────────────────┐
│ API LAYER │
│ FastAPI (31 endpoints) WebSocket (streaming chat) │
└──────────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────────┐
│ YOAK AGENT HARNESS │
│ │
│ Agent Orchestrator ─── assembles system prompt from: │
│ ├─ Philosophy Engine (PG + Blank + Jobs) │
│ ├─ Memory Context (canvas, hypotheses, journal) │
│ ├─ Workflow Context (active step + prompt supplement) │
│ └─ Skill Context (market analysis, user research, etc.) │
│ │
│ Workflow Router ─── detects intent, dispatches to: │
│ ├─ 6 Workflows (idea eval, discovery, validation, ...) │
│ └─ 5 Skills (market, competition, growth, economics, ...) │
└──────────┬──────────────────────────────┬───────────────────────┘
│ │
┌──────────▼──────────┐ ┌──────────────▼───────────────────────┐
│ MEMORY (SQLite) │ │ MODEL LAYER (swappable) │
│ │ │ │
│ Lean Canvas │ │ LiteLLM (Anthropic, OpenAI, │
│ (9 blocks) │ │ DeepSeek, Google, Zhipu, …) │
│ Hypothesis Tracker │ │ Ollama (llama, mistral, │
│ + status history │ │ codellama, gemma, phi, …) │
│ Learning Journal │ │ │
│ (incl. pivots) │ │ Not part of Yoak — you choose │
└─────────────────────┘ └────────────────────────────────────┘
Paul Graham — Instincts (source essays)
- The "well, not field" test — prefer desperate need from a few over mild interest from many
- Schlep blindness bypass — scary ideas are undervalued signals
- Growth as compass — target 5-7% weekly, measure rate not absolute
- Anti-patterns: sitcom startups, premature scaling, big launch fallacy, playing house
- "Relentlessly resourceful" — the goal is fixed, the path is fluid
Steve Blank — Methodology (source writing)
- Customer Development 4-phase state machine (Discovery → Validation → Creation → Building)
- Lean Canvas as a living hypothesis board (9 blocks, each testable)
- MVP type selection (concierge, wizard of oz, landing page, single-feature, pre-order)
- Pivot decision framework with 10 pivot types and structured criteria
- Product/Market Fit measurement (Sean Ellis test, retention curves, LTV/CAC)
- Interview protocols: problem interviews, solution interviews, debrief synthesis
- 2026 concepts: MVP → MPO (Minimum Productive Outcome), P/M Fit → Agent/Customer Outcome Fit
Steve Jobs — Taste
- "Start with the customer experience, work backwards to technology"
- Simplicity as highest sophistication — strip until only the essential remains
- Focus means saying no to 100 good ideas
- Craft: quality must be consistent throughout, even in hidden details
- Empathy + Focus + Impute as the product evaluation triad
| Workflow | Steps | What It Does |
|---|---|---|
| Idea Evaluation | 5 | PG filters, Lean Canvas mapping, riskiest assumption, scoring |
| Customer Discovery | 5 | Hypothesis review, interview planning, debrief, solution testing, phase gate |
| Customer Validation | 6 | MVP development, earlyvangelist sales, sales roadmap, unit economics, P/M Fit, phase gate |
| Pivot Decision | 5 | Evidence review, signal analysis, diagnosis, pivot type selection, new hypothesis |
| PMF Assessment | 3 | Qualitative signals, quantitative metrics, diagnosis |
| Product Critique | 4 | Experience-first review, simplicity audit, focus/quality audit, verdict |
Workflows are state machines — each step injects specific prompts that guide the conversation. The agent automatically routes to the right workflow based on what you're discussing.
| Skill | What It Provides |
|---|---|
| Market Analysis | TAM/SAM/SOM sizing, market type classification, timing analysis |
| User Research | Interview script generation, problem/solution templates, insight synthesis |
| Competitive Intel | Competitor mapping, moat analysis, the "do nothing" competitor |
| Growth Strategy | Growth engine selection (sticky/viral/paid), metric frameworks, PG growth principles |
| Unit Economics | CAC/LTV modeling, burn rate, payback period, the "default alive" test |
All state is stored in a local SQLite database (~/.yoak/yoak.db):
- Lean Canvas — Problem, Solution, Unique Value Proposition, Unfair Advantage, Customer Segments, Cost Structure, Revenue Streams, Channels, Key Metrics
- Hypothesis Tracker — lifecycle management:
untested → testing → validated/invalidated, with linked evidence entries and status history - Learning Journal — append-only log with types: learning, pivot, decision, milestone, interview, experiment
- Phase Tracker — which Customer Development phase you're in (discovery, validation, creation, building)
Memory context is injected into every conversation turn, so the agent always knows your current canvas state, active hypotheses, and recent learnings.
Start with make, make chat, or yoak serve. The war room runs at http://127.0.0.1:8420 with six views:
- Overview — Customer Development phase tracker, hypothesis stats (untested/testing/validated/invalidated), active workflow progress, recent activity
- Chat — Streaming conversation with the cofounder agent, workflow phase indicator, suggested starter prompts
- Canvas — Visual 9-block Lean Canvas with inline editing, version snapshots, compare mode, and per-block hypotheses
- Hypotheses — Full list of testable beliefs with status filters, evidence, and links back to canvas blocks
- Journal — Filterable timeline of learnings, pivots, decisions, experiments with inline creation
- Settings — Model provider configuration (cloud + Ollama), temperature, project name
yoak chat — Interactive terminal chat with the cofounder agent
yoak serve — Start the API server + dashboard
yoak init — First-time setup or reconfigure (project name, model)
yoak canvas — Display the current Lean Canvas
yoak hypotheses — List hypotheses linked to the Lean Canvas
yoak journal — Show recent learning journal entries
yoak export — Export memory to an Obsidian vault (one-way)
yoak config — Manage configuration (show, set)
In chat mode (CLI only), slash commands are intercepted before they reach the model:
| Command | Description |
|---|---|
/canvas |
Print the current Lean Canvas |
/workflow |
Show active workflow, or start one: /workflow idea_evaluation |
/advance |
Manually advance the active workflow step |
/phase |
Show current phase, or set it: /phase validation |
/chatreset |
Clear conversation history and active workflow |
/canvasreset |
Clear canvas blocks and hypotheses |
/reset |
Clear chat, canvas, and learning journal (full fresh start) |
/model |
Show the configured model |
/quit |
Exit chat |
The dashboard uses buttons and API calls instead of slash commands. In chat, you can also ask naturally (e.g. “show the canvas”) — that is handled by the agent, not the slash-command router.
Export Yoak's SQLite memory (Lean Canvas, hypotheses, evidence, journal, pivots) into an Obsidian vault as markdown plus a JSON Canvas file. Direction is DB → vault only. The vault output is generated and disposable; Yoak never reads it back.
yoak export --vault ~/Obsidian/MyVault
yoak export # uses saved vault path from config
yoak export --project mango-trees # output under <vault>/yoak/mango-trees/
yoak export --force # regenerate without confirmationOutput layout:
<vault>/yoak/<project-slug>/
Dashboard.md
<project-slug>.canvas
canvas/01 Problem.md … 09 Key Metrics.md
hypotheses/H-<id>-<slug>.md
journal/YYYY-MM-DD.md
pivots/P-<id>-<slug>.md
Rules:
- Files Yoak writes include
yoak_managed: truein frontmatter. - Yoak skips any existing file that is not yoak-managed (prints a warning).
- Re-export deletes stale yoak-managed hypothesis/pivot/journal files whose IDs or dates no longer exist in the DB.
- Hypothesis status history is tracked in SQLite and exported under
## History.
Yoak defaults to Ollama (free, local, private — no API key needed). To upgrade to a frontier model, just set an API key and run yoak init.
| Provider | Model String | Setup |
|---|---|---|
| Ollama (default) | ollama/llama3.1 |
brew install ollama && ollama pull llama3.1 |
| Anthropic | anthropic/claude-sonnet-4-20250514 |
export ANTHROPIC_API_KEY=... |
| OpenAI | gpt-4o |
export OPENAI_API_KEY=... |
| DeepSeek | deepseek/deepseek-chat |
export DEEPSEEK_API_KEY=... |
gemini/gemini-2.5-pro |
export GEMINI_API_KEY=... |
|
| Zhipu (GLM) | zhipuai/glm-4-flash |
export ZHIPUAI_API_KEY=... |
| Mistral | mistral/mistral-large-latest |
export MISTRAL_API_KEY=... |
Any model supported by LiteLLM works. Run yoak init to switch models at any time.
yoak/
├── pyproject.toml # Package definition, dependencies
├── README.md
├── yoak/
│ ├── core/
│ │ ├── agent.py # Main orchestrator — routes through philosophy + workflows
│ │ ├── router.py # Intent detection → workflow/skill dispatch
│ │ └── config.py # YAML-backed settings with env var support
│ ├── models/
│ │ ├── provider.py # Unified LiteLLM + Ollama interface
│ │ └── streaming.py # Streaming chunk accumulator
│ ├── philosophy/
│ │ ├── graham.py # PG heuristics as callable prompt modules
│ │ ├── blank.py # Customer Dev methodology + phase guidance
│ │ ├── jobs.py # Product design principles + critique
│ │ └── synthesis.py # Combined context builder + intent detection
│ ├── memory/
│ │ ├── store.py # SQLite schema + connection management
│ │ ├── canvas.py # Lean Canvas CRUD + summary renderer
│ │ ├── hypotheses.py # Hypothesis lifecycle, evidence, status history
│ │ └── journal.py # Learning journal + phase management
│ ├── export/
│ │ ├── runner.py # One-way Obsidian vault export orchestration
│ │ ├── writers.py # Markdown note builders (canvas, hypotheses, journal, pivots)
│ │ └── canvas.py # JSON Canvas file for Obsidian
│ ├── workflows/
│ │ ├── base.py # Base workflow state machine
│ │ ├── idea_evaluation.py # 5-step PG-inspired idea scoring
│ │ ├── customer_discovery.py # Blank Phase 1
│ │ ├── customer_validation.py # Blank Phase 2
│ │ ├── pivot_decision.py # Structured pivot-or-persevere
│ │ ├── pmf_assessment.py # Product/Market Fit measurement
│ │ └── product_critique.py # Jobs-inspired quality review
│ ├── skills/
│ │ ├── market_analysis.py # TAM/SAM/SOM, market types
│ │ ├── user_research.py # Interview scripts, synthesis
│ │ ├── competitive_intel.py # Competitor mapping, moats
│ │ ├── growth_strategy.py # Growth engine, metrics
│ │ └── unit_economics.py # CAC/LTV, burn rate
│ ├── prompts/
│ │ ├── system/ # 4 system prompts (cofounder identity, PG, Blank, Jobs)
│ │ ├── workflows/ # 6 workflow prompts (idea eval, discovery, validation, ...)
│ │ └── skills/ # 5 skill prompts (market, interviews, competition, ...)
│ ├── api/
│ │ ├── app.py # FastAPI app with 31 routes
│ │ └── routes/ # Endpoint modules (chat, canvas, hypotheses, journal, ...)
│ └── cli/
│ └── main.py # Typer CLI with Rich formatting
└── dashboard/
├── package.json
└── src/
├── App.tsx # Router + icon sidebar
├── api/client.ts # Full API client + WebSocket
└── pages/ # Overview, Chat, Canvas, Hypotheses, Journal, Settings
When you send a message to the cofounder agent, Yoak:
- Detects intent — maps your message to a workflow (multi-step) or skill (single-turn)
- Assembles context — builds a system prompt from:
- The master cofounder identity prompt
- Relevant PG/Blank/Jobs principles (based on your topic)
- Your current Lean Canvas state
- Recent learning journal entries
- Active workflow step (if any) with its specific guidance prompt
- Or the relevant skill prompt (if routed to a skill)
- Calls your model — sends the assembled messages to the LLM you configured (not baked into Yoak)
- Streams the response — via WebSocket (dashboard) or terminal (CLI)
- Persists what matters — canvas updates, hypotheses, and journal entries land in SQLite
The cofounder persona is consistent across all interactions: direct, honest, occasionally uncomfortable — like a great cofounder who asks the hard questions.
The API runs on http://127.0.0.1:8420 with interactive docs at /docs.
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/chat |
Send a message, get a response |
WS |
/api/ws/chat |
Streaming chat via WebSocket |
POST |
/api/chat/reset |
Clear conversation history and active workflow |
GET |
/api/chat/history |
Get conversation messages |
GET |
/api/canvas |
Get all 9 Lean Canvas blocks with hypotheses |
PUT |
/api/canvas/{block_id} |
Update a canvas block |
POST |
/api/canvas/reset |
Clear canvas blocks and hypotheses |
GET |
/api/hypotheses |
List hypotheses (filter by block, status) |
POST |
/api/hypotheses |
Create a hypothesis |
PATCH |
/api/hypotheses/{id} |
Update status/confidence |
POST |
/api/hypotheses/{id}/evidence |
Add evidence to a hypothesis |
DELETE |
/api/hypotheses/{id} |
Delete a hypothesis |
GET |
/api/journal |
List journal entries (filter by type) |
POST |
/api/journal |
Create a journal entry |
GET |
/api/phase |
Get current Customer Development phase |
PUT |
/api/phase |
Set phase (discovery/validation/creation/building) |
GET |
/api/workflows |
List available workflows |
POST |
/api/workflows/start |
Start a workflow by name |
POST |
/api/workflows/advance |
Advance to next workflow step |
POST |
/api/workflows/cancel |
Cancel active workflow |
GET |
/api/config |
Get current configuration |
PUT |
/api/config |
Update a configuration value |
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run the linter
ruff check yoak/
# Run the dashboard in dev mode (hot reload)
cd dashboard && npm run devYoak stores configuration in ~/.yoak/config.yaml (override with YOAK_DIR env var). project_name is your startup's name — not "yoak" (Yoak is always the agent; your startup is what you're building).
model:
provider: ollama
model: ollama/llama3.1
temperature: 0.7
max_tokens: 4096
ollama:
enabled: true
base_url: http://localhost:11434
model: llama3.1
server:
host: 127.0.0.1
port: 8420
export:
vault_path: null # saved after first successful yoak export
project_slug: null # defaults to slugified project_name
project_name: My StartupMIT