FluxGuard

FluxGuard gives coding agents resource awareness: when to explore, when to parallelize, when to conserve, and when to finish.

It measures quota, context window, request rate limits, and budget flow (flux), returning concise execution advice so agents make cost-effective decisions and avoid unexpected quota exhaustion.

Pre-1.0: review the architecture and supported sources before deploying to production environments.

Why this exists

Coding agents often make expensive decisions without knowing that an account, context window, request quota, credit balance, or time budget is close to exhaustion.

Examples:

• Spawning multiple concurrent subagents when only 8% weekly quota remains.
• Starting a broad codebase refactor right before a hard quota reset window.
• Running complete test matrices repeatedly when targeted test subsets suffice.
• Consuming nearly the entire context window with unfocused repo searches.
• Continuing optional code cleanups after the user's primary objective is solved.

FluxGuard provides agents with a compact, standardized resource signal before every major operation.

Core idea

Instead of exposing raw usage counters or provider-specific metrics, FluxGuard produces a normalized decision signal:

{
  "pressure": "critical",
  "bottleneck": "codex.weekly",
  "effective_remaining_percent": 8,
  "confidence": "high",
  "recommended_mode": "completion_first"
}

The calling agent can immediately adapt its plan (e.g. prioritize finishing active tasks, reduce parallel subagents, or bypass non-critical checks).

Architecture

                         +----------------------+
                         |     Coding Agent     |
                         | Codex / Cursor / ... |
                         +----------+-----------+
                                    |
                                    | MCP
                                    v
+------------------------------------------------------------------+
|                            fluxguard                             |
|                                                                  |
|  MCP API -> Snapshot Service -> Pressure Engine -> Policy Engine |
|                    ^                         ^                   |
|                    |                         |                   |
|             Source Registry          Operation Profile           |
|                    |                                             |
|       +------------+--------------+                              |
|       |                           |                              |
|  Client Sources               Provider Sources                   |
|  Codex                        OpenAI API                         |
|  Claude Code                  Anthropic API                      |
|  Cursor                       xAI                                |
|  Antigravity                  Z.AI / GLM                         |
|  Copilot                      Other providers                    |
|  OpenCode                                                        |
+------------------------------------------------------------------+

Client vs Provider

FluxGuard strictly separates clients (harnesses) from providers (backends):

• Clients / Harnesses: Codex, Claude Code, Cursor, Google Antigravity, GitHub Copilot, OpenCode.
• Providers: OpenAI, Anthropic, xAI, Z.AI, Google, and standard API-compatible endpoints.

One client can use several providers, and one provider can be called from multiple clients. The core domain never couples client telemetry with provider schemas.

Install

macOS and Linux (curl)

curl -fsSL https://raw.githubusercontent.com/suiflex/FluxGuard/develop/scripts/install.sh | sh

The script downloads the release binary for your platform, verifies it against SHA256SUMS, and installs it to $HOME/.local/bin. Set FLUXGUARD_VERSION to pin a release tag or FLUXGUARD_INSTALL_DIR to change the destination path.

Windows (PowerShell)

irm https://raw.githubusercontent.com/suiflex/FluxGuard/develop/scripts/install.ps1 | iex

Installs to %LOCALAPPDATA%\Programs\FluxGuard\bin and verifies integrity against SHA256SUMS. Supports FLUXGUARD_VERSION and FLUXGUARD_INSTALL_DIR overrides.

Homebrew (macOS & Linux)

brew install suiflex/tap/fluxguard

Or tap once, then install:

brew tap suiflex/tap
brew install fluxguard

Scoop (Windows)

scoop bucket add suiflex https://github.com/suiflex/scoop-bucket
scoop install fluxguard

npm (Global Launcher)

npm install --global @suiflex/fluxguard

Resolves fluxguard from PATH or FLUXGUARD_BIN.

Cargo

cargo install fluxguard

Or from a local workspace checkout:

cargo install --path crates/fluxguard

Staying Up To Date

fluxguard update          # install the latest release when one exists
fluxguard update --check  # report only, install nothing
fluxguard update --json   # machine-readable result

The latest release is read from the repository's tags with git ls-remote, so no API token is involved, and the answer is cached for a day in the platform cache directory:

OS	Cache location
macOS	~/Library/Caches/FluxGuard.FluxGuard/update-check.json
Linux	$XDG_CACHE_HOME/fluxguard/ or ~/.cache/fluxguard/
Windows	%LOCALAPPDATA%\FluxGuard\FluxGuard\cache\

A cache is disposable, so it stays out of the configuration directory — nothing here is backed up or synced between machines — and falls back to a directory under the system temp when the platform reports no home. Installing reuses the platform install script above, so the binary lands where it originally did. When the check cannot reach the remote it reports unknown and exits non-zero rather than claiming the current version is latest.

Configure

