transcripted

Imported from r3dbars/transcripted (AGENTS.md). Install upstream with npx skills add r3dbars/transcripted. Copyright stays with the author.

Transcripted Agent Guide

Current repo truth

• main is the current Transcripted product, derived from the earlier Draft codebase.
• The current app on main supports dictation and meetings.
• Meeting capture includes local mic + system audio, imported-audio transcription, optional local-speaker review, and agent-readable Markdown output.
• The older draft / ghostwriting flow is not active on main.
• Sources/TranscriptedCore/ is an in-repo library consumed through Sources/Meeting/. Keep it as a library boundary.
• Sources/Speech/ owns the app-owned local STT path. Meetings reuse that path through Sources/Meeting/MeetingSTTAdapter.swift.
• Sources/Reliability/ owns wake / sleep recovery for hotkeys and active capture flows.
• build.sh builds the app target. The root Package.swift exists for TranscriptedCore package tests and smoke coverage, not as the main app build.

Product capability contract

Simplification work must preserve the current product surface unless the owner explicitly approves a capability change. In particular, keep:

• automatic meeting detection and its record / dismiss / remind flow
• the Speakers directory and speaker review, rename, merge, and delete tools
• per-app dictation Auto Enter
• manual model-cache inspection and cleanup controls
• the status item's right-click quick menu
• retained meeting-audio playback; transcript rows stay static and do not highlight or follow the playhead

These surfaces may share less code underneath, but do not delete, hide, or make them harder to reach as part of an architecture or visual cleanup.

Response voice

• Write like a real person texting a friend, not like a presentation.
• Keep things simple, direct, and useful.
• Use short, punchy sentences most of the time.
• Vary the rhythm. Short punch. Then a little more detail when it helps.
• Use casual connectors when they fit: "so", "anyway", "plus", "also".
• Be honest when something is weird, unclear, or unknown.
• Use light natural hesitation sparingly: "I think maybe", "probably", "not sure but".
• Avoid marketing speak, corporate buzzwords, stiff transitions, and obvious AI phrases like "dive into", "delve into", or "let's explore".
• Avoid piling on adjectives.
• Keep capitalization normal.
• Be relaxed, but still clear. Real, not sloppy.

Read this first

