kleoth
CLAUDE.md8 starsChanged 51 days agoApache-2.0View on GitHub
Local-first macOS voice & capture app: dictation, bot-free meeting recording, screen recording. Native Swift 6 / SwiftUI menu-bar app and a kleoth CLI. Captures mic + system audio locally → transcribes → summarizes → writes Markdown/JSON the user owns. Public repo: github.com/ofcRS/kleoth (Apache-2.0). Keep this file short: commands, architecture, decisions, gotchas. Session narrative goes in docs/SESSION-LOG.md (archived history) or the design docs under docs/plans/, never here.
- Reads credentials
- Deletes or force-pushes
- Commits and pushes
In this repository2 other files it gives its agents.
- summarize-meetingSkill
- transcribe-meetingSkill
The file
We split this CLAUDE.md into the rules it gives an agent
7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 7
Keep this file short: commands, architecture, decisions, gotchas.
- Very specific: line 150
Only OpenRouter + Claude Code get it.
- Very specific: line 233
Read inputNode.inputFormat(forBus:), not outputFormat — the latter is stale after a device switch.
- Very specific: line 260
Never Bundle.module, in app code OR a dependency: SwiftPM's accessor looks only at the .app root and at the BUILD Mac's .build folder, then …
- Distinctive: line 334
Not yet human-verified: the Quick Look click, Reduce Motion, the rubber band, a window resize, "Show scroll bars: Always", the chip states …
- Distinctive: line 335
Always", the chip states with Covers on, macOS 14–15.
- Very specific: line 346
Call detection) and meta.json with context at stop.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Kleoth
Local-first macOS voice & capture app: dictation, bot-free meeting recording, screen recording. Native Swift 6 /
SwiftUI menu-bar app and a kleoth CLI. Captures mic + system audio locally → transcribes →
summarizes → writes Markdown/JSON the user owns. Public repo: github.com/ofcRS/kleoth (Apache-2.0).
Keep this file short: commands, architecture, decisions, gotchas. Session narrative goes in
docs/SESSION-LOG.md (archived history) or the design docs under docs/plans/, never here.
Environment
macOS 26 (Tahoe), Apple Silicon, Swift 6.4, Xcode 27.0 (since 2026-10). Floors: KleothCore/CLI = macOS 13; app = 14.4.
Liquid Glass gated behind if #available(macOS 26, *).
Commands
swift build && swift test # core + CLI (778 tests); CI: .github/workflows/tests.yml (+ app smoke, marketing)
swift build --package-path app # app package
bash app/setup-signing.sh # once: "Kleoth Self-Signed" cert (Accessibility/TCC trust binds to it)
bash app/make-app.sh release # bundle + sign + smoke test + install /Applications/Kleoth.app (KLEOTH_NO_INSTALL=1: dist only)
bash app/smoke-test.sh [Kleoth.app] # the shipped app, build folders hidden: History + all Settings pages (KLEOTH_SMOKE_FRAMES=<dir>)
pkill -x Kleoth; open -a Kleoth # relaunch (make-app does NOT kill the running instance)
pkill -x Kleoth; open -a Kleoth --args -KleothSimulateFirstRun YES # first-run flows again, this launch only
bash app/make-dmg.sh # app/dist/Kleoth-<version>.dmg (version = app/bundle/Info.plist)
swift run kleoth summarize <dir> --model <slug> --provider claude-code|codex|local|openrouter # re-summarize in place
swift run kleoth illustrate <dir>... [--engine codex|openrouter|local] [--style …] [--dry-run] [--force] # meeting covers
# Headless probes (use --product, not --target — --target links no binary)
swift build --package-path app --product localtranscribe && app/.build/debug/localtranscribe <meeting-dir> [scribe]
swift build --package-path app --product dictate && app/.build/debug/dictate 4 [--no-polish] [--device <uid>] [--provider claude-code|codex|local|openrouter] [--text "<raw>" --runs N]
app/.build/debug/dictate --file <audio> [--fail-first N] [--keep-on-failure] # real clip through the Scribe retry policy; N injected transient failures; keep → a REAL pending History row
app/.build/debug/dictate --text "<raw>" [--before s] [--after s] [--selection s | --reference s] [--single-line] [--no-polish] # synthetic focused field → placement, gate, paste; `--focus-probe --help` = the AX probe (reads the app in front: only with the user)
swift build --package-path app --product screenrec && app/.build/debug/screenrec 10 [--inspect f.mp4] [--extract f.mp4] [--words f.m4a] [--sidecar f.mp4 --title T]
swift build --package-path app --product micwatch && caffeinate -s -i app/.build/debug/micwatch --seconds 25 --detector # who holds the mic: bundle ids, pids, owner method, offers; never titles. --titles only with the user (the terminal's grants)
swift build --package-path app --product micopen && caffeinate -s -i app/.build/debug/micopen 13 # holds the mic from another process, samples discarded; exit 3 without an existing mic grant (never prompts)
swift run --package-path app pillsandbox # pill playground
app/.build/debug/pillsandbox --film <dir> --edge right --sequence idle,armed,listening,done,idle # filmstrip PNGs (step@secs; --demo dictation|screen composes README frames)
bash app/branding-src/demo/make-demos.sh # README demo GIFs from the real pill → docs/assets/demo-*.gif
bash app/branding-src/demo/make-app-demos.sh [data-dir] # meeting + viewer GIFs, screenshot-detail.png: a KleothDemo.app copy (-KleothDemo) films its own window
bun app/branding-src/demo/make-demo-data.ts <dir> [--provider local] # fictional meetings/recording, real on-device transcripts + summaries (default: Claude Code)
bun ~/.claude/skills/gpt-images/scripts/gpt-images.ts app/branding-src/<set>/jobs.json # brand imagery (brief: app/branding-src/BRAND.md)
bun marketing/sync.ts check [--offline] | apply [--no-remote] # public pitch: drift report / rewrite README hero, cask, Raycast, images, GitHub About+topics
bun test ./marketing/sync.test.ts # release-gate command parserLogs: /usr/bin/log stream --predicate 'subsystem == "dev.kleoth"' (categories Dictation,
DictationHotkey, Covers, MeetingDetection, MicActivity, PillTrace — the latter needs defaults write dev.kleoth.app KleothPillTrace -bool YES).
Crash reports: ~/Library/Logs/DiagnosticReports/Kleoth-*.ips. Reset TCC: tccutil reset ScreenCapture|Accessibility dev.kleoth.app.
Architecture — two SwiftPM packages
Root package (macOS 13, dep: swift-argument-parser)
KleothCore: Models,HTTPTransportseam,Transcription/(Transcriberprotocol,ScribeClient, normalizer),Summarization/(OpenRouterClient,Summarizer,ModelCatalog), Rendering, SpeakerMapping,Storage/MeetingStore,Config/(Settings, Credentials, Keychain),Pipeline/,Dictation/(chord machine, polisher, log store,PillGeometry,PolishGate,DictationTranscription= Scribe budget + retry policy,DictationAudioStore= kept clips,DictationContextPolicy/DictationContextFit/DictationInsertionPlan= field context),ScreenRecording/(defaults, geometry, session machine, audio math,Record/Storetranscript sidecar),Usage/,Covers/(drawing, store, engines),Meetings/(call detection:MeetingAppCatalog,MeetingServiceMatcher,MeetingSource,MeetingDetector= the pure offer machine,MeetingContext,MeetingNaming,CalendarEventMatcher),Concurrency/(withTimeout,withDeadline).kleothCLI:transcribe,summarize,rename,render,illustrate.KleothCoreTests.
app/ package (macOS 14.4; deps: .. as .package(name: "kleoth-app", path: ".."),
KeyboardShortcuts 2.4.0 vendored in app/Vendor/ with a one-line patch, WhisperKit 0.18)
KleothCapture:Recorder(mic.m4a + system.m4a → 2-channel meeting.m4a),MicCapture,SystemAudioTap(Core Audio process tap),LocalTranscriber(WhisperKit),DictationCapture,InputDevices,AudioFormat(AAC bit-rate clamp,TapWriter),ObjCExceptions,ScreenRecording/(ScreenRecorder+ sources/sink/mix pump/frame gate/MovieWriter),Meetings/(MicActivityMonitor,MicOwnerResolver,WebCallAssertions,WindowTitleReader).KleothObjC:KLCatchObjCException.KleothPillUI: the pill (DictationPanel,DictationPillController, model, view,PillMenu,PillTypes= the contract). Shared by the app andpillsandbox.KleothApp:MenuBarExtraagent;RecordingController(meetings + serial pipeline queue),DictationController,FocusedTextReader(the only code that reads another app's text; call detection'sWindowTitleReaderreads window titles only),ScreenRecordingController,PillCoordinator(single face in front of the pill: dictation, screen recording, meetings),Meetings/(MeetingCaptureTypes,MeetingPillBridge= the meeting side's face in front of the pill,MeetingDetectionController,CalendarLookup),AppConfig(Settings + Keychain overlay),Covers/CoverController,Views/(MenuView, HistoryView with Meetings | Dictations | Recordings scopes,MeetingCoverTile/MeetingCoverBand, SettingsView = flatHStacksidebar overSettingsPage,SettingsCoversSection, Onboarding, recordings viewer), App Intents,kleoth://URL scheme. No test target.- Executables:
taptest,localtranscribe,dictate,screenrec,pillsandbox,micwatch,micopen.
Design docs (binding contracts, error matrices, manual checklists): docs/plans/2026-09-03-dictation.md,
docs/plans/2026-09-06-screen-recording.md, docs/plans/2026-09-07-recordings-viewer.md,
docs/plans/2026-09-23-dictation-retry.md, docs/plans/2026-09-24-summary-truncation-and-onboarding-skip.md,
docs/plans/2026-09-24-positioning.md, docs/plans/2026-09-24-demo-mode.md (-KleothDemo: what a demo launch must never do),
docs/plans/2026-09-24-meeting-illustrations.md, docs/plans/2026-09-24-dictation-context.md,
docs/plans/2026-09-24-meetings-in-the-pill.md.
Data on disk
- Meeting =
~/Kleoth/meeting-yyyy-MM-dd-HHmmss/:mic.m4a,system.m4a,meeting.m4a,transcript.{json,md},summary.{json,md},speakers.json,meta.json; optionalvariants/<tier>/archives the non-active transcript tier. Every meeting hasmeta.jsonfrom stop (title, participants, consent,context= app/service/origin/mic seconds/calendar event/a window title that named a meeting); notranscript.json= "Untranscribed"; a meeting recorded before 0.5.1 may still lackmeta.json. Keysmeeting_detection("true"opt-in) andmeeting_detection_ignored(a JSON object STRING, key → name; keysapp:/site:/webcall:/browser:+ bundle id or service id). - Meeting covers:
cover.jpg+cover.json(CoverRecord:drawn/skipped/removed;skipped/removedblock automatic redraws) in the meeting folder; a dropped-incover.pngshows too; no key inmeta.json. Keyscover_engine(Off is written"off", never empty),cover_automatic,cover_style,cover_models. - Dictations:
~/Kleoth/dictations/<yyyy-MM-dd>.json; dictionary~/.config/kleoth/dictionary.json. A PENDING row (transcription failed/stopped) has empty texts,insert_method: "none",audio_file_name→dictations/audio/<id>.m4a,transcription_error; a retry fills it in place. Rows carryfield_context(cursor|merged|appended|replaced|reference|selection_changed),replaced_text(merges only) andcontext_seconds; the text around the caret is never stored. - Screen recordings:
~/Kleoth/screen-recordings/screen-<stamp>.mp4+<stem>.jsonsidecar (words). - Config:
~/.config/kleoth/config.json(CLI) and ONE consolidated Keychain item (servicedev.kleoth, accountsettings, JSON) read once per launch — click Always Allow on the prompt. UserDefaults:dev.kleoth.dictation.pillPlacement,dev.kleoth.settings.page,dev.kleoth.screenRecording.permissionRequestedAt. - Stored keys are snake_case via
convert{To,From}SnakeCase— no acronyms in stored property names (transcriptionUSDdoes not round-trip;CostBreakdownuses explicit CodingKeys).
Key decisions (do not relitigate)
- Transcription: tier 0 = on-device WhisperKit
large-v3-v20240930_626MB, auto language (chosen over Apple Speech because it lacks Russian, the user's main language); tier 1 = ElevenLabs Scribe on demand ("Fully transcribe"). Mic and system are separate channels → You/Them for free; Scribe gets a mono mix + diarization mapped to channels by per-cluster energy (96% accurate on a live A/B). Auto-transcribe after recording is opt-in (auto_transcribe). Duration always comes from the audio file. - WhisperKit language:
detectLanguagedefaults to false, solanguage: nilsilently means "en".LocalTranscriber.resolveLanguageruns one global detect pass; pinnable viatranscription_language. First model load after a new binary takes ~4 min (Core ML re-specializes); the next is ~1 s. - Summarization: OpenRouter, default
ModelCatalog.defaultModel=z-ai/glm-5.3-flash; strictjson_schemawith fallback tojson_object; output language = transcript language. Summary shape is lean:title?,tldr,overview?,action_items,per_speaker_highlights. - Summary completeness (2026-09-24):
Summarizer.assessaccepts an answer only if it is not cut off (finish"length", or JSON that stops before it closes — Codex, Claude Code and some local servers say"stop"regardless), decodes, and has a non-blanktldrand non-nulloverview,action_items,per_speaker_highlights(blank/empty OK). ONE retry shaped by the failure (cut off → fresh, 2× budget, compact;reasoning: lowonly after an EMPTY cut-off; an empty answer is never replayed), then it throws. Nothing partial is ever saved;meta.jsonnamesmodel/summary_provideronly if that run wrote one. - Dictation retry (2026-09-23): Scribe budget per attempt =
min(120, 25 + 0.5 × clip s), one retry 1 s after a transient failure (timeout, network, 408/429/5xx); dictation URLSession 130 s/150 s so the budget always fires first. A run with no transcript (failed, prep failed, Esc/Settings-off while transcribing — not quit) KEEPS its clip as a pending row; pill "… — saved to History" + Retry (pastes); History "Try again in cloud / on device" is a background job that copies (on device viaenqueuePipelineJob). Pasted dictations still keep no audio. - Hands-free mid-hold (2026-09-24): tap ⌘ while fn+shift is held, or click the push-to-talk pill →
the same capture goes hands-free (
ChordEdgeDetectorlatch→.latchKey; pill →.externalLatch; both →.latched). A MODIFIER on purpose: the monitor is listen-only, so Space would be typed into the target app. Only from a confirmed hold; ⌥/⌃ mid-hold still end. Dictation design §10.3 item 16. - Dictation polish:
DictationDefaults.polishModel=google/gemini-3.5-flash-lite(~1 s), fallback glm-5.3-flash;PolishGateskips chat targets and < 24 words;AppStyle= compose/chat only. - Context-aware dictation (2026-09-24):
FocusedTextReaderis the ONLY code that reads another app's text (window titles for call detection aside; decisions: pure KleothCore). Wake at chord-down, snapshot at release ≤ 0.3 s, re-check before ⌘V ≤ 0.15 s. Selection ≤ 4,000 chars → merged; ≤ 20,000 → dictation after it; unreadable or longer → replaced; changed → dictation as heard (polished_text=raw_text). Caret context: 1,500 before / 500 after. Terminal selection = reference. Only OpenRouter + Claude Code get it.dictation_contextis off only as the STRING"false"; both wake lists are empty (design §10). - OpenRouter account guardrails: no-train + ZDR settings turn
require_parameters: trueinto 404s foropenai/*,mistralai/*,x-ai/*, and forgoogle/gemini-3.8-flashwhentemperatureis sent. The client retries a 400/404 without temperature/reasoning. "The key doesn't work" = this 404. - Un-sandboxed, self-signed:
TextInserterpostsCGEvents (blocked by App Sandbox). Never addcom.apple.security.app-sandboxtoapp/bundle/Kleoth.entitlements. Accessibility + Screen Recording trust are bound to the "Kleoth Self-Signed" identity. Self-signed SCK capture works on this Mac. - Microphone: one app-wide input-device pick (
input_device, empty = Automatic) honoured by all three captures, set viakAudioOutputUnitProperty_CurrentDevicebefore readinginputFormat(forBus:). - Pill: dark capsule docked to a screen edge (
PillPlacement.edge+ fraction), tucked half off-screen when idle, hover → peek dock (Dictate · Meeting · Screen · More), ownPillMenuPanel(neverNSMenu— refused for inactive apps). Panel frames are set by the controller; SwiftUI never animates the window. - Screen recording: SCStream screen + audio + a third
AVAudioEnginemic tap mixed to ONE AAC track; H.264 ≤ 1920 px, 30 fps, fMP4 10 s fragments (player compatibility unverified —fragmentIntervalnil is the retreat). Whole-app SCK exclusion keeps Kleoth's windows out of frame. Recordings are not meetings; they auto-transcribe on device with word timestamps after save. - UI wording: tier badges say "On-device" / "Cloud". Money appears only in Settings → Usage. History deletes go to Trash without confirmation (Finder norm). No illustration in Settings or forms.
- AI providers (2026-09-16):
ChatCompletingis the seam underSummarizer/DictationPolisher; backends = OpenRouter, local OpenAI-compatible server, Claude Code CLI (claude -pwith settings/MCP isolation +--system-prompt, prompt on stdin), Codex CLI (summaries only), Apple on-device (dictation only,KleothOnDevicetarget, weak-linked).ProviderResolverauto order: local → Claude Code → Codex → OpenRouter → Apple.ProviderDetectorcaches its snapshot for 600 s, dropped on every provider-setting write,applicationDidBecomeActive, and the Settings Refresh button. Keys:ai_provider,local_server_url,local_server_key,ai_models; metasummary_provider, logpolish_provider(nil = OpenRouter). OpenRouter's own model still comes from the legacydefault_model/dictation_modelkeys viaSettings.effectiveProviderSettings, withai_modelsoverrides taking priority. Design:docs/plans/2026-09-15-ai-providers.md. - Consent window (2026-09-24): the consent guard lives ONLY in
RecordingController.start(); a refusal bumpsconsentRequest, and the always-mounted menu-bar label opens "Before you record" on it (onChange+ a mount-time check). New start paths (pill meeting button, call detection) just callstart()— no consent check of their own (only the popover and onboarding, which show the notice in place, gate first). The window's start button never closes it; it closes itself onceisRecordingis true. - Positioning (2026-09-24): the public pitch (tagline, GitHub About/topics, README hero, cask/Raycast/
DMG text, hero + social-preview images) is written ONLY in
marketing/positioning.json;bun marketing/sync.ts applywrites the rest — never hand-edit the READMEpositioning/releaseblocks. Three jobs: Dictate · Meet · Record screen (beta). Dictation is "Wispr Flow-style", never "alternative", while its STT is Scribe (cloud); held-back claims are listed inmarketing/README.md. Release gate:reviewed_formust equal the version; the.claude/settings.jsonPreToolUse hook blocksgit tag vX.Y.Z/gh release createuntilcheckpasses. - Meeting covers (2026-09-24): Off by default; engines Codex (
codex execimage_gen,--ephemeral, ChatGPT plan), OpenRouter (POST /api/v1/images,google/gemini-3.1-flash-lite-image) and a local server (Ollamax/flux2-klein). No AppleImageCreator: deprecated 2026-06-11, dead on macOS 27, background-forbidden on 26. A scene step through the summary provider sees only the title + TL;DR + the first 1,500 overview chars; the image engine gets only the scene. Sensitive →skipped, no image call. One retry 2 s after a transient failure (HTTP engines only); budgets: scene 60 s (never retried), image local 300 / Codex 240 / OpenRouter 90 s. Cloud jobs run onCoverController's own serial tail, local ones viaenqueuePipelineJob; a cover never marks a meeting processing. Money only in Settings → Usage (the covers row sumscover.jsoncost). Presentation (2026-09-25): the meeting page is one scroll (player included) that opens with the cover full width (CoverHeroGeometry: width ÷ 2 clamped 200–400 pt, parallax 0.35 with 80 pt of hidden reveal, overscroll stretch, none under Reduce Motion;visualEffect+.scrollView, macOS 14), title + TL;DR under it, Quick Look on click, the menu on right-click /…or a header chip without a picture; rows 56 pt only with a picture or a job; a demo launch shows covers (showsCovers) and draws none. Design:docs/plans/2026-09-24-meeting-illustrations.md(§10 addendum for the full-width cover). Wide since 2026-09-28 (§10 landscape addendum): everycover.jpgis a centred 16:9 crop ≤ 1536 px wide (OpenRouteraspect_ratio16:9, Codex and local 1536×1024), the prompt keeps the characters together in the centre, and the 56 pt tile is a centre square sized by its SHORT side. Older square covers still show; New Cover redraws one wide. - Meetings in the pill (2026-09-25): the meeting bar shows for EVERY meeting (any start path; dictation off
or the pill hidden for the hour too — the hot-mic rule).
.savingis owner-checked (both captures use it); one queued confirmation slot with its owner. The pill's Meeting button just callsstart()(consent = the "Before you record" window, nothing of its own). Design:docs/plans/2026-09-24-meetings-in-the-pill.md(§10 lists the deviations of both phases). - Call detection (2026-09-26): off by default. Kleoth never starts or stops a recording by itself: the pill
offers ("Zoom call — record it?"), and suggests stopping once, 20 s after the linked app lets go of the mic —
only with detection on and no screen recording running. No new permission: titles only with an existing
Screen Recording/Accessibility grant, the calendar only with access given.
MeetingDetectoris pure and owns every timing; after a ticknextDeadlineis nil or > now, and the host still floors its wait at 0.25 s (a past deadline was a main-actor busy loop).IsRunningInputis read on every re-read, never listened to; held mics are re-resolved every 3 s (titles from a 30 s per-pid cache) so a tab that joins a call upgrades — only while a meeting records orMeetingDetector.hasOfferableSessionholds (an app holding the mic all day stops after 10 min). The monitor itself (detection on, or a meeting recording) still re-reads Core Audio every 3 s on its own queue while ANY process holds the mic (10 s when none does), waking the main actor only on a change. It runs during every meeting forcontext, whichstop()captures SYNCHRONOUSLY right afterisRecording = false(before the combine's firstawait, or the detector forgets the linked app) and writes intometa.jsononce; every later writer carries it whole (runPipelinereads the existingmeta.jsonfirst). APillPromptprints as its id only: the opt-in pill trace must never log an offer's text.
Gotchas
AppDelegate→@MainActorcontrollers: useMainActor.assumeIsolated, never aTaskhop (applicationWillTerminatemay exit first).- Any AVFoundation call that can raise (
installTap,connect) goes throughcatchingObjCExceptions; a swallowed NSException surfaces later as a crash inswift_task_isCurrentExecutor. - Read
inputNode.inputFormat(forBus:), notoutputFormat— the latter is stale after a device switch. - One
AVAudioEngineper capture SESSION: create instart(), release on every exit, or a Bluetooth headset stays stuck in HFP (16 kHz) until the engine object is freed. - AAC bit rate must be clamped per sample rate/channels (
AudioFormat.aacSettings); a 16 kHz headset mic rejects 64 kbps with'!dat'. - Off-main audio work:
Recorder.combine,ChannelAudio.mixToMonotake seconds —Task.detached. CoverDrawing.drawruns off the main actor as a nonisolated async call — never wrap it inTask.detached(cancellation would not propagate). Holds whileNonisolatedNonsendingByDefaultstays off.- The meeting page's
NSScrollViewruns under the toolbar (contentInsets.top52 pt on macOS 26): at rest its clip sits at y = -inset, so AppKit scroll offsets (DemoDirector) add the inset back; SwiftUI's.scrollViewminY is already 0 at rest (probed on 26 only). vDSP_measqvis the MEAN of squares;sqrtof it is the RMS. Not a bug.NSEvent.keyCode/characterson a mouse event raise and AppKit swallows the exception WITH the event (a dead click, no log). Checkevent.typefirst in any monitor matching both.- An
NSHostingViewmust never be a floating panel'scontentView(SwiftUI's window-size bridge fights a controller-set frame → AppKit layout-loop abort). Wrap it in a plain container; set frames underwithTransaction(disablesAnimations).pillsandbox(AppKit lifecycle) cannot catch this. import AVKitalone does not link AVKit under SwiftPM;KleothApphas.linkedFramework("AVKit"). Verify withotool -L … | grep AVKit.- Adding a KleothCore source file is invisible to a warm
app/.builduntilapp/.build/arm64-apple-macosx/debug/description.jsonis deleted. Transcriber: Sendableconformance must be declared in the type's own file.swift testfails on every@Testwith "module 'Testing' has no member named__SourceBounds" when Xcode is newer than the Command Line Tools: the compiler takes the macro plugin from Xcode andTesting.frameworkfrom/Library/Developer/CommandLineTools. Fix = install the matching "Command Line Tools for Xcode" (softwareupdate --list) AND thenrm -rf .build(a warm module cache keeps the old framework).swift buildis unaffected; CI runs the tests either way.- Never
Bundle.module, in app code OR a dependency: SwiftPM's accessor looks only at the.approot and at the BUILD Mac's.buildfolder, thenfatalErrors — invisible here, a crash on every other Mac (#17 at launch; then KeyboardShortcuts' recorder in Settings → General, henceapp/Vendor/KeyboardShortcuts). App code usesKleothAssets.url(forResource:withExtension:); every bundle ships inContents/Resources.make-app.sh releasefails on any build path left in the binary (a live accessor), except swift-transformers' Hub (reached only for a tokenizer config withouttokenizer_class; Whisper's have it), and its smoke test runs the app with the build folders moved aside (red-tested on both bugs). Removing the worktree an installed build came from used to be enough to crash it here too. IsSecureEventInputEnabled()is session-wide: a background Chromium browser can hold it with another app in front.ioreg -l -w 0 | grep kCGSSessionSecureInputPIDnames the holder (only while it's on; it can outlive a quit app by ~30 s). A windowless process is credited to the frontmost app.zshhas alogbuiltin — use/usr/bin/log. SyntheticCGEventclicks from the agent shell do nothing (no Accessibility for the terminal); drive the pill throughpillsandboxfilm hooks.- A shell-launched probe gets the TERMINAL's TCC grant; it proves nothing about Kleoth's own.
- App Intents don't surface in Shortcuts (SwiftPM skips
appintentsmetadataprocessor); URL scheme works. - System Events keystrokes go to whatever app is frontmost, and
open -a Kleoth/activatedo not reliably bring an agent app forward — check the frontmost process first, and never UI-script while the user is using the Mac (a stray ⌘, landed in Slack mid-meeting, 2026-09-23). Kleoth's own buttons respond to AXclickonce its window is open. - SwiftUI
onChangenever fires for the value a view MOUNTS with: a request counter bumped just beforeopenWindowdoes not reach the new window. History request sites also setHistoryRouting.requestedScope, consumed on appear. - Provider detection: the local-server probe opens its own 2 s/3 s ephemeral
URLSession(the defaultURLSessionTransportwaits for connectivity and hangs forever with no server listening);codex login statusprints "Logged in using ChatGPT" to stderr, not stdout — check both streams. - Ollama's OpenAI-compatible
/v1ignores a per-requestnum_ctxand reportedly drops the START of an over-long prompt without an error (its default context can be 4k): long meetings needOLLAMA_CONTEXT_LENGTH≥ 32768 on the server.assesssees only the answer, so it can't catch the loss (summary spec §9 Q4). -KleothSimulateFirstRun YESreads consent + onboarding as not done for that launch only. It is read from the argument domain alone (defaults writedoes nothing) and writes nothing, and--argsreaches only a NEW process (pkill -x Kleothfirst). Read first-run state fromRecordingController, never the Keychain, or the flag can't reach it.- AX timeouts go on EACH element read (
AXUIElementSetMessagingTimeout), never on the system-wide element — that sets it for the whole process. - Chromium/Electron build their AX tree only once a client reads the APPLICATION element's
AXRole: that read is the chord-down wake. The first dictation after such an app launches may get no context. - Terminals are recognized by bundle id BEFORE the role: Ghostty's screen reports
AXTextArealike an editor, but ⌘V goes to the program's input, never over the selection. DictationPrompt.system/schemaJSONare SHA-256-pinned: no-context polish requests stay byte-identical (providers cache the prefix).contextSystemissystemplus string replacements (the\nOUTPUT\nline,language's wording): keep those anchors, and re-pin only on purpose.- Pill backdrops (
PillCoordinator.recompute()): screen recording > meeting > resting pill > hidden.setBackdroptakes over only a resting-family phase (otherwise it just stores it) and the pill appliesmodel.phasea main-queue turn late, so a capture start sets its backdrop FIRST, then dismisses its own leftover phase (MeetingPillBridge.started);clearCapturePhaseBlockingwithdraws the other capture's. The other order leaves a hot mic with no bar. A rising bar clears ANY sticky.failed(a dictation's is terminal), and bothsetBackdropand the coordinator read the phase still to land (pendingPhase/upcomingState). referenceSizeis resolved against the four-field dock (275 pt, every edge) and, on bottom/top, the meeting bar (240 pt): a new longest shape must be folded in there, or a pill parked near a corner creeps.- Core Audio: per-process
IsRunningInputlisteners register and never fire (listen toIsRunning/Devices, then re-read), andAudioObjectRemovePropertyListenerBlockfrom Swift silently removes nothing (listeners stacked per start): useAudioObjectAdd/RemovePropertyListenerwith one@convention(c)proc. micwatch --titlesfrom a shell reads titles with the TERMINAL's grants, andmicopenholds the mic under them. An unattended probe withoutcaffeinate -s -ican hit Maintenance Sleep mid-run (timers 15 min late).
Security (hard rules)
- API keys are never printed or committed.
.envandconfig.jsonare gitignored; inspect.envwithcut -d= -f1. Live probes read the key into a shell var and put it only in a header. - The repo is public — anything on
mainis world-readable.
State (update in place, keep to a few lines)
- v0.5.0 (2026-09-25): hands-free mid-hold, dictation retry + pending dictations, summary completeness + the "Before you record" window, meeting covers (opt-in), the secure-input holder named, macOS 15 first-launch copy. The user verified hands-free and dictation retry in daily use and waived the other manual checklists (providers, pill menu, screen recording, recordings viewer, summary §6) on 2026-09-25.
- v0.5.1 (published 2026-09-27, without the visual checks — the user's call): context-aware dictation, on-device
turns, covers full width, meetings in the pill + call detection. v0.5.2 (2026-09-27): the launch crash on every
Mac but the build Mac (#17,
Bundle.module) — reported by the first outside user. v0.5.3 (2026-09-28): the same trap in KeyboardShortcuts, a Settings crash (#22); vendored + a release-build guard on any dependency. Since then: the packaged-app smoke test (demo-mode design §7) in everymake-app.sh releaseand in CI (tests.yml, macos-26). - Covers hero (0.5.1): full-width band + parallax + Quick Look + 56 pt
rows + scene prompt rev. 4 + slash/temp fixes. Verified: core tests, both builds,
illustrate --dry-runbefore/after. Still to film: the demo-mode frames (KLEOTH_DEMO_FRAMES: light/dark × 3 offsets, a no-cover page). Not yet human-verified: the Quick Look click, Reduce Motion, the rubber band, a window resize, "Show scroll bars: Always", the chip states with Covers on, macOS 14–15. Follow-ups: a bottom-pinned mini-player, a cover in the README demo data. - Context-aware dictation (merged for 0.5.1; design
docs/plans/2026-09-24-dictation-context.md): the field's selection + 1,500/500 chars around the cursor go to OpenRouter/Claude Code with the words; a selection merges in place. The user dictates with it daily; the design §6 checklist (1–24) was not run item by item. - On-device meeting turns (merged for 0.5.1; demo-mode §6 #2): meetings transcribe with
LocalTranscriber.Timing .speechRuns(word alignment, one entry per run of speech) andTranscriptNormalizersplits alocal-whisperchannel's turn where another channel spoke entirely inside the pause; Scribe grouping unchanged. Verified on fictional audio only (5/6 exact turn order); not yet on a real meeting or end to end in Russian. - Meetings in the pill (merged for 0.5.1): phase 1 = the four-field dock, the meeting
bar for every meeting, "Meeting saved"; phase 2 = call detection (offers, the stop suggestion, Settings → Meetings →
Call detection) and
meta.jsonwithcontextat stop. Both whole-branch reviews' fixes are in (design §10 items 47–55). Verified: core tests, both builds, code-read traces, amicopencalibration on a locked screen (listener trigger 0.05–0.21 s on take, ≤ 0.34 s on release; a bare binary resolves to no owner, so no offer). Not yet: the pill films, the calibration on an awake Mac, design §6 manual items 1–11 and the real-call list (§6 step 9), the Settings section by eye. The README pill GIFs (make-demos.sh) still show the three-field dock. - Next: the visual checks 0.5.1 shipped without (pill films, covers demo frames, the user's look, real calls); issue
#16 (a custom-command AI provider; Local server already takes any OpenAI-compatible URL); the README demo GIFs
are the user's call. Designs (local until each branch lands):
docs/plans/2026-09-24-*.md. Later: live help (spec + 24-task plan ready, deferred by the user), History as one timeline, onboarding. Dropped: trimming silence before Scribe. - Positioning (2026-09-24): merged (PR #5); GitHub About/topics applied and social preview uploaded by hand
2026-09-25. Demo GIFs: merged (PR #7). Later: a Kleoth
landing page at shck.dev/kleoth (
~/projects/shck.dev), fed frompositioning.json(marketing/README.md). - Demo films (2026-09-25, merged PR #7; no captions under the GIFs by choice): pill GIFs + meeting/viewer GIFs + screenshot, the last three from a
-KleothDemocopy of the app (isolation verified: real data/defaults/Keychain/saved state unchanged). Found, not fixed (designdocs/plans/2026-09-24-demo-mode.md§6): the Recordings empty state forces a ~900 pt History minimum height. - Open threads:
.scratch/video-recording-thread/(shipped; depth checks only).docs/CODE-REVIEW.mdstays local/uncommitted by request.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

