Documentation

Get Flywheel running.

Flywheel is open source (MIT). The standalone CLI needs only Python and git — no keys, no accounts — and the full demo sprint runs in about 60 seconds. This page covers install, the demo, running a real sprint for your company, and the approval workflow.

Quickstart Prerequisites Two ways to run Run a real sprint Approvals Verify install Chat mode Safety model Further reading

Quickstart: the 60-second demo

No Hermes, no API keys. Clone the repo, check your environment, and compile a full sample sprint for a fictional company (ExampleAI):

# 1. Get the code git clone https://github.com/ksimback/hermes-flywheel cd hermes-flywheel # 2. Confirm your environment is ready python skills/flywheel-agent/scripts/flywheel.py doctor # 3. Run the full demo sprint (no keys required) python skills/flywheel-agent/scripts/flywheel.py run --demo

The demo runs the whole deterministic pipeline — intake → launch → backlinks → leads → creators → spend cards → trends → sprint report → validation — and writes a complete reviewable sprint to demo/demo-output/weekly_flywheel_sprint.md.

Honest data provenance: the sample fixture data is used only when you pass --demo. Real runs never fall back to fabricated data — missing research means a section is skipped cleanly, not faked.

Prerequisites

✓Python 3.8+ and git — that's all you need for the CLI and the demo.
+SERPER_API_KEY (optional) — unlocks live backlink/listing and trend research via serper.dev.
+STRIPE_API_KEY (optional, test key sk_test_...) — real test-mode payment authorization cards. Live keys are always refused; nothing is ever charged.
+A leads CSV (optional) — your own warm-outbound targets.
+Hermes + a model provider (optional) — only for the chat / Slack / Telegram experience.

Flywheel runs on Linux, macOS, and Windows (the test suite runs on all three in CI).

Two ways to run Flywheel

Both paths use the same pipeline underneath. Pick the one that fits you:

A. Standalone CLI (start here)

What it is: run the Python pipeline directly from your terminal.

Needs: Python 3.8+ and git. Nothing else to try the demo.

Best for: trying Flywheel now, cron/automation, or wiring the pipeline into your own agent.

B. Chat agent (via Hermes)

What it is: the conversational GTM employee in terminal, Slack, or Telegram.

Needs: Hermes — a separate, external agent runtime from Nous Research — plus a model provider.

Best for: the "hire a GTM teammate" experience with live research and chat approvals.

Everything except the interactive chat surface runs standalone with no keys, so you can evaluate Flywheel end to end before deciding on Hermes.

Run a real sprint for your company

Standalone, no Hermes. The pipeline always produces launch planning and approval-gated spend cards from your product profile alone; each optional input adds another live section. Anything you don't supply is skipped cleanly — you get a partial sprint you can fill in and re-run.

# 1. (optional) Live backlink + trend research export SERPER_API_KEY=sk_your_serper_key # 2. (optional) Your warm-outbound targets # columns: name,title,company,bio,source,url,engagement_context cp data/leads.example.csv data/leads.csv # 3. Compile the sprint from your product context python skills/flywheel-agent/scripts/flywheel.py run \ "Product: MyCo (https://myco.com) ICP: <who you sell to> Competitors: rival-a.com, rival-b.com Budget: $500 Focus: outbound + launch" \ --leads-csv data/leads.csv

What each input unlocks in a real (non-demo) run:

Section

Requires

Without it

Launch plan

Your product profile (always)

Always included

Spend cards

Your product profile (always)

Included (simulated unless a Stripe test key is set)

Backlinks & trends

SERPER_API_KEY or your own --input JSON

Skipped

Warm outbound

--leads-csv <file> or data/leads.csv

Skipped

Creator campaigns

Agent research via --input (no headless source yet)

Skipped

Read the result in demo/demo-output/weekly_flywheel_sprint.md (or the folder you pass to --output-dir). Re-running for the same product continues the sprint and preserves your approvals; pass --new-sprint to start a fresh week.

Review and approve

Approvals are a persisted state machine (approvals.py) — real, durable state transitions enforced in code, not prompt-only concepts. Nothing can be approved or executed while the sprint is a draft, and only approved items can be executed.

# The flow: draft → review/edit → finalize → approve → execute python skills/flywheel-agent/scripts/approvals.py status # show current approval state python skills/flywheel-agent/scripts/approvals.py finalize # draft → finalized, unlocks execution python skills/flywheel-agent/scripts/approvals.py approve outbound # approve a section (or an item id)

Approval state lives in data/sprint_state.json with archived history in data/sprint_history.jsonl — both founder-local and gitignored. When the next sprint compiles, the prior sprint's approvals are archived and next week's focus is ordered by what you actually greenlit: more of what gets approved, less of what gets rejected.

Verify your install

Three commands confirm a fresh clone works end to end, no keys required:

python skills/flywheel-agent/scripts/flywheel.py doctor # environment/readiness python skills/flywheel-agent/scripts/flywheel.py run --demo # full ExampleAI sprint python -m pytest -q # full test suite

doctor should report Python OK and all scripts present; the demo should end with ✓ Sprint compiled to demo/demo-output/weekly_flywheel_sprint.md; the suite (161 tests) should pass. If all three succeed, the pipeline is working on your machine.

Chat mode (via Hermes)

What is Hermes? Hermes is a separate open agent runtime from Nous Research — it provides the chat interface, model connection, web research tools, and the Slack/Telegram gateway. It is not part of the Flywheel repository, and you only need it for chat mode. If Hermes or your model provider isn't set up, use the standalone CLI — you get the same sprint, driven by commands instead of chat.

# If Hermes is already installed hermes profile install github.com/ksimback/hermes-flywheel --alias --yes hermes -p flywheel-agent setup --portal flywheel-agent chat # Fresh machine: install Hermes first curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash hermes setup --portal

Then start with a prompt like:

Run a GTM sprint for ExampleAI. ICP: e-commerce founders. Competitors: CartPilot, ShopFlow, GrowthDock. Budget: $2k this week. Focus: warm outbound + creator distribution.

Flywheel replies with a short acknowledgement, works quietly, then returns a draft review dashboard. Useful commands inside the chat: help, review launch, review outbound, start walkthrough, edit <section>: <change>, finalize sprint, approve <section>, show approvals.

Safety model

Flywheel is intentionally approval-gated, and the gates are enforced in code:

✕No auto-DMs. No auto-email. No auto-posting. No autonomous spend.
✓External actions require explicit founder approval, backed by the persisted state machine.
✓Stripe cards are simulated by default ("simulated": true). With a genuine test key, real unconfirmed test-mode PaymentIntents are created — no payment method attached, manual capture, nothing ever charged. Live keys (sk_live_...) are refused outright.
✓Demo fixture data is only used when --demo is passed — real runs never fabricate data.
✓All sprint state is founder-local and gitignored. Nothing leaves your machine.