Run is the entry point for the CLI. Returns an exit code.

SpawnTab opens a new iTerm2 tab with the given title, cwd, and command. envVars are attached as an inline prefix to `command` only — so they are prese

UninstallSessionStartHook removes any SessionStart entry whose inner command matches `command`.

UninstallSkill removes the skill directory for this harness.

UninstallUserPromptSubmitHook removes any UserPromptSubmit entry matching `command`. Used by `flow skill uninstall`.

addOwner implements `flow add owner "<name>" --work-dir <p> --every <dur>`.

addPlaybook implements `flow add playbook "<name>" [flags]`.

autoCell builds the AUTO column in table output: the run status, with the supervisor pid appended for a running run (so the user can see / act on it a

autoRunColor maps an autonomous-run status to a display color: running → cyan (in flight), completed → green, dead → red (needs eyes).

bgAgentInRegistry returns the registry entry for sessionID (any state: working / blocked / idle / done / failed / stopped), or nil if the session is a

bgAgentsJSONExited builds a registry entry for an exited session (no pid / status — `state` only), as `claude agents --json --all` reports a stopped/f

bgPlaybookContext computes (playbookSlug, isFirstRun) for a task's bootstrap prompt, mirroring the interactive bootstrap path. Returns ("", false) for

buildAppleScript activates Warp, waits for the new tab from `open warp://...` to take key focus, then keystrokes `bash <scriptPath>` + Return into the

buildCloseoutSweepPrompt composes the headless prompt that drives the post-done close-out sweep. The prompt is passed as a single positional arg to `c

buildScript produces the bash script body that the keystroked `bash <path>` line invokes. Shape: #!/bin/bash rm -- "$0" printf '\033]2;%s\007' '<t

classify maps a tool_use block to a lookup kind. The bool is false when the block is not a lookup (or is an own-bootstrap read we skip).

clearOwnerTickBookkeeping clears tick_pid/tick_started without recording a tick result — used when a dispatched tick is skipped (e.g. owner no longer

cmdDoBackground is the $FLOW_TERM=bg branch of `flow do`. It spawns (or resumes) a terminal-free background agent via the harness's BackgroundLauncher

cmdHook dispatches `flow hook <subcommand>`. Two subcommands: - session-start: wired as a Claude Code SessionStart hook so that every session start (

cmdUpdateProject implements `flow update project <ref> [--priority <p>]`. Project field edits are minimal — priority is the only post-creation field w

cmdUpdateTask implements `flow update task <ref> [--work-dir <path>] [--mkdir] [--status <s>] [--assignee <name>] [--due-date <date>] [--waiting ...]

cmdWorkdirAdd registers <path> (making it absolute), auto-detects git remote from .git/config, and upserts. Accepts --name and --description anywhere

cmdWorkdirList prints all registered workdirs sorted by last_used_at descending (NULLs last). Each row is rendered across two output lines when a desc

cmdWorkdirRemove deletes a workdir row. Does not touch the filesystem and does not null out tasks.work_dir.

cmdWorkdirScan walks a root (or ~/code and ~/work by default) up to 3 levels deep, finds .git directories, and either prints candidates or upserts the

computeAvgKBFileBytes returns the average byte size of *.md files in kbDir. Returns 0 if the directory is missing or empty.

---- helpers ----

countKBFacts counts entry lines (starting with "- ") across kb/*.md.

dirSize sums the byte sizes of files with the given extension under dir. Returns 0 if the directory is missing or empty.

emitAmbientSkillHint is the unbound-session branch of the SessionStart hook. The user has installed flow — a personal task/ session manager and knowle

ensureUpdatesDir is a small utility used in tests to pre-create an updates directory. Kept here so tests can share it without exposing internals elsew

extractWorkdirBoolFlag removes a bare boolean flag anywhere in args and returns (found, remaining). Named specifically to avoid collisions with parall

fileSize returns the byte size of the file at path, or 0 if it does not exist.

focusByTTY drives Terminal.app's AppleScript dictionary to find a tab whose `tty` property matches and select it. Terminal.app addresses tabs at the w

focusByTTY drives iTerm2's AppleScript dictionary to find a session whose `tty` property matches and select it (and its enclosing tab and window). The

formatDueDateInfo returns a parenthetical like "(in 3 days)", "(today)", or "(overdue by 2 days)" for display next to the date.

formatToolInput returns a compact one-line summary of a tool call's input.

gradientText renders text filled with the flow wave gradient onto a tightly-sized transparent image.

humanizeLastUsed renders last_used_at as "(used 2d ago)" / "(never used)".

isAccessibilityDenied reports whether an osascript failure looks like a missing-Accessibility-permission error. Matches the same fragments as internal

isValidStatus checks the task status enum.

launchAutoRun creates the per-run log directory, starts the detached supervisor via autoLauncher, and returns (pid, logPath). It does NOT touch the DB

lookupBoundTaskSlug returns the slug of the bound task, or "" if the session is unbound. Thin wrapper over lookupBoundTask.

migrateTasksSessionIDUnique creates the partial unique index on tasks(session_id) WHERE session_id IS NOT NULL. Older DBs may have two tasks sharing a

migrateTasksSessionInvariant rebuilds the tasks table to enforce `CHECK (status = 'backlog' OR session_id IS NOT NULL)`. SQLite does not support addin

normalizeTags canonicalizes each tag and drops empties, preserving order.

notesCell builds the trailing NOTES column in table output. Each fragment is colored independently so the row reads well at a glance. waitMax > 0 trun

ownerNext implements `flow owner next <slug> --in <dur> | --at <when>`: set the owner's next tick time. This is how a tick SELF-PACES — at the end of

ownerPause stops an owner from ticking while preserving all its state.

ownerRetire implements `flow owner retire <slug> [--delete]`. Graceful retire (default) marks the owner status='retired' + archived: it stops ticking

ownerStart marks an owner active and schedules its first tick now, so the next scheduler pass picks it up. Then it ticks every Every.

ownerTickDue implements `flow owner tick-due`: the scheduler pass that the OS timer (launchd) invokes on an interval.

paneIDForHarnessSession parses zellij list-panes JSON and returns the pane id of the first non-plugin pane whose pane_command mentions `binary` and ca

parseOwnerWhen accepts an RFC3339 timestamp or a date expression (YYYY-MM-DD, today, tomorrow, weekday, Nd) for `flow owner next --at`.

printPlaybookMetadata writes the human-readable view of a playbook row.

printProjectMetadata writes the human-readable view of a project row.

---------- pretty printers ---------- printTaskMetadata writes the human-readable view of a task row.

reconcileOwnerTick promotes a stale running tick to 'dead' when its supervisor pid is no longer alive (crash, kill, reboot — anything that prevented r

recordAutoRunLaunched writes the 'running' bookkeeping after a successful launch.

recordOwnerInteractiveTick marks a hand-triggered interactive tick as having run (last_tick_* only). It leaves next_wake_at untouched so the interacti

recordOwnerTickDispatched is recordOwnerTickStarted plus advancing the schedule floor (next_wake_at) — the scheduler dispatch path.

recordOwnerTickStarted stamps the running-tick bookkeeping (pid + start) for a hand-triggered headless tick. It does not advance the schedule.

registeredHarnessNames returns the comma-joined list of harness Names this binary supports. Used in error messages so the user sees the available alte

relativeWake formats an RFC3339 wake time relative to now, e.g. "(in 22m)" or "(overdue 5m)". Returns "" if ts can't be parsed.

resolveEditRef resolves a ref that could be a task, project, or playbook. Supports task/, project/, and playbook/ prefixes. Includes archived rows.

resolveGitConfigPath returns the absolute path to the git config for a repo rooted at path, or "" if none exists. Handles both the common case (.git i

resolveProjectRef resolves a ref to a project. Includes archived rows.

scaleImage resizes src to w×h using high-quality resampling.

showPlaybookCmd implements `flow show playbook [<ref>]`.

showProjectCmd implements `flow show project [<ref>]`. With no argument, falls back to the project of the task bound to the current Claude session.

showTaskCmd implements `flow show task [<ref>]`.

staleDaysThreshold returns the staleness threshold in days. Reads FLOW_STALE_DAYS env var; defaults to 3.

statsWithoutAutomation returns a Stats value where automation is zero.