How it works

This page explains what devkit puts on your machine, how updates arrive, and what it never touches. Daily work needs none of it.

One setup per machine, not per project

The shared setup — skills, agents, rules, hooks, scripts — is one signed, versioned release installed once per machine. Projects keep only their own context and permissions.

Layer	Contents	Where it lives
Shared setup	Skills, agents, rules, hooks, scripts, workflows, themes	~/.onedot-devkit, linked into ~/.claude/, updated at a session boundary
Project context	Facts, conventions, decisions, permissions	Committed in the project, owned by the project
Machine tools	CLI tools and Claude plugins	Installed by devkit sync

Updates

A release is verified before it is used: signature, version, channel, size and checksum must match, or the download is discarded and the current version stays. A session start activates a verified release by switching one symlink, then fetches the next one in the background; a running session is never changed under you, and every earlier version stays available for devkit rollback.

Command	Result
devkit sync	fetches, verifies, activates and installs tools now
devkit fetch	verifies and stages a version without activating it
devkit apply	activates the staged version without fetching
devkit rollback [version]	switches back to an earlier installed version
devkit config channel stable|latest	stable is the team channel, latest the early channel

devkit doctor reports an update check older than 48 hours as stale. A machine refuses a remote version older than the one it already verified; devkit rollback is the way back.

What stays yours

• Same-named personal files win. A personal skill, agent, rule or hook with the same name as a shared one stays untouched; the shared one stays inactive and devkit doctor names the collision.
• Your settings win. Values such as the main model are set only when missing.
• Only devkit's own links are removed. devkit off removes links and hook wiring and keeps version and config; devkit unlink also removes local state. MCP client entries and personal configuration survive both.
• Failures are visible. A tool that cannot be installed makes devkit sync fail instead of finishing; a failed update is shown by devkit doctor instead of being reported as done.

Sources

The default source is the signed endpoint. Maintainers can point a machine at a checkout and run it through dev mode:

bash

devkit config source-http https://devkit.one-dot.io
devkit config source-local /path/to/onedot-devkit

Claude Code is the primary runtime; Codex, OpenCode and Pi receive the shared setup through runtime adapters.