FuguNano

Open & light-weight reimplementation of Sakana Fugu

Evidence-gated Evo Engineering for multi-agent software work

Quick Start | How It Works | Commands | Workflow | Self-Harness | Parity

FuguNano is a small, training-free control plane for multi-agent coding. It does not train a conductor — it makes the agents you already have work as one auditable loop: plan, dispatch, gather, review, repair, learn, and improve the harness itself. Every step is backed by deterministic evidence, not model prose.

Why FuguNano

How It Works

One short pipeline, gated at every hop by the packets below:

flowchart LR
  A["TASK"] --> B["Plan"]
  B --> C["Guard prompt"]
  C --> D["Dispatch agents"]
  D --> E["Cache + join barrier"]
  E --> F["Integrate worktrees"]
  F --> G["Independent review"]
  G -->|ACCEPTED| H["Ship + learn"]
  G -->|NEEDS FIX| I["Review/incident/recovery packets"]
  I --> J["Bounded repair loop"]
  J --> G
  H --> K["Self-Harness"]
  K --> B

The day-to-day path is intentionally short:

fuguectl preflight --harness lite
fuguectl preflight --harness codex
fuguectl preflight --harness opencode --target opencode/deepseek-v4-flash-free
fuguectl preflight --harness agy
fuguectl preflight --harness fugue-cc

fuguectl task new "implement feature"
fuguectl plan "implement feature" --harness lite --models a,b --out /tmp/fugunano-plan --timeout-ms 120000 --allow-partial --codex-clean --harness-arg x --codex-arg x --opencode-arg x --agy-arg x --task TASK.md
fuguectl guard prompt /tmp/prompt.md --source-ref TASK.md
fuguectl dispatch cc-deepseek --template impl --task TASK.md --task-type backend
fuguectl cache barrier 1
fuguectl integrate --work /path/to/project --agents "cc-deepseek cc-kimi"
fuguectl review packet /tmp/review.txt --json
fuguectl incident packet /tmp/failure.log --json
fuguectl incident recovery /tmp/failure.log --json
fuguectl loop record --verdict NEEDS_FIX --round 1
fuguectl loop decide

fuguectl smoke --harness all --codex-clean --timeout-ms 120000 --task TASK.md --out-dir /tmp/fugunano-smoke writes summary.json with status/passed/failed/exitCode.

fuguectl plan ... writes <out>/summary.json with status/exitCode/allowPartial/succeeded/available/failed, so planning can be inspected without reading model chat.

Quick Start

Requirements: macOS or Linux, Node.js >= 18.18, git, tmux, and whichever model credentials you choose to use. Codex is recommended for independent 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
make install
make verify
make ci-clean

Real keys stay outside the repository:

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

For the optional fugue-cc worktree fleet:

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

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

Install the operator skill:

make install-skill
~/.claude/skills/fugunano/fuguectl selftest

The skill is convenient for Claude Code, but the workflow is runtime-neutral. Codex, OpenCode, Antigravity, and future agents use the same agent profiles. Frontend/UI work may be sent through agy --prompt "..."; review should remain independent.

Evidence Packets

The loop does not run on prose — it runs on typed packets. Each one is deterministic TypeScript that gates a hop in the pipeline above and becomes fuel for the evolution loop below.

Agent Runtime Contract

The core only knows one Harness port (dispatch(req) → Result, health()), so adding an agent never touches orchestration. Four core harnesses (fugue-cc|codex|opencode|agy) stay in the default surface; experimental runtimes are opt-in and excluded from preflight --all.

A new agent is a registry entry plus a preflight probe and a smoke test, not a core change. Every harness satisfies the same port, so it inherits the guard and certificate gates for free.

Evidence-gated Evolution

FuguNano treats runtime evidence as the start of an engineering loop, not the end of a report. Packets become weakness signals; candidate edits to engineering surfaces are scored on fixed held-in/held-out cases; only non-regressing changes are promoted and written to auditable lineage. Safety surfaces such as guard-rule always require operator promotion — the agent can never quietly relax its own guardrails.

Dogfood fixture: .fugunano/evolution/evo-guard-rule-tighten-gh-release-certificate.json records a real guard-rule promotion for a missing action-certificate check.

Self-Harness is the first backend of this loop — it evolves the harness config surfaces (system prompt, memory, skills, …):

It mines verifier-grounded failures, proposes bounded edits, and promotes only non-regressing changes. Read the operator guide in docs/SELF_HARNESS.md.

Command Surface

orchestration/fuguectl/fuguectl is the production entry point: 28 subcommands, 29 test suites, and 410 wrapper assertions.

Fugu, OpenFugu, FuguNano

FuguNano is the lightest open entry point on this road: start with policies, ports, review gates, evidence packets, and harness improvement before deciding whether a learned conductor is worth the cost.

Docs Map

Development

npm run scan
npm run lint:launchers
npm run check:docs
npm run test:fuguectl
cd engine && npm run check && npm run build
npm run ci

The engine is strict TypeScript with ports and adapters. The repo keeps shell usage as thin launchers; new durable behavior should live in engine/.

Acknowledgements

FuguNano builds on ideas from Sakana AI Fugu, OpenFugu, Shanghai AI Lab Self-Harness, Codex/Claude/OpenCode runtime tooling, and recent work on agent review, provenance, incident response, memory, and prompt safety. See NOTICE and docs/PARITY.md for the reference list.

Security

Do not commit real keys. Put local secrets in ~/.config/cc-model-secrets.env. Report vulnerabilities privately.

License

Apache-2.0. See LICENSE.