{"id":51270013,"url":"https://github.com/halaprix/hermes-flywheel","last_synced_at":"2026-06-29T17:01:11.059Z","repository":{"id":357208903,"uuid":"1235758823","full_name":"halaprix/hermes-flywheel","owner":"halaprix","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-11T19:19:51.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T21:27:44.781Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/halaprix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-11T16:17:32.000Z","updated_at":"2026-05-11T19:20:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/halaprix/hermes-flywheel","commit_stats":null,"previous_names":["halaprix/hermes-flywheel"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/halaprix/hermes-flywheel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halaprix%2Fhermes-flywheel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halaprix%2Fhermes-flywheel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halaprix%2Fhermes-flywheel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halaprix%2Fhermes-flywheel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/halaprix","download_url":"https://codeload.github.com/halaprix/hermes-flywheel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halaprix%2Fhermes-flywheel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34935530,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-29T17:01:07.491Z","updated_at":"2026-06-29T17:01:10.994Z","avatar_url":"https://github.com/halaprix.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hermes Flywheel\n\n\u003cp align=\"center\"\u003e\n  \u003cpre\u003e\n   ██╗  ██╗███████╗██████╗ ███╗   ███╗███████╗███████╗    ███████╗██╗  ██╗   ██╗██╗    ██╗██████╗ ██╗  ██╗███████╗███████╗██╗\n   ██║  ██║██╔════╝██╔══██╗████╗ ████║██╔════╝██╔════╝    ██╔════╝██║  ╚██╗ ██╔╝██║    ██║██╔══██╗██║  ██║██╔════╝██╔════╝██║\n   ███████║█████╗  ██████╔╝██╔████╔██║█████╗  ███████╗    █████╗  ██║   ╚████╔╝ ██║ █╗ ██║██████╔╝███████║█████╗  █████╗  ██║\n   ██╔══██║██╔══╝  ██╔══██╗██║╚██╔╝██║██╔══╝  ╚════██║    ██╔══╝  ██║    ╚██╔╝  ██║███╗██║██╔══██╗██╔══██║██╔══╝  ██╔══╝  ╚═╝\n   ██║  ██║███████╗██║  ██║██║ ╚═╝ ██║███████╗███████║    ██║     ███████╗██║   ╚███╔███╔╝██║  ██║██║  ██║███████╗███████╗██╗\n   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚══════╝╚══════╝    ╚═╝     ╚══════╝╚═╝    ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚══════╝╚═╝\n  \u003c/pre\u003e\n  \u003cem\u003eA beads task-graph MCP server for \u003ca href=\"https://github.com/NousResearch/hermes-agent\"\u003eHermes Agent\u003c/a\u003e\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.11+-blue\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/hermes-agent-mcp-purple\" alt=\"Hermes MCP\"\u003e\n\u003c/p\u003e\n\n---\n\nPlan-first, bead-driven development for Hermes Agent. Reverse-engineered from Jeff Emanuel's [Agentic Coding Flywheel](https://agent-flywheel.com/) — the same methodology that shipped 20,000+ lines of production Go in a single day with coordinated AI swarms.\n\nTracks work as **beads** (self-contained tasks with dependency graphs) in a flat JSONL file. A pure-Python graph engine runs PageRank, critical path, and betweenness centrality so agents know exactly which bead to work on next. No Dolt, no SQLite, no daemons. No VPS required.\n\n```\nPlan → Beads → Triage → Execute → Land → Repeat\n```\n\n## Why a flywheel?\n\nBecause flat TODO lists don't know what blocks what. A bead graph tells you:\n\n- **Which task unblocks the most downstream work** (PageRank)\n- **The longest dependency chain** determining project minimum time (critical path)\n- **Where your bottleneck sits** (betweenness centrality)\n- **What you can safely work on** right now without stepping on anyone's toes\n\nAn agent with a flat list picks whatever looks interesting. An agent with a bead graph picks the mathematically optimal next step.\n\n## Install\n\n### Quick (uvx — zero install)\n\n```bash\nuvx hermes-flywheel\n```\n\n### From source\n\n```bash\ngit clone https://github.com/halaprix/hermes-flywheel.git\ncd hermes-flywheel\npip install .\n```\n\n### Docker\n\n```bash\ndocker run -v $(pwd):/workspace -e FLYWHEEL_PROJECT_ROOT=/workspace ghcr.io/halaprix/hermes-flywheel\n```\n\n## Wire into Hermes\n\nAdd to `~/.hermes/config.yaml`:\n\n```yaml\nmcp_servers:\n  flywheel:\n    command: uvx\n    args: [\"hermes-flywheel\"]\n    env:\n      FLYWHEEL_PROJECT_ROOT: \"/path/to/your/project\"\n```\n\nOr for a local clone:\n\n```yaml\nmcp_servers:\n  flywheel:\n    command: python\n    args: [\"-m\", \"hermes_flywheel.server\"]\n    env:\n      PYTHONPATH: \"/path/to/hermes-flywheel\"\n      FLYWHEEL_PROJECT_ROOT: \"/path/to/your/project\"\n```\n\nRestart Hermes. You should see `mcp_flywheel_beads_*` tools in your session.\n\n## Usage\n\nLoad the skill:\n\n```\n/skill flywheel\n```\n\nThe agent now operates in flywheel mode. Planning happens before any code is written. Work is tracked as beads with dependencies. Graph analytics tell the agent what to work on next.\n\n### Quick start — your first beads\n\n```\nbeads_create(title=\"Add auth middleware\", type=\"feature\", priority=1)\nbeads_create(title=\"Add login UI\", type=\"feature\", priority=2)\nbeads_update(bead_id=\"bd-xxx\", dependencies=[\"bd-yyy\"])\nbeads_ready()          → what can I work on?\nbeads_triage()         → what should I work on? (robot_next)\nbeads_update(bead_id=\"bd-xxx\", claim=\"agent-1\")   → mine now\n# ... do the work ...\nflywheel_land(bead_id=\"bd-xxx\")                   → done, clean exit\n```\n\n### Formulas — reusable workflows\n\nPour a formula into a molecule. The formula expands into a hierarchy of beads with dependencies:\n\n```\nformula_install(\"feature\")\nformula_pour(\"feature\", {\"feature_name\": \"dark mode\"})\n```\n\nBuilt-in formulas: `feature`, `bugfix`, `refactor`, `release`. Define your own in `.beads/formulas/*.formula.toml`.\n\n## Tools\n\n| Tool | What it does |\n|------|-------------|\n| `beads_create` | Create a bead with deterministic hash ID |\n| `beads_update` | Update status, dependencies, claim, metadata |\n| `beads_list` | List beads with optional filters |\n| `beads_ready` | Beads you can work on right now |\n| `beads_triage` | Full graph analytics: robot_next, critical path, bottlenecks, cycles |\n| `beads_remember` | Store knowledge in bead metadata (no separate MEMORY.md) |\n| `flywheel_land` | Shutdown protocol: close, checklist, follow-ups |\n| `flywheel_stats` | Summary statistics |\n| `formula_pour` | Expand a formula into a molecule |\n| `formula_list` | List available formulas |\n| `formula_install` | Install a built-in formula |\n\n## Storage\n\nAll beads live in `.beads/issues.jsonl`. One JSON object per line. Git-friendly. Writes use `os.replace()` for atomicity — the file is either old or new, never a half-written mess.\n\n## How it fits into Hermes\n\nThe flywheel layers on top, replacing nothing:\n\n- **Planning**: converts plans to beads with graph dependencies\n- **Execution**: tells you which beads to delegate, then you spawn subagents with `delegate_task`\n- **Memory**: adds structured per-task memory via `beads_remember` — cleaner than `MEMORY.md`\n- **Kanban**: different beast. Kanban is for multi-profile work queues. Flywheel is for graph-driven single-project execution\n\nLoad `/skill flywheel` when you want graph intelligence. Don't load it for quick file edits.\n\n## Credits\n\nMethodology: [Jeff Emanuel](https://github.com/Dicklesworthstone) (Dicklesworthstone).  \nOriginal beads: [gastownhall/beads](https://github.com/gastownhall/beads).  \nReverse-engineered and adapted for Hermes by [@halaprix](https://github.com/halaprix).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalaprix%2Fhermes-flywheel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhalaprix%2Fhermes-flywheel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalaprix%2Fhermes-flywheel/lists"}