fugu — an OpenBSD-native AI coding agent
========================================
fugu is an interactive terminal program that pairs a large-language-
model chat API with local tools (file read/write/edit, shell, search,
brokered web access, and bounded read-only subagents) so a model can
work inside a project under the user's direction. It is
privilege-separated in the manner of OpenBSD
base daemons: every security property is enforced by pledge(2),
unveil(2), and process boundaries, never by prompt or convention.
fugu is OpenBSD-only, by design. There are no portability shims; a
build failing on any other system is correct behavior.
Lineage
-------
fugu is a clean-room reimplementation, in behavior rather than
source, of the TypeScript agent "pi" by Mario Zechner. This tree is
additionally a clean-room reimplementation of the first fugu: it was
built from the specification in handoff/, not from the prior C
source.
Building
--------
BSD make on OpenBSD-current or the current release:
make obj
make
make regress # run every test suite
make check # clean-room rebuild + full regress (pre-commit gate)
make install # PREFIX defaults to /usr/local
A hardened debug build compiles with UBSan in trap mode:
make FUGU_DEBUG=1 check
Credentialed/public-network and clean-host package checks are explicit release
targets, never part of the hermetic gate:
make live-check-help
make live-check
make live-check-privileged
The required environment and safety prerequisites are documented in
`docs/release-live-checks.md`.
The checks selected by `-fsanitize=undefined` remain enabled except Clang's
function-type probe: that probe reads metadata from executable text and is
incompatible with OpenBSD's execute-only PIE mappings. Indirect-call types
remain compile-time checked under the normal warning set.
Direct installation expects the system group `_fugu` to exist because
the front binary is installed `root:_fugu` mode 2555. The OpenBSD port
creates that registered group automatically; a non-root staging install
may override `BINOWN` and `BINGRP` together with `DESTDIR`.
Layout
------
src/fugu/ coordinator and user-facing binary
src/common/ modules shared across programs
src/fugu-*/ privilege-separated terminal, API, web, tool, and
editor workers
regress/ test suites (bsd.regress.mk); see regress/README
for the invariant traceability table
docs/adr/ architecture decision records
docs/design/ milestone designs and release verification notes
port/ staged OpenBSD port under productivity/fugu
handoff/ the normative specification this tree implements
Vendored code
-------------
src/common/jsmn.h is jsmn (MIT, Copyright Serge Zaitsev), a
single-header JSON tokenizer, vendored per the dependency charter:
base has no JSON parser, and a hand-rolled tokenizer would be the
most attacked surface in the program. Only src/common/json.c
includes it; the rest of the tree uses that module's API, so the
escaping and length discipline live in one place.
License
-------
ISC. Copyright (c) 2026 Isaac <isaac@itm.works>.
src/common/log.c and src/common/log.h are OpenBSD base code
(Copyright Henning Brauer, ISC) carried per the style charter.
