A repo-native, multi-agent coding loop powered by 9+ LLMs (isolated via
Claude Code) and an independent Codex reviewer. Lightweight, bounded, and
self-improving (Self-Harness) - no coordinator training required.
It is intentionally provider-neutral: use the accessible models you trust
today, add more runtimes tomorrow, and keep the engineering loop the same.

Highlights

• One operator surface - fuguectl drives preflight, dispatch, cache,
  integration, review, loop state, routing, skills, and runtime maintenance.
• Runtime-neutral agents - logical agent profiles route work to Claude Code
  provider instances, Codex models, OpenCode providers, or future harnesses
  without changing the loop.
• Extensible model pool - current profiles are just starting points.
  Community adapters can add accessible commercial, open, private, local, or
  self-hosted models without changing FuguNano's core contract.
• Real isolation - workers edit separate worktrees with scoped workspaces,
  selected skills, and optional ownership enforcement.
• Review stays independent - implementers write, while Codex or another
  configured independent reviewer returns ACCEPTED or NEEDS FIX.
• No lost outputs - dispatch can persist reviewer/agent output with --out,
  and the join barrier still enforces N sent, N returned.
• Bounded repair - keep-best, confirmation passes, user escalation, and
  non-convergence states keep the loop from spinning forever.
• Learning without training - allocation blends benchmark priors with live
  review outcomes, and completed TASK traces can be distilled into replayed
  experience memory selected by the next task or prompt.
• Self-Harness ready - the TypeScript engine can mine failed runs, propose
  bounded harness edits, and promote only non-regressing changes.

Quick Start

Requirements: macOS or Linux, Node.js >= 18.18, git, tmux, and the model/API
credentials you choose to use. Codex is recommended for review.

git clone https://github.com/BicaMindLabs/FuguNano fugunano
cd fugunano

/path/to/fugunano/orchestration/fuguectl/fuguectl help quickstart
/path/to/fugunano/orchestration/fuguectl/fuguectl init --dry-run
make doctor       # inspect local CLIs and provider readiness
make install      # install model launchers
make verify       # verify launcher wiring
make ci-clean     # run the full local gate from a clean engine install

Real keys stay outside the repository:

mkdir -p ~/.config
$EDITOR ~/.config/cc-model-secrets.env

Choose the runtimes you want to use. The TypeScript engine now models agents as
profiles: a logical id, a harness (fugue-cc, codex, opencode), an optional
harness-native target, and a model family used by policy. See
docs/AGENT_RUNTIME.md.

For the optional fugue-cc worktree fleet, add a provider config to the project
you want the fleet to edit:

cp orchestration/fugue-cc/provider.config.example /path/to/project/.fugue-cc/provider.config
cd /path/to/project
fugue-cc

Then run the operator from another shell:

/path/to/fugunano/orchestration/fuguectl/fuguectl preflight --harness fugue-cc
/path/to/fugunano/orchestration/fuguectl/fuguectl fleet status

Operator Skill

make install-skill

This installs /fugunano to ~/.claude/skills/fugunano as a convenience operator
entry for Claude Code. The workflow itself is not Claude Code-specific: Codex,
OpenCode, Antigravity, and other agents can follow AGENTS.md and
dispatch through the same agent profiles. Smoke-test the installed bundle:

~/.claude/skills/fugunano/fuguectl selftest

How The Loop Works

fuguectl preflight --harness codex        # lite reviewer path
fuguectl preflight --harness opencode --target opencode/deepseek-v4-flash-free
fuguectl preflight --harness agy
fuguectl preflight --harness lite         # all lite runtimes: codex + opencode + agy
fuguectl preflight --harness fugue-cc     # full worktree fleet path
fuguectl task new "implement feature"
fuguectl plan "implement feature" --harness lite --codex-clean --allow-partial --out /tmp/fugunano-plan --task TASK.md
fuguectl dispatch cc-deepseek --template impl --task TASK.md --task-type backend
fuguectl cache barrier <round>
fuguectl integrate --work /path/to/project --agents "cc-deepseek cc-kimi"
fuguectl loop record --verdict NEEDS_FIX --round 1
fuguectl loop decide

Read the full walkthrough in docs/WORKFLOW.md.

Fugu, OpenFugu, And FuguNano

