Kungfu: durable Work for agents you already run

The handoff problem Kungfu is aimed at

The README opens with the claim that your agents do not hand off the work, you do. That is a fair description of the usual loop: you copy a summary out of one session, paste it into another, restate decisions that were already made, and then check which parts survived the move. The stated target is anyone who uses more than one agent surface on the same task, whether that is Codex, Claude Code, OpenCode, Amp, or a surface the team wrote itself.

The project deliberately does not ask you to abandon those tools. The README calls kungfu run agent the golden path and says Kungfu is not a required replacement for Codex, Claude Code, VS Code, terminals or other agent surfaces. What it moves out of the session is the Work itself: the objective, progress, evidence, next action and completion state. Chat history stays where it was. For a team that has already standardised on one vendor's CLI, the pitch is narrower than it first sounds, and that narrowness is the honest part of the design.

Project, Work and Attempt: the three objects that carry state

Kungfu's data model has three concepts. A Project remembers where related Work belongs. A Work holds one durable objective and its current truth. An Attempt records what one agent tried, including failure, without replacing or erasing the Work. The README states that the same Work state is reachable from native agent consoles, the Kungfu TUI and GUI, the CLI, and APIs.

The concurrency rule matters more than the vocabulary. If another live agent already owns a Work, Kungfu stops a second writer instead of letting two agents silently diverge. That is a single-writer lock at the Work level, and it is the mechanism that makes the continuity claim testable rather than aspirational. It also means a stalled agent session can block a Work until ownership is released, which the README does not walk through.

Completion is separated from production. An agent can produce a candidate result and its evidence; it cannot approve its own Work. The README describes a governed review and settlement path as the only route to completion. That is a governance choice, not a technical one, and it only pays off if someone on the team is actually willing to act as the reviewer.

Installing the CLI and running the recovery story

The README gives a reviewed per-user installer for macOS and Linux. It states that the installer does not use sudo and does not edit your shell profile, and that you must follow the exact PATH step it prints before the kungfu command resolves. There is a separate installation guide for Windows, higher-assurance installation, explicit version pinning and troubleshooting; the README does not reproduce those steps.

curl -fsSL https://kungfu.tech/install.sh | sh

Once kungfu is on PATH, the README's deterministic check is the recovery story. It runs inside a project directory and needs no provider credentials, because it drives the built-in Mock Agent rather than a real model.

cd your-project
KUNGFU_MOCK_AGENT_SCENARIO=recovery-story kungfu

The README describes the expected behaviour: the same Work passes through three consecutive Attempts, a disconnect, a crash, and then a recovered delivery. Because the scenario is deterministic, what you are exercising is Kungfu's local continuity and recovery path, not any particular model's behaviour. A shorter variant crosses a question, an approval and a ready-for-review result within a single Attempt:

KUNGFU_MOCK_AGENT_SCENARIO=multi-step kungfu

After that, the README's path for keeping your current agent is to paste a sentence into it rather than to change tools. The sentence it gives is: Run `kungfu agent brief`, then guide me through my first Project and Work. Keep me in my current agent, and use Kungfu as the durable Work layer. The alternative is to launch the agent through Kungfu, which keeps the familiar native console and puts the Work behind it.

cd your-project
kungfu run codex

Substitute claude, opencode or amp for codex if that is the agent you already use. A task argument creates the first Work directly: kungfu run codex "Prepare the release notes". Running kungfu with no arguments opens the optional terminal view.

What .kungfu/ is, and why the README warns about Git

The first run creates a .kungfu/ directory in the project. The README describes it as the project-local workspace for durable Work and runtime state, and gives two instructions: do not delete it, and do not add the whole directory to Git. It also says most contents stay local and that Kungfu never stages, commits or pushes files for you.

The README does not publish a file-by-file inventory of .kungfu/, and it does not document a rollback procedure for the workspace. What it does provide is an inspection route. Ask your agent to run kungfu agent map --json and follow the workspaceGit policy in the output before staging anything. That is the concrete answer to the obvious question of what belongs in version control: the policy is machine-readable and comes from the tool rather than from a wiki page. The repository itself carries a .kungfu/ entry at the top level, which is consistent with the tool being used on its own source tree, though the README does not say that explicitly.

