// Release new versions of sidecar. Covers version tagging with semver, td dependency updates, go.mod validation, CHANGELOG updates, GoReleaser automation, Homebrew tap updates, and verification steps. Use when preparing or executing a release.
| name | release-sidecar |
| description | Release new versions of sidecar. Covers version tagging with semver, td dependency updates, go.mod validation, CHANGELOG updates, GoReleaser automation, Homebrew tap updates, and verification steps. Use when preparing or executing a release. |
| disable-model-invocation | true |
git status shows no changes)go test ./...)gh auth status)replace directives in go.mod.goreleaser.yml in repo root)HOMEBREW_TAP_TOKEN secret exists in GitHub repo settingsBeware of go.work: A parent go.work file can silently use local dependencies instead of published versions. Always use GOWORK=off when updating dependencies and testing builds.
Follow semantic versioning:
git tag -l | sort -V | tail -1
Sidecar embeds td as a Go module. Always update to latest before releasing:
GOWORK=off go get github.com/marcus/td@latest
GOWORK=off go mod tidy
Ensure no replace directives (they break go install):
grep replace go.mod && echo "ERROR: Remove replace directives before releasing!" && exit 1
GOWORK=off go build ./...
If this fails with "undefined" errors, the required dependency version hasn't been published yet.
## [vX.Y.Z] - YYYY-MM-DD
### Features
- New feature description
### Bug Fixes
- Fix description
### Dependencies
- Dependency update description
git add CHANGELOG.md
git commit -m "docs: Update changelog for vX.Y.Z"
git tag vX.Y.Z -m "Brief description of release"
git push origin main && git push origin vX.Y.Z
Pushing the tag triggers GitHub Actions GoReleaser, which:
⚠️ GoReleaser does NOT update the Homebrew tap automatically. The tap uses source-build formulas (to avoid macOS Gatekeeper warnings on pre-built binaries), which GoReleaser doesn't support. You MUST manually update the tap.
The Homebrew tap at marcus/homebrew-tap must be updated for every release.
If you skip this, users will see "update available" but brew upgrade won't find it (see #122).
# Get the source tarball SHA256
curl -sL "https://github.com/marcus/sidecar/archive/refs/tags/vX.Y.Z.tar.gz" | shasum -a 256
# Edit the formula (local tap is at /opt/homebrew/Library/Taps/marcus/homebrew-tap/)
# Update: url (tag version) and sha256
cd /opt/homebrew/Library/Taps/marcus/homebrew-tap
# Edit Formula/sidecar.rb — update version in URL and sha256
# Commit and push
git add Formula/sidecar.rb
git commit -m "sidecar: bump to vX.Y.Z"
git push
Also bump td and nightshift formulas if releasing those.
# Check workflow succeeded
gh run list --workflow=release.yml --limit=1
# Check release exists with binaries
gh release view vX.Y.Z
# Test Homebrew install
brew install marcus/tap/sidecar
sidecar --version
# Test go install (critical!)
GOWORK=off go install github.com/marcus/sidecar/cmd/sidecar@vX.Y.Z
sidecar --version
# Should output: sidecar version vX.Y.Z
# Test update notification
go build -ldflags "-X main.Version=v0.0.1" -o /tmp/sidecar-test ./cmd/sidecar
/tmp/sidecar-test
# Should show toast: "Update vX.Y.Z available!"
Version is embedded at build time via ldflags:
go build -ldflags "-X main.Version=v0.2.0" ./cmd/sidecar
go install -ldflags "-X main.Version=v0.2.0" ./cmd/sidecar
Without ldflags, version falls back to:
go install)devel+abc123)develOn startup, sidecar checks https://api.github.com/repos/marcus/sidecar/releases/latest, compares tag_name against current version, and shows a toast if newer. Results cached for 3 hours. Pre-release suffixes (-rc1, -beta) are stripped for comparison. Dev versions skip the check.
gh release delete vX.Y.Zgoreleaser release --cleancurl -fsSL https://raw.githubusercontent.com/marcus/sidecar/main/setup.sh | bashbrew install marcus/tap/sidecargo install github.com/marcus/sidecar/cmd/sidecar@latestGOWORK=off go get github.com/marcus/td@latest)replace directives in go.modGOWORK=off go build ./...)GOWORK=off go install ...@vX.Y.Z)Reference for keyboard shortcut implementation, keybinding registration, shortcut parity with vim and other TUI tools, and the complete shortcut assignment table across all sidecar plugins. Use when adding or modifying keyboard shortcuts, checking shortcut assignments, resolving key conflicts, or assessing alignment with vim conventions.
Create conversation adapters for importing AI chat history from different tools (Claude Code, Cursor, Warp, Codex, etc.). Covers the adapter.Adapter interface, caching strategies, incremental parsing, watch/FD management, and performance standards. Use when creating a new adapter, modifying adapter behavior, or debugging adapter performance issues. See references/ for Cursor DB and Warp SQLite schema details.
Writing and maintaining the Sidecar Docusaurus documentation site, including page structure, doc authoring, blog posts, styling, images, and deployment workflow. Use when writing documentation, updating the docs site, adding pages or blog posts, or working with Docusaurus configuration.
Create declarative modals using the modal library API. Covers modal types (confirm, input, select, form), sections (Text, Buttons, Input, Textarea, Checkbox, List, When, Custom), rendering with OverlayModal, and keyboard/mouse handling. Use when adding modals or dialogs to the application.
Create new sidecar plugins implementing the plugin.Plugin interface, rendering views with Bubble Tea, handling keyboard input via keymap contexts, and integrating with the app shell (footer hints, event bus, adapters). Use when creating a new plugin, modifying plugin architecture, or debugging plugin rendering/lifecycle issues. See references/ for sidebar list and fixed footer layout details.
Create prompts for sidecar workspaces. Covers prompt structure (name, ticketMode, body), template variables (ticket with fallbacks), config file locations (global vs project), and scope overrides. Use when creating or modifying prompts in sidecar config files.