Flux ·

Flux is a completely open, hackable, unopinionated task management engine.

<p align="center"> <img src="./docs/kibo-mascot.png" width="220" /> </p>

Flux is your ultimate task management sidekick – a lightning-fast Kanban board that lets humans, AI agents, and automations team up to crush chaos. With built-in MCP (Model Context Protocol) integration, your LLMs can jump in and run the show: creating tasks, updating statuses, and keeping everything in sync. No more rigid workflows or SaaS lock-in – just pure, flexible productivity magic! ✨

Why settle for boring task trackers when you can enter the Flux Zone? Inspired by the wild energy of a flux capacitor (hello, Back to the Future fans!), this open-source gem decouples tasks from execution, making it the perfect playground for developers, teams, and AI enthusiasts. Ready to go viral? Star this repo and let's make task management fun again! ⭐

Why Flux? Because Chaos is So Last Year

Ever felt like your projects are a tangled mess of tools, bots, and half-baked ideas? Flux fixes that by being:

• Execution-Agnostic: Tasks live here, but how they get done? That's up to you – manual, API, webhooks, or let Claude/GPT take the wheel.
• AI-Powered Awesomeness: Hook up your LLMs via MCP and watch them automate the mundane. "Hey AI, create a task for fixing that bug!" – Done. 🤖
• Simple & Speedy: Single JSON file, drag-and-drop UI, git-native sync. No bloat, just flow.

Flux isn't just another Kanban board – it's the open-source engine for the future of work. Developers love it because it's hackable, extensible, and screams "build on me!" If you're tinkering with AI agents or just need a better way to organize, this is your ticket to productivity paradise.

<p align="center"> <img src="./docs/sample-workflow.png" alt="Sample workflow" /> <br /> <em>Sample workflow</em> </p>

Features

• Multi-Project Kanban Boards: Juggle epics, tasks, and dependencies like a pro.

• Task Dependencies: See what's blocked at a glance – no more surprises!

• MCP Integration: Let LLMs list, create, update, or delete tasks programmatically.

• Real-Time Updates: SSE keeps everyone in sync – web UI, APIs, and beyond.

• Webhooks Galore: Integrate with Slack, GitHub, CI/CD – trigger actions on task changes.

• API-First Design: Full REST endpoints for ultimate control.

• Git-Native Sync: flux push / flux pull syncs via flux-data branch.

• CLI-First: Full CLI with MCP parity (flux ready, flux task, etc.)

• Agent Memory: Task comments for persistent context across sessions

• Priority System: P0/P1/P2 priorities for agent task ordering

• Blob Storage: Attach files (images, docs, logs) to tasks via CLI, API, or MCP.

Quick Start: Up and Running in a Flux Second ⚡

# CLI only (npm)
npm install -g flux-tasks

# Full stack with Web UI (Docker)
curl -fsSL https://raw.githubusercontent.com/sirsjg/flux/main/scripts/quickstart.sh | bash  # macOS/Linux
irm https://raw.githubusercontent.com/sirsjg/flux/main/scripts/quickstart.ps1 | iex         # Windows

This will start both the web UI (http://localhost:3000) and the MCP server. Press Ctrl+C to stop the MCP server when you're done.

# Claude Code
claude mcp add flux -- docker exec -i flux-web bun packages/mcp/dist/index.js

# Codex
codex mcp add flux -- docker exec -i flux-web bun packages/mcp/dist/index.js

Let your agent know!

cat << 'EOF' >> AGENTS.md
---
You are an autonomous agent using Flux for task management.

RULES:
- All work MUST belong to exactly one project_id.
- You MUST NOT guess or invent a project_id.
- You MUST NOT switch projects without explicit instruction.

STARTUP (MANDATORY):
1. List projects.
2. Select or create ONE project.
3. Confirm the active project_id before any work.

EXECUTION:
- Include project_id in EVERY Flux call.
- Track all work as tasks.
- Update task status as work progresses.
- Close tasks immediately when complete.
- Comment on tasks where appropriate.

CONTEXT LOSS:
- If unsure of project_id, STOP.
- Re-list projects and tasks.
- Ask the user if ambiguity remains.

FORBIDDEN:
- Working without a confirmed project_id.
- Mixing tasks across projects.
- Relying on memory outside Flux.

If these rules cannot be followed, halt and request clarification.
EOF

---

Documentation

Looking for install options, assistant setup, APIs, or webhooks? Start here:

• docs/installation-docker.md - the fastest path to a production-ready Flux stack with a shared data volume for instant sync.
• docs/installation-source.md - build from source, run locally, and get a dev workflow that feels effortless.
• docs/cli.md - full CLI reference for terminal-based task management with MCP parity.
• docs/claude-code-plugin.md - Claude Code plugin that turns your project requirements into a structured Flux board with epics, tasks, and dependencies.
• docs/assistant-setup.md - connect Claude Desktop or ChatGPT and unlock agent-driven work with best-practice guardrails.
• docs/ideas.md - creative ways to use Flux, from agent swarms to automation-first workflows.
• docs/mcp.md - the complete MCP surface area so your assistants can list, create, and update everything with confidence.
• docs/api.md - REST endpoints for building automations, integrations, or custom frontends.
• docs/webhooks.md - real-time events with signatures, retries, and examples to power your workflows.
• docs/architecture.md - understand the monorepo, storage model, and why Flux stays fast and simple.
• docs/roadmap.md - where Flux is headed and what we are shipping next.

Dogfooding

Flux uses itself for task management. Tasks are stored on the flux-data branch and synced via git:

flux pull               # Fetch latest tasks from flux-data branch
flux ready              # Show unblocked tasks sorted by priority
flux task update <id> --status in_progress
flux push "message"     # Commit and push task changes

Configure remote server in .flux/config.json:

{
  "server": "https://app.getflux.dev",
  "apiKey": "$FLUX_API_KEY"
}

The $FLUX_API_KEY expands from .env.local.

Ecosystem

Tools that work well with Flux:

Tool	Description
Momentum	Watches Flux for task changes and automatically spawns agents to work on them
Spec Kit	Create spec-driven requirements that generate Flux epics and tasks
n8n	Workflow automation that triggers on Flux events
Zapier	Connect Flux to 5,000+ apps via REST API and webhooks

Contributing

Flux is early and moving quickly. If you want to help shape it, contributions are welcome. Open an issue for ideas and bugs, or pick something from the roadmap and send a PR. See CONTRIBUTING.md for details.

License

MIT. See LICENSE.