Versioning

Versioning

Codeman follows semantic versioning. This page says what the version number actually promises, which matters if you are building anything against Codeman.

Covered by the version number

Breaking any of these after 1.0 requires a major bump:

1. The CLI. Command names, documented flags, and their behaviour. The npm package is aicodeman and installs both the aicodeman and codeman commands; renaming either is breaking.
2. The HTTP API and SSE channel, served under /api/v1 with the uniform envelope and conventional status codes. Endpoint paths, the envelope, errorCode values, and SSE event names are all stable.
3. Documented deployment environment variables: CODEMAN_PASSWORD, CODEMAN_USERNAME, CODEMAN_HOST, CODEMAN_PORT, CODEMAN_INSTANCE, CODEMAN_ALLOWED_HOSTS, CODEMAN_DATA_DIR, CODEMAN_TMUX_SOCKET, plus the --host, --port, and --https flags.
4. The published xterm-zerolag-input library, on its own independent version line. Codeman reaching 1.0 says nothing about that package's version.

Additive changes are not breaking: new endpoints, new optional fields, new error codes, new SSE events. Genuinely breaking API changes would ship under a new prefix rather than changing /api/v1.

Not covered

These can change in a minor or even patch release:

1. The ~/.codeman/ state file formats. Migrations are made on a best-effort basis and have been done across renames, but the on-disk shape is not a contract. Do not write tooling against it.
2. Internal TypeScript modules. The npm package is CLI-only. There is no stable library entry point, and importing it programmatically is unsupported.
3. Experimental and opt-in features, whatever the app's version: gesture control, agent teams, and anything labelled experimental in the UI or docs.

Deprecation

• Additive changes are preferred over breaking ones.
• A covered surface slated for removal is deprecated first: it keeps working for at least one minor release, with a runtime warning and a changelog note pointing at the replacement, then is removed in the next major.
• Backwards-compatibility shims are kept until a major boundary.

Releases

Releases are managed with changesets. Every release:

• Bumps the version and updates CHANGELOG.md.
• Publishes to npm as aicodeman.
• Cuts a GitHub release, tagged codeman@X.Y.Z.
• Credits its contributors and bug reporters by name in the release notes.

There is no fixed cadence. Patches ship when fixes are ready, which in practice is often.

Which version am I on?

codeman --version

Or App Settings → Updates, which also checks for a newer one and can install it. See Running As A Service.

Read next

• HTTP API - the stable API surface itself.
• Contributing - how changes get made.
• docs/versioning-policy.md - the authoritative statement.