🌊

flo

Your local flow orchestrator — git, PRs, and project recipes in one tool.
sync · checkout · commit · submit · run

---

Install

npm install -g flo-tools     # then run `flo`

Or run it on demand, no install:

npx flo-tools --help

The package is flo-tools (source under tools/flo); its binary is flo. For the release flow, see the contributing guide.

Quickstart

flo --help              # list commands
flo setup               # per-dev config: trunk, prefix, PR mode (stored under ~/.flo)
flo sync                # update trunk, prune merged branches, restack
flo checkout            # pick a branch from a graph view
flo commit -a -m "msg"  # stage + commit (branches off trunk if needed)
flo submit              # push + open/update a PR (draft or ready-for-review, per setup)
flo <recipe>            # run a project command defined in flo.yml

Docs

Live at https://brunokiafuka.github.io/toolkit/ (built with Starlight, source under docs/).

• Quickstart — install, first-run setup, a typical loop
• Command reference — every command, flags, and behavior notes
• Configuration — flo.yml schema: commands, init steps, validation
• Recipes — ready-made flo.yml patterns
• Contributing guide — local dev, tests, release flow

Local dev

pnpm install
pnpm run install:flo    # symlinks ~/.local/bin/flo

Layout

./
├── tools/
│   └── flo/         # the tool — self-contained, owns its deps
├── docs/            # Starlight site (deploys to GitHub Pages)
└── package.json     # pnpm workspace root (tools/*, docs)

The repo is a pnpm workspace shaped for one tool today — extra tools/<name> slots stay open for whatever lands next.

Philosophy

• Scripts over services. Small, local, reversible.
• One tool, one job. No shared runtime — each tool owns its dependencies under tools/<name>.
• Boring stack. TypeScript + tsx, no bundler, no framework.