tsm: Instructions file for Codex

tsm — Notes for Claude

tsm is a Touch-ID-gated secrets manager for macOS. Two halves in one repo:

• Go CLI (tsm) at the repo root — user-facing commands and agent integration.
• Swift daemon (tsmd) in tsmd/ — owns the encrypted vault, Keychain, Touch ID, audit log.

They communicate via newline-delimited JSON-RPC 2.0 over a Unix socket. The CLI auto-spawns the daemon on first use.

Layout

go.mod, main.go        # Go CLI entry
cmd/                   # cobra subcommands (one file per command)
internal/
  client/              # JSON-RPC Unix socket client + Caller interface
  daemon/              # tsmd lifecycle (spawn, wait-for-socket)
  jsonrpc/             # JSON-RPC 2.0 types
  normalize/           # Kebab() — derives ids from display names
  paths/               # XDG path resolution
tsmd/                  # SwiftPM package (the daemon)
  Sources/tsmd/        # one .swift file per concern
  Tests/tsmdTests/     # XCTest, ~83 tests

Build & test

just test                 # go test ./... + swift test (tsmd/)
just build                # both binaries → dist/bin/
cp dist/bin/tsm dist/bin/tsmd ~/.local/bin/
pgrep -fl "/.local/bin/tsmd" | awk '{print $1}' | xargs -r kill   # stop the old daemon before reinstalling

The daemon must be ad-hoc signed (Apple Silicon requirement). swift build does this automatically. Do not run codesign --remove-signature on the binary.

Releasing

Tag-driven: git tag -a vX.Y.Z && git push origin vX.Y.Z triggers .github/workflows/release.yml. Full procedure and one-time setup are in RELEASING.md — read it before cutting a release. Rules that are easy to get wrong:

• Tag the merge commit on main, never a feature branch. Expect one github-actions[bot] commit on main after every release (plugin version bump); pull before branching.
• Don't hand-edit versions. npm/*/package.json stay 0.0.0 (workflow rewrites from the tag at publish time). plugin/.claude-plugin/plugin.json and .claude-plugin/marketplace.json are bumped and committed by the workflow — that one has to land in git because claude plugin update only refreshes when the manifest version changes.
• Publish order is load-bearing. @tashian/tsm-darwin-arm64 publishes before the wrapper @tashian/tsm so optionalDependencies resolve. Don't reorder.
• npm Trusted Publishing needs Node 24 / npm 11. Node 22's npm 10 silently publishes unauthenticated and 404s — don't downgrade setup-node.
• Irreversible. A published npm version can't be re-published. Confirm the version before pushing the tag.