Flunner

The AI-Agent Sidekick & Cross-Platform Desktop Workbench for Flutter.

---

Overview

Flunner is the dedicated developer workbench and runtime sidekick for AI coding agents on desktop.

While your AI coding assistant (Cursor, Claude Code, Windsurf, GitHub Copilot, Roo Code, Aider, Antigravity) generates code and creates diffs, Flunner lives right alongside as your calm, hyper-responsive runtime cockpit—giving you instant hot-reloads, device orchestration, live diagnostic streams, PTY terminal tasks, and Git checkpoints with zero IDE clutter.

Agents can also connect over Model Context Protocol (MCP) to the running workbench — not a headless CLI — and inspect or drive projects, devices, sessions, logs, git, and the integrated terminal.

"While your AI agent writes the code, Flunner commands the runtime."

Related project

This repository is the cross-platform Flutter desktop rewrite of Flunner. The original native macOS Swift/SwiftUI edition lives at stackwares/flunner.

Both apps share MCP discovery paths and workspace storage on macOS, so recent projects can carry over. Do not run both apps at the same time.

---

Built for the AI Coding Era

• In-app MCP Server — Cursor, Claude Code, and other MCP clients can inspect and drive the live workbench over localhost (projects, devices, runs, logs, git, and terminal). Enable it in Settings → Agents.
• Zero-Friction Hot Reload & Restart — Instantly test agent-generated UI and logic modifications with sub-second response times without ever leaving your editor.
• High-Density Diagnostics for Prompts — Stream structured logs with multi-level filtering (Info, Error, Command), regex search, and 1-click diagnostic export to feed crash dumps directly back into AI prompts.
• Atomic Git Checkpoints — Built-in source control sheet to inspect diffs, stage files, and commit agent iterations before running further prompts.
• Multi-Device Target Orchestration — Effortlessly launch and switch between iOS Simulators, Android Virtual Devices (AVDs), macOS Desktop, and Chrome Web targets.
• Cross-Platform Desktop — One Flutter codebase targeting macOS, Linux, and Windows with the same workbench loop.

---

Features

• Instant Runtime Control — Trigger Hot Reload and Hot Restart with zero latency. Live session indicators keep you informed of compilation and process state.
• High-Throughput Console — Smooth multi-line selection, real-time search, timestamp toggling, and fast filtering by log level (Info, Error, Command).
• Integrated PTY Terminal — Built-in interactive terminal tabs with full shell support (zsh, fvm, bash) in the project working directory.
• Device & Emulator Management — Automatic detection and launching of iOS Simulators, Android Virtual Devices (AVDs), macOS desktop targets, and Chrome web instances via Flutter daemon.
• Git & Source Control Sheet — Stage files, inspect unified diffs, compose commits, switch branches, and push without leaving the workbench.
• Project Maintenance & SDK Diagnostics — One-click flutter pub get, flutter clean, integrated flutter doctor diagnostics viewer, and quick access to Flutter / Dart documentation.
• Purpose-Built Design — Calm workbench aesthetics, light/dark appearance support, flex color schemes, and custom font scaling.
• In-app MCP Server — While Flunner is running, AI agents can inspect and drive the live workbench over localhost.

---

Requirements

• Flutter SDK: 3.47+ (supports standard Flutter installs and FVM)
• Desktop toolchain: macOS 15+, Linux, or Windows build support for your target platform
• Flutter SDK on PATH (or via FVM) for daemon, run, and device discovery

Web, iOS, and Android are out of v1 scope. The daemon, PTY terminal, git integration, and MCP listener require a desktop process.

---

Quick Start

Prebuilt installers are not published yet — build from source:

git clone https://github.com/stackwares/flunner-flutter.git
cd flunner-flutter
flutter pub get
flutter analyze
flutter test
flutter run -d macos   # or linux / windows

Product loop

1. Open a Flutter project folder (pubspec.yaml with a flutter: key).
2. Pick a device from flutter daemon.
3. Run on that device (flutter run --machine).
4. Watch Console / Output, hot reload, hot restart, stop.
5. Pub get is allowed while a session is running. Clean + Pub Get is not.
6. Optional PTY terminal in the project working directory (`Ctrl+``).
7. Source Control sheet for git status, stage, commit, fetch, pull, push.

---

Keyboard Shortcuts

Shortcut	Action
⌘ R / Ctrl R	Run Project / Active Configuration
r	Hot Reload
R	Hot Restart
⌘ . / Ctrl .	Stop Running Session
`⌃ ``	Toggle Integrated Terminal Pane
⌘ 2 / Ctrl 2	Open Source Control Sheet
⌘ , / Ctrl ,	Settings

---

MCP Server

Flunner exposes a localhost Model Context Protocol server while the app is running. Agents talk to the live workbench — not a headless CLI — so they can switch devices, run/stop sessions, read logs, and drive git/terminal.

1. Launch Flunner.
2. Open Settings → Agents.
3. Copy Cursor / Claude / Codex snippets or write agent config files.
4. Enable Re-sync on launch so URL and bearer token updates apply automatically after each launch.

Example Cursor / Claude config:

{
  "mcpServers": {
    "flunner": {
      "url": "http://127.0.0.1:47321/mcp",
      "headers": {
        "Authorization": "Bearer <token-from-settings>"
      }
    }
  }
}

The server binds 127.0.0.1 only (preferred port 47321, falls forward across 20 ports). Discovery is also written to:

• macOS: ~/Library/Application Support/Flunner/mcp-server.json
• Linux: ~/.local/share/Flunner/mcp-server.json
• Windows: %APPDATA%/Flunner/mcp-server.json

Call get_status first to see the current project, devices, sessions, and whether Pub Get / Clean / Run are available. Destructive git tools require confirm: true. Missing Bearer tokens return 401.

---

Architecture

Flunner is built with Flutter desktop and an MVVM-style layout:

• UI Layer: Material workbench chrome with feature modules for workspace, console, terminal, source control, and settings.
• Terminal Engine: Integrated PTY shell sessions via pty2 and xterm.
• Process Orchestration: Asynchronous runners communicating with the Flutter daemon JSON-RPC protocol over stdio through a login-interactive shell so FVM PATH works.
• Agent Interface: An in-process localhost MCP server (Streamable HTTP) so editors can call the same workbench APIs as the UI.

lib/
├── domain/models/     # prefs, devices, git, workspace snapshots
├── data/services/     # daemon, terminal, MCP, prefs/workspace stores
├── data/repositories/
└── ui/features/       # workspace, console, terminal, source control, settings
test/

---

Contributing

Contributions from the community are warmly welcomed! Please read our Contributing Guide and Code of Conduct before submitting a pull request.

---

License

Flunner is open-source software licensed under the MIT License.

---

Crafted with ❤️ by Oliver Martinez & Stackwares