KunAgent/Kun: a local-first AI agent workspace with one runtime for desktop GUI and TUI

The problem Kun targets: agents that answer instead of finishing

Kun is aimed at the gap between a chat answer and a delivered change. The README frames the project as moving AI from answering questions to completing work, and the workbench is organised around two modes rather than one chat box. Code mode covers software delivery and carries a Design canvas inside the same task. Work mode covers writing, document analysis and presentation output. The intended user is someone with a real project directory who wants the agent to read workspace context, form a plan, call tools, modify files, run verification and leave the evidence beside the task.

That framing matters because it sets the acceptance criteria. A general chat client can produce a patch; it usually cannot tell you which plan step produced it, which approval was granted, or which test run backed the claim. Kun's answer is to attach plans, todos, tool calls, file changes, browser and terminal results, and approvals to a single task record. The README also states that requirements and plans are saved in the project by default, so they can enter version control, code review and later recovery. For a team that already reviews diffs, that is the interesting design decision: the agent's reasoning artefacts become reviewable files rather than scrollback.

One kun serve runtime behind the GUI and the TUI

The architecture claim is specific: the desktop GUI and the terminal TUI are not two products sharing a config file. They connect to the same local `kun serve` runtime and share threads, goals, plans, approvals and background tasks. The README describes the split by use case rather than by capability: the GUI is for observing, reviewing and controlling the process, while the TUI is for keyboard-focused work.

The package manifest confirms the shape. The root package is named kun-gui with the description "Electron workbench for the Kun runtime (HTTP/SSE)", and the runtime lives in the `kun/` workspace, built by `npm run build:kun` before the Electron app starts. There is a `smoke:dual-runtime` script, which suggests the two front ends are exercised together rather than assumed to match. The transport is HTTP with server-sent events, so the GUI is a client of the local runtime, not the runtime itself.

That has a practical consequence worth stating plainly. Killing the Electron window does not necessarily mean the runtime stops, and long-running scheduled tasks are described as background tasks attached to the runtime. Whether that is what you want depends on whether you treat the agent as an application or as a service on your machine. The README does not document the shutdown or restart semantics of `kun serve`, and the README does not document rollback of a scheduled task, so treat runtime lifetime as something to verify in your own environment rather than something the documentation settles.

Installing Kun and running a first verifiable task

The README's five-minute path is a download, not a build. It points to GitHub Releases and lists the packaging per platform: `.dmg` or `.zip` for macOS on Apple Silicon and Intel, `.exe` for Windows x64, and `.AppImage` or `.deb` for Linux x64. After launch, the documented sequence is to choose a language, configure a model subscription, plan, API or custom Provider, open a local project or create a workspace, and send a task that is narrow and verifiable.

If you prefer to run from source, the README states the requirements as Node.js 22.19+, npm, and at least one working model connection. The package.json engines field agrees, requiring node >=22.19.0.

git clone https://github.com/KunAgent/Kun.git
cd Kun
npm ci
npm run dev

`npm run dev` is documented as building the runtime and starting the Electron development environment. For a slower network in mainland China the README gives an npm mirror variant, which changes only where packages are fetched:

npm ci --registry=https://registry.npmmirror.com

If you want the terminal instead of the window, the documented command builds the runtime and launches the TUI entry point:

npm run dev:tui

Inside a project directory, the README says the desktop build exposes a `kun` command that connects to the same runtime:

kun

One packaging change is worth reading twice. From 0.3.8 the project no longer ships a separate TUI archive; the TUI is reached through the terminal command bundled with the desktop application. If your workflow depends on installing the TUI independently, that path is gone, and docs/kun-tui.md is the place the README sends you for commands and configuration.

What local-first does and does not promise about your data

Kun's README is unusually direct here, and the section heading says it: local-first does not mean never online. Sessions, preferences, logs and runtime data are stored on the machine by default. The moment you select a cloud model, prompts, attachments and task context are sent to the chosen Provider, and the README tells you to check that service's data policy before use. Tool permissions, sensitive operations and extension permissions are surfaced in the interface and remain your decision.

This is the correct framing, but it also means "local-first" describes storage and runtime placement, not confidentiality. The project is model-agnostic by design. The README lists preset coverage across the ChatGPT / Codex, Claude, Gemini, Cursor, Ollama, DeepSeek, Kimi, GLM, Qwen, MiniMax and Xiaomi MiMo ecosystems, and notes that login method, available models, region and quota depend on the current version and the Provider's rules. The model provider presets are documented in docs/model-provider-presets.md.

