Skip to content

Upgrading

To upgrade a project to a new release of uncoded:

  1. Find the release that the project uses. For version 6 or later, run uv run uncoded --version. For an earlier version, read the version from the pre-commit hook's entry, or run uvx uncoded --version if there is no hook.
  2. Read the changelog for every release after that release.
  3. If the new release is major, follow the section below for each major release that the upgrade crosses, oldest first.
  4. Run uv lock --upgrade-package uncoded.
  5. Run uv run uncoded sync, and commit uv.lock and every installed skill file that the command writes, rewrites or removes.

From version 5 to version 6

Version 6 supports projects that use uv and require Python 3.12 or later. It runs uncoded from the project's uv environment and reads its settings only from pyproject.toml.

  1. If the project has no pyproject.toml, create a uv project first. If the project supports Python below 3.12, raise that requirement before upgrading, or keep using version 5.
  2. Add uncoded as a development dependency with uv add --dev uncoded.
  3. Move the settings from .uncoded.toml into a [tool.uncoded] table in pyproject.toml, then delete .uncoded.toml.
  4. Change the uncoded pre-commit hook's entry to uv run uncoded sync.
  5. Run uv run uncoded sync, then commit the regenerated installed skill files with pyproject.toml, uv.lock and the pre-commit configuration.

From version 4 to version 5

Version 5 no longer reads the required-version setting. Delete it from the configuration file. The version in the entry of the pre-commit hook now pins uncoded. If the project has no hook, add one as Refresh on commit says.

From version 3 to version 4

Version 4 adds uncoded init and a required version, runs body and refs only inside a project, and lays stubs out in the standard stub style.

  1. Run version 4, which rewrites every stub in the new layout:
uvx uncoded@4.0.0 sync

Commit every installed skill file that it writes or rewrites.

  1. Pin the project to version 4, so that every machine runs the same uncoded. Add this setting to the configuration file:
required-version = "4.0.0"

If a pre-commit hook runs uncoded, name the same version in its entry, as uvx uncoded@4.0.0 sync, since uncoded refuses any other version.

  1. Delete any skill that an earlier version of uncoded wrote under a name it no longer uses, since version 4 no longer removes them:
rm -rf .agents/skills/coherence-review .claude/skills/coherence-review
rm -rf .agents/skills/uncoded-coherence-review .claude/skills/uncoded-coherence-review
rm -rf .agents/skills/uncoded-review .claude/skills/uncoded-review

Check first that none of them is a skill of the project's own.

  1. Run uncoded body and uncoded refs from inside the project. They now stop outside a project, and when the --in file is outside the project directory. A script that ran them from elsewhere changes directory first.

  2. On Windows, expect / between directories in the paths that uncoded refs prints. A script that read them with \ changes to match.

From version 2 to version 3

Version 3 keeps generated indexes local, renames the semantic consistency review, and makes navigation skills load once per session.

  1. Stop tracking .uncoded/, then rebuild the index locally:
git rm -r --cached .uncoded
uvx uncoded sync

Commit the updated files under .agents/skills/ and .claude/skills/. The generated .uncoded/.gitignore keeps the rebuilt index out of Git.

  1. Add always_run: true to the local uncoded pre-commit hook. The ignored index must also be refreshed when a commit only deletes files.

  2. Change every skill pointer from uncoded-coherence-review to uncoded-consistency-review. Delete the old generated skill:

rm -rf .agents/skills/uncoded-coherence-review .claude/skills/uncoded-coherence-review
  1. Replace any always-on navigation instructions in AGENTS.md or CLAUDE.md with the skill-loading instructions from Getting started.

From version 1 to version 2

Version 2 replaces instruction injection with generated skills.

  1. Run the final version 2 release to create the skill files:
uvx uncoded@2.1.1 sync

It also removes the version 1 skills, coherence-review and uncoded-review. Later releases leave them in place.

  1. Remove the old marker blocks from AGENTS.md or CLAUDE.md:
<!-- uncoded:start ... -->
...
<!-- uncoded:end -->
<!-- uncoded:docs:start ... -->
...
<!-- uncoded:docs:end -->
  1. Change every skill pointer from coherence-review to uncoded-coherence-review.

  2. Remove instruction-files from pyproject.toml or .uncoded.toml because version 2 no longer reads it.

  3. To keep navigation always on, add the skill-loading instructions from Getting started to AGENTS.md or CLAUDE.md.