agentflare MCP server
Commit Nov 13, 2026Optimizes AI coding agents for cost and performance while providing a coordination layer for multi-agent workflows.
Also known as getappz/agentflare
- Stars
- 7
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is agentflare MCP?
agentflare optimizes AI coding agents for cost and performance while providing a coordination layer for multi-agent workflows.
Summary generated from the project's README
About agentflare MCP server
Developers using AI coding agents like Claude Code, Cursor, or Windsurf can use agentflare to reduce token costs and manage complex multi-agent workflows. The tool functions as a Rust-based binary that optimizes individual sessions through context compression and built-in memory that persists knowledge across different sessions. It provides a coordination layer that allows multiple agents to work on the same codebase without colliding by using a shared backlog of work items.
Users interact with the system via a CLI or through MCP tools that integrate directly into their existing IDEs and coding environments. The coordination layer includes a local-first backend with a daemon for background execution and a web dashboard for monitoring costs, claims, and job submissions. It features specialized tools for reviewing code changes, managing versioned artifacts, and performing global searches across seventeen different data sources including GitHub, web, and academic repositories.
What you can do with it
- 1Coordinate multiple autonomous agentsA developer can set up a shared backlog where agents claim specific tasks to prevent them from working on the same files simultaneously.
- 2Automate end-to-end coding tasksYou can instruct an agent to claim a work item, set up a dedicated worktree, and run a headless agent to submit a pull request automatically.
- 3Verify code review findingsUse the review capability to ensure that an agent's findings are accurately cited against the actual code diffs.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablegetappz/agentflare is public and reachablegithub.com/getappz/agentflare ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/getappz/agentflare ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagentflare
Run AI coding agents efficiently, and coordinate more than one of them. A Rust binary for Claude Code, Codex, Cursor, Windsurf, VS Code, Cline, and Continue. The core CLI needs no Node; integrations and optional capabilities use external tools.
Status: Beta
agentflare is under active development. The optimization layer (lean-ctx
integration, memory, optimize output/code/context and the always-on
runtime layer) is the most mature part — CI-gated, tested, in daily use. The
multi-agent coordination layer (tasks, review, coaching, artifacts, handoffs,
daemon, work) is newer and still finding its shape: CLI flags, MCP tool
names, and on-disk formats there can change without a major version bump.
See STATUS.md for what's stable vs. still moving, before you build automation on top of a specific flag or MCP tool signature.
What this is
agentflare is two things bundled into one binary:
1. Optimization — cut the token/cost overhead of running a single AI coding agent session.
| Layer | What it compresses | Tool |
|---|---|---|
| lean-ctx | focused views of tool I/O within a session — reads, shell output and search, with references for recovering detail | yvgude/lean-ctx |
| memory (built-in) | knowledge across sessions — decisions, facts, preferences that survive a session ending | ships in the binary, SQLite + FTS5, no separate install |
agentflare optimize output (formerly Caveman) |
compresses markdown files you give it, so the agent reads fewer tokens each time it loads them (needs model access) | built into the binary |
agentflare optimize code (formerly Ponytail) |
code-writing minimalism, hooked into Claude Code and Codex | built into the binary |
agentflare optimize context |
on-demand BM25/FTS5 relevance scoring over a session transcript (optimize context score). The PreCompact hook is wired for upgrade compatibility but inert: Claude Code's PreCompact accepts no injected context, so compaction survival is left to lean-ctx |
built into the binary |
agentflare optimize retrieve |
reversible-compression retrieve (CCR) — pulls back the original, full-fidelity content that output/context compression replaced, when an agent actually needs it | built into the binary |
| runtime layer (always-on, no CLI surface) | automatic session hygiene and model-routing nudges, surfaced via hooks | built into the binary |
agentflare optimize also answers to its legacy alias agentflare flare (and opt) for
backward compat with earlier install scripts.
2. Coordination — a lightweight, local-first backend for running more than one agent (or agent session) against the same body of work, exposed as MCP tools any MCP-capable agent can call:
| Capability | What it's for |
|---|---|
Work items (item, claim) |
A shared backlog — create/list/search items, claim one before working it so two agents don't collide, mark done. |
Autonomous work (work) |
Claim an item, provision a worktree, run a headless agent against it, and report back (comment + PR) — unattended, end to end. |
Review (review) |
Submit findings against a diff/PR; agentflare verifies each citation against the actual diff, dedups overlapping findings, and tags each CONFIRMED/UNIQUE/DISPUTED/UNVERIFIED. |
Artifacts (artifact) |
Publish specs, plans, and docs as versioned, shareable pages — a durable handoff surface between agents (and to you) instead of scratch files that vanish with the session. |
Handoff (handoff) |
Pass context to a specific agent/runtime, addressed and threaded, when work moves from one agent to another. |
Coaching (coaching CLI + hook) |
Small persistent nudges surfaced to an agent — at session start, and via contextual triggers (BM25 relevance against the tool call/prompt) so a rule only shows up when it's actually relevant. |
Daemon (daemon) |
Background lifecycle for the coordination layer — PID file, flock lock, Unix socket/Windows named-pipe IPC, launchd/systemd autostart, cached update checks. |
Dashboard (serve) |
Web dashboard and execution host — boards, items, cost, claims, job submission and controls, workflow recovery, workers and schedules. |
Friction logging (vent) |
Append-only per-repo JSONL of tool/workflow friction as it happens; a classifier auto-files the actionable entries as backlog items. |
GitHub ops (flare_git MCP tool, git CLI) |
PRs, issues, releases, and workflow runs against GitHub — including a bounded pr_wait poll — on top of the branch-protection/provenance git shim. |
Skills (skill) |
Registry for SKILL.md playbooks — search (BM25), load, and eval, so an agent can pull in a project-specific procedure on demand. |
Summarize (summarize CLI + bundled skill) |
Summarize YouTube videos with source links and configurable text/Markdown/JSON output, or extract timestamped captions through direct HTTP and browser fallback. |
Auth vault (auth, vault) |
Encrypted credential storage for agent auth profiles (rotation, cooldown, health scoring); vault separately holds lightweight per-project secrets (unlock/lock/print-env). |
Global search (search MCP tool) |
One entrypoint across 17 sources — store, memory, code, web, social, news, GitHub, academic, datasets, websites, weather, financial, crypto, fx, indicators, YouTube, Bluesky. |
@mention references |
Inline @I…/@A…/@search:… references in tool output resolve across items, artifacts, and search results. |
| Git-aware PATH shim | Impersonates git; branch-protection policy resolves against the target file's own repo, not the host process's cwd, so a stray write can't land on master/main from the wrong worktree. |
| Comments, labels, projects, webhooks, channel_send | Threaded discussion on items, categorization, cross-project views, and outbound notifications (Telegram/Slack/Discord). |
See Git shim workflow for worktree claims, protected-branch checkout, scope checks, and approved force-push retries.
A companion crate, flare-proxy, provides an Anthropic-compatible HTTP proxy in
front of alternate/free OpenAI-style providers. The dashboard mounts it at
/proxy/v1/messages; provider routing is configured separately from agent setup.
The coordination stores are local-first. Stdio MCP can access them without a
daemon. The optional daemon / serve process hosts background execution:
workers, workflow recovery, supervisor ticks and interval schedules. Starting
serve can execute queued work; its HTTP surface includes write/control routes
and has no general authentication. Keep its default loopback binding.
See the source-backed architecture and operator reference
for process boundaries, installation differences and verification limits.
For user outcomes, entry points and prerequisites, see the
product feature and capability catalog.
lean-ctx and the built-in memory aren't substitutes for each other — one saves tokens inside a session, the other saves the re-explaining tax across sessions. The coordination layer is a different axis entirely: it's not about a single session's token bill, it's about multiple agents (or multiple sessions of the same agent, over time) staying out of each other's way and handing off work cleanly.
Evidence-backed project lessons
Raw observations stay observations until an explicit memory MCP promotion:
{"action":"promote","title":"Prefer the bounded launch path","content":"Why this applies here","project":"my-project","evidence_ids":[12],"confidence":0.8,"run_id":"<workflow-run-uuid>"}
The run must exist in the workflow database, be terminal, contain a recorded execution outcome, and belong to a work item in the requested project. Supporting observations must be live and project-scoped. Promotion records the run/journal link and observation hashes in the existing relations table. Execution provenance does not prove a lesson correct; confidence remains an explicit estimate.
Recall, context, memory search and observation listings include lesson provenance
and the minimum confidence across its evidence receipts. Lesson contents and
receipts are immutable: create a new lesson for a revision, optionally relating it
with supersedes. Ordinary remember/curate writes cannot create or rewrite lessons.
Memory sync excludes local lessons and skips remote lesson imports while preserving
remote records, because its format does not carry locally verified run receipts.
Generic workflows without work-item project provenance cannot back promotion yet.
Workflow schedules
agentflare workflow schedule registers an interval trigger for a project-local
workflow at <repo>/.agentflare/workflows/<name>.json. Schedules and their
occurrence history live in ~/.agentflare/workflows.db (UTC epoch seconds,
every at least 60s). The same actions are on the workflow MCP tool:
schedule_create, schedule_list, schedule_show, schedule_update,
schedule_enable, schedule_disable, schedule_remove, schedule_fire,
schedule_runs.
Manual fire (CLI or schedule_fire) only enqueues a durable occurrence and
returns its id with status queued. It does not start a workflow run. The
daemon claims that queue on its next tick — every 60 seconds, including the
first tick after boot — and is the only process that executes it. Exiting or
killing the client does not abandon a queued occurrence. While the daemon is
down, fire still succeeds and reports queued; waiting for daemon.
The schedule ticker starts next to the binary-staleness watchdog, outside work-item dispatch recovery. A failed work-item smoke test, registration, or recovery turns work dispatch off only; schedules keep firing.
disable stops new scheduled admissions. It does not cancel a run the daemon
already claimed, and a manual fire of a disabled schedule still enqueues.
remove deletes the schedule and its occurrence history. It does not cancel
a workflow that has already started. Start receipts in workflow_start_receipts
stay behind so a later tick cannot launch that occurrence again.
The driver writes the terminal outcome into schedule_runs when it finishes.
The next tick copies the outcome if that write failed. A paused run stays
dispatched and keeps blocking overlap until something resumes or cancels it.
A committed start whose driver never launched is recorded as interrupted
and is not replaced with a new run.
Each schedule keeps the newest 100 non-skip terminal occurrences and,
separately, the newest 100 skip rows (skipped_missed, skipped_overlap).
Rows that are still queued, dispatching, or dispatched are never pruned to
make room. Receipts are kept for the life of the database in this phase.
Why Rust: the core CLI and hooks run as a native binary without requiring Node. That does not bundle every integration: lean-ctx is separate, agent execution needs the selected agent and credentials, and browser automation can download mise, agent-browser and Chrome for Testing on first use. See installation and first use.
No plugin marketplace required for Claude Code, Codex, or Cursor —
agentflare init --agent X writes hooks into the target's own settings file
(~/.claude/settings.json, ~/.codex/hooks.json, or .cursor/hooks.json).
For Codex, use init or the plugin, not both: installing both duplicates lifecycle hooks.
Metrics
The result below comes from the upstream project's benchmark, which agentflare has not re-run. It is not a prediction for your project. The coordination layer has no comparable benchmark suite yet (see STATUS.md).
| Tool | Reported result | Source and method | Limits |
|---|---|---|---|
agentflare optimize code |
About 54% less code, 20% lower cost and 27% faster | Ponytail's agentic benchmark: 12 feature tasks on one FastAPI + React repository, Haiku 4.5, four runs per task/arm | One repository and model, small sample. Code volume does not measure code quality. |
lean-ctx's earlier read-mode figures are withdrawn by upstream.
Measure your repository with lean-ctx benchmark report .; local representation
comparisons do not establish model quality or monetary savings.
Real usage, one live project
Not a demo — pulled live from the maintainer's own project while building this repo, for a sense of scale. Not a controlled benchmark; one data point, your mileage varies.
optimize code code-minimalism markers logged, no token figure (agentflare optimize code doesn't measure per-repo savings)
memory 2 sessions, 11 observations tracked, across 2 projects (agentflare memory sessions/search)
Check your own: lean-ctx gain · agentflare cost · agentflare optimize code gain/debt ·
agentflare memory context. Don't trust this table blindly either — re-run those commands yourself.
Install the CLI
Linux/macOS (downloads a prebuilt binary; verifies its checksum when
sha256sum or shasum is available, otherwise warns and skips verification;
builds from source instead if run from inside a clone):
curl -fsSL https://raw.githubusercontent.com/getappz/agentflare/master/install.sh | sh
Homebrew:
brew tap getappz/agentflare
brew install agentflare
Windows, build from source (requires Rust and a working native linker):
git clone https://github.com/getappz/agentflare
cd agentflare
.\install.ps1
Windows, Scoop (prebuilt binary — not Authenticode-signed, so Defender/SmartScreen false-positives are possible; verify with cosign/SLSA instead, see "Verifying release binaries" below; report an issue if hit):
scoop bucket add agentflare https://github.com/getappz/agentflare
scoop install agentflare
Any platform with Rust, no clone needed:
cargo install --git https://github.com/getappz/agentflare
Uninstall:
curl -fsSL https://raw.githubusercontent.com/getappz/agentflare/master/install.sh | sh -s -- --uninstall
Verifying release binaries
The Unix download installer verifies SHA-256 checksums when a checksum tool is available; source builds do not download a release binary. Checksums can catch a corrupted download, not a substituted one. For higher-assurance environments, verify the cryptographic signature and build provenance before running the binary.
cosign (signing identity)
Every release binary is signed in CI using
cosign keyless signing via the
GitHub OIDC token — the certificate is issued by Fulcio and bound to this
repo's release.yml workflow, so verifiers pin to the workflow identity
instead of a long-lived key.
VERSION=v0.x.x
FILE=agentflare-x86_64-unknown-linux-gnu.tar.gz
curl -fL -o "$FILE" "https://github.com/getappz/agentflare/releases/download/${VERSION}/${FILE}"
curl -fL -o "${FILE}.cosign.bundle" "https://github.com/getappz/agentflare/releases/download/${VERSION}/${FILE}.cosign.bundle"
cosign verify-blob \
--bundle "${FILE}.cosign.bundle" \
--certificate-identity-regexp '^https://github\.com/getappz/agentflare/\.github/workflows/release\.yml@refs/tags/v.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
"$FILE"
SLSA L3 provenance (build process)
cosign proves this repo's CI signed it; SLSA provenance proves how it was
built — which commit, workflow, and inputs. Releases include a
<tag>.intoto.jsonl attestation generated by the
SLSA GitHub generator.
Verify with slsa-verifier:
curl -fL -o "${VERSION}.intoto.jsonl" "https://github.com/getappz/agentflare/releases/download/${VERSION}/${VERSION}.intoto.jsonl"
slsa-verifier verify-artifact \
--provenance-path "${VERSION}.intoto.jsonl" \
--source-uri github.com/getappz/agentflare \
--source-tag "${VERSION}" \
"$FILE"
Both print a Verified/PASSED line and exit 0 on success — do not run the
binary on failure. --certificate-identity-regexp/--certificate-oidc-issuer
and --source-uri/--source-tag are the load-bearing flags in each command;
loosening any of them defeats the point.
| Attack | SHA-256 checksums | cosign keyless | SLSA L3 provenance |
|---|---|---|---|
| Corrupted download | ✅ caught | ✅ caught | ✅ caught |
| Substituted binary at release | ❌ SHA256SUMS would also be swapped | ✅ certificate identity ≠ this repo's workflow | ✅ provenance source-uri ≠ this repo |
| Stolen release-pipeline secret | ❌ | ✅ no long-lived secret to steal | ✅ provenance binds to specific workflow run |
| Tampered build process | ❌ | ❌ — cosign signs the artifact, not the build | ✅ provenance records the exact workflow, commit, and inputs |
SHA-256 stays the default in the installers above because it needs no extra client-side tooling; cosign and SLSA are opt-in for environments that need the higher tier.
Set up an agent
One command per tool. init checks existing components, installs missing ones,
merges host configuration, and can prompt to refresh rules or configure optional
integrations.
agentflare init --agent claude-code # writes ~/.claude/settings.json hooks directly, no marketplace
agentflare init --agent codex # writes ~/.codex/hooks.json and registers the MCP server
agentflare init --agent cursor # writes .cursor/hooks.json directly, no marketplace
agentflare init --agent windsurf
agentflare init --agent vscode-copilot
agentflare init --agent cline
agentflare init --agent continue
Codex loads hooks from ~/.codex/hooks.json; init wires the supported
agentflare lifecycle hooks there. The .codex-plugin/ compatibility manifest
also supports packaging those hooks in a Codex plugin. Use one hook installation
path per machine so events do not run twice. In Codex, review the installed
hooks with /hooks and trust them before relying on them in interactive or
headless runs. Codex requires trust for non-managed hooks. After reviewing a
work item, mcp__flare__review(action="submit", findings=[...]) records review
completion for the item gate; an empty findings list is valid when the review
found no issues. For verification, run tests through mcp__lean_ctx__ctx_shell:
Codex's native Bash hook omits the process exit status, so its result cannot
prove that a test passed.
Each run checks rule files, installs lean-ctx if missing, and wires hooks/MCP where the host supports it. Already-satisfied components are skipped; managed rules and existing hook configuration may be refreshed or merged. Persistent memory ships in the binary itself — nothing to install for it.
Claude plugin
For Claude Code you can install agentflare as a plugin instead of wiring command
hooks. The plugin's mod runs inside Claude Code and calls the agentflare mcp
server's autopilot tool, so the hot paths no longer spawn an agentflare hook
process per tool call.
/plugin install agentflare --marketplace getappz/agentflare
The plugin lives in its own root, plugins/agentflare-claude/ (manifest,
hooks.json, the mod under mod/, its tests under tests/); the repository
marketplace points there, so the repo-root hooks/hooks.json (the Codex
plugin's) is never loaded into Claude Code. To work on it, run
claude --plugin-dir plugins/agentflare-claude, and check it with
claude plugin validate plugins/agentflare-claude and
claude plugin test plugins/agentflare-claude.
It provides:
- In-process guards: the same checks as the
PreToolUsehook, in the same order and with the same reasons (branch guard, destructive-data guard, claim guard, TodoWrite redirect, enforced coaching rules, completion gate), run before every mutating, shell, TodoWrite, ToolSearch, review and gateway call and fail closed; read-only calls can be auto-allowed. Enforced coaching rules apply only to those checked tools: a rule whose trigger is another tool (WebFetch, Grep, Task and so on) is not enforced in plugin mode. They key on agentflare's tools under whatever name its server runs (mcp__flare__*, ormcp__plugin_agentflare_agentflare__*in a plugin-only install). - Cached briefing: identity, active item and coaching are served as a system-prompt section and refreshed when the item changes.
- Compaction checkpoint: a handoff is written before
/compactand re-injected on the next turn. - Subagent shaping: every subagent spawn is shaped and routed.
- Turn-end memory capture: learnings are classified and remembered when a turn ends.
- Attended autopilot: pulls the next ready item when the session is idle.
Control it with /flare status|autopilot on|off|once|doctor|briefing refresh.
Settings (userConfig):
| Field | Default | Meaning |
|---|---|---|
autopilot |
off |
off, once (pull one item, then back to off) or on |
idleMinutes |
3 |
Idle time before autopilot pulls work |
maxCostUsd |
25 |
Session cost ceiling above which autopilot will not pull work |
memoryCapture |
auto |
auto, ask or off |
readOnlyAutoAllow |
false |
Let the guard turn a prompt on a read-only tool into an allow. Off by default because it also overrides your own ask rules; deny is always kept |
guardTimeoutMs |
3000 |
How long a guard check waits for the MCP server |
When the plugin is installed, agentflare init --agent claude-code skips the
PreToolUse, PostToolUse, PreCompact and SubagentStart hooks the mod
covers, and agentflare doctor flags any of them that are wired twice. Stop
(inter-agent mail, busy/idle liveness) and PostToolUseFailure (friction
nudges, failure recall) stay wired: the mod does not cover them. The
PreToolUse hook also delivered mid-turn mail, the batching and staleness
nudges and per-tool coaching nudges; in plugin mode mail arrives at turn end
through Stop, and the nudges are not produced. Requires Claude Code 2.1.287 or newer.
Notes:
- If you already configured an MCP server that runs the same
agentflare mcpcommand (for example one namedflare), Claude Code drops the plugin's own copy as a duplicate and the mod talks to yours. Nothing to change; just keep that server pointing at anagentflarebinary that has theautopilottool. - The mod's own calls to that server (
autopilot,memory,get_routing_suggestion) are allowed at the permission check, so they work in headlessclaude -pand auto mode without--allowedTools. The same tools called by the model keep your normal permission rules. - Classic
PreToolUse/PostToolUsecommand hooks you still have wired run on the mod's own calls too, so leave them unwired (asinitdoes) to keep the spawn savings.
agentflare MCP questions
What does agentflare optimize?
It reduces token and cost overhead by compressing tool I/O, markdown files, code, and session context.
Does agentflare require Node.js to run?
No, the core CLI is a Rust binary that requires no Node runtime.
Can agentflare coordinate multiple agents?
Yes, it provides a coordination layer for running multiple agents or sessions against the same body of work using MCP tools.
How does the memory feature work?
It provides built-in knowledge across sessions using SQLite and FTS5 to store decisions, facts, and preferences.