Kit (kitctl)

Kit manages the skills, agents, MCP servers, hooks, plugins and instruction blocks your coding agents (Claude Code, Codex and, documented but not yet verified, Cursor) load. You keep named loadouts in a warehouse (~/kits by default); kitctl writes each harness's own config for them in a project or in your home, with an ownership ledger so kitctl off puts back exactly what was there.

0.1.0 can:

• start a warehouse (kitctl init), check it (validate) and show what a loadout means per harness, with every capability gap and its remedy (resolve);
• check a loadout against what is actually installed (doctor, read-only);
• apply loadouts to a project or to your home (--user): use, off, apply, status, eject, each showing its plan and asking before it writes;
• copy warehouse skill folders and worker agents, and run a loadout's setup steps (after asking);
• estimate each harness's always-on listing and hold it to a loadout budget (doctor).

Kit never writes trust: approving hooks, MCP servers and projects stays with you.

Run

Python 3.11+:

uv tool install kitctl          # or: uvx kitctl --version
kitctl init && kitctl validate
kitctl use starter --repo path/to/repo

# From a checkout:
uv run kitctl --version

Node 20+ with uv installed:

npx kitctl --version
npx kitctl inventory --root /path/to/repo --json

The npm package is a thin launcher around the bundled Python wheel from the same release. It uses uvx with that local wheel; it does not require a PyPI release, run install scripts, or ship a kit binary. uv manages Python if needed.

Start a warehouse of your own (~/kits, or KIT_WAREHOUSE), with a starter loadout that only adds an instruction block:

uv run kitctl init
uv run kitctl validate

Loadouts (read-only; nothing is written):

uv run kitctl validate ~/kits
uv run kitctl resolve brand-studio --harness claude --warehouse ~/kits
uv run kitctl resolve brand-studio:audit --harness codex --json
uv run kitctl resolve brand-studio --harness cursor   # documented facts only; see the gaps

doctor checks a loadout against what is actually installed in the roots you name. It never fixes anything or starts an MCP server:

uv run kitctl doctor --loadout brand-studio --root ~ --root path/to/repo

It also estimates the always-on listing each harness carries for the loadout plus the roots' kit.yaml loadouts (instruction block, listed skills and agents, ceil(chars / 4)) and warns when it is over a loadout's budget (see the model).

use, off, plan, apply, status and eject manage a project's native config through an ownership ledger. They show the plan and ask before writing (--yes skips the question), and kitctl off restores the original bytes (see apply):

uv run kitctl use brand-studio --repo path/to/repo --dry-run   # the plan only
uv run kitctl use brand-studio --repo path/to/repo             # the plan, then [y/N]
uv run kitctl off brand-studio --repo path/to/repo             # the undo
uv run kitctl use core --user                                   # ~/.claude, ~/.codex, ~/.agents
KITCTL_SANDBOX=/tmp/kit-sandbox uv run kitctl ...               # confine writes to one directory

resolve prints the effective native config a loadout would produce and every capability gap. See the model.

inventory defaults to the current directory. Repeat --root to inspect several repositories, or explicitly pass your home directory to include user config. There is no recursive search through unrelated repositories. Symlinked skills and configuration are skipped with warnings. JSON includes file paths and hashes, never configuration contents. Exit codes: 0 complete, 1 partial due to skipped items, 2 invalid arguments or roots. Reports may reveal private paths; keep them out of public source control.

Develop

uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest
uv build
uv run python scripts/prepare_npm.py
npm --prefix npm test
cd npm
npm pack --dry-run

Tests use throwaway HOME, CODEX_HOME, CLAUDE_CONFIG_DIR, and repository fixtures. CI runs on Linux and Windows with Python 3.11 and 3.14. A local pre-commit configuration and CI check reject common token formats and private keys. Install the hook with uvx pre-commit install if desired; this basic check is not a comprehensive secret scanner.

See PLAN.md, design, harness reference, and publishing.

Naming

Kit ships only the kitctl command. AWS's Kubernetes Iteration Toolkit and Gravwell also use a kitctl binary; installing those tools alongside Kit can cause PATH collisions. This project is independent of those projects and KitOps.

MIT License. The code repository and private warehouse are deliberately separate.