Kungfu

Kungfu is a local-first runtime that records real-world agent work and verifies what actually got done. It works alongside the agents and execution surfaces you already use.

Never Guess. Facts Unfold.

Status: Coming soon.

Kungfu turns execution into Episodes, bounded causal units that bind Facts, Artifacts, Receipts, dependencies, and verification roots into one inspectable record. Episodes can be sealed, exported, and replayed to support recovery and evidence-based Decisions.

Real-world work happens in Episodes.
Facts are authoritative. Projections are rebuildable.
Claims require Proof before they support Decisions.

This open monorepo contains the low-latency runtime, CLI and TUI, desktop GUI, language bindings, SDKs, extension system, product assembly, and the shared qualification contracts that keep them aligned. The user-facing distribution is named Kungfu Episodes; the runtime, command, SDKs, and extension system use the Kungfu, libkungfu, and kfx names.

Logs show activity. Traces show calls. Workflows describe intended steps. A chat session preserves a conversation. None of them, by itself, is the durable object needed to answer:

• What actually happened?
• Which facts and artifacts belong to the work?
• What did the runtime acknowledge, and what survived a crash?
• What evidence supports completion?
• What may safely happen next?

An Episode gives those questions one stable semantic boundary without making a process, UI, mutable database row, or provider session the authority. Read The Episode for the narrative and Vocabulary for the precise public terms.

• Record typed runtime Facts in an append-only journal with explicit schema ownership and provenance.
• Inspect Episodes, causal Timelines, Artifacts, Receipts, Cuts, Watermarks, and rebuildable Projections.
• Query current and historical fact state with proof and lineage attached.
• Replay recorded Facts, Rewind an Episode for forensic inspection, and qualify Recovery without silently repeating external side effects.
• Embed libkungfu, use one ecosystem SDK, add a kfx, or assemble a complete application without adopting every higher layer.
• Qualify visibility, durability, recovery, and meaning as one end-to-end contract rather than treating ingestion speed as sufficient evidence.

• New to Kungfu: use the curated Documentation Guide.
• Choosing a product layer: read Choose Your Kungfu.
• Evaluating trust or production use: begin with Known Limits and the Single-host institutional trust profile.
• Looking up one exact question: use the exhaustive Documentation Map.
• Contributing: read CONTRIBUTING.md.

An installed runtime also carries an agent-readable product brief:

kungfu agent brief
kungfu agent capabilities --json
kungfu agent choose-mode --json

To evaluate the source tree before public artifacts are available:

git clone https://github.com/kungfu-systems/kungfu.git
cd kungfu
./shifu doctor
./shifu sync && ./shifu build

Higher layers add convenience; they do not become a second authority over the Facts. Product Layers defines the independent qualification contract behind these choices.

The data plane is yijinjing, a low-latency append-only mmap journal shared by C++, Python, and Node. Closed kernel records use fixed-layout Hana POD schemas; open and domain Facts use FlatBuffers. JSON is an edge rendering or interchange format, not a third journal schema.

Live work and Replay use the same frame and runtime semantics. SQLite and GUI models are rebuildable Projections over journal-backed authority. The runtime, capability SDK, application SDK, reference surfaces, and product assembly remain separate layers with explicit contracts. See Architecture and Event Model.

Kungfu began with the Chinese idea of 功夫: capability built through disciplined practice. As the product evolved, KUNGFU acquired a recursive technical meaning: KUNGFU UNGFU: Never Guess. Facts Unfold.

The name describes the architecture: deeply integrated at the product surface, self-bootstrapping from Facts at the core. Read Why Kungfu? for the complete recursion and its connection to the product's fact-first design.

Kungfu v4 is Coming soon. Source-built capabilities and qualification slices exist, but public packaging, cross-platform evidence, strong power-loss durability, and the institutional profile remain staged unless the linked evidence says otherwise.

Design intent, implemented behavior, qualified guarantees, and released artifacts are deliberately distinct. Before relying on a claim, check Contracts, Known Limits, and the applicable retained qualification evidence.

• Product home: https://kungfu.tech
• Developer and agent surface: https://libkungfu.dev
• Documentation: docs/README.md
• Issues and questions: GitHub issue forms
• Security reports: SECURITY.md
• License: Apache License 2.0