[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11496":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":13,"stars7d":13,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":15,"starSnapshotCount":15,"syncStatus":13,"lastSyncTime":27,"discoverSource":28},11496,"flow","Facets-cloud\u002Fflow","Facets-cloud","Turn isolated Claude sessions into a continuous working relationship",null,"Go",133,12,2,20,0,13,6,49.64,"MIT License",false,"main",true,[],"2026-06-12 04:00:55","# flow\n\n![Status](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fstatus-alpha-orange) ![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue.svg)\n\n> A complete task manager for Claude Code — and the working memory\n> layer that turns every session from a brilliant new hire into the\n> engineer on your team.\n\n## See it in action\n\nA four-act demo of how flow compounds context across days and tasks.\nThe work is silly on purpose — Star Trek bridge starships — so the\nmechanic is what you watch, not the code.\n\n**Act 1 — Capture the work.** Just talk. flow interviews you for\nwhat \u002F why \u002F where \u002F done-when, drafts a structured brief, and opens\na dedicated Claude session for the task in a new tab.\n\n![Act 1 — task intake](docs\u002Fdemo\u002F01-task-intake.gif)\n\n**Act 2 — Work, then park.** The session has the brief, the project\ncontext, and the knowledge base loaded. You build until you hit a\nblocker — here, \"Kirk needs to review this\" — and tell Claude to\npark it. Status flips to `waiting`. Tab can close.\n\n![Act 2 — execution and park](docs\u002Fdemo\u002F02-task-execution.gif)\n\n**Act 3 — Resume and close.** A day later you say \"Kirk signed off.\"\nSame session resumes with full memory of where it left off. `flow\ndone` flips status and triggers the sweep — Claude re-reads the\nwhole transcript and writes durable facts (Kirk approved the design,\nthe ship class, the conventions used) into the knowledge base.\n\n![Act 3 — approval and close](docs\u002Fdemo\u002F03-approval-and-close.gif)\n\n**Act 4 — Months later, a new captain.** New task: \"Picard's the new\nboss, he wants the starship as an SVG.\" Brand new session, but it\nalready knows the ship, knows the design choices Kirk approved,\nknows the project conventions — because the KB carried it. Claude\njust gets to work.\n\n![Act 4 — Picard's SVG upgrade](docs\u002Fdemo\u002F04-picard-svg-upgrade.gif)\n\nThat fourth session is what flow is really about. Not the first\nsession — the fiftieth.\n\n## Why flow\n\nIf you use Claude Code daily, you've felt the ceiling: every session\nis a new hire. Brilliant, capable, ready to help — but with no memory\nof yesterday's decisions, last week's migrations, or the half-finished\nthreads in your other tabs. You spend the first ten minutes of every\nsession catching it up.\n\nflow changes the relationship. It's a complete task manager —\nprojects, tasks, structured briefs, progress notes, playbooks for\nrecurring work — *and* a working memory layer that injects all of it\ninto every Claude session automatically. Capture once, work with\nClaude on it forever.\n\nThe first session feels normal. By session ten, Claude knows your\ncodebase quirks, your team, the customer you keep mentioning, and\nthe migration you're three steps into. By session fifty, it's the\nengineer on your team — not a new hire you re-explain yourself to\nevery morning.\n\nBuilt for power users who want Claude to *work with them*, not just\n*help them*.\n\n## How context compounds\n\nEvery task feeds the same knowledge base. Every closed task makes\nthe next one smarter.\n\n```\n                                       ┌────────────────────────┐\n                                       │   ~\u002F.flow\u002Fkb\u002F          │\n                                       │   user · org · products│\n                                       │   processes · business │\n                                       └─────▲──────────▲───────┘\n                                             │          │\n                  flow do \u003Ctask>             │ scoop    │ sweep\n   ┌────────┐  ─────────────────▶  ┌─────────┴──────────┴─────┐\n   │  Task  │                      │      Claude session      │\n   │  brief │  ◀──── updates ───── │  loads brief + kb +      │\n   │ +notes │                      │  notes + repo conventions│\n   └────────┘  ─── flow done ───▶  └──────────────────────────┘\n                                       (auto-sweep transcript\n                                        into kb on done)\n```\n\n- **Scoop (live):** during a session the flow skill listens for\n  durable facts you mention — your role, a teammate's name, a\n  product convention — and appends them to the matching kb file\n  on the fly.\n- **Sweep (on `flow done`):** when you close a task, flow spawns\n  a headless Claude pass that re-reads the entire transcript and\n  pulls anything kb-worthy that the live scoop missed. The status\n  flip is the contract; the sweep is best-effort.\n- **Cross-reference:** `flow transcript \u003Csibling-task>` lets a\n  current session read what was decided in a related one — useful\n  when the brief alone doesn't carry enough context.\n\nNet effect: the longer you use flow, the more your knowledge base\ngrows, the less you re-explain yourself.\n\n## Playbooks for the work you do on cadence\n\nSome work repeats. Weekly reviews. Daily PR triage. On-call rotations.\nCustomer-meeting prep.\n\nA **playbook** is a reusable run definition — a markdown brief that\ndescribes what a run does. `flow run playbook weekly-review` snapshots\nthat brief into a fresh task and spawns a new Claude session against\nit. Every run is reproducible (it executes against a frozen snapshot,\nso editing the playbook later doesn't rewrite history) and contributes\nback to the knowledge base on `flow done` like any other task.\n\n```\n┌──────────┐  flow run playbook weekly-review\n│ Playbook │ ────────▶ snapshot ─────▶ new task ─────▶ new session\n│  brief   │           (frozen for                     (executes\n└──────────┘            reproducibility)                against snapshot)\n```\n\nSame compounding mechanic — your weekly review session two months from\nnow will know everything every prior weekly review surfaced.\n\n## Install\n\nIn any Claude Code session, paste this:\n\n> Install flow from https:\u002F\u002Fgithub.com\u002FFacets-cloud\u002Fflow\n\nClaude reads the repo, downloads the binary, and runs `flow init` —\nwhich installs the flow skill into `~\u002F.claude\u002Fskills\u002Fflow\u002FSKILL.md`\nand registers a SessionStart hook so every future Claude session\nloads the skill automatically. Then say **\"let's get to work\"** and\nfollow along.\n\n\u003Cdetails>\n\u003Csummary>Manual install (curl + chmod + flow init)\u003C\u002Fsummary>\n\n```bash\n# 1. Download the binary for your Mac.\nARCH=arm64        # Apple Silicon (M1\u002FM2\u002FM3\u002FM4) — use amd64 for Intel.\n\ncurl -fsSL -o \u002Fusr\u002Flocal\u002Fbin\u002Fflow \\\n  \"https:\u002F\u002Fgithub.com\u002FFacets-cloud\u002Fflow\u002Freleases\u002Flatest\u002Fdownload\u002Fflow-darwin-${ARCH}\"\nchmod +x \u002Fusr\u002Flocal\u002Fbin\u002Fflow\nxattr -d com.apple.quarantine \u002Fusr\u002Flocal\u002Fbin\u002Fflow 2>\u002Fdev\u002Fnull || true\n\n# 2. Initialize. This is required — it creates ~\u002F.flow\u002F, the SQLite\n#    index, the knowledge base, AND installs the Claude skill +\n#    SessionStart hook. Without this step, Claude can't talk to flow.\nflow init\n```\n\n`flow init` is the step that wires flow into Claude Code. It:\n\n- Creates `~\u002F.flow\u002F` (database, kb, projects, tasks, playbooks)\n- Writes the flow skill to `~\u002F.claude\u002Fskills\u002Fflow\u002FSKILL.md`\n- Adds a SessionStart hook to `~\u002F.claude\u002Fsettings.json` so every new\n  Claude Code session auto-loads the skill\n\nThe `xattr` step removes Gatekeeper's quarantine attribute so macOS\ndoesn't refuse to run the unsigned binary.\n\n\u003C\u002Fdetails>\n\n## Upgrade\n\nIn any Claude Code session:\n\n> Upgrade flow from https:\u002F\u002Fgithub.com\u002FFacets-cloud\u002Fflow\n\nClaude fetches the latest release binary and runs `flow skill\nupdate` to refresh the skill and re-wire the SessionStart and\nUserPromptSubmit hooks. Check the running version with\n`flow --version`.\n\n## Quickstart\n\nJust open Claude and say **\"let's get to work\"**. The skill\nhandles the rest.\n\n## What you get\n\n- **One task, one Claude session, one tab.** `flow do \u003Ctask>`\n  spawns a dedicated tab in iTerm2, Warp, stock macOS Terminal, kitty\n  (requires `allow_remote_control yes` in `kitty.conf`), or your\n  current zellij session (requires zellij ≥ 0.40) — flow picks\n  whichever you launched it from. Override with\n  `FLOW_TERM=warp|iterm|terminal|zellij|kitty` when you're on a\n  non-standard host. Tomorrow's `flow do \u003Ctask>` resumes the same\n  conversation.\n- **Interview-driven task capture.** No forms. flow asks\n  what \u002F why \u002F where \u002F done-when, then writes a structured brief.\n- **A knowledge base that grows.** Five markdown buckets for\n  durable facts about you, your team, products, processes, and\n  customers. Live-appended during sessions; auto-swept from\n  transcripts on `flow done`.\n- **Per-task progress notes.** Append-only logs. Pick up where\n  you left off, even after a week away.\n- **Playbooks for cadence work.** Weekly reviews, daily triage,\n  on-call rotations — define once, run on demand.\n- **A Claude skill that speaks plain English.** \"What should I\n  work on\", \"resume auth\", \"save a note\" — the skill turns intent\n  into flow commands.\n\n## How it works under the hood\n\n`flow do \u003Ctask>` pre-allocates a session UUID, writes it to the\ntask row, and spawns a tab in zellij (when `$ZELLIJ` is set), kitty\n(when `$KITTY_WINDOW_ID` is set or `$TERM=xterm-kitty`), the backend\nnamed in `$FLOW_TERM` (when set), or Warp \u002F iTerm2 \u002F stock\nTerminal.app (auto-detected from `$TERM_PROGRAM`) — chosen in that\npriority order, with iTerm as the historical fallback — running\n`claude --session-id \u003Cuuid>` with `FLOW_TASK` \u002F `FLOW_PROJECT` inlined.\nThe jsonl file lands at the deterministic path\n`~\u002F.claude\u002Fprojects\u002F\u003Cencoded-cwd>\u002F\u003Cuuid>.jsonl`, so future\n`flow do` calls run `claude --resume \u003Cuuid>` to continue the same\nconversation. A SessionStart hook re-injects the task brief,\nupdates, and CLAUDE.md context on every resume; a UserPromptSubmit\nhook keeps the flow skill discoverable in ad-hoc Claude sessions.\n\nThe first `flow do` from stock Terminal.app needs macOS Accessibility\npermission for the **app hosting your shell** — not the `flow` binary\nitself. Terminal.app's AppleScript dictionary has no \"make new tab\"\nverb, so flow drives cmd-T through System Events, and System Events\nchecks Accessibility against the responsible parent app. Until that's\ngranted, `flow do` errors out with a multi-line explanation pointing at\nSystem Settings → Privacy & Security → Accessibility (enable the\ntoggle for \"Terminal\" if you launched flow from Terminal.app, \"iTerm\"\nfrom iTerm2, \"Claude\" if Claude Code is the host, etc.; add it via the\n+ button if it's not listed). After the grant the spawn is silent.\niTerm2 doesn't need this — it has a native `create tab` verb.\n\n### One-shot instructions with `--with`\n\n`flow do \u003Ctask> --with \"\u003Cinstruction>\"` resumes (or starts) the task's\nsession and injects the instruction as the first user message —\nprefixed with `[via flow do --with]` so the model can tell injected\ninput from typed input.\n\n`--with-file \u003Cpath>` is the same idea for longer instructions: instead\nof embedding the file contents, flow injects `read instructions at\n\u003Cabsolute path>` and the session uses its Read tool to load the file.\nNo size limits. The flags are mutually exclusive, and cannot be\ncombined with `--here` (there's no spawned session to inject into).\n\n```bash\n# Nudge a parked task without opening the tab.\nflow do auth --with \"check if upstream PR merged and update the brief if so\"\n\n# --with on a done task auto-rolls it back to in-progress, so playbooks\n# can fire on previously-closed work.\nflow do auth --with \"are we still blocked on the security review?\"\n\n# Hand the session a longer brief to follow.\nflow do auth --with-file ~\u002Fplaybooks\u002Ftriage-checklist.md\n```\n\nThis is the lane scheduled playbooks use to fire instructions at\nexisting tasks without manual intervention. `flow run playbook \u003Cslug>`\naccepts the same flags for ad-hoc per-run instructions.\n\n## Your data — local, portable, yours\n\nEverything flow stores lives under `~\u002F.flow\u002F` (override with\n`$FLOW_ROOT`). No server, no cloud, no telemetry. Plain markdown\nbeside a SQLite index — readable in any editor, versionable in git.\n\n```\n~\u002F.flow\u002F\n  flow.db                          # SQLite — projects, tasks, playbooks index\n  kb\u002F\n    user.md  org.md  products.md\n    processes.md  business.md      # 5 markdown buckets, append-only\n  projects\u002F\u003Cslug>\u002F\n    brief.md\n    updates\u002FYYYY-MM-DD-*.md\n  tasks\u002F\u003Cslug>\u002F\n    brief.md\n    updates\u002FYYYY-MM-DD-*.md\n  playbooks\u002F\u003Cslug>\u002F\n    brief.md\n    updates\u002FYYYY-MM-DD-*.md\n```\n\nThe SQLite database is an *index*, not the source of truth — every\ntask and project has its real content in the markdown files next to\nit. You could delete `flow.db` and rebuild it from the markdown if\nyou had to.\n\n### Backup & sync\n\nPick whichever fits your workflow:\n\n- **Git (recommended for single-user history).**\n  ```bash\n  cd ~\u002F.flow && git init && git add . && git commit -m \"initial\"\n  ```\n  Commit periodically. The SQLite file is binary, so diffs aren't\n  useful, but each commit is a clean snapshot. **If you push to a\n  shared remote**, add `kb\u002F` to `.gitignore` first — kb files often\n  contain personal or org-sensitive notes you don't want public.\n\n- **Time Machine \u002F system backup.** Just works, no setup.\n\n- **iCloud Drive \u002F Dropbox \u002F Google Drive.** Symlink `~\u002F.flow` into\n  the synced folder:\n  ```bash\n  mv ~\u002F.flow ~\u002FLibrary\u002FMobile\\ Documents\u002Fcom~apple~CloudDocs\u002Fflow\n  ln -s ~\u002FLibrary\u002FMobile\\ Documents\u002Fcom~apple~CloudDocs\u002Fflow ~\u002F.flow\n  ```\n  ⚠️ **Don't run flow on two machines simultaneously** through a\n  synced folder — SQLite doesn't tolerate concurrent writes from\n  separate hosts and you can corrupt `flow.db`. Use this for backup\n  + occasional second-machine access, not active multi-machine use.\n\n- **Manual rsync.** `rsync -a ~\u002F.flow\u002F \u002Fpath\u002Fto\u002Fbackup\u002Fflow\u002F` on a\n  schedule. Same caveat about concurrent writes.\n\nTo move flow to a new machine: copy `~\u002F.flow\u002F` over, install the\nbinary, and run `flow init` once — it'll pick up the existing data\nand reinstall the skill + hook.\n\n## Where flow runs (and where we'd love help)\n\nToday flow runs on **macOS (iTerm2, Warp, stock Terminal.app, kitty,\nor zellij) + Claude Code only**. That's the stack we use, and that's\nwhat the session-spawn layer was built and tested against. zellij\nand kitty work on Linux too as a side effect — both are\ncross-platform and flow's zellij \u002F kitty backends don't depend on\nany macOS APIs. Kitty needs `allow_remote_control yes` (or\n`socket-only`) in `kitty.conf` so flow can drive `kitty @ launch`\nfrom inside the running kitty instance.\n\nThe architecture is portable — session spawning is one small\npackage — but other harnesses (Codex, Cursor, plain shell) and other\nterminals (Linux + tmux\u002Fwezterm, Windows Terminal) need contributors\nwho run those stacks daily and care enough to wire them in. If that's\nyou, [a PR is very welcome](CONTRIBUTING.md).\n\n## Where flow came from\n\nflow started as an internal tool at Facets. We use Claude Code every\nday, and the context-loss problem was eating into how much of the\ntool's capability we could actually use. flow fixed that for us — to\nthe point where we couldn't imagine working without it. We're\nopen-sourcing it as-is because it might do the same for you.\n\nThis is not a Facets product. There's no signup, no cloud, no upsell.\nJust the tool we built for ourselves.\n\n## Docs & contributing\n\n- [Contributing](CONTRIBUTING.md) — bug reports, PRs, dev setup\n- [Changelog](CHANGELOG.md)\n- [Security](SECURITY.md) — how to report issues\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n\n## License\n\n[MIT](LICENSE) — © 2026 Facets Cloud\n","flow 是一个任务管理器，旨在将孤立的Claude会话转变为持续的工作关系。它通过结构化简报、项目上下文和知识库加载，支持用户在Claude会话中无缝地进行任务的启动、暂停与恢复。其核心功能包括自动化的任务状态管理和长期记忆机制，确保即使是在长时间间隔后重新开始的任务也能保持上下文连贯性。该项目使用Go语言编写，适合需要频繁利用AI助手进行代码开发或复杂问题解决的场景，特别是当工作涉及多个阶段且需跨时间维持一致性时。MIT许可证下开源。","2026-06-11 03:32:02","CREATED_QUERY"]