Website · Documentation · Architecture · CLI reference

FloofClaw is a tiny C runtime for durable AI agents. It turns messages, timers, API calls, and worker results into inspectable event-driven runs that survive restarts and continue until no work remains.

~635 KiB single binary · C11 · durable filesystem state · JSON/JSONL by default · macOS, Linux, and Android ARM64

🚀 Quickstart

The offline path needs a C11 compiler, make, and a POSIX userland. It uses the committed mock-backed hello floop, so it needs no account, API key, gateway, or network connection.

git clone https://github.com/FloofLogic/Floofclaw.git
cd Floofclaw
make -j4
./bin/fclaw run -h --text "hello"

Start the always-on local runtime and talk to it from another terminal:

./bin/fclaw gateway start -h
./bin/fclaw -i -h

Stop it later with ./bin/fclaw gateway stop -h.

Ready for a real model? The guided path is the onboarding wizard:

./scripts/onboard.sh

It walks identity, provider key, floop, channels, the bundled-action enablement checklist (each action verified live before it is switched on), and a gateway health probe — needing only bash and bin/fclaw. Re-running it is safe: it keeps existing answers and repairs.

Prefer doing it by hand? Store a key without placing it in shell history—for example, ./bin/fclaw auth set-stdin -h gemini_key—then follow the provider guide to select a provider-backed floop and profile.

Optional components

libcurl enables real HTTP providers; OpenSSL 3 enables TLS channels. Some optional actions and local inspection apps use python3, jq, or curl, but none sits underneath the C runtime.

Public source releases include the pinned pluck source as ordinary files. Development checkouts that want the web_read action can initialize its public source and build it with:

git submodule update --init actions/common/web_read/_pluck
bash actions/common/web_read/build.sh

Note

FloofClaw is not another chatbot framework. It is the engine agents run inside when their work needs to survive restarts, stay economical, and be accountable over time.

✨ Why FloofClaw feels different

🐜 Native C, all the way down

The engine is written entirely in C from scratch. No Node, Python, JVM, framework, or language runtime sits underneath it—just a ~635 KiB C binary. The full provider/TLS build links libcurl and OpenSSL 3; the mock-only build can omit both.

📂 The filesystem is the database

No PostgreSQL, SQLite, Redis, or vector database. The filesystem is the durable substrate: append-only event logs are truth, state files are rebuildable projections, and runs can be replayed after crashes.

🤖 Agents are first-class operators

Every public command speaks structured JSON or JSONL by default. The entire runtime is directly composable by agents, shell scripts, and automation. Human-readable output is still one flag away, but machines are treated as operators—not an afterthought.

fclaw view -a <run_id>  # compact JSONL for an agent
fclaw view -h <run_id>  # formatted output for a human

🔎 Every model call is a glass box

Every request, response, token record, cache boundary, action call, event, and stderr artifact is inspectable. Runs can be viewed, replayed, costed, and traced without treating an opaque “agent turn” as truth.

📏 Small enough to audit

Measurements from the 0.24.1 source release on arm64 macOS with Apple clang 17. Run make metrics to reproduce them at the exact measured revision.

What	Measured result
Stripped executable	650,664 bytes (~635 KiB)
Runtime C/header source	39,420 lines
Full provider/TLS build libraries	2 — libcurl and OpenSSL 3; the mock-only build can omit both
Mock-backed hello run	0.124 s
Idle isolated gateway RSS	~11.6 MiB
Quiet supervision review	exactly 1 model call

🧭 How it works

A floop is a declarative profile of ordered, event-gated steps. The C kernel walks that profile, validates envelopes, runs jobs, appends events, and waits for consequences. Product behavior stays in floops, agent packets, and action contracts; the kernel remains a walker, not a judge.

floops/     shippable loop + agent bundles
actions/    declared capabilities and effect boundaries
runtime/    the small C kernel
workspace/  event logs, projections, and run artifacts
tests/      isolated runtime checks and hermetic smoke coverage

🪟 Inspect a run

Every triggering event creates a run directory:

workspace/runs/<run_id>/
├── event_log.jsonl       # behavioral truth
├── runstate.json         # durable scheduler envelope
├── state.json            # rebuildable materialized view
├── trace.jsonl           # diagnostic decisions
├── provider_calls/       # numbered raw requests, responses, and metadata
├── agent_outputs/        # raw agent artifacts
└── action_calls/         # numbered action artifacts and stderr

The command line exposes the same evidence directly:

./bin/fclaw view -a <run_id>
./bin/fclaw replay -a workspace/runs/<run_id>/event_log.jsonl
./bin/fclaw usage -a
./bin/fclaw cacheview -a --agent <agent_id> -n 8

A run may contain retries, multiple LLM-backed phases, or compaction. Count provider_calls/*_meta.json or the usage ledger for exact model-call cost—not run directories.

🧠 Pick a floop

Floop	Best for	Model needed?
hello	Offline smoke tests and a zero-account first run	No — mock-backed
openclaw	Event-driven chat, coding, and tool use with durable memory	Yes
floofclaw	Long-lived concerns, scheduled reviews, workers, and proactive messages	Yes

./bin/fclaw run -h --floop openclaw --text "investigate this bug"
./bin/fclaw gateway start -h --floop floofclaw

See Choosing a floop for the complete shipped set and configuration guidance.

🧩 Extend by adding a directory

There is no central registration list and no framework container to wire up.

action          copy into actions/   → restart          → fclaw actions -h
native adapter  copy into adapters/  → make → restart   → fclaw adapters -h
floop           copy into floops/    → select and run   → fclaw floops -h

Only a native adapter requires a rebuild because it is C and links into the same executable. Start with the extension guide.

🌍 Build targets

FloofClaw builds for macOS, Linux, and Android ARM64. Android produces the same CLI executable—not an APK library or app-specific wrapper.

ANDROID_NDK_ROOT="$ANDROID_HOME/ndk/27.0.12077973" \
FCLAW_ANDROID_DEPS_ROOT=/path/to/android-arm64-static-deps \
make android-arm64

See the Android ARM64 build guide for the dependency layout, API selection, and device smoke command.

🧪 Tested like a runtime

make test

The routine offline gate runs 32 unit tests, 139 integration tests, fixture isolation, the local-client lifecycle probe, and a hermetic smoke with mock provider responses. Major-version release preparation adds ASan, UBSan, small-stack, fuzz, chaos, disk-full/read-only, and thrash campaigns through make robustness.

Read the reproducible history behind those claims in Testing investment.

📚 Go deeper

• What is FloofClaw?
• Architecture
• CLI output contract
• Providers
• Discord
• Floops
• Actions
• Constitution

📄 License

FloofClaw is open source under the Apache License 2.0. Commercial and noncommercial use, modification, and distribution are permitted under its terms.