docks-kit

Portable configuration kit for AI coding agents. Per-tool Single Source of Truth (SoT) directories deploy to each tool's user-config location. Clone once to get a consistent AI-assisted environment on supported Linux, macOS, and Windows machines. Tuned for token efficiency without sacrificing quality.

Supported harnesses: Claude Code, Codex, and Oh My Pi (omp). The kit also deploys agentskills.io universal skills.

Quick start

git clone https://github.com/DocksDocks/public.git ~/projects/public
cd ~/projects/public
./docks-kit harnesses       # choose this machine's flag-less sync harnesses
./docks-kit sync            # deploy this machine's harness selection
./docks-kit sync omp        # deploy omp explicitly
./docks-kit status          # doctor view: drift, toolchain, plugins, skills

POSIX hosts use the ./docks-kit launcher on Linux x64 and arm64 and on macOS arm64. Windows uses .\docks-kit.ps1 on x64. Each launcher prefers the matching compiled binary in cli/dist/ only when its version matches the checkout. Otherwise it runs from source via Bun and auto-installs Bun plus dependencies when needed. Hosts outside this matrix fail immediately and never fall back to Bun source. Stale ignored build artifacts cannot mask newer checkout code.

Other install paths include global bun add -g docks-kit, the POSIX curl installer, and the Windows PowerShell installer. See ./docks-kit docs install.

No-Bun recovery path:

Download the platform release binary from GitHub Releases and run it directly. The executable carries the generated sync payload; no checkout or adjacent SoT/ directory is required.

Source and global installs require Bun. npm-global tools require Node/npm. jq is optional doctor/test tooling. curl is needed only to download Bun's upstream installer when Bun is absent: by the POSIX launcher and installer, and by sync's Bun bootstrap, which a release binary can also run. The Windows launcher and installer use Invoke-WebRequest.

CLI

docks-kit sync [claude] [codex] [agents] [omp]  deploy explicit targets or the machine selection
docks-kit harnesses                             view or change this machine's selection
docks-kit update [--no-sync]                    self-update the kit (autodetects checkout vs global install), then sync
docks-kit model <claude|codex> [value]          get/set the DEPLOYED model (TTY picker)
docks-kit models [claude|codex|omp] [--refresh]  live catalogs for enabled harnesses (`--json`)
docks-kit omp [--model <m>|--pick] [args...]    one omp session on a free model, nothing deployed changes
docks-kit omp --fast                            toggle omp fast mode for OpenAI/Codex models, then exit
docks-kit toolchain [check|ensure <tool>|outdated|upgrade]  verified-version floors for external tools
docks-kit status [--json]                       deployed-vs-SoT drift + toolchain + counts
docks-kit plugins list [--json]                 enabledPlugins tri-state vs installed
docks-kit skills list [--json]                  universal skills vs manifest
docks-kit docs [topic]                          self-documentation (12 topics)
--help --version --wizard --completions    built-in

The CLI is a typed Effect 4 RC front-end on Bun; all mutation runs through EngineNative in cli/src/engine-native/, with golden-regression coverage for dry-run output, mutation snapshots, and argv logs. Its dependency graph is effect@4.0.0-rc.115 (including effect/unstable/cli), @effect/platform-bun@4.0.0-rc.115 (BunServices.layer and BunRuntime.runMain), @effect/vitest@4.0.0-rc.115, and vitest@5.0.3 (inside the @effect/vitest peer range >=5.0.0 <6.0.0). @effect/cli and @effect/platform are removed: neither has a 4.x release, the CLI API moved into core, and the standalone platform package was unused here.

Key flags (docks-kit sync)

Flag	Effect
--dry-run	Preview without applying
--reconcile	Reconcile kit-owned settings toward SoT (user-only keys preserved)
--prune	Uninstall kit-managed plugins/marketplaces/skills not in SoT
--claude-model=<m>	Deploy-time modifier: deployed Claude model
--claude-compact-window=<n>	Deploy-time modifier: autocompact window (680k)
--claude-permissive	Deploy-time modifier: empty ask/deny (sandboxes only)
--claude-plugin=<name>	Sticky opt-in plugin (supabase, n8n)
--codex-model=<m>	Deploy-time modifier: deployed Codex model
--skip-bubblewrap	Skip optional bubblewrap bootstrap (Codex Linux sandbox)
--skip-plugin-refresh	Install missing plugins but skip refresh-only updates

Deploy-time modifiers change deployed config only — the SoT is untouched and a later flag-less sync reverts them. Full reference: docks-kit docs flags (includes the old→new rename table for the pre-CLI sync.sh flags).

How syncing works

