Klepai is our free desktop chat for the model servers you host: Ollama and any OpenAI-compatible endpoint on your network, in one window on macOS, Windows and Linux. The launch posts covered v0.0.1. This one is about v0.0.2, which closes a gap someone else found for us: two agents working in the same project folder at the same time.

Quick answer: v0.0.2 adds a collision guard. Before an agent starts, Klepai checks whether another Klepai-launched agent is already working in that folder or anywhere under it. If so, you get a warning that names the running conversation, and you choose: run anyway, run isolated in a git worktree, or cancel.

Where it came from

Nobody hit the bug. A reply to one of our posts asked how we handle working-tree collisions when two agents write concurrently. We ran on the same model, so the question applied: nothing in Klepai stopped it. The whole release exists to close that gap before it turns into a lost afternoon of overwritten edits. The PRD says so openly: plans/v0.0.2.md in the repo lists the problem, the stories, and what stayed out of scope.

How the guard works

Klepai tracks the agents it launched itself: the built-in agent and spawned CLIs such as Claude Code or Codex. The registry is keyed by project path, and the check covers the folder plus its subfolders. A second agent on a subfolder trips the same warning.

The warning is advisory. It names the conversation holding the folder and offers three buttons. Run anyway accepts the risk. Cancel backs out. Run in worktree appears only when the folder is a git repository, and it is the interesting one.

The worktree lifecycle

Choosing the worktree copies the project to a sibling folder on its own branch, klepai/agent-N. The conversation's file operations run against that copy, so the main folder stays exactly as it was while the agent works.

When the agent finishes, Klepai commits all changes on the worktree branch first. The main history stays untouched. Then it asks you: merge into the project, or keep the branch. A merge that hits conflicts aborts by design. The branch and the worktree survive, and the dialog lists the git commands to finish the merge by hand. A clean merge tidies both away.

What it does not do

Stated plainly, because agent tooling overpromises often enough:

• Agents started outside Klepai stay invisible. If you run Claude Code from a terminal, Klepai does not know about it: no lockfile sniffing, no guessing from process lists.
• Folders without git get the warning without the worktree option. Without git there is no reliable way to merge the work back.
• Two agents sharing a folder after Run anyway get no extra on-screen marker in this release.

Also new since launch

Chats keep running in the background while you start another one. Attachments accept any file type, beyond images. And the landing page now carries per-platform download buttons plus the whole release roadmap through 1.0.

Next on the roadmap is v0.1.0: answer variants you step through with < and > to compare retries. Repo and downloads: github.com/CrystalPlatforms/klepai. Feedback is fastest as GitHub issues.