OpenWhisperer: Instructions file for Claude Code

AGENTS.md

This file defines the project-scoped rules, workflows, commands, and architecture details for AI agents working in the OpenWhisperer repository.

Commands

All Swift commands run from the app/ directory (it's the SwiftPM package root).

cd app
swift build                                           # debug build
swift build -c release                                # release build
OW_SIGN_IDENTITY="OpenWhisperer Dev" ./build-dmg.sh   # build signed bundle + .dmg for local dev (keeps TCC grants)
./build-dmg.sh                                        # build ad-hoc bundle + .dmg (release) into app/.build/

swift run OpenWhispererKitTests      # pure-logic unit tests (exits non-zero on failure)
swift run HookTests                  # bash-hook integration tests (stubbed curl + temp HOME)

swift run OpenWhisperer --serve-tts  # headless TTS server on :8000 (no GUI) for curl/CI; TTS_PORT overrides

Manual TTS smoke checks (server must be running, GUI or --serve-tts):

curl http://localhost:8000/v1/models
echo "hello" | scripts/speak.sh

Testing notes

• This machine has Command Line Tools only, no full Xcode, so there is no XCTest/swift-testing. Both test targets are plain @main executables that aggregate *Failures() -> [String] check groups and exit(1) if any fail. There is no per-test filter — to narrow a run, comment out check-group calls in the runner (Tests/OpenWhispererKitTests/SubmitTriggerTests.swift or Tests/HookTests/main.swift).
• Only pure logic (no AppKit/AVFoundation/WhisperKit) is unit-testable, and it lives in the OpenWhispererKit target precisely so it builds fast under CLT. Put new testable logic there.

Working on changes

The loop this repo already follows. The parent checkout stays on main; feature branches live only under .claude/worktrees/ — never branch in place.

Pick the lightest safe path:

• Local (commit straight to main, no PR) — docs/CLAUDE.md/comment edits, or a small, self-contained, low-risk code fix where a PR adds ceremony without safety. Stay on main, make the smallest edit, verify (readback for docs; the test targets for code), commit, push. If it unexpectedly grows beyond small/isolated, switch to the PR path before committing.
• PR — multiple files, real logic, a dependency change, or user-visible behavior:
  1. Worktree off main: git worktree add .claude/worktrees/<slug> -b <slug> (or EnterWorktree in Claude Code).
  2. Build + test from app/: swift run OpenWhispererKitTests and swift run HookTests (both exit(1) on failure). For a packaged .app/.dmg, use OW_SIGN_IDENTITY="OpenWhisperer Dev" ./build-dmg.sh locally so TCC grants survive the rebuild (see Conventions).
  3. PR: rebase onto origin/main if it moved, push, gh pr create.
  4. After merge: sync main (git pull --ff-only), git worktree remove .claude/worktrees/<slug>, delete the branch. Leave no orphaned worktree dir — a stale bundle holding :8000 is a known foot-gun.