# Agentflare

> Run AI coding agents efficiently, and coordinate more than one of them. Zero fluff, zero runtime deps.

- **Type:** MCP server
- **Install:** `agentstack add mcp-getappz-agentflare`
- **Verified:** Pending review
- **Seller:** [getappz](https://agentstack.voostack.com/s/getappz)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [getappz](https://github.com/getappz)
- **Source:** https://github.com/getappz/agentflare
- **Website:** https://agentflare.dev

## Install

```sh
agentstack add mcp-getappz-agentflare
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# agentflare

**Run AI coding agents efficiently, and coordinate more than one of them.**
**A single Rust binary, no Node, no runtime dependencies — across Claude Code,
Codex, Cursor, Windsurf, VS Code, Cline, and Continue.**

[](LICENSE)
[](STATUS.md)

---

## Status: Beta

agentflare is under active development. The optimization layer (lean-ctx
integration, memory, Caveman/Ponytail wiring) is the most mature part — CI-gated,
tested, in daily use. The multi-agent coordination layer (tasks, review, coaching,
artifacts, handoffs) 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](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** | tool I/O *within* a session — reads, shell output, search, up to 99% | [yvgude/lean-ctx](https://github.com/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 |
| **Caveman** (Claude Code only) | conversation verbosity, ~65% | companion plugin |
| **Ponytail** (Claude Code only) | code-writing over-engineering | companion plugin |

**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. |
| **Review** (`review`) | Submit findings against a diff/PR, run consensus across reviewers, track scores over time. |
| **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 today, moving toward contextual triggers (tool-name and prompt-relevance) so rules only show up when actually relevant. |
| **Comments, labels, projects, webhooks, channel_send** | Threaded discussion on items, categorization, cross-project views, and outbound notifications. |

Everything above is local-first (SQLite-backed), no daemon, reachable over the
same stdio MCP transport agentflare already exposes for the optimization layer.

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.

**Why Rust, not Node:** Claude Code doesn't bundle or require Node.js — it's a
standalone compiled binary. A plugin whose hooks shell out to `node` breaks on
any machine that installed Claude Code without separately installing Node.
agentflare is a single static binary; the only runtime dependency is agentflare
itself.

**No plugin marketplace for Claude Code or Cursor** — `agentflare init --agent X`
writes the hook config directly into the target's own settings file (Claude
Code's `~/.claude/settings.json`, Cursor's `.cursor/hooks.json`). Codex is the
one exception: its hook system only activates through its plugin loader, so
that wiring ships as a small `.codex-plugin/` manifest instead.

## Metrics

Numbers below are each project's own published, reproducible benchmarks — attributed,
not blended into a fake combined total, and not accepted on faith. Where a claim had no
supporting evidence in its own repo, it's flagged instead of repeated. These cover the
**optimization layer** specifically — the coordination layer is too new for a
comparable benchmark suite yet (see [STATUS.md](STATUS.md)).

| Tool | Published claim | Methodology | Confidence |
|---|---|---|---|
| lean-ctx | 98.1% compression (`map` mode), 96.7% (`signatures`), ~99.99% cached re-read | CI-gated, reproducible via `lean-ctx benchmark report .`, measured on a 50-file repo with the GPT-4o tokenizer | High — real, reproducible, methodology named |
| Caveman | 65% avg output-token reduction (range 22–87%, 10 prompts) | Committed in `benchmarks/`/`evals/` — and its own docs flag the failure mode: ~1–1.5k input-token overhead per turn can make it net-negative on already-terse workloads (`docs/HONEST-NUMBERS.md`) | High — reproducible, unusually transparent about limits |
| Ponytail | ~54% less code (94% ceiling on best task), ~20% cheaper, ~27% faster, 100% safe | 12 real feature tasks on a FastAPI+React repo, Haiku 4.5, n=4 — self-corrected an earlier overgeneralized single-shot figure | High — reproducible, self-corrected once already |

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

```
lean-ctx   34.2M tokens saved   92% compression   $88.45 saved   (lifetime; lean-ctx gain)
caveman    1.16M tokens saved (~65%)                              (single session; caveman-stats hook)
ponytail   23 `ponytail:` shortcut markers logged, no token figure (ponytail 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` · `/caveman-stats` (Claude Code) · `ponytail-debt` skill ·
`agentflare memory context`. Don't trust this table blindly either — re-run those commands yourself.

---

## Install the CLI

**Linux/macOS** (downloads a prebuilt binary, checksum-verified; builds from
source instead if run from inside a clone):
```bash
curl -fsSL https://raw.githubusercontent.com/getappz/agentflare/master/install.sh | sh
```

**Homebrew:**
```bash
brew tap getappz/agentflare
brew install agentflare
```

**Windows, build from source** (no unsigned prebuilt binary to trip an AV
heuristic):
```powershell
git clone https://github.com/getappz/agentflare
cd agentflare
.\install.ps1
```

**Windows, Scoop** (prebuilt binary — unsigned, like most small Rust CLIs;
Defender/SmartScreen false-positives are possible, report an issue if hit):
```powershell
scoop bucket add agentflare https://github.com/getappz/agentflare
scoop install agentflare
```

**Any platform with Rust, no clone needed:**
```bash
cargo install --git https://github.com/getappz/agentflare
```

**Uninstall:**
```bash
curl -fsSL https://raw.githubusercontent.com/getappz/agentflare/master/install.sh | sh -s -- --uninstall
```

## Set up an agent

One command per tool, run once. Running it is the consent — installs happen
immediately, no separate confirm step.

```bash
agentflare init --agent claude-code    # writes ~/.claude/settings.json hooks directly, no marketplace
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** is the one exception — its hook system only activates through its own
plugin loader:
```
codex plugin marketplace add getappz/agentflare
codex plugin install agentflare
```
then `agentflare init --agent codex` for the rules/lean-ctx setup (Codex's
hook wiring itself comes from the plugin manifest, not `init`).

Each run: writes rule files (if absent), installs lean-ctx (native `curl | sh`
or Homebrew installer) if missing, wires hooks/MCP where the host supports
it. Detection-first — already-satisfied components are skipped, nothing gets
clobbered. Persistent memory ships in the binary itself — nothing to install
for it.

## Docs-only fallback (Aider, other AGENTS.md readers)

```bash
curl -sL https://raw.githubusercontent.com/getappz/agentflare/master/AGENTS.md > AGENTS.md
```

---

## Architecture

```
src/
├── paths.rs             # home-dir resolution (AGENTFLARE_HOME_OVERRIDE for tests —
│                         # dirs::home_dir() ignores HOME/USERPROFILE overrides on
│                         # Windows, learned the hard way)
├── state.rs              # ~/.agentflare/state.json — on/off flag for the hooks
├── rule_text.rs           # shared rule copy (Exa, git, lean-ctx usage)
├── memory/                # built-in persistent memory (SQLite + FTS5)
├── compact.rs             # ephemeral FTS5/BM25 relevance scorer (PreCompact hook)
├── coaching/               # session nudges: rule storage, CRUD, CLI presentation
├── claims.rs, review.rs    # work-item claiming, review/consensus (coordination layer)
├── artifacts.rs, channels.rs   # artifact publishing, outbound notifications
├── mcp_server.rs, mcp_prompts.rs  # MCP stdio server exposing both layers as tools
├── auth.rs, auth_crypt.rs, auth_db.rs, auth_runner.rs  # auth profile vault
├── components.rs          # registry: each entry checks + fixes itself, host-aware
├── init.rs                # `agentflare init --agent X` — runs every component,
│                           # wires hooks directly for claude-code/cursor
├── hook.rs                # `agentflare hook session-start|prompt-submit|... --agent X`
└── main.rs                 # clap CLI, dispatch across 45 modules

.codex-plugin/              # Codex only — its hooks require the plugin loader
install.sh, install.ps1      # installers (checksum-verified download / local build)
.github/workflows/          # ci.yml (build+test), release.yml (cross-compile on tag)
```

Adding a new managed component means adding one entry to `components.rs` — neither
`init` nor `hook` hardcodes per-tool logic.

---

## What Gets Created

**Claude Code**: `~/.claude/rules/{exa,git,lean-ctx}.md`, `~/.claude/settings.json` hooks section, `~/.config/{caveman,ponytail}/config.json`, `~/.agentflare/` (includes the built-in memory database).

**Codex**: project-local `AGENTS.md` (only if absent), `~/.agentflare/`.

**Cursor**: project-local `.cursor/rules/agentflare.mdc`, `.cursor/hooks.json`, `~/.cursor/mcp.json`, `~/.agentflare/`.

**Windsurf/VS Code/Cline**: project-local rules file (see table above), MCP config for lean-ctx.

**Continue**: `.continue/mcpServers/agentflare.json`.

Nothing is created if it already exists.

---

## Uninstall

Remove the binary (see Install section above), then remove whatever `init`
wrote for the hosts you set up — see "What Gets Created" above. Ponytail/
Caveman plugins themselves stay installed (uninstall separately if wanted).

---

MIT License

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [getappz](https://github.com/getappz)
- **Source:** [getappz/agentflare](https://github.com/getappz/agentflare)
- **License:** MIT
- **Homepage:** https://agentflare.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-getappz-agentflare
- Seller: https://agentstack.voostack.com/s/getappz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.