<p align="center">
  <img src="assets/brand/fluxion-logo.svg" width="132" alt="Fluxion logo">
</p>

<h1 align="center">Fluxion Bus</h1>

[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md)

https://github.com/user-attachments/assets/7ff8be14-f4e6-4bd9-9ceb-bbf425fafba3

_Illustrative demo with staged data, not a live recording._

Fluxion Bus is the open-source project behind the Fluxion macOS app and local
agent gateway.

**Fluxion** lets your primary AI agent delegate scoped tasks across **Codex**,
**Claude Code**, and **Antigravity** through one local MCP server.

Stay inside your current agent while Fluxion routes work to another provider,
preserves sessions, reports progress and results, and records file changes for
review or recovery.

Fluxion also reads provider-reported quota windows, detects and notifies you
when the provider resets them, and can automatically make a minimal Agent call
after a reset to start the next rolling window immediately.

Quota and usage data are not limited to tasks delegated through Fluxion.
Fluxion reads them directly from provider APIs, local agent services, or local
agent histories; it does not calculate provider quota from Fluxion task
records.

Local-first, single-tenant, and self-hosted. No Fluxion account or SaaS
dependency; default exposure is `127.0.0.1`.

## Why Fluxion

### Cross-provider delegation without leaving your primary agent

```text
┌────────────────────────────────────────────┐
│ Primary agent                              │
│ Codex / Claude Code / Antigravity          │
└─────────────────────┬──────────────────────┘
                      │ MCP: delegate scoped subtask
                      ▼
              ┌──────────────────┐
              │ Fluxion MCP      │
              │ route + supervise│
              └────────┬─────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
       Codex      Claude Code   Antigravity
          │            │            │
          └────────────┼────────────┘
                       ▼
       status / result / changed files / revert
                       │
                       ▼
                 Primary agent
```

- Route each subtask to a different provider.
- Continue executor-native sessions across repeated calls.
- Choose read-only investigation or explicitly authorized edits.
- Inspect async status, logs, artifacts, and changed files.
- Revert recoverable text-file changes after review.

### Turn quota resets into usable windows

```text
 Claude quota     Codex quota     Antigravity quota
      └───────────────┬──────────────────┘
                      ▼
             ┌─────────────────┐
             │ Fluxion quota   │
             │ monitor + sched │
             └────────┬────────┘
                      │
         ┌────────────┼──────────────┐
         ▼            ▼              ▼
      Web UI      macOS app     Reset detected
                                      │
                               Auto Ping + notify
                          Slack/Telegram/WeChat/LINE/QQ/Feishu
```

- See remaining quota and reset countdowns across providers.
- Monitor provider/account quota, including usage made outside Fluxion.
- Use the browser-based console on macOS or Linux.
- Use the native macOS app for menu bar quota, service controls, and setup.
- Detect provider-side quota resets.
- Automatically make a minimal Agent call after a detected reset to start the
  next rolling window.
- Send quota-reset notifications through Slack, Telegram, WeChat, LINE, QQ, or
  Feishu.

### Control local agents remotely

Send tasks from Slack, Telegram, WeChat, LINE, QQ, or Feishu while away from
your computer. Fluxion routes the message to a local Codex, Claude Code, or
Antigravity executor, then returns progress updates and the final result in the
same conversation.

```text
Phone / remote device
Slack/Telegram/WeChat/LINE/QQ/Feishu
          │
          ▼
 Fluxion messaging gateway
          │
          ▼
Codex / Claude / Antigravity
          │
          ▼
 progress updates + final result
```

Remote conversations preserve their executor session, so follow-up messages can
continue the same task context. Users can also inspect recent tasks, check
gateway status, reset a conversation, or cancel queued/running tasks through
channel control commands.

WeChat uses iLink QR-code login. Bind the account once, enable the channel, and
start the same messaging gateway used by the other messaging channels.

## Platform Support

