Configuration¶

flower has no config file format, and no config subcommand that actually goes anywhere — all configuration is environment variables plus .env files, plus a batch of policy objects that can only be supplied from the Python side. This page gathers what's scattered across five places into one: every variable, the order credentials are looked up in, what syntax .env accepts, what setting_sources=[] actually isolates, what a single run leaves on disk, what each of the three session store layers drops, and how it waits when the network is down. Terminology follows the glossary throughout.

Full environment variable table¶

Five groups: credentials and endpoints flower reads directly, model selection, path lookup, behavior switches, and what flower writes to the agent subprocess. You don't set the last group — set it and it gets overwritten anyway.

Credentials and endpoints¶

If neither is set (or both are empty strings), check_credentials() returns that four-line error, and Runtime.__init__ also raises RuntimeError (env.py:184-194; runtime.py:156-158).

Model selection¶

flower reads only three of these for its own decisions; the rest are loaded and passed straight through to the SDK.

If flower setup filled in a model name, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, and ANTHROPIC_DEFAULT_SONNET_MODEL all three get written together (cli.py:1383-1385).

Paths and lookup¶

Behavior switches¶

Both are escape hatches: not setting them is the norm, setting them makes flower do one thing less. Any non-empty value takes effect; the value itself isn't parsed (update.py:121; cli.py:1413).

A flower run from git source isn't affected by auto-update; FLOWER_NO_UPDATE is a no-op for it — the update command recognizes a .git in the repo at that step and returns None immediately (update.py:83-87).

What flower writes to the agent subprocess¶

These three are generated by CompactPolicy.env() and stuffed into ClaudeAgentOptions.env (agent.py:48-58, :241-245), controlling the harness's built-in compact. Setting them in your shell means nothing — what actually takes effect is the copy flower passes to the subprocess.

What the container wrapper reads¶

These two aren't read by flower proper; they're read by the docker/flowerbox shell wrapper. See Deployment for full usage.

The keys in .env aren't limited to the above. The parser loads every k=v line into os.environ, with no allowlist (env.py:30, :102-107). The KNOWN set made up of the 9 credential keys above only does two things: acts as an allowlist when borrowing ~/.claude config (env.py:72), and bounds the fields printed by describe() when starting with -v (env.py:205).

Credential lookup priority¶

When load_dotenv() is called with no path, it reads every file that exists in the following order (env.py:45-53, :78-112):

1. Process environment variables — always highest. No .env can override an already-exported value. (env.py:91)
2. The file $FLOWER_ENV points at — only present if set. (env.py:48-49)
3. $PWD/.env — the current working directory. cd into a project and it reads the nearest one. (env.py:50)
4. ${XDG_CONFIG_HOME:-~/.config}/flower/.env — the per-user global location, the one flower setup writes. (env.py:51, :39-42)
5. The .env at the source repo root — three levels up from flower/core/env.py. Only present when running from source; a flower installed via pip / pipx / uv lives in site-packages and has no such file. (env.py:52)
6. The env block of ~/.claude/settings.json, then ~/.claude/settings.local.json — the last fallback, takes only the 9 credential keys. (env.py:56-75, :109-111)

Which file wins: entry 3 (project .env) beats entry 4 (global .env), entry 4 beats entry 5 (repo-root .env), all three beat entry 6 (Claude Code's config), and none of them beat entry 1 (the process environment).

The mechanism is "don't overwrite a key that already has a value" (env.py:90-93): the ones earlier in the order claim keys first, the later ones only fill gaps. So priority is computed per key, not per file — if the project .env only writes ANTHROPIC_BASE_URL, the token can still come from the global one. The first value that appears for a given key is settled for life.

Entry 6 is only enabled during automatic lookup. Give an explicit path (load_dotenv("/path/to/.env")) and it reads only that one file, with no fallback whatsoever (env.py:86-87, :109).

Entry 6: borrowing Claude Code's token¶

It reads ~/.claude/settings.json then ~/.claude/settings.local.json in order, takes the data["env"] dict, and picks out these 9 keys (env.py:31-36, :65-74):

ANTHROPIC_API_KEY   ANTHROPIC_AUTH_TOKEN   ANTHROPIC_BASE_URL
ANTHROPIC_MODEL     ANTHROPIC_DEFAULT_OPUS_MODEL    ANTHROPIC_DEFAULT_SONNET_MODEL
ANTHROPIC_DEFAULT_HAIKU_MODEL    CLAUDE_CODE_SUBAGENT_MODEL    CLAUDE_CODE_EFFORT_LEVEL

If the file doesn't exist, can't be read, or isn't valid JSON (OSError / ValueError), it returns an empty dict and moves on — a broken fallback shouldn't take the run down with it (env.py:62-63, :66-69).

The stance in the code: all it borrows is "where to find the token"; nothing else in settings.json (permission rules, hooks, model settings) is taken over, so this doesn't violate the portability promise of setting_sources=[] (env.py:17-19, :59-61). install.sh:77 pitches it as a feature: someone with Claude Code already configured on the machine won't even see the config screen.

flower 不读 ~/.claude/settings.json —— 那是可移植性的代价。

.env parsing rules¶

The parsing rules are short enough to memorize (env.py:95-107, 13 lines): strip each line, skip blank lines, lines starting with #, and lines with no =; split the rest at the first = into key and value, strip each side, then run the value through .strip("'\"") once — any leading or trailing single or double quotes are stripped, without requiring them to be paired.

Accepted forms:

Not accepted. Writing these raises no error, you just silently get an unexpected value:

An empty value claims the key. If ANTHROPIC_AUTH_TOKEN= appears in a higher-priority file, take() runs os.environ["ANTHROPIC_AUTH_TOKEN"] = "", and then later files can't fill it in because "the key already exists" (env.py:90-93); meanwhile check_credentials() tests for truthiness, so an empty string still counts as unconfigured (env.py:186). The result is neither credentials nor a fallback. If you don't want a key, delete the whole line — don't leave an empty one.

The cost of portability¶

That one line in build_options() is the whole mechanism (agent.py:207):

"setting_sources": [] if portable else ["project"],

portable=True is the default for Runtime, and no command-line switch can turn it off — to turn it off you have to go through the Python API and write Runtime(portable=False), which becomes ["project"], i.e. reads the project's .claude/.

What gets isolated¶

Domain capability doesn't go through this path — it ships with the repo, loaded via plugins=[{"type": "local", "path": PLUGIN_DIR}] (agent.py:26, :210-212), see Deployment. Domain instructions are appended after the native Claude Code system prompt, not a replacement (agent.py:198-202), so specialization doesn't cost you general capability.

What to carry when switching machines¶

• Credentials: one file. Copy ~/.config/flower/.env over, or reconfigure once on the new machine. Don't bring it and nothing runs — nothing gets inherited automatically.
• Continuity state: the whole directory. runs/ (session store, manifest, lineage) and .flower/ (workbench).
• But paths must match. lineage.json stores the workspace's absolute path; if it doesn't match it's treated as absent, silently falling back to a new session, with no error (lineage.py:65-66). The reason is that the SDK's project_key is derived from the workspace path (/, _, . all replaced with -, runtime.py:40-41); move the directory and the old session_id can no longer be found.

Disk layout¶

A single flower run writes two trees: <run_dir>/ holds the ledger and sessions, and <workspace>/.flower/ holds the workbench. Both default to under the current directory, but their bases differ.

<run_dir>/ — default ./runs/¶

runs/
  sessions.db        SQLite, full transcript (including each subagent's own)
  manifest.json      run manifest: each step's session_id / cost / retries / failure reason, accumulated across processes
  lineage.json       lineage: step name → session_id, reconnecting a re-run in the same directory relies on it
  aside/             the oracle's separate Runtime, its own sessions.db + manifest.json
  workbench/         only when going through the run / once path and given -W

Each line of manifest.json is asdict(StepResult) plus two patches (runtime.py:44-71, :579-582):

The write policy is append, don't overwrite: each flush re-reads the file, replaces the lines whose run equals its own with the latest, and leaves other lines untouched (runtime.py:564-586). So running multiple flowers in parallel in the same directory won't have their ledgers clobber each other.

The stuff in runs/ is pure data, readable offline anytime with sqlite3 or tools/analyze_run.py.

<workspace>/.flower/ — the workbench¶

.flower/
  INDEX.md      auto-generated index, injected into the main agent's system prompt
  scripts/      scripts to be run a second time. The first line `# desc: 一句话` appears in the index
  artifacts/    long outputs over 2000 characters: reports, data, logs
  notes/        cross-step decision records
  spill/        spilled large tool results, filename = first 16 chars of the content sha256 + `.txt`

The three subdirectories plus the index are created by Workbench (workbench.py:73-92). INDEX.md goes through the session-level system_prompt.append, which subagents can't inherit — so the rule "write long outputs to artifacts/" must be relayed by the coordinator in the task brief, that being the only channel.

The go path always generates these under notes/:

With --isolate the workbench moves outside the repo: <parent of workspace>/.flower-<workspace name>/ (starter.py:47-55). A worktree is each agent's private copy, the workbench is a shared layer across agents, and shared things can't go inside a private fence. In this case the path given to the model is absolute (workbench.py:69-71, :142-145).

spill/ has two writers, with different landing algorithms:

Under the default layout these are the same directory. But when the workbench is moved away (-W lands it in runs/workbench/, or --isolate lands it outside the repo) the two split apart — the TrimPolicy copy is always inside the workspace, because the agent's Read must be able to reach it.

What spill_guard swaps in isn't one line, it's one line of pointer plus the first 400 characters (guard.py:132-140). Calls that read the spill file itself are let through, otherwise "use Read to read the full text" is an empty phrase — read it back and it's over threshold again, spilled again, an infinite loop (guard.py:155-170).

The sessions.db schema¶

Three tables, the CREATE statements are in stores/sqlite.py:27-51:

CREATE TABLE entries (
    store_key TEXT NOT NULL,
    seq       INTEGER NOT NULL,
    uid       TEXT,
    payload   TEXT NOT NULL,
    PRIMARY KEY (store_key, seq)
);
CREATE UNIQUE INDEX entries_uid
    ON entries(store_key, uid) WHERE uid IS NOT NULL;
CREATE TABLE meta (
    store_key TEXT PRIMARY KEY,
    mtime     INTEGER NOT NULL,
    next_seq  INTEGER NOT NULL
);
CREATE TABLE summaries (
    project_key TEXT NOT NULL,
    session_id  TEXT NOT NULL,
    mtime       INTEGER NOT NULL,
    data        TEXT NOT NULL,
    PRIMARY KEY (project_key, session_id)
);

store_key is built (sqlite.py:54-58) as <project_key>/<session_id>, with subagents adding a further subpath. project_key is derived by the SDK from the workspace path — /, _, . all replaced with -.

Look at a real sample (human-test/HT002/runs/sessions.db):

sqlite3 runs/sessions.db "select store_key, next_seq from meta;"

-Users-hechenyu-explore-test-ide/601c8c91-6c4b-4525-8a5f-295b99bf9515|37
-Users-hechenyu-explore-test-ide/47395075-bec7-466e-80cd-f4d60b360235|80
-Users-hechenyu-explore-test-ide/47395075-…/subagents/agent-a99a6ce30a5471f44|104

That one has 956 entries, 10 meta, and 4 summaries — of the 10 sessions 4 are main transcripts, 6 are subagents', and summaries exactly equals the number of main transcripts.

The three session store layers¶

append (write) is always a full spill to disk, not a word changed. The three layers only affect load (the copy read back and fed to the model). The actual order of load is:

SqliteSessionStore.load     read out all entries from the entries table by seq
  → TrimmingSessionStore.expire()   time-sensitive Bash results → swapped for "expired"
  → TrimmingSessionStore.trim()     old large tool_results → spilled + swapped for a pointer
    → PruningSessionStore.prune()   synthetic error messages / old denied calls → removed wholesale and the chain relinked

Layer 2 is trim, layer 3 is prune — trim drops by size and value, prune drops by "is it an error", don't conflate them. Full signatures in the Python API.

SqliteSessionStore — the foundation¶

SqliteSessionStore(path: str | Path)

A SQLite implementation with zero external dependencies. To swap in Postgres / S3 / Redis, implement the same protocol; the SDK ships a conformance test suite claude_agent_sdk.testing.session_store_conformance you can validate against directly (sqlite.py:1-8).

Besides the protocol methods, there are three synchronous queries, for flower's own use:

TrimmingSessionStore + TrimPolicy / EphemeralPolicy¶

TrimmingSessionStore(path, workspace, policy: TrimPolicy | None = None,
                     ephemeral: EphemeralPolicy | None = None)

Two orthogonal rules. TrimPolicy handles size:

The trimmed body is written as <first 16 chars of sha256>.txt, and the original position is swapped for [工具结果已归档:N 字符。完整内容在 <路径>,需要时用 Read 读取] (trim.py:54-57, :308-317).

EphemeralPolicy handles timeliness: results from git status, ls, ps and the like are short, and by size would never get their turn to be trimmed, but their correctness decays over time — a git status from 20 turns ago isn't "useless", it's misleading.

Applies only to Bash tool results, and the command must match EPHEMERAL_CMD. Read isn't included: file contents don't distort into being misleading merely because time passes, and it may be exactly what the model's reasoning rests on (trim.py:153-160). Expired content is not spilled — archiving an expired git status is pointless, rerun it once and you have it.

The judging function is is_ephemeral(cmd), and it is also the permission list handed back to the coordinator: delegate_guard(allow_glance=True) uses the same function (trim.py:63-68, :128-150). The two sets must always be equal — allow it but don't trim it and an expired git status occupies context forever; trim it but don't allow it and the coordinator dispatches a subagent for a single ls, trading 4.3k of startup cost for a few dozen characters. Adding one command to the allowlist says both of those things at once.

When to use which:

• Want only disconnection debris kept out of context → do nothing, Runtime defaults to PruningSessionStore. trim=False just doesn't trim large results; removal still happens.
• Long runs, large tool output → trim=True. The go path CLI has it on by default, use --no-trim to turn it off in reverse.
• The coordinator has glance=True on → ephemeral must stay on, reasons in the previous paragraph.

PruningSessionStore + PrunePolicy¶

PruningSessionStore(path, workspace, policy: TrimPolicy | None = None,
                    prune: PrunePolicy | None = None,
                    ephemeral: EphemeralPolicy | None = None)

keep_denials is the only Runtime constructor argument passed straight through to this layer (Runtime(keep_denials=N)). The reason for defaulting to 1 rather than 0: the most recent denial is a valid signal, preventing the model from repeatedly retrying the same blocked command within a single turn. Don't raise it — a denied call was never executed, its result carries no information, and in measurement one occupies 273 characters (a 93-character refusal plus 180 characters of the dead command's text), and it misleads: in measurement, after the coordinator reads a few "don't use Bash directly" lines, it stops even trying an allowed git status and just says "Bash is restricted, dispatch an agent to look" (prune.py:135-148).

heal_orphans cures resume 400-ing every time after an interruption: the interruption breaks at a message boundary, the tool_use in flight at the time may have no tool_result following it at all, while the API requires the two to be paired. This bad history left in the transcript won't go away on its own, so every subsequent resume gets bounced by it. The fix is to insert a user entry after the assistant entry containing the orphan, filling in the results for all orphans in that entry at once, then reroute the parentUuid that originally pointed at that assistant to point at this inserted one (prune.py:95-147). Add, don't delete: deleting an orphan requires relinking the parent-child chain, and the same assistant entry may still hold valid blocks, text, and thinking that would get caught in the crossfire (prune.py:195-204).

Three structural red lines, violating which makes the API error out directly:

1. The tool_result block itself must be present, only content can be swapped. Miss one and it's "Missing Tool Result Block" (trim.py:20-22; prune.py:79-92).
2. isCompactSummary / isMeta entries can't be touched — that's the only form in which the compacted history exists (trim.py:179-181).
3. Remove an entry and you must reattach its children to its parent. The transcript is a single parentUuid chain, the harness walks back from the leaf, and wherever the chain breaks all the history before it is lost (prune.py:95-122). So relink() must receive the full list including the entry to be removed, and does the filtering itself.

Not one word of the original in SQLite is changed — the three layers only affect "the copy fed back to the model" (trim.py:18; prune.py:8).

Network resilience¶

A long-horizon workflow runs for hours at a stretch, and the network will drop at least once. The default behavior is bad: the moment it drops, the harness stuffs a synthetic assistant message into the transcript (model="<synthetic>", isApiErrorMessage=true), with the body API Error: Can't reach the API server …; it becomes the session's leaf, so a later resume feeds it back as "what the model said last", and the model thinks it's discussing a network failure; it also mixes into StepResult.text and passes down the workflow to the next step's prompt (resilience.py:1-22).

The resilience layer does three things, none optional: probe, resume instead of restart, keep errors out of context.

Resilience parameters¶

The backoff formula (resilience.py:119-121):

min(base_delay * 2 ** (attempt - 1), max_delay) * (0.75 + random() * 0.5)

That is ±25% jitter, avoiding a bunch of processes rushing in together the instant the network recovers. At defaults: the 1^st backoff is 4 seconds (actually 3–5), the 2^nd is 8 seconds (6–10), and from the 5^th it caps at 120 seconds (90–150).

Probe strategy¶

• What it probes is the host:port of ANTHROPIC_BASE_URL, not api.anthropic.com (resilience.py:67-72). With a self-hosted gateway, the latter being reachable says nothing about the former.
• DNS plus a TCP handshake only: getaddrinfo then connect_tcp then close immediately. No HTTP, no credentials, no cost (resilience.py:75-85). The probe must be free, otherwise "probing every 15 seconds while offline" itself becomes a failure.
• Any failure counts as unreachable — no distinction between DNS being down and TCP being refused.
• wait_online() hangs there waiting: returns True when reachable, returns False after a full max_offline_wait. On the first unreachability it notifies one line <host>:<port> 不可达,等待恢复(最多 60 分钟), and on recovery notifies one more line <host>:<port> 恢复,继续, without flooding the screen in between (resilience.py:126-140).

The credential probe before the run starts is a separate matter: it actually sends one POST <BASE_URL>/v1/messages, max_tokens=16, with a default timeout of 20 seconds (env.py:126-181). Don't set max_tokens to 1 — in measurement a model with forced chain-of-thought can't even fit its thinking, and the server struggles until 30 seconds before returning; set it to 16 and it takes only 3.6 seconds (env.py:120-123).

Error classification¶

classify(text) returns one of three. Judge fatal first: a 401 and the like often carry words like "connection" in their text too, and getting the order backwards causes a deadlock wait (resilience.py:53-64).

Distinguishing retryable from non-retryable is the core of this layer: network jitter should wait, a credential error should stop immediately — deadlock-waiting while offline is right, but deadlock-waiting on a mistyped key is just burning time.

What gets held out of context¶

1. Synthetic error messages. PruningSessionStore removes them wholesale at load and relinks parentUuid (prune.py:27-32, :191-195). Kept verbatim in SQLite, just not fed back.
2. In the event stream it's kind="error", not "text", so it doesn't enter StepResult.text, and therefore doesn't pass down the workflow into the next step's prompt (resilience.py:17-18).
3. resume_prompt deliberately contains no error detail. The model needs to know "you were interrupted, keep going", not whether it was ENOTFOUND or 503. That belongs in the log, not the context (resilience.py:112-113). For the log, look at the errors field of manifest.json.

Resume instead of restart: by the time the failure occurs the session_id is already in hand, use resume to reconnect from the interruption point, and the earlier cost isn't wasted.

Related¶

• Command line — how each switch maps to the configuration on this page.
• Python API — full signatures of Runtime, the three stores, and Resilience.
• Deployment — running in a container, distributing domain capability via a plugin.
• Glossary — the precise meaning of every term used on this page.