Developer overview
Where to start if you want to change kittymux: how it is built, how to test a change safely, how the docs stay honest, and what to work on next.
kittymux is small on purpose: a configuration layer for kitty, not a daemon. Most of it is pure Python that can be tested without kitty, plus a few pieces that run inside kitty, a handful of kittens for the interfaces, and shell scripts for glue.
Architecture
The modules, the rules that keep state honest, and the kitty facts the code depends on.
Contribute
Set up a worktree, run the gates and open a pull request.
Testing
Unit tests, real-kitty rigs and the edge cases that still need a person.
Docs maintenance
How these pages are structured, generated and checked, and the plan for the docs site.
Release checklist
What must be true before you announce a release, and what not to claim.
Roadmap
What to work on next, in order, with what blocks each item.
The working contract
AGENTS.md in the repository root is the contract for people and coding agents alike. Four rules shape everything.
- Never restart a live kitty. Work in an isolated worktree, test with the rigs, merge, then reload only.
- A test must never touch another kitty on the machine. Each rig runs its own kitty and ends by checking that no other kitty changed.
- A state needs positive evidence. Silence is never "waiting", and a false "finished" is the worst class of bug.
- No credential in the repository, real or credential-shaped, in tests, docs or commit messages.