• Additive by default — user-only settings keys, plugins, and skills survive a plain sync. Reconciliation toward the SoT is explicit (--reconcile / --prune).
• Per-machine selection — ~/.docks-kit/kit.db drives a flag-less sync. A missing selection selects Claude Code, Codex, and universal skills. It does not select omp. Use docks-kit harnesses to view or change the selection. With no stored selection, its picker pre-ticks every harness, omp included.
• Idempotent — every step is safe to re-run; no-change syncs are no-ops.
• Toolchain floors — SoT/toolchain.json records the kit-verified version floors for external tools (bun, bwrap, …). docks-kit toolchain check prints the full doctor table. Bun is the one managed install and is pinned to its verified version.
• Model catalog — enabled harnesses provide live Claude, Codex, or omp model IDs; SoT/models.json supplies Claude and Codex aliases, notes, and the offline fallback. omp has no curated fallback list.
• Claude runtime — sync materializes three dependency-free Bun .mjs programs for statusline, SessionStart, and Notification. Quota display uses Claude's native rate_limits; there is no OAuth fetch, shared usage cache, or Stop hook. If Bun cannot be resolved or bootstrapped, sync preserves a working legacy hook/statusline setup and reports that migration is deferred.
• Command guards — omp, Claude Code, and Codex share one fail-closed policy for destructive shell commands; to remove, agents use the trash (gio trash -- <path>, or trash <path> on macOS); omp agents remove a temporary file or directory with docks-kit scratch remove. rm of the home directory or / and HOME reassignment are denied. omp also denies every recursive rm, find -delete, find -exec rm, and xargs rm, and runs any other rm without a prompt. In omp, git clean, git reset --hard, any git push that could force, and the common forms of a git command that skips the repository's hooks (--no-verify, git commit -n, a core.hooksPath change) ask; Claude Code and Codex also ask before find -delete, a recursive rm, and every git rm. An omp subagent cannot answer an ask, so omp rejects it; a Codex ask can go to its auto_review reviewer. Details, per-tool differences, and gaps: docks-kit docs command-guards.
• Agent cleanup (omp) — docks-kit scratch creates agent temporary directories and removes agent temporary files and directories with checked paths, and docks-kit tidy removes merged idle worktrees, their containers, orphaned processes, and idle scratch directories; --report lists other disk and memory use. The kit omp plugin docks-kit-omp exposes these as tools, reminds the agent of what it created, and runs the sweep at most once per 12 hours.

Repository map

Path	Purpose
SoT/.claude/	Claude Code SoT (settings template, Bun runtime programs, CLAUDE.md)
SoT/.codex/	Codex SoT (config.toml, rules, AGENTS.md, marketplace)
SoT/.omp/	omp SoT (AGENTS.md, config.yml, models.yml, mcp.json, intercom.json, and the plugin/ source of docks-kit-omp)
SoT/.agents/	Universal-skill manifest
SoT/models.json	Curated aliases, notes, and offline Claude/Codex fallback
SoT/toolchain.json	Verified-version floors
cli/src/engine-native/	EngineNative sync/model/toolchain implementation
cli/src/generated/sotPayload.ts	Generated in-memory payload used by standalone and npm installs
cli/	docks-kit CLI (Effect 4 RC on Bun) + bundled docs topics
docks-kit / docks-kit.ps1	POSIX and Windows launchers (binary → Bun-from-source)
install.sh / install.ps1	POSIX and Windows global installers
docs/PLAN.md	Plan record standard; plans are GitHub issues
AGENTS.md / CLAUDE.md	Agent-facing engineering rules / Claude Code specifics

Platform support

Platform	Architecture	docks-kit binary	Sync engine
Linux	x64	✅	✅ native
Linux	arm64	✅	✅ native
macOS	arm64	✅	✅ native
Windows	x64	✅	✅ native

Details: docks-kit docs platforms.

Releases

Tagging cli-v* builds four standalone binaries: docks-kit-linux-x64, docks-kit-linux-arm64, docks-kit-darwin-arm64, and docks-kit-windows-x64.exe. The workflow attaches them plus SHA256SUMS to the GitHub release. npm publishes the exact package tarball through trusted publishing with OIDC provenance. Published binaries, checksums, and release notes are available on GitHub Releases. Each docks-kit npm release bundles the CLI + generated payload, so releases are versioned config snapshots without shipping the authoring SoT/ tree.

Deeper docs

• docks-kit docs <topic> - overview, sync-layers, flags, modifiers, models, omp-models, omp-context, command-guards, toolchain, plugins, install, platforms (works offline, bundled with the CLI)
• AGENTS.md — engineering rules for agents working on the kit
• CLAUDE.md — Claude Code specifics: env vars, session management, permission mode, open concerns