The TUI and GUI are described as sidecar views for showing and managing Projects and Work across agent sessions. They are optional. Nothing in the README makes them a prerequisite for an agent conversation.

The three proofs, and what they do not prove

The README organises its durability argument as three ordered questions: can Work survive a new agent, can it survive failure, and who is allowed to complete it. Each is backed by an auditable demo whose evidence is committed under docs/qualification/evidence/auditable-demo/ and referenced from the README by a content hash. The first isolates continuity across two fresh agent sessions without copied chat. The second runs inside a disposable Project where the connection drops, a new process resumes, that process crashes, and both Attempts stay under the same Work. The third separates agent exit, independent review and settlement.

The README is careful about the limits of these artifacts. It calls them bounded exact-artifact demonstrations and states they are not provider rankings, production certification, or authority to complete real Work. That caveat is doing real work: a hash-pinned recording shows that a path executed once under controlled conditions, not that your repository will behave the same way under load.

There is a second, more practical limitation in the same area. The Mock Agent covers Work creation and execution, but the README says regular onboarding still needs a supported real agent for independent review, so this is not yet an end-to-end zero-external-agent path. If you have no supported agent available, the mock scenarios will show you the mechanism and then stop.

Kungfu against a plain task file or an issue tracker

The obvious alternative is a Markdown task file committed to the repository, or an issue tracker that agents read and write through its API. Both keep state outside a chat session, which is the same problem Kungfu names, and both cost nothing to adopt.

The difference is in what each one records. A task file holds whatever a human or agent last wrote into it, so a failed attempt usually leaves no trace unless someone documents it. Kungfu's Attempt object exists specifically to record what one agent tried, including failure, without replacing the Work. The single-writer rule is the other difference: a shared file or issue has no mechanism that stops two live agents from appending conflicting updates, whereas the README states Kungfu stops a second writer on a Work it already considers owned. The settlement path is the third: an issue tracker will let an agent close its own ticket, and Kungfu's documented design does not.

That is the trade. You take on a C++ runtime, a project-local workspace directory and a governance step in exchange for attempt-level history and a completion gate. If your work is one agent, one session, one sitting, the task file wins on every axis.

Release line, licence and what upgrading costs

The current release line is v4.0.0-alpha.3, published on 2026-08-24, with v4.0.0-alpha.2 on 2026-08-15 and a shifu-v4.0.0-alpha.3 tag on the same day as alpha.3. The default branch is dev/v4/v4.0.0. The last push to the repository was on 2026-08-24. The project is not archived.

Alpha version numbers plus a v4 major line are the practical upgrade signal here. The README does not document a migration path between v4 alpha releases, and it does not describe a compatibility guarantee for the on-disk format of .kungfu/. Since the README tells you not to delete that directory, a format change in a later alpha has nowhere obvious to go. Treat the workspace as reproducible rather than precious until the version line stabilises, and pin the version if you install for a team; the README points to the installation guide for explicit version pinning but does not give the syntax.

Kungfu is Apache-2.0. The repository also carries LICENSE-POLICY.md, TRADEMARK.md, ACCEPTABLE_USE.md, PROVIDER_COMPLIANCE.md and THIRD_PARTY_NOTICES.md, and the README refers to Kungfu UNGFU as a signature. Those files, not this article, are the source for what the licence permits and what the trademark covers. If you plan to redistribute the CLI or run it against a commercial model provider, read PROVIDER_COMPLIANCE.md and LICENSE-POLICY.md directly. This is not legal advice.

Editorial conclusion

Adopt Kungfu if you already switch between agent surfaces on the same task and want the objective, evidence and settlement state to live outside the chat. Do not adopt it if you need a finished product today: the README calls it Alpha, the release line is v4.0.0-alpha.3, and regular onboarding still needs a supported real agent for independent review. Before trusting it with real work, run the two deterministic mock scenarios, then run kungfu agent map --json in a throwaway repository and read the workspaceGit policy it returns before you stage anything in .kungfu/.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes