fugu — an OpenBSD-native AI coding agent
========================================
fugu is a personal interactive terminal program for one **Owner**: the human
who runs it and owns every model credential it consumes. It pairs a large-language-
model 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 Owner'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.
The experimental Claude subscription adapter is deliberately single-person.
It uses the Owner's Claude Pro or Max quota through an unofficial, observed
Claude Code-compatible HTTP profile implemented entirely in C. It is not an
Anthropic-supported third-party authentication contract; it may stop working
without notice or trigger upstream account enforcement. Do not host fugu,
share it with another human, put it behind a service or API, or use one
subscription token for team traffic. Direct API providers are the supported
route for every shared, service, team, or customer-facing use.
fugu is OpenBSD-only, by design. There are no portability shims; a
build failing on any other system is correct behavior.
Claude Max setup
----------------
Generate a long-lived inference token while logged into the Owner's Claude Pro
or Max account:
claude setup-token
Paste the printed token into the protected configuration, then select the
personal subscription Provider:
provider "claude"
model "claude-sonnet-4-6"
oauth_token "sk-ant-oat01-..."
The `claude` command is used only to provision the token; fugu neither installs
nor executes Claude Code. At runtime the token exists only in `fugu-api`, which
adds it to a fixed Anthropic TLS request after the process has lost all file,
write, and execution authority. Every model-selected Tool still passes through
fugu's existing allowlist and kernel-confined executors.
The package has no Node.js, Python, Claude Code, or Agent SDK runtime
dependency. The active compatibility profile is `claude-code-2.1.185`; its
snapshot date is 2026-07-16. Its identifying headers and request transforms are
intentionally versioned because they are undocumented and volatile. Token
refresh and replacement are manual.
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.
Repository
----------
The canonical repository is:
ssh://got.fugu.farm/fugu_agent.git
The OpenBSD development checkout is normally `/home/isaac/fugu`.
Clone it with an explicit destination when creating that checkout:
git clone ssh://got.fugu.farm/fugu_agent.git /home/isaac/fugu
The current port version is 0.3. The `v0.1` tag preserves the previous
canonical release state.
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 CHECK_JOBS=1 check # same gate with serial regression suites
make VERBOSE=1 check # same gate with the complete live transcript
make local-port # stage clean HEAD as a checksummed local port
make install # PREFIX defaults to /usr/local
The default `make check` builds with four jobs, runs up to four isolated
regression suites at once, and reports concise phase and per-suite status,
check counts, and total elapsed time. `CHECK_JOBS` selects another positive
bound for both phases; `CHECK_JOBS=1` is the serial diagnostic mode. The gate
fails immediately on a compiler warning, failed test, skipped/disabled proof,
or expected/unexpected failure, cancels active sibling suites, then prints the
complete failed output and a focused rerun command. `VERBOSE=1` keeps the build
and suites serial so it can show live compiler commands and individual
assertions; other nonempty `VERBOSE` values are rejected. `make regress`
retains the ordinary detailed OpenBSD regression output.
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`.
For ordinary local deployment and package-level testing, build and install
through the OpenBSD ports framework rather than running the source-tree
install target as root. `make local-port` creates the committed source archive,
stages `productivity/fugu` under `/usr/ports/mystuff`, and runs the framework's
checksum targets; package construction and installation remain explicit ports
operations. The complete checkout-to-package procedure,
including the local/remote repository topology, SSH agent forwarding,
deployment verification, rollback, and repeat installations during
development, is in
[docs/openbsd-development.md](docs/openbsd-development.md).
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.
