mayfly

Short-lived agents. One task. Then gone.

Ephemeral single-purpose workers for Cursor, Claude, Codex, OpenCode, and friends.

mayfly hatch examples/fix-test.json --worktree /path/to/repo
# → validate → buckets worktree → spawn harness → watch done_when / TTL → tear down → report

Not a teammate. Not a persona. A disposable specialist with a hard lifespan.

Current release: v0.1.6 · repo nixpt/mayfly

Long-lived agent sessions expand scope, linger, and multiply. mayfly is the opposite contract:

For durable fleet work, use horses + agent-launch. For "fix this one thing and vanish", use mayfly.

cargo install --git https://github.com/nixpt/mayfly --tag v0.1.6
# or from a checkout:
cargo install --path .
# binary: mayfly

Not yet installed on nixps (s463): nothing puts mayfly on PATH there.

Needs host harness binaries on PATH for the runners you use (cursor-agent, claude, codex, …). Optional: buckets for --worktree.

copilot tools (MAYFLY-16). Rules are translated into Copilot permission rules, never broadened silently: Bash → shell, Bash(cmd) / Bash(prefix:*) → shell(cmd) / shell(prefix:*); Edit → write; Edit(//abs/file) → write(/abs/file) and Edit(/file) → write(<cwd>/file), with --add-dir for a directory outside the project; bare Read/Grep/Glob/LS need no rule. Globs, path-scoped reads, bare relative Edit(file) (Copilot would match that name in any directory), MCP tools and any other tool are refused. With no Bash rule the shell is denied outright. With one, validate notes that Copilot also auto-approves its built-in read-only commands (ls, cat, pwd, git log, gh pr list, …): writes, network and other commands stay denied (live-verified, Copilot CLI 1.0.98).

tools and read_only are mutually exclusive. mcp_servers without tools is refused. An mcp__<server>__* tool whose server is not listed in mcp_servers is refused. Unknown mcp_servers names (missing from the user's Claude mcpServers) fail validate.

"Refused" means validate/hatch exit 2 before anything is created. A knob that would be silently ignored is worse than a refusal: the caller would believe a cheap, read-only, capped run happened.

A read-only hatch can't write files, so its done_when must not require writes. Its answer is the harness's stdout (stdout_tail in the report).

Success requires done_when to pass (and the harness to exit 0). MAYFLY_DONE printed without a passing done_when is recorded as a failed claim, not a success. For exec, the exit code must equal expect_exit. A failed hatch never exits 0, even when the harness did.

In a repo that has adopted .jagent/ (the fleet's v2 layout), mayfly keeps both halves with the project:

mayfly init-runners                        # scaffold read.json (claude, haiku, read_only, 10m, $0.25) + README; never overwrites
mayfly runners                             # name  harness  model  read_only  ttl
mayfly hatch task.json --runner read       # runner defaults merged under the task
mayfly validate task.json --runner read

Merge rule: the task's fields win, and nested objects (budget, constraints, aging) merge key by key. Arrays and scalars are replaced. task and done_when must come from the task; a runner that sets them is rejected. An unknown --runner exits 2 and lists the known ones.

State dir precedence: --state-dir > MAYFLY_STATE_DIR > <main checkout>/.jagent/local/mayfly (when the task's cwd, or the caller's for list/status, is inside a repo whose main checkout has .jagent/; linked worktrees resolve to their main checkout) > ~/.local/state/mayfly. mayfly warns if .jagent/local/ isn't gitignored. It never creates .jagent/ in a repo that hasn't adopted it: runner commands exit 2 there, and state falls back to home. .jagent/state/ is reserved for squadron and never used.

# Check a task without spawning
mayfly validate examples/fix-test.json

# Hatch (dry-run prints the plan; omit --dry-run to launch)
mayfly hatch examples/fix-test.json --dry-run

# Hatch into a throwaway git worktree (public nixpt/buckets — on PATH)
mayfly hatch examples/fix-test.json --worktree /path/to/repo
mayfly hatch examples/fix-test.json --worktree . --branch mayfly/demo --keep-worktree

# Watch / force end
mayfly status <id>
mayfly expire <id>
mayfly list

--worktree shells out to buckets worktree create/remove (no crates.io path-dep). Flame/firefly are intentionally not used for hatch cwd — different layer.

{
  "task": "Fix the failing test in foo::bar::test_baz",
  "done_when": {
    "type": "command",
    "run": "cargo test -p foo bar::test_baz -- --exact",
    "expect_exit": 0
  },
  "harness": "cursor",
  "cwd": ".",
  "ttl": "15m"
}

See DESIGN.md for the full contract (aging ladder, adapters, fuzziness gate).

Fleet wrappers ccf / cxf are shell functions; export their env (or run under a login zsh that defines them) before mayfly hatch with harness ccf/cxf.

Optional smoke (needs jq + harness on PATH):

cargo build --release
MAYFLY_BIN=./target/release/mayfly ./scripts/smoke-harness.sh cursor
MAYFLY_BIN=./target/release/mayfly ./scripts/smoke-harness.sh cxf   # FLOWNET_TOKEN_CODEX
MAYFLY_BIN=./target/release/mayfly ./scripts/smoke-harness.sh ccf   # ANTHROPIC_* flownet env
MAYFLY_OPENCODE_MODEL=opencode/big-pickle \
  MAYFLY_BIN=./target/release/mayfly ./scripts/smoke-harness.sh opencode

Missing harness binaries error clearly (harness '…' binary … not found on PATH) instead of hanging.

From a dispatched horse or any shell with buckets + mayfly on PATH:

mayfly hatch /path/to/task.json --worktree "$REPO"
# provisions sibling worktree via buckets, runs harness, tears down with --force

Prefer mechanical done_when + TTL ≤ 2h. Durable multi-step work stays on horses/agent-launch.

Ready-made tasks under examples/fleet/ for repetitive fleet chores (Haiku, curated tools — no --dangerously-skip-permissions). All three verified live (2026-10-08).

Writing a fleet task:

• File rules are Edit(//abs/path): Write(...) rules never match, and /x in a rule is project-root-relative.
• A Bash(prefix:*) rule matches one simple command. Tell the agent to run each command alone (no loops, pipes, &&, ;, redirects); a compound command is denied unless every part matches.
• done_when must still fail before the agent starts. hatch refuses one that already passes (a stale output file, command: true): it would end the hatch at the first poll, before the agent did anything.

mkdir -p /build/tmp/mayfly
mayfly hatch examples/fleet/mailer.json                         # → /build/tmp/mayfly/mailer-digest.md
AGENT_NAME=foreman mayfly hatch examples/fleet/inbox-digest.json # → /build/tmp/mayfly/inbox-digest.md
mayfly hatch examples/fleet/pr-survey.json                       # → /build/tmp/mayfly/pr-survey.md

Delete the previous output first; a leftover file makes done_when pass before the agent starts.

foreman / horse     → multi-step, memory, merge
mayfly              → throwaway *agents* (harness + TTL)
agent-launch        → resource-controlled durable dispatch
buckets             → throwaway *runtimes* + *worktrees* (mayfly uses worktree)
flame / firefly     → workspace OS (heat/brands/fuel) — held, not wired

Self-contained: no path deps on peer projects.

The project logo, monochrome mark, and social preview are in assets/. See assets/README.md for usage and palette details.

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.