Flunner

The AI-Agent Sidekick & Native macOS Workbench for Flutter.

---

⚡ Overview

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

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."

---

🤖 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 (r / R) 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 native Git 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.
• 🪶 Calm, Ultra-Lightweight Footprint — 100% native Swift & SwiftUI architecture with negligible RAM and CPU usage, saving your machine's full power for local LLMs, compilers, and agents.

---

✨ Features

• ⚡️ Instant Runtime Control — Trigger Hot Reload (r) and Hot Restart (R) 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 powered by SwiftTerm with full interactive shell support (zsh, fvm, bash).
• 📱 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 — Native source control dialog to 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 — Native macOS HIG adherence, custom copper/graphite workbench aesthetics, light/dark appearance support, and custom font scaling.
• 🔌 In-app MCP Server — While Flunner is running, AI agents can inspect and drive the live workbench over localhost (projects, devices, runs, logs, git, and terminal).

---

📋 Requirements

• macOS: 15.0 (Sequoia) or newer
• Flutter SDK: 3.0+ (supports standard Flutter installs and FVM)
• Xcode: 16.0+ (for building from source)
• Swift: 5.9+

---

🚀 Quick Start

Download DMG Installer (Recommended)

1. Download the latest Flunner.dmg from GitHub Releases.
2. Open the disk image and drag Flunner to your Applications folder.
3. Launch Flunner from Applications or Spotlight.

Tip: If macOS Gatekeeper alerts you when launching an ad-hoc signed build for the first time, right-click (or Control-click) Flunner.app in /Applications and click Open.

---

Install via Homebrew

Install the macOS app via Homebrew Cask:

brew install --cask stackwares/tap/flunner

To upgrade later:

brew upgrade --cask flunner

---

Building & Running from Source

Clone the repository and run the convenience script:

# Clone the repository
git clone https://github.com/stackwares/flunner.git
cd flunner

# Build and launch in Debug mode
./script/build_and_run.sh

# Package a Release DMG installer (.dmg & .zip in dist/)
./script/build_dmg.sh

Using Swift Package Manager / Xcode

You can also build directly via SwiftPM or generate the Xcode project:

# Build via Swift CLI
swift build

# Run unit and integration tests
swift test

# (Optional) Generate Xcode project using XcodeGen
xcodegen generate
open Flunner.xcodeproj

---

⌨️ Keyboard Shortcuts

Shortcut	Action
⌘ R	Run Project / Active Configuration
r	Hot Reload
R	Hot Restart
⌘ .	Stop Running Session
`⌃ ``	Toggle Integrated Terminal Pane
⌘ 2	Open Source Control Sheet
⌘ ,	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. Click Connect Selected Agents for Cursor, Claude Code, or Codex.
4. Enable Keep in sync when Flunner starts so URL and bearer token updates apply automatically after each launch.

Manual fallback: copy the JSON snippet from the same tab if you prefer to edit agent config yourself.

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). Discovery is also written to ~/Library/Application Support/Flunner/mcp-server.json. Call get_status first to see the current project, devices, sessions, and whether Pub Get / Clean / Run are available.

---

🏗️ Architecture

Flunner is built using modern native Swift and SwiftUI patterns:

• UI Layer: Pure SwiftUI targeting macOS 15 with strict concurrency checking enabled.
• Terminal Engine: Integrated PTY shell sessions using SwiftTerm.
• Process Orchestration: Robust asynchronous process runners communicating with the Flutter daemon JSON-RPC protocol over stdio.
• Agent Interface: An in-process localhost MCP server (Streamable HTTP) so editors can call the same workbench APIs as the UI.
• Project Structure: Dual-source configuration using Package.swift (SPM) and project.yml (XcodeGen).

Flunner/
├── Sources/
│   └── Flunner/
│       ├── Models/         # App state, devices, launch configs, daemon protocol
│       ├── Services/       # Flutter daemon, runner, Git, terminal, in-app MCP server
│       ├── Views/          # Console, terminal, sidebar, controls, settings
│       └── Design/         # Design tokens, color palette, typography
├── Tests/
│   └── FlunnerTests/       # Unit and integration test suites
└── script/                 # Build, run, and log streaming automation

---

🤝 Contributing

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

1. Fork the repo and create a feature branch (git checkout -b feature/amazing-feature)
2. Commit your changes (git commit -m 'Add amazing feature')
3. Ensure all tests pass (swift test)
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

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

---

Crafted with ❤️ by Oliver Martinez & Stackwares