kungfu-systems/kungfu

Kungfu – Durable Work Layer for LLM‑Agents

What it is

• Kungfu is a command‑line tool (with optional TUI/GUI) that sits beside any LLM‑based coding or reasoning agent (e.g., GitHub Copilot Codex, Anthropic Claude, OpenCode, Amp, or a self‑hosted model). It records the Work—the objective, evidence, decisions, and state—outside the chat session so that the same Work can survive agent hand‑offs, crashes, or disconnections.

Core concepts

Concept	Meaning
Project	A folder that groups related Work items. Kungfu creates a hidden .kungfu/ directory here to store state.
Work	A single durable task (e.g., “prepare release notes”). It holds the current truth, progress, and required evidence.
Attempt	One execution of a Work by an Agent. Each Attempt is logged, even if it fails, without overwriting the Work.

How it works

1. Start an Agent through Kungfu – kungfu run codex "Prepare the release notes". Kungfu launches the chosen agent, passes the prompt, and records everything the agent does as an Attempt.
2. Switch agents freely – Because the Work lives in .kungfu/, you can later run kungfu run claude and continue the same task without re‑explaining context.
3. Recovery from failure – If the agent crashes or the connection drops, the next Attempt picks up the same Work, preserving prior evidence and decisions.
4. Independent completion – An agent can propose a result, but Kungfu requires a separate review/settlement step before marking the Work as complete, preventing an agent from self‑approving.

Key features

• Agent‑agnostic: works with any CLI‑compatible LLM agent that can run local commands.
• Deterministic mock agent: a built‑in agent (KUNGFU_MOCK_AGENT_SCENARIO) lets you demo continuity and failure‑recovery without any API keys.
• Side‑car UI: optional terminal UI (kungfu) and graphical UI for visualising Projects, Work, and Attempts.
• Auditable evidence: each Attempt stores the prompt, response, and any generated artefacts, enabling inspection and compliance.
• Safety guards: prevents two agents from writing the same Work simultaneously.
• Open‑source standards: ships with the KFD engineering standard and a Buildchain that produces verifiable release passports.

Installation (macOS / Linux / Windows)

# One‑line installer (no sudo, no shell profile changes)
curl -fsSL https://kungfu.tech/install.sh | sh

After the script prints the PATH addition, add it to your shell (or follow the Windows guide). The installer pulls the latest Alpha release.

Quick start

# Inside any project folder
KUNGFU_MOCK_AGENT_SCENARIO=recovery-story kungfu   # runs a deterministic three‑step demo
# Or run a real agent
kungfu run codex "Write the changelog for v2.3"

The hidden .kungfu/ directory will appear; keep it out of version control.

Typical use cases

• Long‑running development tasks where you may switch between cheaper and more powerful LLMs.
• Team settings where multiple engineers (or bots) need to collaborate on the same AI‑generated work without losing context.
• Compliance / audit scenarios that require a full, immutable log of what the model produced and why.

Maturity

• The project is in Alpha (v4). It runs on macOS, Linux, and Windows, but the API and UI may still change. The README warns that the release is a prerelease channel and points to “Alpha Status” and “Known Limits” docs for details.

License

• Apache‑2.0 (see LICENSE).

Where to learn more

• System overview: docs/concepts/system-overview.md
• Agent‑work lab tutorial: docs/guides/agent-work-lab.md
• Full documentation map: docs/MAP.md
• Release artifacts: https://github.com/kungfu-systems/kungfu/releases/latest

---

Kungfu is essentially a continuity layer for LLM‑driven agents, letting you treat AI‑generated work like a regular software artifact that survives crashes, hand‑offs, and model changes.