flower¶
A portable long-horizon agent framework built on the Claude Agent SDK.
Turn Claude Code into a dedicated agent you can carry with you, customize the interaction of, and run for days — without giving up any of its capability. The agent on the main thread only makes decisions; all the hands-on work goes to subagents. Requirements get clarified before work starts, and whether the work is actually done is judged by a different role. Move to another machine and the behavior is identical — it does not read the host's settings, and it brings its own credentials.
The four numbers come from HT001 — the run in which an agent wrote a terminal IDE from scratch under flower.
One command to install, no Node required¶
The script finds uv / pipx / pip on its own and installs the flower command. All you need is Python ≥ 3.10 — the Claude Code CLI is not required either. Once installed, cd into any project directory and type flower: the first time it asks for an API key or a gateway address, you configure it once, it is stored in ~/.config/flower/.env, and it applies everywhere. If Claude Code is already installed and configured on this machine, it borrows that token directly and does not even ask. Full steps and troubleshooting in Install.
It blocks four classes of failure for you¶
Clarify¶
Afraid of building the wrong thing — before any work starts, a role that only asks questions and never touches anything keeps asking until things are clear, then freezes the requirements into a document that every later step reads at the start.
Goal guard¶
Afraid it will claim done when it is not — at the end of every round of work a separate role judges independently: achieved, move on; not achieved, send it back; can't be verified in this environment, stop and ask a human.
Continuity¶
Afraid of hours of work crashing and starting over — type flower again in the same directory and it picks up where it left off, the same whether the process was killed or the machine rebooted, and you do not have to remember any id.
What makes it "long-horizon"¶
The coordinator on the main thread carries only decisions and does not get Write or Edit — writing code, running tests, looking things up all go to subagents, and a subagent's trial and error goes into another transcript; the main thread only receives a report of no more than 30 lines. In that 10.4-hour HT001 run, 94.8% of body characters landed in subagents, and of 1,893 hands-on tool calls only 32 ever entered the coordinator's view. That is why the main thread only grew to 185.9K after 70 rounds and never compacted once — how this layer works, and what the other three layers are, see Context economics.
Raw records of two real long runs¶
- HT001 — writing a terminal IDE from scratch. $171.62 / 10.4 hours / main-thread context grew to 185.9K, delivered 12,212 lines of product code, lost the network once mid-run and finished on its own.
- HT002 — getting it installed and running on macOS. $38.24 / about 1 hour, the first run with the goal guard; the program did start up, and the verdict was not achievable, so it surfaced and asked a human.
Both pages also write down what does not hold up: in HT001 the agent judged one of its own acceptance items wrong, and HT002 turned git clone && make && ./cppide into an hour. Every number can be recomputed from runs/manifest.json and sessions.db — these are records, not marketing.
Where to start reading¶
- Want to run it right now — Quickstart: three commands to get it running, then how to read what scrolls past on screen.
- Want the concepts first — Core concepts: runs, steps, sessions, the five roles, all in five minutes.
- Want to wire it into your own code — Python API:
Runtime,Step, the five role factories, signatures and defaults for all 62 public symbols.