fluxguard config          # interactive editor: pick sources, set thresholds
fluxguard config path     # print the file this machine reads
fluxguard config check    # validate the file and the environment overrides
fluxguard config --dry-run # show what the editor would write, write nothing

The editor probes every adapter before it asks anything, so each row shows whether that source is present on this machine, whether enabling it actually yields quota data, and its probe state. Sources marked detection only have no verified machine-readable quota surface yet and report source_unsupported when refreshed, so the editor never pre-selects one.

Already-enabled sources stay selected; on a first run the editor pre-selects the sources that are both present and able to read quota. Writing keeps the previous file beside the new one as config.toml.bak, and the whole configuration is re-validated before anything is written. Hand-written comments do not survive a rewrite.

Thresholds can also be set by hand or through the environment:

[pressure]
guarded_remaining_percent   = 50
conserve_remaining_percent  = 25
critical_remaining_percent  = 10
emergency_remaining_percent = 3

FLUXGUARD_PRESSURE_GUARDED_REMAINING_PERCENT=65   # environment wins over the file

Connect to a Client

FluxGuard provides an interactive installer that writes merge-safe MCP configuration entries with automatic .bak backups:

fluxguard install

Run without --client on a terminal and it shows a menu of supported harnesses, with the ones already configured on this machine marked and pre-selected. Without a terminal it exits rather than guessing a target.

Or configure non-interactively for specific harnesses:

fluxguard install --client claude-code
fluxguard install --client cursor
fluxguard install --client opencode
fluxguard install --client antigravity
fluxguard install --client openclaw
fluxguard install --client codex
fluxguard install --client hermes
fluxguard install --client arsy

Registration is handled by Kurir: codex, hermes, and arsy delegate to their own mcp add command, and omp prints a portable snippet.

Preview changes without modifying files:

fluxguard install --client claude-code --print --dry-run

For harnesses with standalone stdio configuration (e.g. 9router), run:

fluxguard serve

Commands

Command	What it does
fluxguard serve	Serve MCP over stdio — the mode a client launches
fluxguard serve-http --listen 127.0.0.1:8080	Serve MCP over HTTP
fluxguard daemon	Run the source supervisor in the foreground
fluxguard status [--json]	Current combined pressure
fluxguard advice <operation> [--importance …] [--json]	Advice for one operation (alias: fluxguard hook)
fluxguard sources	Registered sources and their state
fluxguard doctor	Probe every configured source and say why one is unavailable
fluxguard config [check|path] [--dry-run]	Edit, validate, or locate the configuration
fluxguard install [--client …]	Register FluxGuard with a harness
fluxguard update [--check] [--json]	Check for and install a newer release

<operation> is one of inspect_targeted, search_broad, edit_small, refactor_large, test_targeted, test_full, spawn_subagent, spawn_parallel_subagents, research_external, generate_artifacts, checkpoint, finalize. Underscores, not hyphens: an unrecognized name is accepted as a custom operation whose cost is unknown, which weakens the advice rather than failing. --importance is required, useful, or optional (default optional).

fluxguard advice spawn_parallel_subagents --importance useful --json

MCP Tools & Resources

FluxGuard keeps its public MCP tool surface small, stable, and machine-readable:

• resource_status: Returns a normalized snapshot of current resource consumption and active limits.
• resource_advice: Evaluates an upcoming operation against current resource pressure and provides execution recommendations.
• resource_refresh: Forces a live refresh of one or more upstream telemetry sources.

Detailed diagnostic data is provided through MCP resources:

• fluxguard://status/full
• fluxguard://sources
• fluxguard://diagnostics

Security & Local Privacy

• Local-only execution: Operates on your machine via stdio MCP transport. No telemetry or usage stats are ever sent to remote services.
• Credential safety: Redacts API keys, tokens, session cookies, and authorization headers before structured logging.
• Merge-safe configs: Preserves existing settings and comments when registering MCP servers with client config files.

Documentation

Document	What it covers
Vision	What FluxGuard is for, and what it refuses to become
Architecture	Layer boundaries and the crate map
Domain Model	BudgetSnapshot, windows, freshness, provenance
MCP Contract	The three tools and their response shapes
Policy Engine	How pressure becomes advice
Source Adapters	The adapter contract and its failure modes
Client Integrations	Per-harness wiring
Provider Matrix	What each source can actually read today
Security & Privacy	What is never logged or uploaded
Observability	Diagnostics and redaction
Testing	What every adapter and policy change must cover
Roadmap	Sequence of work
Codex Implementation Plan	The first vertical slice, phase by phase
Non-Goals	Deliberate exclusions
Research Notes	Source investigation notes
ADRs	Decisions and their reasoning

Contributing, including how to add a source: CONTRIBUTING.md. Agent-facing rules for this repository: CLAUDE.md (AGENTS.md is a symlink to it).

License

Apache-2.0