sync-orchestration-context

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 x64 and arm64. Windows uses .\docks-kit.ps1 on x64 and arm64. 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 [email protected] (including effect/unstable/cli), @effect/[email protected] (BunServices.layer and BunRuntime.runMain), @effect/[email protected], and [email protected] (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)

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). rm of the home directory or / and HOME reassignment are denied. omp also denies every recursive rm and asks before any other rm. find -delete, git clean, git reset --hard, any git push that could force, and git rm other than git rm -- <path> ask; Claude Code and Codex also ask before 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.

Repository map