we release far too often right now: 37 tags since 2026-06-29, close to one a day. For anyone running agterm as a daily driver every release means quitting and relaunching the app, and even with session restore that is disruptive. Time to plan the first stable release and change the model.
when
not yet. The precondition is the current version running stable for at least a few days with no major surprises. Small hotfixes inside that window are fine and don't reset the clock, a real regression does.
what v1.0.0 means
back compatibility guarantee, first of all. That needs an explicit list of what is covered. My current take:
- control API:
agtermctl command names, arguments, and JSON output fields. Additive only inside 1.x, no removals or renames, no field disappearing from tree
keymap.conf format: existing action names and syntax keep working- persisted state:
windows.json, windows/<id>.json, and the legacy workspaces.json migration path. Any 1.x build opens state written by any earlier 1.x
- the
AGTERM_* env vars a session shell sees
- installed agent skill and status hooks keep working against a newer app
open for argument: whether the ghostty config passthrough and the Settings schema are in or out of the guarantee.
release cadence after 1.0
slower and predictable. Something like monthly, and only when there is something worth shipping, no release just because the month rolled over. Hotfixes go out whenever they are needed and are exempt from the cadence.
work items
- decide the covered-surface list above
- write the policy down (a README section or
docs/compatibility.md) so it is a contract rather than an intention
- audit the current control API for anything we would regret freezing: command or argument names, output field shapes we would rather rename before the door closes
- define what a 1.x to 2.x break looks like and how it gets announced
we release far too often right now: 37 tags since 2026-06-29, close to one a day. For anyone running agterm as a daily driver every release means quitting and relaunching the app, and even with session restore that is disruptive. Time to plan the first stable release and change the model.
when
not yet. The precondition is the current version running stable for at least a few days with no major surprises. Small hotfixes inside that window are fine and don't reset the clock, a real regression does.
what v1.0.0 means
back compatibility guarantee, first of all. That needs an explicit list of what is covered. My current take:
agtermctlcommand names, arguments, and JSON output fields. Additive only inside 1.x, no removals or renames, no field disappearing fromtreekeymap.confformat: existing action names and syntax keep workingwindows.json,windows/<id>.json, and the legacyworkspaces.jsonmigration path. Any 1.x build opens state written by any earlier 1.xAGTERM_*env vars a session shell seesopen for argument: whether the ghostty config passthrough and the Settings schema are in or out of the guarantee.
release cadence after 1.0
slower and predictable. Something like monthly, and only when there is something worth shipping, no release just because the month rolled over. Hotfixes go out whenever they are needed and are exempt from the cadence.
work items
docs/compatibility.md) so it is a contract rather than an intention