| Capability | macOS | Linux | Windows |
| --- | --- | --- | --- |
| MCP cross-provider delegation | Supported | Expected, not verified | Not verified |
| Web quota console | Supported | Expected, not verified | Not verified |
| Scheduler auto-ping and notifications | Supported | Expected, not verified | Not verified |
| Native macOS app | macOS 12+ | Not available | Not available |

Linux support is expected for non-native features based on the implementation,
but has not yet been manually verified.

The menu bar app runs on macOS 12 or newer; its Launch at Login toggle
requires macOS 13+ and is disabled on macOS 12.

Provider quota probes depend on compatible local credentials or services.
Antigravity live quota, for example, requires its local sidecar to be running.
The displayed quota comes from those provider or agent sources, not from a
counter of tasks routed through Fluxion.

## Install and Verify

Requirements:

- At least one installed and authenticated executor CLI: `codex`, `claude`, or
  `agy`
  - Codex: either the standalone CLI, or the Codex desktop app — its bundled
    CLI is detected automatically on macOS, and its login satisfies auth.
- Python 3.12+ (Python 3.13 recommended) for CLI/backend installs. The macOS
  desktop app can install `python@3.13` through Homebrew when needed.
- Node 18+ only when rebuilding the Web console frontend locally.

### macOS desktop app (recommended)

The desktop app runs on Apple Silicon (M-series) Macs. Intel users should build from source or use the CLI installation below.