0. AGENT_START.md for the short agent entrypoint
1. README.md
2. AGENTS.md
3. docs/repo-layout.md
4. docs/agent-onboarding.md
5. CLAUDE.md
6. Sources/CLAUDE.md
7. the nearest local CLAUDE.md for the area you are changing
8. Sources/Accessibility/CLAUDE.md when touching focused-editor AX metadata, overlay placement, or paste-back context
9. Sources/Dictation/CLAUDE.md when touching dictation persistence
10. Sources/Meeting/CLAUDE.md when touching meeting capture or meeting UI
11. Sources/TranscriptedCore/CLAUDE.md when touching the shared library
12. Sources/Speech/CLAUDE.md when touching dictation STT, audio recovery, or device handling
13. Sources/Support/CLAUDE.md when touching shared preferences, permissions, paths, or Claude Desktop install flow
14. Sources/UI/CLAUDE.md when touching overlay, menubar, onboarding, settings, or agent-connect UI
15. Sources/Capture/CLAUDE.md when touching hotkeys or physical dictation trigger routing
16. Tests/README.md
17. docs/storage-paths.md
18. Sources/Reliability/CLAUDE.md when touching wake / sleep recovery or hotkey recovery
19. Sources/Observability/CLAUDE.md when touching crash reporting, event forwarding, anonymous analytics, or app updates
20. docs/release-packaging.md when touching packaging, signing, notarization, or user-facing releases
21. docs/sparkle-updates.md when touching app updates or cutting a release users should receive in-app
22. Tools/*/CLAUDE.md when touching standalone CLI, MCP, or QA tools

Use docs/repo-layout.md as the canonical directory map and doc hierarchy. Use .agents/test-matrix.yml as the quick path-to-verification map, with this file taking precedence when there is any conflict.

Coordinator closeout

When a worker lane reports back to the Transcripted coordinator, use this exact one-line shape and keep it short:

COORD_DONE: GREEN/BRIEF/RED | PR URL if any | changes made | GitHub cleanup recommendations | decisions needed | tests/checks run | lanes used: Codex=...; Claude=...; Local=...; Windows=... | smallest next action

For review, merge-room, and worker-thread prompts, include the Maestro lane contract. Codex is the final reviewer / merger. Claude is for risky reasoning. Mac local models and the Windows worker are cheap first-pass lanes for summaries, clustering, log triage, and draft work. If a lane is skipped, say why in the closeout.

For non-Codex lanes, use ~/.codex/bin/maestro-delegate whenever possible, for example maestro-delegate local --label pr-dedupe -- "...", maestro-delegate windows --label review -- "...", or maestro-delegate claude --label risk-review -- "...". A lane only counts as used if the closeout includes a real MAESTRO_PROOF path, output path, or pasted command output.

Use docs/agent-closeout.md for the status meanings and GitHub cleanup boundaries.

Build and test

bash build-deps.sh
bash build.sh --no-open
bash run-tests.sh
bash run-integration-smoke.sh
swift test

Rules. Use .agents/test-matrix.yml for the full path-to-verification map; these are the common minimums:

1. After changing Swift source, run bash build.sh --no-open and bash run-tests.sh.
2. If you touch Sources/Meeting/ or Sources/TranscriptedCore/, also run bash build-deps.sh --force and bash run-integration-smoke.sh.
3. If you touch Package.swift, Sources/TranscriptedCore/, or the public core seam, also run bash build-deps.sh --force, bash run-integration-smoke.sh, and swift test.
4. build.sh must not compile Sources/TranscriptedCore/ directly into the app target.

PR QA levels:

• Tiny docs-only: run scripts/dev/agent-preflight.sh and the mapped docs gate. Do not require full release QA for spelling, comments, or internal docs that do not change release truth.
• Meaningful code: run codex-review against the real PR base, then run the union of .agents/test-matrix.yml checks for the changed paths.
• Broad, risky, or release-impacting: run codex-review, the mapped checks, and bash scripts/ops/transcripted-qa-bench.sh --mode full.

Treat release notes, appcast/update docs, Homebrew cask docs, QA-gate docs, and public download/release-truth docs as release-impacting even when the diff is Markdown-only.

codex-review means: an independent model review of the full PR diff against the real base branch — e.g. codex review from the OpenAI Codex CLI, or an equivalent independent agent reviewer. Record the verdict (and any findings you rejected, with reasons) in the PR description. It is not defined as a repo script; any tool that reviews the true diff qualifies.

Before opening a repair branch

When a PR goes dirty (conflicting) the reflex is to spin up a fresh repair-pr-NNNN branch. Do not. First confirm the change did not ALREADY merge under a different PR number — this has burned multiple threads that each re-opened a repair branch for a fix that was already on main.

Required step before opening any repair/redo/reland branch:

python3 scripts/dev/check-superseded.py --pr <dirty-pr-number>
# or, once you are on the repair branch:
python3 scripts/dev/check-superseded.py --branch "$(git branch --show-current)"

• Exit 3 with STOP: #NNNN already merged this means the scope is already on main. Close the dirty PR as superseded and do the work only if something is genuinely still missing. Do not open the repair branch.
• Exit 0 (no merged PR already covers ...) means the change is novel. Proceed.

scripts/dev/agent-preflight.sh also prints this reminder automatically when it detects a repair-shaped branch name.

Releases, Sparkle, and Homebrew

When the task is a user-facing release, package handoff, or update-path change, agents must treat Sparkle as part of the release contract, not as optional follow-up work.

Rules:

1. Read docs/release-packaging.md and docs/sparkle-updates.md before changing release flow.
2. For builds intended for other machines, use build-beta.sh, not build.sh.
3. A release is not complete just because a DMG exists. For in-app updates to work, the release flow must also:
   • publish the signed archive where users can fetch it
   • update docs/appcast.xml
   • push the updated appcast to the branch that backs the live feed
4. If the release should also be installable or upgradeable through Homebrew, the release flow must also:
   • run bash scripts/release/update-cask.sh <version> after the GitHub release is published
   • commit the updated Casks/transcripted.rb
   • push that cask update so brew install and brew upgrade see the new version
5. If Sparkle metadata was not updated, say explicitly that existing installs will not discover the new release in-app yet.
6. If the Homebrew cask was not updated, say explicitly that brew install / brew upgrade will still point at the older release.
7. If the release artifact URL, appcast URL, public key, Sparkle tooling, or Homebrew install path changes, update the docs in the same change.
8. Keep Info.plist Sparkle settings aligned with the actual release feed:
   • SUFeedURL
   • SUPublicEDKey
   • any automatic-check / automatic-download flags
9. Preferred release verification for release-path changes:
   • bash build-deps.sh --force when dependency tooling changes
   • bash build.sh --no-open
   • bash run-tests.sh
   • SKIP_NOTARIZATION=1 bash build-beta.sh '' <user-name> for packaging smoke, or the full notarized path when cutting a real release

Observability, Sentry, and Analytics

Treat Sentry and PostHog as explicitly bounded integrations, not generic log sinks.

Rules:

1. Read Sources/Observability/CLAUDE.md before changing crash reporting, event forwarding, anonymous analytics, file logging, or update plumbing.
2. Runtime Sentry config lives in Info.plist under:
   • TranscriptedSentryDSN
   • TranscriptedSentryEnvironment
   • TranscriptedSentryReleasePrefix
   • optional: TranscriptedSentryAppHangTrackingEnabled
3. Local overrides for testing can come from process environment:
   • SENTRY_DSN
   • SENTRY_ENVIRONMENT
   • SENTRY_RELEASE
   • SENTRY_DIST
   • SENTRY_ENABLE_APP_HANG_TRACKING
4. Runtime PostHog config lives in Info.plist under:
   • TranscriptedPostHogAPIKey
   • TranscriptedPostHogHost
5. Local overrides for analytics testing can come from process environment:
   • POSTHOG_API_KEY
   • POSTHOG_HOST
6. The user-facing crash reporting and anonymous analytics preferences are stored by CrashReportingPreferences and AnalyticsPreferences. Both default to enabled until the user changes them in Settings or onboarding.
7. EventReporter does not forward every .error event to Sentry. Off-device forwarding is gated by the explicit allowlist in Sources/Observability/SentryEventPolicy.swift.
8. PostHog events and properties are gated by Sources/Observability/AnalyticsEventPolicy.swift.
9. Keep off-device payloads privacy-safe. Do not send raw transcript text, audio references, meeting titles, speaker names, emails, tokens, or absolute file paths. If payload shape changes, update the relevant sanitizer and tests in the same change:
   • Sources/Observability/SentryPayloadSanitizer.swift
   • Sources/Observability/AnalyticsPayloadSanitizer.swift
10. Test and smoke runs should keep local production logs clean with TRANSCRIPTED_DISABLE_FILE_LOGGER=1 when invoking binaries directly.
11. Preserve the user verification path when touching the integrations:

• Settings should still expose the crash-reporting toggle
• Settings should still expose the anonymous analytics toggle
• About should still expose the Send diagnostics action when Sentry is configured (the old Send Test Sentry Event settings row was removed by owner decision in the 2026-08 settings simplification)

12. Preferred verification for observability-related changes:

• bash build.sh --no-open
• bash run-tests.sh
• confirm Sentry, analytics, and observability preference tests still pass through run-tests.sh

Testing gotchas

• run-tests.sh is a custom swiftc runner, not XCTest.
• Root fast tests are discovered by convention: Tests/FooTests.swift must expose exactly one top-level testFoo() entry function.
• Tests/TranscriptedCoreTests/ is a separate Swift Package target, run via swift test rather than run-tests.sh.

Storage

Current app builds on main default to Transcripted-named Application Support paths:

• app support root: ~/Library/Application Support/Transcripted/
• capture library: ~/Library/Application Support/Transcripted/captures/
• meetings: ~/Library/Application Support/Transcripted/captures/meetings/
• dictations: ~/Library/Application Support/Transcripted/captures/dictations/

The user can relocate the capture library in Settings via transcriptSaveLocation. App-owned state, cache, logs, and temp files stay under ~/Library/Application Support/Transcripted/.

Historic Draft paths still exist for migration and standalone-tool fallback.

See docs/storage-paths.md for the canonical storage map, including legacy fallbacks and TranscriptedCore standalone defaults.

Default orchestration: ultracode + workflows

For substantive work — research, audits, multi-file or cross-cutting changes, design, and reviews — default to authoring and running a Workflow that fans out parallel agents and adversarially verifies findings, rather than working solo. Reserve solo execution for trivial mechanical edits and conversational replies. Spawned worker threads inherit this default: a thread doing real work should itself orchestrate with a workflow wherever breadth or independent verification helps. Token cost is not the constraint here — correctness and coverage are. This is "ultracode" as the standing default for this repo.