Sakana Fugu, OpenFugu, and FuguNano share the same direction: when a
single frontier model or hardware path is expensive, unavailable, or hard to
govern, coordination becomes the system capability. The difference is where
that coordination layer lives.

FuguNano is not a replacement for Fugu or OpenFugu. It is the lightest open
entry point on the same road: use policies, ports, review gates, and harness
improvement first, then decide whether a learned conductor is worth the cost.

The planning panel prints per-agent dispatch duration and, with --task,
persists planner status, output size or error kind/exit code, plus artifact
paths in the TASK log through append-safe writes, so concurrent planners do not
overwrite each other's audit lines. dispatch --verbose prints an obs line to stderr, and dispatches with --task persist
start status plus terminal status, duration, output size, error kind on failure,
and optional --out artifact path in the TASK log, so live Codex/OpenCode/AGY
runs leave an observable trace without contaminating model stdout or durable
artifacts. task new uses exclusive file creation for concurrent operators, and
all TASK audit appenders (task log, dispatch --task, plan --task,
summary --task, integrate --task) share a lightweight lock with task done
so final status updates do not clobber concurrent audit lines.

Command Surface

orchestration/fuguectl/fuguectl is the production operator entry point. It has
24 subcommands and 25 test suites.

TypeScript Engine

engine/ is the typed implementation: strict TypeScript, ports-and-adapters
layering, pure domain policy, and real harness/storage adapters.
AgentRegistry is the engine-native step away from script-first orchestration:
the coordinator can dispatch one round across fugue-cc, Codex, and OpenCode
by resolving logical agent ids to runtime profiles.

cd engine
npm run check
npm run build
node dist/cli/main.js version

The engine CLI currently exposes:

fugue version
fugue doctor
fugue init [--dry-run|--write]
fugue fleet status|up|down
fugue allocate <task-type>|list|record|feed|stats|reset|decay
fugue smoke [--harness all|codex|opencode|agy] [--timeout-ms n] [--task <file>] [--out-dir <dir>]
fugue dispatch <target> --harness fugue-cc|codex|opencode|agy [--timeout-ms n] [--codex-clean] [--harness-arg x] [--out <file>] [--require-output] [--verbose] --template <name>|--prompt-file <file>|--prompt <text>
fugue integrate --work <repo> --agents "a b" [--ownership file] [--dry]
fugue skills index|list|match|show|inject|validate|forge
fugue preflight [--harness fugue-cc|codex|opencode|agy|lite|all] [--model provider/model|--target provider/model] [--config-only] [provider.config]
fugue cache init|put|fail|status|barrier|collect|list|resume --cache <dir>
fugue plan "<goal>" --harness fugue-cc|codex|opencode|agy|lite --out <dir> [--models m1,m2] [--timeout-ms n] [--allow-partial] [--codex-clean] [--harness-arg x] [--codex-arg x] [--opencode-arg x] [--agy-arg x] [--task <file>]
fugue task new|log|done
fugue template <name> --dir <templates> [--set KEY=VALUE ...]
fugue workspace list|show|model|context
fugue experience add|learn|list|recall|show --store <dir>
fugue summary <round> --cache <dir> [--task <file>]
fugue runtime check [--strict] --state <dir> [--skill <installed SKILL.md>] [--alias-skill <legacy SKILL.md>] [--repo-skill <repo SKILL.md>]
fugue runtime adapt --state <dir> [--skill <installed SKILL.md>] [--alias-skill <legacy SKILL.md>] [--repo-skill <repo SKILL.md>]
fugue run set|round|status|next|clear
fugue loop init|record|decide|next|status
fugue goal template|show|check
fugue agent-registry template|validate|list|resolve
fugue self-harness template|run

Quick live smoke, after preflight --harness lite passes:

fuguectl preflight --harness lite
fuguectl smoke --harness all --codex-clean --timeout-ms 120000 --task TASK.md --out-dir /tmp/fugunano-smoke

When --out-dir is set, smoke writes per-harness transcripts plus
summary.json, a machine-readable result manifest with top-level
status/passed/failed/exitCode plus status, duration, output size, and
artifact path for each lite runtime. With --task, the audit log also records
the final summary path and pass/fail counts.

