@kontextmind/kxm/docs/architecture/inventory.md

KXM local-first multi-agent orchestration and operator dashboard

# Surfaces

Read from `plugins/kxm/src/cli.ts`, `plugins/kxm/src/config-editor.ts`,
`plugins/kxm/src/extension.ts`, `scripts/kxm-hub.mjs`,
`plugins/kxm/src/hub.ts`, `plugins/kxm/src/runtime-supervisor.ts`,
`plugins/kxm/src/runtime-paths.ts`, `plugins/kxm/src/mcp-server.ts`,
`plugins/kxm/src/oneshot-producer.ts`, `plugins/kxm/src/studio-layout.ts`,
`plugins/kxm/src/cli/types.ts` (`workspaceDirs`),
`plugins/kxm/src/local-snapshot.ts`, `scripts/kxm-worker.mjs`, and
`python/kxm-control/src/kxm_control/{api,registry}.py`.

| Surface | Started by | Listener or path | Store it owns | Defining file |
| --- | --- | --- | --- | --- |
| `kxm` CLI | `node scripts/kxm.mjs` or the installed bin | no listener | none | `plugins/kxm/src/cli.ts` |
| Configuration editor | `kxm config edit --scope project\|user`; OMP/Pi `/kxm config` uses project scope | `.kxm/config.yaml` or the user `config.yaml` | the selected config file; only bounded non-secret scalar fields | `plugins/kxm/src/config-editor.ts` |
| Hub | `kxm hub start` via `scripts/kxm-hub.mjs` | `127.0.0.1:7331` | `.kxm/state/kxm.db` under the workspace state dir | `plugins/kxm/src/hub.ts` |
| Hub credentials | written when the hub starts | `hub-env.json` under the user state root | that JSON file, not SQLite | `plugins/kxm/src/hub-env.ts` |
| Hub cloud binding | `kxm hub bind <url> --cloud --token-env/--token-command` | no listener; writes the binding record and never stores the token | binding record; token stays in the named env or command | `plugins/kxm/src/cli/hub.ts` |
| Runtime supervisor | `kxm runtime` / `scripts/kxm-runtime-supervisor.mjs` | `127.0.0.1` and the requested port, or ephemeral | registry and event stores below | `plugins/kxm/src/runtime-supervisor.ts` |
| Runtime registry | opened by the supervisor | `runtime/registry.db` under the user state root | `registry.db`. A lane worktree registers under its project: same project id, its own control root, `lane_of` set. A registering root is the primary worktree when its git common dir is `<root>/.git`; if that primary registers while the live home row is not primary, the primary becomes the home row and every other live row of that repository becomes its lane. | `plugins/kxm/src/runtime-paths.ts` |
| Runtime event store | opened by the supervisor | `runtime/projects/<key>/run-events.db` | `run-events.db`. `kxm improve report` and `kxm routing report` read the home store and every lane store for the registered project id through one read-only query of `registry.db` (`plugins/kxm/src/improve-sources.ts`). An absent registry, or a checkout that is not registered, reads only that checkout's own store. Paths come from the stored project keys. | `plugins/kxm/src/runtime-paths.ts` |
| MCP server | Claude plugin or stdio launch | stdio | none | `plugins/kxm/src/mcp-server.ts` |
| One-shot harness | supervisor producer | child process, no listener | none | `plugins/kxm/src/oneshot-producer.ts` |
| Pi worker | `kxm agent worker` | no HTTP listener in `scripts/kxm-worker.mjs` | none of its own | `scripts/kxm-worker.mjs` |
| Studio | `kxm studio serve` | `127.0.0.1:4242` | none; `/api/control/account` is a bounded relay to the configured control API | `plugins/kxm/src/studio-layout.ts` |
| Python control API | ASGI server loading `kxm_control.api:app` | deployment-selected; the package declares no network default | `kxm_registry` in the fixed `kxmd` PostgreSQL database and the configured tenant artifact root | `python/kxm-control/src/kxm_control/api.py` |
| Workspace config | `workspaceDirs` | `.kxm/config`, or `KXM_CONFIG_DIR` | files in that directory | `plugins/kxm/src/cli/types.ts` |
| Workspace logs | `workspaceDirs` | `.kxm/logs`, or `KXM_LOGS_DIR` | log files | `plugins/kxm/src/cli/types.ts` |
| Workspace assets | `workspaceDirs` | `.kxm/assets`, or `KXM_ASSETS_DIR` | asset files | `plugins/kxm/src/cli/types.ts` |
| Workspace state | `workspaceDirs` | `.kxm/state`, or `KXM_STATE_DIR` | `kxm.db` when the hub uses this directory | `plugins/kxm/src/cli/types.ts` |
| Lane registry | `kxm lane create` | no listener | `lanes.json` under the workspace state dir | `plugins/kxm/src/cli/lanes.ts` |
| Landing | `kxm land` via `scripts/pr-land.mjs` | no listener | `land-release-context.json` and `land-phases-before.json` under `.kxm/logs` | `scripts/pr-land.mjs` |
| Assignment runner entry | `kxm assign <verb>` | no listener | none; the runner writes task records | `plugins/kxm/src/cli/assign.ts` |
| Docs site | `kxm docs serve` via `ops/docs-site/serve.py` | the tailnet IPv4 from `tailscale ip -4` and one port; refuses any other address | none; serves the built `site/` | `ops/docs-site/serve.py` |

On macOS the user state root is `Library/Application Support/KXM` under the
home directory (`kxmUserStateRoot` in `plugins/kxm/src/bindings.ts`). Windows
uses `AppData/Local/KXM`. Other platforms use `$XDG_STATE_HOME/kxm` or
`.local/state/kxm`. `KXM_STATE_HOME` overrides that root when it is absolute.
The tracker mentions `docs/operations.md` for the six backup roots. That page
indexes the operations guides and links the six roots to
[Backup and restore](../operations/backup-and-restore.md). It also holds
[Cross-box peer attach](../operations.md#cross-box-peer-attach).

## Related

- [Platform](platform.md)
- [Backup and restore](../operations/backup-and-restore.md)