Channels
FlowBoard
By Local-first project management and persistent context for OpenClaw, Claude Code, Codex, Cursor, and multi-agent coding workflows.
Install
npm install
npmREADME
<h1 align="center">FlowBoard</h1>
<p align="center">
<strong>Project workspaces for AI agents. Built for <a href="https://github.com/openclaw/openclaw">OpenClaw</a> and external coding agents.</strong>
</p>
<p align="center">
<a href="https://github.com/rasimme/FlowBoard/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License"></a>
<a href="https://github.com/rasimme/FlowBoard/releases"><img src="https://img.shields.io/badge/version-v5.1.0-orange.svg" alt="Version"></a>
<a href="https://github.com/rasimme/FlowBoard"><img src="https://img.shields.io/github/stars/rasimme/FlowBoard?style=social" alt="Stars"></a>
</p>
<p align="center">
<a href="#quick-start">Quick Start</a> •
<a href="#features">Features</a> •
<a href="#-idea-canvas">Idea Canvas</a> •
<a href="#remote-access-telegram-mini-app">Remote Access</a> •
<a href="docs/README.md">Docs</a> •
<a href="CHANGELOG.md">Changelog</a>
</p>
---
Your agent loses context every session. What was I building? What decisions did I make? What's the next task? All gone.
**FlowBoard fixes that.**
- **📂 Project context on demand** — Activate a project and your agent gets goals, decisions, live task state, and specs. Lazy-loaded to save tokens.
- **📋 Kanban you both use** — Your agent creates tasks, writes specs, claims work, checkpoints progress, and moves cards through review. You see the full multi-agent workflow live.
- **💡 Idea Canvas** — Brainstorm together visually. One click turns connected ideas into tasks with specs and subtasks.
---
## Why FlowBoard?
The real problem isn't a missing task board — it's that your agent starts every session blank. Across several projects, you re-explain the goal, the decisions, and where things stand, again and again.
FlowBoard is a **context layer for your projects.** Each project keeps its goal, decisions, live task state, and specs in one place, and your agent pulls in exactly the slice it needs, when it needs it — **lazy-loaded, so token usage stays low.** Switch projects and the right context follows; nothing to re-explain.
Everything else builds on that layer:
- **Agent-native Kanban** — tasks, specs, claims, checkpoints, and review, so "where things stand" is always live instead of narrated.
- **Idea Canvas** — brainstorm visually, then promote connected notes straight into tasks and specs.
- **Spec-driven development** — the Specify workflow turns a rough idea into a proper spec through a short clarify loop, so agents build from a clear definition of done, not a one-line title.
- **Modular Overview** — a per-project dashboard that surfaces the context that matters at a glance.
- **Built for many agents** — stable identity, claims, and a live multi-agent view, for OpenClaw and external agents alike.
It's local-first: everything runs on your machine, event-sourced in SQLite — no SaaS, no account, and your project names stay on your box.
---
## Features
### 📂 Project Workspaces
Activate a project and the agent gets the context it needs — goal, scope, architecture, decisions, current task state, specs. Everything is loaded on demand: the agent pulls in what it needs, when it needs it, keeping token usage low. Switch between projects without losing track.
- Structured project files: `PROJECT.md` → `DECISIONS.md` → `specs/` (canvas lives in the database)
- HZL-backed task runtime with claims, leases, checkpoints, comments, and review gates
- A per-project **Project type** (`List`, `Standard`, or `Development`) that tunes agent guidance without blocking task creation
- Non-blocking **Structure review** for vague titles or missing descriptions, visible and acknowledgeable from the Overview
- Lazy loading — zero overhead when no project is active
- Session handoff — pick up exactly where you left off
### 🧩 Modular Project Overview
Every project gets a composable landing page: a widget grid both you and
your agents can shape. 26 widgets across five clusters — what needs you
(blocked, approvals, open agent questions), live activity and momentum,
direction (milestones as definition-of-done checklists, stats, board
preview), a full GitHub family (repo status, CI history, PRs, releases,
issues — one repo binding per project, token optional for private
repos), and knowledge (file viewer, context index, notes, quick links).
Drag-and-drop editing with presets, or let the agent compose it via the
same REST API:
```
PUT /api/projects/:name/overview { version: 1, layout: "grid", widgets: [...] }
PUT /api/projects/:name/overview { "preset": "coding" }
```
### 📋 Agent-Native Kanban
Your agent operates the board through the same REST API as the dashboard. It creates tasks, sets priorities, writes specs with acceptance criteria, claims work with leases, checkpoints progress, and hands completed work to review.
- Tasks with workflow: `backlog → open → in-progress → review → done`
- Parent tasks with subtasks, progress tracking, and automatic parent status updates
- Spec files with acceptance criteria and logs; agents can create a task and its spec atomically
- Canonical work states (`Working`, `Waiting`, `Blocked`, `Paused`) with a compact claim/state control and one attention signal
- Multi-agent visibility: every active claim, task title, progress, lease health, checkpoints, comments, and review approvals
### 💡 Idea Canvas
A node-based brainstorming space. Sticky notes with connections form clusters. One click runs the **Specify workflow** — a guided ANALYZE → CLARIFY → GENERATE loop that asks a few clarifying questions and turns the ideas into proper specs (not just titles):
- **Simple idea** → Task with title and priority
- **Detailed idea** → Task + spec with acceptance criteria
- **Complex cluster** → Parent task + subtasks with specs
Visual brainstorming → spec-backed, structured tasks — zero manual overhead.
### 📁 File Explorer
Browse, preview, and edit project files without leaving the dashboard. The default tree focuses on canonical knowledge Markdown (`PROJECT.md`, `SESSIONS.md`, `DECISIONS.md`, `context/*.md`, `specs/*.md`); use **Show hidden** / `?includeHidden=true` when you intentionally need custom Markdown or operational files. Markdown rendering, a CodeMirror-powered editor, spec files, context uploads, and auto-refresh keep the project workspace inspectable without dropping to a shell.
### 📱 Telegram Mini App
Access FlowBoard remotely from Telegram. Secure authentication via HMAC-SHA256, mobile-optimized UI, works through Cloudflare Tunnel, ngrok, or Tailscale.
---
## Quick Start
**Two commands, then open the dashboard:**
```bash
openclaw plugins install flowboard # wires the project-context hook
node scripts/setup.mjs # build the UI + run the dashboard as a per-user service
```
Open **http://localhost:18790**, click the **Finish setup** chip in the header,
then issue an explicit FlowBoard command in your live agent chat, for example
`FlowBoard: create project my-app`. Done — the rest of this section is detail.
> **Prerequisites:** Node.js ≥ 18 and `npm` on your `PATH`. The `openclaw plugins install` path also needs **OpenClaw ≥ 2026.6.6** — the dashboard runs standalone, but the project-context hook requires OpenClaw.
### Already installed as an OpenClaw plugin?
`openclaw plugins install flowboard` wires the project-context hook. To bring
up the dashboard in one step — install deps, build the UI, register a
per-user service (launchd/systemd) and verify health:
```bash
node scripts/setup.mjs # or: npm run setup
node scripts/setup.mjs --dry-run # preview, change nothing
```
Re-run with `--update` after `openclaw plugins update` to rebuild & restart.
`--update` requires the standard FlowBoard service to exist and preserves its
persisted environment (including auth/tunnel variables and `JWT_SECRET`). Shell
variables never replace persisted update values implicitly. Persist a named,
allowlisted shell value by adding `--override-env=VARIABLE` to the update
command. Rotate `JWT_SECRET` only with
`node scripts/setup.mjs --rotate-secret`; rotation re-registers and restarts the
service immediately. On macOS, setup writes launchd output to the owner-only
`~/Library/Logs/FlowBoard/flowboard-dashboard.log` (directory `0700`, file
`0600`, service umask `077`) rather than a shared `/tmp` path.
Prefer the manual path? It's below.
### Updating
After `openclaw plugins update flowboard` the new plugin source is on disk but
the running dashboard still serves the previous build. Two ways to apply it:
- **From the dashboard.** The header **Update** panel
(SnippetUpgrade) detects the version mismatch and shows an *"Update available -
vX -> vY"* chip only when self-update is explicitly enabled. Click
**Update & restart** — it sends an explicit request confirmation to
`POST /api/update/run`, which runs `setup.mjs --update`
(reinstall deps + rebuild UI + merge the existing standard service
environment + restart, leaving project data untouched), then reloads the
page onto the new build. **Safety:** The API
requires `FLOWBOARD_ENABLE_SELF_UPDATE=true` to be set
explicitly in the service configuration before the UI update button is active;
see below.
- **From the CLI (operator action).** `node scripts/setup.mjs --update` from the
FlowBoard checkout does the same rebuild + restart without additional confirmation.
Recommended for automated deployments or operator-initiated updates.
**Self-Update Safety (T-417-6).** In-dashboard updates are **disabled by default**
for published installs. To enable them, set `FLOWBOARD_ENABLE_SELF_UPDATE=true` in
your standard
... (truncated)
channels
Comments
Sign in to leave a comment