Kungfu

Kungfu is an open-source monorepo for real-world agent work: a local-first, journal-first runtime for recording facts, replaying work, and building verifiable agent-facing applications.

The user-facing desktop and CLI distributions are released as Kungfu Episodes. The repository, runtime, command, SDKs, and extension system use the Kungfu, libkungfu, and kfx names.

Facts before trust. In KFD terms, a load-bearing claim should never stand alone: bind it to a verifiable source, artifact, manifest, or runtime receipt. (KFD; design philosophy; facts before trust.)

Public entrypoints:

• Product home:
• Developer and agent map:
• Source and open monorepo: this repository

The product goal is to make fact-first responsibility the path of least resistance: once a user starts relying on Kungfu, the natural way to use it should be to inspect facts, understand responsibility, and make control decisions from local proof rather than from opaque claims.

The commercial product surface is prepared in this repository as part of the same open-source monorepo. Public release artifacts use the Kungfu Episodes name; the underlying runtime and developer-facing surfaces remain Kungfu.

At its core is a low-latency, append-only event journal with a shared, strongly-typed schema, exposed zero-copy to C++, Python, and Node. Kungfu offers these capabilities — the journal, in-process state, and deterministic replay — as a foundation (SDK) to build on, and ships a minimal reference application built on that foundation.

Originally created for trading execution, the core is general: anything that needs to capture, share, and faithfully replay high-frequency event streams.

Core ideas

• Journal-first data plane — one append-only event log (yijinjing) with a unified runtime schema (kungfu/yijinjing/schema) carrying source / destination / nanosecond timestamp / carrier type metadata. Every component consumes the same frames rather than inventing its own format.
• Zero-copy, multi-language runtime — the same in-process journal data is shared across C++, Python, and Node (N-API) without serialization on the hot path.
• Deterministic replay — live and replay run on the same runtime and the same journal semantics, so recorded streams replay with high precision rather than through a separate engine.

Build on it

Kungfu is meant to be a base others build on, not a single fixed application:

• Capabilities SDK — consume journal / state / replay from your own code in C++, Python, or Node.
• Extension points — add features and UI to a Kungfu application.
• Application SDK — assemble a complete application on top of Kungfu, with Kungfu as the underlying dependency.

The repository ships the core plus a minimal reference application that demonstrates and exercises these capabilities.

The toolchain comes with the runtime

A guiding principle of kungfu is that the machine adapts to the person, not the other way around. The kungfu runtime is batteries-included: it embeds a Python and a Node runtime and brings a full Python development lifecycle — dependency management, formatting, and ahead-of-time compilation — reachable through kungfu engage. Building a kfx extension does not start by assembling a toolchain: most extension development needs no separately installed Python, Node, or package manager.

The runtime deliberately absorbs this complexity so its users do not have to. To keep that convenience sustainable rather than bespoke, the absorbed tooling is built on mainstream, well-maintained foundations.

Components

• Core & runtime — yijinjing (journal, storage semantics, and runtime schema) plus libkungfu runtime bindings, packaged as @kungfu-tech/core. It embeds a Python and a Node runtime and is fronted by the kungfu end-user command; operator-facing shell slices such as kungfu cockpit, managed runs, and skill context injection grow under the same command.
• Capability SDK — typed, framework-neutral access to journal / state / replay (framework/api).
• Application SDK — scaffolding to build kfx extensions, create Kungfu Skills, and assemble applications (developer/sdk).
• Reference surfaces — two minimal reference UIs over the same capability SDK: a desktop GUI on Electron + React (framework/gui) and a terminal TUI (framework/tui).
• Product assembly — dogfood desktop and CLI products bundling the runtime, both reference UIs, the SDK and first-party kfx (product).

Runs on Windows, macOS, and Linux (including arm64). See docs/architecture.md for how these pieces are layered.

Getting started

See CONTRIBUTING.md for the toolchain, build steps, coding conventions, and the pull request / release flow.

# install fnm and uv once, then:
git clone [email protected]:kungfu-systems/kungfu.git
cd kungfu
./kungfu-code sync && ./kungfu-code build

Documentation

Start at the documentation map — it routes your question (why it’s built this way / how to trust the artifact / how to use it) to the right document, and is readable by both people and agents.

• Installed agent entrypoint: kungfu agent brief, kungfu agent capabilities --json, and kungfu agent choose-mode --json.
• docs/MAP.md — the question-indexed map of all documentation.
• docs/concepts.md — the vocabulary in one place (kungfu/kfx/sdk, libkungfu, yijinjing, journal, schema, …).
• docs/design-philosophy.md — the two first principles the whole design follows from, and how the architecture falls out of them.
• docs/facts-before-trust.md — why Kungfu starts from accountability: facts before trust, local proof before control.
• docs/architecture.md — how the repository is layered (runtime, capability SDK, application SDK, reference surfaces) and why.
• docs/skills.md — design target for Kungfu Skills: SKILL.md as the minimal source, compact agent catalog injection, Node/Python manage modes, and kfx dependency composition.
• CONTRIBUTING.md — toolchain, build, conventions, releases.
• LICENSE-POLICY.md — project licensing, DCO-based contributions, third-party notice policy, and commercial boundary.
• TRADEMARK.md — official project mark and fork identity boundary.
• ACCEPTABLE_USE.md — acceptable use of official hosted, managed, and maintainer-operated services.
• PROVIDER_COMPLIANCE.md — official posture for provider APIs, CLIs, credentials, usage attribution, and anti-bypass boundaries.
• SECURITY.md — how to report vulnerabilities privately.
• docs/version-release-design.md — versioning and release mechanism rationale.
• framework/core/docs/adr/ — architecture decision records.

Feedback & support

Project contact happens through GitHub — there is no email support channel.

• Bugs, feature requests, questions, and documentation issues: open an issue.
• Changes: open a pull request (see CONTRIBUTING.md).
• Security vulnerabilities: report them privately — see SECURITY.md.

License

Apache License 2.0.