Two consequences follow. First, a fully offline posture is only as good as the local model you connect, and the README does not claim that any particular local Provider is validated. Second, because Provider availability shifts with region and account rules, a configuration that works today is not a guarantee about next quarter. That is a Provider property, not a Kun defect, but it lands on whoever operates the workbench.

Where Kun is the wrong tool

The licence is the first hard boundary. Kun uses the PolyForm Noncommercial License 1.0.0, and the README states it is for learning, research and noncommercial use only. Commercial use, commercial distribution, SaaS or hosted services, resale, or integration into a commercial product require separate written authorisation from the author. The repository's licence field is reported as NOASSERTION, so if you are evaluating this for anything with a revenue path, read LICENSE and CLA.md directly rather than relying on a badge. Nothing here is legal advice; the point is that the permission boundary is stated in the project's own words and it is narrow.

The second boundary is scope. Work mode reads PDF and Office documents and analyses spreadsheets, but the README says Office files remain read-only. If your requirement is to write back into a .docx or .xlsx in place, Kun does not do that. The third is operational: this is an Electron application with a local runtime, a workspace of packages, and a build chain that compiles the runtime before the app. It is not a single binary you drop into a CI container, and the README does not present it as a headless server product. Teams that want an agent embedded in an existing pipeline will find more friction here than a library-shaped alternative.

Finally, the repository is not archived and the last push was on 2026-09-09, with v0.3.9 released on 2026-09-06. That is recent, but the README also shows a packaging change in 0.3.8 that removed a distribution channel. Fast iteration and moving install surfaces are the same fact viewed twice.

How Kun differs from a plain OpenAI-compatible client

The obvious alternative for many readers is a thin OpenAI-compatible chat client pointed at a local or hosted endpoint. The difference is not the model call, which both make. It is what surrounds the call. A plain client keeps a conversation; Kun keeps a task with a plan, todos, tool calls, file diffs, terminal and browser results, approvals and verification evidence, and it persists requirements and plans inside the project so they can be versioned and reviewed.

The second difference is the runtime split. A chat client is one front end. Kun runs one local runtime with two front ends, HTTP and SSE between them, which is why the same thread can be observed in the GUI and driven from the terminal. The third difference is the extension surface. The repository ships examples/extensions/ and examples/ui-plugins/, and the README points to docs/extensions/README.md, docs/workflow-loop.md and docs/project-mcp-skills.md for Loops, MCP and Skills. Automation is a first-class concept here, expressed as scheduled tasks, loops, hooks, MCP servers, skills and installable extensions.

That breadth is also the cost. A thin client has almost nothing to learn. Kun asks you to understand modes, Providers, permissions, the runtime, and the extension model before you get the most out of it. The README's own five-minute path is deliberately small for that reason: pick a Provider, open a project, send one narrow verifiable task.

Maintenance, upgrade cost and licence implications

On maintenance, the facts are the release cadence and the branch policy, not a promise. The latest release listed is v0.3.9 on 2026-09-06, with v0.3.8 the same day and v0.3.7 on 2026-08-28. The last push to the repository was on 2026-09-09. The README states that the daily integration branch is `develop` and that pull requests should target `develop`, with external contributions requiring acceptance of CLA.md. If you fork, that is the branch to track.

Upgrade cost is concentrated in two places. Distribution changed at 0.3.8, when the standalone TUI archive was dropped in favour of the terminal command inside the desktop application, so any script that fetched a TUI tarball needs rewriting. Second, Provider presets move with vendor rules; the README explicitly ties login method, model availability, region and quota to the current version and the Provider. A pinned Kun version does not pin the Provider behind it.

On licensing, the practical reading is that the default is noncommercial, and the commercial routes named in the README (commercial use, commercial distribution, SaaS or hosted operation, resale, embedding in a commercial product) each require separate written authorisation. The repository also carries THIRD_PARTY_NOTICES.md, which is where dependency obligations would be recorded. If your organisation has a policy against noncommercial licences, this is a stop condition, not a negotiation point.

Editorial conclusion

Adopt Kun if you want an agent that plans, edits files, runs verification and leaves diffs and test output next to the task, and if your use is study, research or other noncommercial work. Do not adopt it for a commercial product, a hosted service or resale, because the licence requires separate written permission for those. Before committing, verify which model Provider you can actually connect, confirm that your Node version satisfies the >=22.19.0 engine field if you build from source, and read docs/kun-tui.md to check whether the TUI still covers the commands your workflow depends on after the 0.3.8 packaging change.

Frequently asked questions

Official sources

1. Issues
2. KunAgent/Kun on GitHub
3. Project website
4. README
5. Releases