Metadata-Version: 2.5
Name: kitctl
Version: 0.1.0
Summary: Inventory and manage agent skills, MCP connectors, hooks, and loadouts.
Project-URL: Repository, https://github.com/ConnorBritain/kitctl
Project-URL: Issues, https://github.com/ConnorBritain/kitctl/issues
Author: Connor England
License-Expression: MIT
License-File: LICENSE
Keywords: agents,claude,codex,mcp,skills
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.11
Requires-Dist: ruamel-yaml<0.19,>=0.18.10
Requires-Dist: tomlkit<0.14,>=0.13.2
Description-Content-Type: text/markdown

# 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+:

```sh
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](https://docs.astral.sh/uv/getting-started/installation/):

```sh
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:

```sh
uv run kitctl init
uv run kitctl validate
```

Loadouts (read-only; nothing is written):

```sh
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:

```sh
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](docs/model.md#budget)).

`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](docs/apply.md#writing)):

```sh
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](docs/model.md).

`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

```sh
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](PLAN.md), [design](docs/design.md),
[harness reference](docs/harness-reference.md), and [publishing](docs/publishing.md).

## 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.
