kiv · command line · v0
Git for kit files
kiv is Git for kit files: object-level diffs, three-way merges through the kit, and a merge queue for agents working in parallel worktrees. Git keeps the history and runs the worktrees; kiv adds what Git cannot do for a slide file. kiv v0 works with slide files only: .pptx and .kslide.
Copy for AI
$ kiv init --kit slide=/path/to/kition-slide
$ kiv save -m "base"
$ kiv ws add ../ch-03 -b ch-03 # a worktree per agent
$ cd ../ch-03
$ kiv read slides.pptx # the slide file as text (or --json)
$ kiv run slides.pptx text.set --slide 3 \
--params '{"id":267,"text":"Revenue grew 21%"}'
$ kiv render slides.pptx --slide 3 --out p3.png
$ kiv save -m "Update the revenue slide" --agent writer-3 --task ch-03
$ cd ../main
$ kiv land ch-01 ch-02 ch-03 # exit 1 if any branch conflicted$ git diff slides.pptx # without kiv
Binary files a/slides.pptx and b/slides.pptx differ
$ kiv diff # with kiv
### slides.pptx (modified)
~ slide 5 "Roadmap"
~ [275] Rectangle 2: fill "#2E6FD8" → "#2E8B57"How it works
01- GitHistory and worktrees
kiv init makes or prepares a Git repository: slide files go through kiv’s merge driver and textconv, so plain git diff and git merge work too.
- kivDiff, merge, land
kiv runs each kit through its own headless executable, the same kition-<kit> the MCP server and the SDK use. kiv itself never parses the file.
- YouLand the branches
One worktree per agent. kiv land merges them back one by one and backs out the ones that conflict, with the base, ours and theirs values.
The commands
02kiv init [--kit slide=<path>]Make or prepare a Git repository: *.pptx and *.kslide go through kiv.kiv statusgit status, plus an object-level summary of each changed slide file.kiv diff [from] [to] [--png <dir>]Object-level diff, HEAD to the working tree by default; --png renders the changed slides before and after. Other files diff as in Git.kiv save -m … [--agent] [--task]Open each changed slide file with the kit to check it (exit 2 and nothing committed if one fails), then commit with Kiv-Agent and Kiv-Task trailers.kiv log [-n]History with the agent and task of each commit.kiv ws add · list · rmgit worktree, one per agent.kiv merge <branch>Three-way merge through the kit. On a conflict the merge stays in progress: fix it, then kiv save.kiv land <branch…>A merge queue: merge each branch in turn, back out the ones that conflict, report them.kiv conflictsThe conflicts of the last merge in this worktree: file, slide, shape, field, and the three values.kiv read · render · run · newFor agents: read a slide file as text or JSON, render a slide to PNG, run a kit command and save, make an empty slide file.kiv doctorCheck Git, the repository and kition-slide; say how to install what is missing.
Every kiv command takes --json, with fixed exit codes: 0 done, 1 conflicts, 2 a check failed, 4 usage or environment error.
A complete example
03Three agents edit the same six-slide deck in three worktrees. Agent a retitles the cover, b recolours a roadmap box, c retitles the cover too. kiv land lands a and b and backs out c, which conflicts with a on the cover title.
# agent a, in ../a
kiv run slides.kslide text.set --slide 1 \
--params '{"id":261,"text":"Q3 Business Review: Record Quarter"}'
kiv save -m "Retitle the cover" --agent a --task cover
# agent b, in ../b
kiv run slides.kslide shape.fill --slide 5 \
--params '{"color":"#2E8B57","ids":[275]}'
kiv save -m "Highlight the Q4 milestone" --agent b --task roadmap
# agent c, in ../c
kiv run slides.kslide text.set --slide 1 \
--params '{"id":261,"text":"Q3 Review (Draft)"}'
kiv save -m "Mark the slide file as a draft" --agent c$ kiv land a b c
== a
merged a
### slides.kslide
~ slide 1 "Q3 Business Review: Record Quarter"
~ [261] Title 1: text "Q3 Business Review" → "Q3 Business Review: Record Quarter"
== b
merged b
### slides.kslide
~ slide 5 "Roadmap"
~ [275] Rectangle 2: fill "#2E6FD8" → "#2E8B57"
== c
c conflicts: backed out, not merged
conflict slides.kslide slide 1 [261] Title 1 text: base "Q3 Business Review",
ours "Q3 Business Review: Record Quarter", theirs "Q3 Review (Draft)" (the file keeps ours)
landed 2, backed out 1: c
$ echo $?
1Limits and requirements
04- Slide files only (
.pptx,.kslide): the slide kit is the only one with a driver. - kiv needs the slide kit’s headless executable,
kition-slide. Without it Git keeps working:git diffshows a one-line stand-in per slide file, andkiv saveexits 4. - Slides have no persistent id yet, so kiv pairs slides by content. Two identical slides may pair up wrongly.
- Merges replay text, position and size, and solid fills. Added or deleted shapes and slide properties are reported, not merged.
- When a merge has to rewrite a
.pptx, the kit’s export drops embedded fonts, chart data and vendor tags; keep.kslidein the repository and export pptx when needed. - The diff sees what the kit inspects (kind, name, text, box, fill, rotation, layout, notes, background, transition), not fonts, paragraphs, tables or chart data.
- kiv is Git for kit files: object-level diffs, three-way merges through the kit, and a merge queue for agents working in parallel worktrees.
- kiv v0 works with slide files only: .pptx and .kslide.
- kiv runs each kit through its own headless executable, the same kition-<kit> the MCP server and the SDK use.
- Every kiv command takes --json, with fixed exit codes: 0 done, 1 conflicts, 2 a check failed, 4 usage or environment error.
- kiv is open source under Apache-2.0, with prebuilt binaries.
- kiv drivers for notes, tables, boards and film.
Give an agent the same kits over MCP instead: Kits for agents.
The headless executables kiv drives