Flowy

Agentic persistent planning

Jira, Linear, Trello are built for humans clicking boards. AI agents don't click boards. When your agent needs to plan work, track progress, and close tickets, those tools add friction, load context, and get in the way.

Flowy is where agents store plans and flow through execution. Features are master plans. Tasks are execution steps. Everything persists in a database, not as files cluttering your git history. Your agent flows through work without friction.

You get full observability on what every agent planned, built, and shipped.

Get Started

Flowy runs in one of two modes. Pick the one that fits:

• Self-hosted — a local server you run yourself (flowy serve). No account, no subscription, your data stays on your machine. Start here if you just want to try Flowy.
• Remote (hosted) — the managed service at flowy-ai.fly.dev. Register with an email, then subscribe at checkout. The hosted server gates data operations behind an active subscription.

Quickstart (self-hosted, no account)

npm i -g @sqaoss/flowy
flowy setup local          # installs the bundled server, points the CLI at localhost
flowy serve &              # starts the local server on 127.0.0.1:4000

cd my-project
flowy init                 # auto-detects the git repo, creates + maps a project

flowy feature create --title "User Auth" --description "Email + OAuth login"
flowy feature set "User Auth"

flowy task create --title "Implement OAuth" --description "Wire up the OAuth provider"
flowy status <task-id> in_progress
flowy status <task-id> done

flowy serve runs in the foreground; the & backgrounds it. Stop it with kill %1 or run it in a separate terminal. Data lives in ./flowy.sqlite.

Quickstart (remote/hosted)

npm i -g @sqaoss/flowy
flowy setup remote --email you@example.com   # registers; prints an apiKey + checkoutUrl

cd my-project
flowy init                                   # auto-detects the git repo, creates + maps a project
flowy task create --title "First task" --description "Try it out"

setup remote registers your email and stores the returned API key. It prints a checkoutUrl — open it to start a subscription. Until you do, the hosted server may reject data operations with An active subscription is required. You no longer need to choose a tier up front (--tier is optional); pick one at checkout.

Every command outputs JSON. Your agent reads it, acts on it, moves to the next task.

Descriptions: literal vs. file

--description is always literal text — it is never read as a file path. To load a description from a file (or stdin), use --description-file:

flowy task create --title "Write tests"   --description "Unit + integration tests"
flowy feature create --title "User Auth"  --description-file auth-spec.md
flowy task create --title "From stdin"    --description-file -      # reads stdin

Dependencies and ready work

Tasks can block one another. Mark a dependency, inspect it, and ask for only the tasks that are actually actionable right now:

flowy task block <blocker-id> <blocked-id>   # blocker must finish before blocked
flowy task deps <id>                          # what blocks this task, and what it blocks
flowy task show <id>                          # task details, now including blockedBy/blocks

flowy task list --ready                        # only unblocked, not-done tasks (active project)
flowy task list --ready --project <project-id> # ...scoped to a specific project
flowy task list --all                          # every task across the whole backlog

--ready returns tasks that are not done/cancelled and have zero unfinished blockers — the work an agent can pick up next.

Import and export

Move a whole backlog in or out as a single JSON manifest. Import is idempotent: each node carries a stable key (a client-key), so re-importing updates the matching nodes in place instead of duplicating them. Edges (part_of, blocks) round-trip through the real edge model, so a block you created by hand is captured on export and not re-created on the next import.

flowy export                 # print the active project's manifest to stdout
flowy export backlog.json    # ...or write it to a file
flowy import backlog.json    # ingest a manifest (create new, update existing by key)

A manifest looks like:

{
  "version": 1,
  "nodes": [
    { "key": "proj", "type": "project", "title": "My Project" },
    { "key": "auth", "type": "feature", "title": "User Auth", "parent": "proj" },
    { "key": "oauth", "type": "task", "title": "Implement OAuth", "parent": "auth", "status": "draft" }
  ],
  "edges": [
    { "source": "oauth", "target": "auth", "relation": "part_of" }
  ]
}

Each node's parent implies a part_of edge, so the simplest manifests need no explicit edges. blocks dependencies go in edges. The reserved __flowyKey metadata field stores the client-key; your own metadata is preserved alongside it and stripped back out on export.

Agent Skill

flowy setup installs an agent skill so your AI agent automatically knows every command. If that install step fails (offline, no npx, registry hiccup), setup prints a warning telling you to install it manually:

npx skills add sqaoss/flowy

See skills/using-flowy/SKILL.md for the full skill reference.

Data Model

project -> feature -> task
  1:many     1:many

Every task belongs to a feature. Every feature belongs to a project. No orphans.

Status Flow

draft -> pending_review -> approved -> in_progress -> done

Also: blocked, cancelled. Only pending_review entities can be approved.

Self-Hosted

Run Flowy on your own machine — no Docker, no account, no subscription. flowy setup local installs a bundled server pinned to your CLI version and points the CLI at localhost; flowy serve runs it natively over SQLite.

flowy setup local            # install the bundled server, configure the CLI
flowy serve                  # bind 127.0.0.1:4000, store data in ./flowy.sqlite
flowy serve --port 5000 --host 0.0.0.0 --db ~/flowy.sqlite   # override defaults

The self-hosted server supports the full planning workflow — init, project/feature/task CRUD, status, approve, search, tree, task deps, task list --ready/--all, and import/export. Account-only commands (whoami, billing, key) are remote-mode features and don't apply locally.

Command Reference

All commands output JSON to stdout; errors go to stderr as { "error": "message" }.

Configuration

Config is stored at ~/.config/flowy/config.json. These environment variables override config:

Development

bun run test          # CLI tests
bun run check         # Lint + format
bun run typecheck     # TypeScript

cd server && bunx --bun vitest run   # Server tests

License

Apache-2.0. Copyright 2026 SQA & Automation SRL.