The easiest way in is [Homebrew](https://brew.sh):

```bash
brew install --cask superposed-labs/tap/fluxion
```

The cask clears the quarantine flag for you, so there are no Gatekeeper
steps — just launch it. Update later with `brew upgrade --cask fluxion`.

**No Homebrew?** Download the `Fluxion.app` DMG from the [latest Release](https://github.com/superposed-labs/fluxion-bus/releases/latest) (verify it against `SHA256SUMS`) and drag it into `/Applications`. The app is unsigned and not notarized, so Gatekeeper blocks the first launch: either open **System Settings → Privacy & Security** and click **Open Anyway**, or run the command below to clear quarantine yourself:

```bash
xattr -dr com.apple.quarantine /Applications/Fluxion.app
```

On first launch, Fluxion uses `~/.local/share/fluxion` as the managed backend path and offers **Install / Repair**. The app then installs the backend from the source snapshot and dependency wheels bundled inside the app, creates `.venv`, initializes `.env`, and starts the local services — no git, network access, Xcode Command Line Tools, or local Node build required.

If Python 3.12+ is not already available and Homebrew is installed, the
installer uses Homebrew to install `python@3.13`; without Homebrew, the app
points you to the python.org installer before setup starts. Executor CLIs such
as `codex`, `claude`, or `agy` still need to be installed and authenticated
separately.

### Let your agent configure CLI/MCP

For CLI-first use, MCP registration, or non-desktop installs, the agent you
already use can run the backend installation end to end: prerequisites,
installer, MCP registration for your client, and verification. Paste this into
Claude Code, Codex, or Antigravity from the project directory you want Fluxion
to work on:

```text
Read https://raw.githubusercontent.com/superposed-labs/fluxion-bus/main/docs/agent-install.md
and follow it to install and configure Fluxion on this machine. Use the current
directory as the first authorized workspace, register the MCP server with the
client you are running in, then run the verification steps and report the results.
```

The agent follows [docs/agent-install.md](docs/agent-install.md), which wraps
the same installer used below. It finishes with a per-component status report
covering the backend CLI, MCP registration, and Web console static assets. The
macOS desktop app is distributed separately through the Release DMG.

### Manual install

Install or update Fluxion for the current user:

```bash
curl -fsSL https://raw.githubusercontent.com/superposed-labs/fluxion-bus/main/scripts/install.sh \
  | bash -s -- --no-desktop
```

The installer uses `~/.local/share/fluxion`, links commands into
`~/.local/bin`, and installs the CLI, Gateway, and MCP commands. The prebuilt
macOS app is distributed through the Release DMG; use the source installer for
backend/CLI setup and development workflows. Run the same command again to
update while preserving `.env` and `data/`.

By default, the directory where the install command is run becomes the first
authorized workspace. Override it when needed:

```bash
curl -fsSL https://raw.githubusercontent.com/superposed-labs/fluxion-bus/main/scripts/install.sh \
  | FLUXION_WORKSPACE=/absolute/path/to/project bash -s -- --no-desktop
```

Uninstall while preserving configuration and data in a timestamped backup:

```bash
~/.local/share/fluxion/scripts/uninstall.sh
```

Use `--purge` only when the configuration and runtime data should also be
deleted.

### Development install

For a source checkout used for Fluxion development:

```bash
git clone git@github.com:superposed-labs/fluxion-bus.git
cd fluxion-bus

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Detect an executor and create a minimal .env with real paths.
fluxion init

# Check configuration, executor availability, and workspace authorization.
fluxion doctor

# Verify the local execution path with a read-only task.
fluxion run "Summarize this project and explain how to run its tests."
```

Allow edits explicitly:

```bash
fluxion run --write "Fix the failing tests."
```

Initialize Fluxion for another workspace:

```bash
fluxion init --workspace /absolute/path/to/project
fluxion doctor --workspace /absolute/path/to/project
fluxion run --workspace /absolute/path/to/project "Inspect this project."
```

`fluxion init` creates a deliberately small `.env`; [`.env.example`](.env.example)
mirrors that minimal shape for manual setup. For advanced manual configuration,
see [`.env.advanced.example`](.env.advanced.example),
[Configuration](docs/configuration.md), and [`scripts/install.sh`](scripts/install.sh).

## MCP Delegation Quick Start

Register `fluxion-mcp` with the primary agent where you already work. Complete
client-specific examples for Claude Code, Codex, and Antigravity are in the
[MCP reference](docs/mcp.md#client-setup).

Example Claude Code registration:

```bash
claude mcp add -s user \
  -e FLUXION_ENV_FILE=<fluxion-repo>/.env \
  -e FLUXION_WORKSPACE_ROOT=<fluxion-repo> \
  -e FLUXION_DATA_DIR=<fluxion-repo>/data \
  fluxion -- <fluxion-repo>/.venv/bin/fluxion-mcp
```

The primary agent can then delegate a focused subtask:

```json
{
  "agent": "claude",
  "project": "web",
  "profile": "inspect",
  "mode": "read-only",
  "prompt": "Investigate why the login form is submitting twice."
}
```

Fluxion returns a `run_id`. The primary agent can inspect status, fetch the
result, cancel the run, review changed files, or revert a reviewed
workspace-writing run through the same MCP server.

For multi-project usage, configure project keys with
`FLUXION_PROJECTS_FILE`; see [Project registry](docs/configuration.md#project-registry).

## Quota Monitoring Quick Start

### Web Console
If you installed the prebuilt app or used the installer, the console is ready. Start it directly:

```bash
fluxion-web                  # http://127.0.0.1:8765
```

*(If running from a Git clone or rebuilding static assets: `cd web && npm install && npm run build && cd ..` before running the command).*

### macOS Menu Bar App
If you downloaded the prebuilt `Fluxion.dmg`, drag it into `/Applications` and open it.

If building the menu bar app from your local source checkout (this compiles natively for your machine's architecture, whether Apple Silicon or Intel):

```bash
npm --prefix web ci
npm --prefix web run build
./desktop/build.sh
open desktop/Fluxion.app
```

`desktop/build.sh` reuses this Web console build on later runs. It does not
rebuild the frontend automatically.

The menu bar app can configure and start quota monitoring, automatic pings,
reset notifications, and companion services. The actual background auto-ping
and notification work is performed by `fluxion-scheduler`, which also runs
without the menu bar app on Linux.

The app can remain inside the repository or be copied to `/Applications`. When
launched outside the repository, it asks the user to select the Fluxion source
checkout and stores that path under `~/Library/Application Support/Fluxion/`.

```bash
fluxion-scheduler
```

See [Quota monitoring](docs/quota-monitoring.md) and
[Scheduler](docs/scheduler.md) for provider sources, configuration, and
always-on deployment.

## Messaging Channels

`fluxion-gateway` accepts remote tasks from Slack, Telegram, WeChat, LINE, QQ,
and Feishu and submits them through the same router used by MCP and the local
CLI. It replies in the same conversation with execution status and the final
result.

```bash
fluxion-gateway
```

See [Configuration](docs/configuration.md#messaging-channel-configuration) for
channel and workspace settings.

## Provider Gateway

`fluxion-provider` exposes Fluxion's local agent executors (such as Claude, Codex, or Antigravity) as an API provider endpoint (`http://127.0.0.1:8787`). External tools call it instead of a metered model API, and the work runs on a CLI you already have a subscription for. It speaks the OpenAI Responses API (Codex sub-agents) and the Anthropic Messages API (Claude Code).

```bash
fluxion-provider init
fluxion-provider serve
```

> **Routing Codex's own sub-agents is discontinued on Codex 0.149 and later.**
> Codex stopped letting an agent role choose its `model_provider` (upstream
> commit `1a6e07a4fe`, #39299 — deliberate hardening, with a test that keeps it
> closed), so a `fluxion_worker` spawn inherits the parent session's provider,
> runs on your own OpenAI model, and never reaches the gateway. Nothing errors.
> Fluxion refuses to install the integration on those versions. Use
> `mcp__fluxion__run_subagent` instead; it launches local agents directly and is
> unaffected. Details in
> [Provider Gateway](docs/provider-gateway.md#client-codex).

On Codex 0.148 and earlier, to route Codex's sub-agents to Fluxion:

1. Open **Fluxion Preferences → Provider Routing**.
2. Confirm that **Provider Gateway** is running.
3. Under **Codex Integration**, click **Install / Repair**.
4. Choose the Codex model used for role capabilities and usage attribution,
   then install.
5. Restart Codex so it loads the new role files.

This installs `fluxion_auto`, `fluxion_worker`, `fluxion_explorer`, and
`fluxion_reviewer`. Name the role explicitly when delegating, for example:
**“Use the `fluxion_worker` role to inspect this change.”**

This native Codex integration is separate from registering the Fluxion MCP
server. MCP registration exposes `mcp__fluxion__*` tools; Codex Integration
routes Codex's own `spawn_agent` roles through the Provider Gateway. You can
use either integration independently.

For a CLI-only install:

```bash
fluxion-provider install-codex-config --model gpt-5.6-terra
```

See [Provider Gateway](docs/provider-gateway.md#client-codex) for model
selection, verification, read-only routing constraints, security token setup,
and diagnostic commands.

## Documentation

- [Architecture](docs/architecture.md) — full system diagram, surfaces, shared
  state, and project layout
- [Agent-assisted installation](docs/agent-install.md) — step-by-step install
  instructions written for an AI agent to execute
- [MCP reference](docs/mcp.md) — client setup, tools, status states, cancel, and
  safe revert flows
- [Quota monitoring](docs/quota-monitoring.md) — provider sources, Web
  console, macOS app, privacy, and notifications
- [macOS app](desktop/README.md) — release packaging, managed backend,
  `/Applications` installation, and development override
- [Usage statistics](docs/usage-statistics.md) — agent-history coverage,
  independence from Fluxion delegation, cost estimates, and Fast-mode
  limitations
- [Scheduler](docs/scheduler.md) — auto-ping, quota-reset triggers, cron rules,
  and deployment
- [Provider Gateway](docs/provider-gateway.md) — local provider endpoint, auth tokens, and Codex integration
- [Configuration](docs/configuration.md) — executors, authorization, channels,
  Web UI, and environment variables
- [Deployment](deploy/README.md) — launchd and systemd service templates

## License

[Apache License 2.0](LICENSE) — see also [NOTICE](NOTICE).