For OpenCode, preflight --target <provider/model> checks the local
opencode models registry before dispatch, so a stale or unavailable model is
caught before the run starts.
For Antigravity, --harness agy dispatches through agy --prompt; target
default uses the current Antigravity settings, while any other target is passed
as --model.
For planning across the Codex Bar runtimes, fuguectl plan --harness lite
dispatches to Codex, OpenCode, and Antigravity in parallel. Custom lite planner
targets must be prefixed, for example
--models codex:gpt-5.5,opencode:opencode/deepseek-v4-flash-free,agy:default.
Add --codex-clean when a Codex planner should ignore local config/rules while
keeping the plan output directory writable; OpenCode and Antigravity keep their
own runtime args.
Add --allow-partial during exploratory planning when a slow planner should not
discard successfully completed plans from the others.
When --out is set, planning also writes <out>/summary.json with top-level
status/exitCode/allowPartial/succeeded/available/failed plus each
planner's artifact status, duration, and error metadata. The summary is written
at dispatch start as status=running with per-planner artifactStatus=pending,
then atomically replaced by the final ok|partial|failed result.

runtime check also compares the repo's orchestration/fuguectl/ bundle with
the installed workflow bundle. Add --strict when automation should fail on
installed-skill drift:
fuguectl runtime check --strict --skill ~/.claude/skills/fugunano/SKILL.md --repo-skill orchestration/fuguectl/SKILL.md.
By default, runtime sync also checks the legacy ~/.claude/skills/fugue alias
when the primary target is the canonical fugunano skill; use --alias-skill
to add explicit migration aliases. runtime adapt --apply syncs all configured
skill targets, so local agent instructions and helper entrypoints do not drift
behind the repo after the workflow evolves. If fugue-cc is unavailable, adapt
still syncs the bundle but exits non-zero so provider automation can detect the
skipped runtime restart/stamp.

Self-Harness

Self-Harness improves the harness configuration, not the base model. FuguNano's
implementation is an engine-native abstraction inspired by Shanghai Artificial
Intelligence Laboratory's paper
Self-Harness: Harnesses That Improve Themselves.

orchestration/fuguectl/fuguectl self-harness template > /tmp/self-harness.json
orchestration/fuguectl/fuguectl self-harness run \
  --spec /tmp/self-harness.json \
  --state ~/.config/fugunano \
  --cwd /path/to/workspace

The strict JSON spec, editable surfaces, validation rules, and smoke tests are in
docs/SELF_HARNESS.md.

Repository Map

Safety Model

• Keep real keys in ~/.config/cc-model-secrets.env or ignored local config.
• Keep .fugue-cc/ out of git.
• Route review to Codex or another independent reviewer. Antigravity (agy) is supported as an implementer runtime; legacy gemini CLI is retired.
• Never advance a round until the join barrier has all terminal results.
• Let deterministic gates fail before spending reviewer tokens.
• Run npm run ci before pushing.

Development

make ci          # scan + launcher lint + docs + plugin/fuguectl + engine checks
make ci-clean    # same, but clean-installs engine dependencies first
make scan        # secret-leak gate
make lint        # Node launcher syntax check
make check-docs  # README + Self-Harness docs drift gate
make test        # cn-plugin + fuguectl selftest
make test-engine # TypeScript engine typecheck + lint + vitest
make doctor      # local environment recon
make help        # list all make targets

Root npm scripts mirror the same gates:

npm run ci
npm run ci:clean
npm run lint:launchers
npm run test:fuguectl
npm run test:engine

Security

See SECURITY.md. The repository contains only sanitized examples,
CI scans for leaks, and vulnerabilities should be reported privately through
GitHub Security Advisory.

Acknowledgements

• Sakana AI Fugu for the diverse-model orchestration framing.
• trotsky1997/OpenFugu for the complementary training-based reconstruction.
• openai/codex-plugin-cc for the plugin architecture that the /cn:* layer derives from.
• Zleap-AI/Zleap-Agent for workspace isolation and experience-memory inspiration.
• SeemSeam/claude_codex_bridge as a reference for the provider-runtime bridge.
• Shanghai Artificial Intelligence Laboratory's Self-Harness paper for the harness-improvement loop that inspired fuguectl self-harness.
• kunchenguid/no-mistakes and lavish-axi for loop-state and docs-drift ideas.
• merkyor/Lynn for orchestrator-side ownership enforcement inspiration.
• Anthropic's official skill-creator meta-skill for the skill authoring and validation flow.

See NOTICE for attribution detail.

License

Apache-2.0 © 2026 BicaMind Labs.