Dev Mode — run the setup from a checkout

Dev mode runs your local onedot-devkit checkout as the active setup instead of the signed release. Use it when you change a skill, rule, hook, script or the CLI and want to see the result in a real session before a release exists.

The runtime stays the same: ~/.onedot-devkit/current points at a version directory, and every session resolves skills, hooks and scripts through that link. Dev mode only changes where that version comes from.

Set up once

1. Clone the repository: git clone git@github.com:onedot-digital-crew/onedot-devkit.git ~/Sites/onedot-devkit
2. Point the source at it: devkit config source-local ~/Sites/onedot-devkit — or install with DEVKIT_SOURCE_LOCAL=1 bash install.sh from inside the clone, which keeps the local source instead of switching to the signed endpoint.
3. Build the first dev version: devkit maint dev-sync
4. Start a new Claude session. The status line shows the version as <base>-dev@<sha7>.

devkit status names the source, so a machine that is unexpectedly on a checkout is visible there.

Daily loop

bash

devkit maint dev-sync              # committed HEAD, the default
devkit maint dev-sync --worktree   # working tree, including uncommitted edits

A dev version takes effect in the next session. A running session keeps the paths it resolved at start, so nothing changes underneath it.

devkit maint dev-sync builds the committed state, compiles the Rust binary (cargo build --release -p devkit) and ships it as the version's bin/devkit, exactly as a release does.

If a payload file (content/, hooks/, keys/) or a Rust source (rust/) is uncommitted, the run names the files on a ⚠ line and builds from a clean HEAD export instead of the checkout. The result is exactly the last commit: a parallel session's unfinished edits stay out, and they no longer block the sync. Your own uncommitted edits are not in it either — commit them first, or use --worktree for the fast self-edit loop. --worktree picks up every edit in the checkout, including a parallel session's unfinished work.

Inside the devkit repository the loop is automatic: a SessionStart hook reports which version the session runs and whether it matches HEAD, a Stop hook rebuilds after each turn in the background, and a failed rebuild is reported at the next session start with its log path. Claude Code reads these hooks from .claude/settings.json, Codex from .codex/hooks.json; devkit sync pre-trusts them when devkit config codex-hook-trust all is set; otherwise Codex asks once per new hook command.

What happens under the hood

Versions are immutable and bound to their name. A plain devkit sync therefore refuses a changed payload under an unchanged VERSION. devkit maint dev-sync derives a version name of its own instead — <next patch>-dev.<utc epoch>.<sha8> — so each distinct payload gets its own directory and the invariant holds. The epoch keeps a newer build sorting above the active one.

Old dev versions are pruned; the last three stay (DEVKIT_DEV_SYNC_KEEP changes the count). A directory a process still runs from is never removed.

Leave dev mode

1. devkit config source-http https://devkit.one-dot.io
2. devkit rollback <released version> — a dev version sorts above every release, so a plain devkit sync would refuse the step down as a downgrade. devkit version lists the installed versions.
3. Start a new session.

Symptoms

Symptom	Cause	Fix
devkit maint dev-sync says it needs a local source	The source is the signed endpoint or Git	devkit config source-local <checkout>
⚠ line listing files	Payload files are uncommitted; the HEAD export was built without them	Commit your own, or devkit maint dev-sync --worktree
Session start says the session does not run on HEAD	You committed after the last rebuild	The rebuild is already running; start a new session when it is done
Last dev sync failed, log path shown	The build or the sync stopped	Read the log, fix the cause, run devkit maint dev-sync
The change is not visible	The session started before the rebuild	Start a new session; devkit status shows the active version