Draft spaces

Stage edits on a private git branch, review the diff, then merge or discard them as a unit.

A draft space is a private copy of your knowledge base where an agent can write freely. Nothing in a draft touches the live pages until you merge it, and discarding it leaves no trace. Use drafts when a batch of edits should be reviewed and published together.

• An agent session that should not publish half-finished work.
• A batch of edits you want to review as one diff.
• Several agents working in parallel, each in its own draft.

Each draft is a git branch named draft/<id> with its own worktree under .kiwi/drafts/. Drafts need the git versioning strategy and a repository with at least one commit.

Turn on drafts

Drafts are off by default on the server.

.kiwi/config.toml

[drafts]
enabled = true
max_active = 10   # default

Without this, draft endpoints return 501 with drafts not enabled. The in-process MCP server (kiwifs mcp --root) has drafts available without this setting.

Lifecycle

1. Create

   Create a draft and keep its id. Creation fails with 409 when max_active drafts already exist.

2. Write

   Read, write, delete, and list files inside the draft. Each write commits to the draft branch. Draft writes are not indexed, searchable, or broadcast to the web UI.

3. Review

   Diff the draft against the main branch to see exactly what would change.

4. Merge or discard

   Merge fast-forwards the main branch to the draft, so its commits land in history unchanged and the file watcher indexes the new content. If the main branch moved since the draft was created, merge fails with 409. Discard deletes the branch and worktree.

Use drafts

REST

Terminal

# Create
curl -X POST 'http://localhost:3333/api/kiwi/drafts' -H 'X-Actor: agent:writer'

# Write a file inside draft a1b2c3
curl -X PUT 'http://localhost:3333/api/kiwi/drafts/a1b2c3/file?path=concepts/auth.md' \
  --data-binary @auth.md

# Review, then merge
curl 'http://localhost:3333/api/kiwi/drafts/a1b2c3/diff'
curl -X POST 'http://localhost:3333/api/kiwi/drafts/a1b2c3/merge'

Also: GET /drafts, GET /drafts/{id}, GET and DELETE /drafts/{id}/file, GET /drafts/{id}/tree, and DELETE /drafts/{id} to discard.

MCP

Tool	Purpose
kiwi_draft_create	Start a draft
kiwi_draft_list	List active drafts
kiwi_draft_read	Read a file inside a draft
kiwi_draft_write	Write a file inside a draft
kiwi_draft_diff	Diff a draft against main
kiwi_draft_merge	Merge a draft
kiwi_draft_discard	Delete a draft

Related

Drafts API

Every draft endpoint and response.

Versioning

How commits and history work.

Task claims

Lease a path so agents do not edit the same page at once.

MCP

Connect an agent to KiwiFS.