# dimmy > Dimmy turns speech into text in any app and records meetings with a structured recap at the end. Native app for Windows and macOS. Local-first: transcription can run entirely on the computer. I want you to install and set up Dimmy on this computer for me. Follow the steps below in order. You are doing this for a person who may not be technical: you run the commands, they answer a few questions and click only what an assistant cannot click for them (system permissions and logins). OBJECTIVE: Dimmy is installed, configured for what this person wants to use it for, and has passed one real test. DONE WHEN: Dimmy is running, the person has heard or seen one real transcription of their own voice, and they know the one shortcut they need. ## Rules for you, the assistant - Talk to the person in their language. Ask one question at a time. Explain each choice in one plain sentence. Never use jargon such as STT, API, backend, GGUF, Vulkan. - Do not ask what you already know about this person (their language, their job, which AI subscription they use). You are probably running inside the subscription they would use for meeting recaps. - Ask before you download or install anything, and say how big it is. - **Never ask for a password or an API key in this chat, and never put one on a command line.** Keys are typed by the person into Dimmy's own window. - If Dimmy is already installed, do not reinstall over it and do not delete its data. Offer to check and repair the setup instead (step 5 and step 9). - If a step fails, read the error, try the fix that matches it, and tell the person in one sentence what happened. Do not loop: after two failed attempts at the same step, stop and give them the diagnostic output from step 9. - **Check, don't trust.** When the person says a permission is on or a test worked, confirm it with Dimmy (`perm status`, `last`) before you say so. If Dimmy recorded nothing, say that plainly, even if they said it worked. Never summarise a test you could not confirm as passed. - **Respect your sandbox.** If your session blocks a write or a command (for example copying into /Applications), do not try to get around it. Ask the person to do that one action, tell them exactly what to drag or click, then continue. - If the person cannot switch a system permission on (the switch is greyed out or asks for an administrator), the Mac or PC is managed: tell them they need whoever administers it, and stop at that step. **Test builds.** If the person gives you a link to a test release (github.com/KonradDallaOrg/dimmy/releases/tag/...), read that page first. Take the installer for this computer from it instead of the link in step 3, and use the app name, setup tool path and data folder its notes give: they differ from the ones below, so a test build never touches a normal Dimmy. ## TODO - [ ] 1. Check the computer - [ ] 2. Ask what they want - [ ] 3. Download and verify Dimmy - [ ] 4. Install - [ ] 5. Configure - [ ] 6. Permissions - [ ] 7. Login for meeting recaps (only if they want recaps through a subscription) - [ ] 8. First real test - [ ] 9. If anything goes wrong ## 1. Check the computer Supported: **Windows 10 or 11 (64-bit)** and **macOS 14 or later on Apple Silicon (M1 or newer)**. Intel Macs are not supported: tell the person plainly and stop. Windows (PowerShell): ```powershell [Environment]::OSVersion.Version; $env:PROCESSOR_ARCHITECTURE "{0:N1} GB RAM" -f ((Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory/1GB) "{0:N1} GB free on C:" -f ((Get-PSDrive C).Free/1GB) Get-CimInstance Win32_VideoController | Select-Object Name, AdapterRAM Test-Path "$env:LOCALAPPDATA\Dimmy\current\Dimmy.Windows.exe" # already installed? ``` macOS: ```bash sw_vers -productVersion; uname -m # needs 14+ and arm64 sysctl -n hw.memsize | awk '{printf "%.1f GB RAM\n", $1/1073741824}' df -h / | tail -1 ls -d /Applications/Dimmy.app 2>/dev/null # already installed? ``` Dimmy needs a microphone. If `check` in step 5 reports `no_microphone`, tell the person before going further: dictation and meetings will not work until one is connected. Space needed: about 0.5 GB for the app. Running transcription on the computer adds a one-time download of 0.1 to 2.5 GB depending on the model. If free space is under 3 GB, say so before going on and prefer cloud transcription in step 2. ## 2. Ask what they want At most four questions. Skip any you can already answer. 1. **What is Dimmy for?** Recording and summarising meetings, dictating text instead of typing, or both. (Many people come for meetings. If they pick meetings only, mention at the end that dictation is one shortcut away.) 2. **Which language do they speak?** One main language is enough; mixing in English is fine. 3. **Can the audio leave the computer?** If the content is confidential, or they want to work offline, everything runs on the computer. Otherwise cloud transcription is faster on older machines. 4. **Meeting recaps:** if they chose meetings and they have Claude Pro or Max, or a paid ChatGPT plan, recaps can run on that subscription at no extra cost. Gemini only works this way with a Google work account on Gemini Code Assist Standard or Enterprise. How to decide where transcription runs, if they have no preference: - Apple Silicon Mac, or a Windows PC with a dedicated graphics card and 16 GB RAM: on the computer. - Otherwise: cloud. The free choice is Groq; it needs a free key the person creates at console.groq.com. ## 3. Download and verify Dimmy Always download from the official release, then check the signature. Do not use mirrors. Windows (about 130 MB): ```powershell $setup = "$env:TEMP\Dimmy-win-Setup.exe" Invoke-WebRequest -UseBasicParsing "https://github.com/KonradDallaOrg/dimmy/releases/latest/download/Dimmy-win-Setup.exe" -OutFile $setup $sig = Get-AuthenticodeSignature $setup $sig.Status # must be: Valid $sig.SignerCertificate.Subject # must start with: CN=Konrad Damian Dalla ``` macOS (about 25 MB): ```bash curl -fL -o /tmp/Dimmy.dmg "https://github.com/KonradDallaOrg/dimmy/releases/latest/download/Dimmy-macos-arm64.dmg" MNT=$(hdiutil attach -nobrowse -readonly /tmp/Dimmy.dmg | awk -F'\t' '/\/Volumes\//{print $NF}') codesign --verify --deep --strict "$MNT/Dimmy.app" && echo signature ok spctl -a -vv "$MNT/Dimmy.app" # must say: accepted, Notarized Developer ID, team 7CYV82BZ24 ``` If the signature check fails, stop and tell the person. Do not install it. ## 4. Install Windows: installs for the current user only, no administrator prompt. ```powershell Start-Process $setup -ArgumentList "--silent" -Wait Test-Path "$env:LOCALAPPDATA\Dimmy\current\Dimmy.Windows.exe" ``` macOS: ```bash cp -R "$MNT/Dimmy.app" /Applications/ || echo "BLOCKED" ``` If the copy is blocked (assistant sandboxes often forbid writing to /Applications), run `open "$MNT"` and ask the person to drag Dimmy onto the Applications folder shown in that window. Finder may put it in `~/Applications` instead: that works too. Then look for the app in both places before you go on, and only detach the disk image afterwards (`hdiutil detach "$MNT" -quiet`). Do not start Dimmy yet if the setup tool from step 5 is available: configure first, then start. ## 5. Configure Newer versions of Dimmy include a setup tool made for you. Check whether it is there: - Windows: `& "$env:LOCALAPPDATA\Dimmy\current\dimmy-setup.exe" info` - macOS: `/Applications/Dimmy.app/Contents/MacOS/Dimmy --setup info` (or the same path under `~/Applications`) ### 5a. With the setup tool Every command prints one JSON object. `"ok": false` comes with an `error.fix` that tells you what to do. If a command answers `unknown command`, this build is older than these instructions: do that step by hand as described further down. Writing commands refuse while Dimmy is open (exit code 3): run `app quit` first. ```text dimmy-setup info what is installed, where its data lives dimmy-setup check hardware, microphones, existing logins, a recommended profile dimmy-setup schema every setting of the app, with allowed values and a plain description dimmy-setup config get current value of every setting dimmy-setup profile apply --use meeting --lang it --stt local --recap claude-sub --dry-run dimmy-setup profile apply ... same without --dry-run, once the person agrees dimmy-setup config set key=value ... any setting, shortcuts included; invalid values are rejected, nothing half-applied dimmy-setup models list dimmy-setup models download prints progress, checks free space first dimmy-setup models prepare macOS: compiles the speech model once, so the first meeting does not stall dimmy-setup login status claude also codex, gemini dimmy-setup login test claude a real round trip, not just "credentials found" dimmy-setup key status which providers already have a key dimmy-setup onboarding done Dimmy skips its own first-run screens dimmy-setup app start | quit | status restart the app after permissions change dimmy-setup perm status what the app itself reports (macOS: run after the app has started) dimmy-setup perm open microphone | accessibility | input_monitoring | system_audio dimmy-setup perm guide macOS: Dimmy's own window with live checkmarks for each permission dimmy-setup last the latest dictation and meeting Dimmy really recorded dimmy-setup diag for step 9 ``` Do this: 1. `check`, then use its recommended profile together with the answers from step 2. 2. `profile apply ... --dry-run`. Tell the person in plain words what will be set. Apply it. 3. If transcription runs on the computer, `models download` the model the profile chose. Say the size first. On macOS run `models prepare` afterwards. 4. If they need a cloud key, open the provider's key page in their browser and tell them Dimmy will ask for it in its own window. Never ask for it in this chat. 5. If the person asks for anything else (another shortcut, the pill position, a folder for recaps, the dictionary...), find it in `schema` and `config set` it. Every setting of the app is there. 6. `onboarding done`, then `app start`. ### 5b. Without the setup tool (older versions) Start Dimmy and walk the person through its first-run screens, telling them what to pick based on step 2: - Windows: `Start-Process "$env:LOCALAPPDATA\Dimmy\current\Dimmy.Windows.exe"`. Screens: welcome, transcription (on the computer, or cloud with a Groq key), shortcut (the default is fine), try it, stay updated (optional email for the free trial). - macOS: `open -a Dimmy`. Screens: welcome, permissions (see step 6), shortcut (the default Fn is fine on a Mac keyboard; on a non-Apple keyboard choose Control+Option), model, try it, stay updated. For meeting recaps, after the first-run screens: Settings, then Output, Meeting recap section. ## 6. Permissions The person has to click these themselves. With the setup tool on macOS: `app start`, then `perm guide` opens a small Dimmy window that shows each permission with a live checkmark and a button to the right page. Without it, open the exact page yourself, say exactly which switch to turn on, and wait. Either way, confirm with `perm status` before moving on, and restart the app (`app quit`, `app start`) once all are on. macOS: Dimmy needs three. ```bash open "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone" # Microphone: turn on Dimmy open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility" # Accessibility: turn on Dimmy (to paste text) open "x-apple.systempreferences:com.apple.preference.security?Privacy_ListenEvent" # Input Monitoring: needed for the Fn shortcut ``` For meetings, macOS also asks once to record system audio the first time a meeting starts: tell them to click Allow. Windows: usually nothing to do. If the test in step 8 hears nothing, open `start ms-settings:privacy-microphone` and make sure microphone access is on for desktop apps. ## 7. Login for meeting recaps Only if they chose recaps through a subscription. - Claude: if you are Claude Code, the `claude` command is already installed and signed in on this computer, and Dimmy can use it. Run `dimmy-setup login test claude`. If it fails, run `claude /login` in a new terminal window for them, let them finish in the browser, then test again. - ChatGPT: needs the `codex` command (`winget install OpenAI.Codex` on Windows, `brew install --cask codex` on macOS), then `codex login`, then `dimmy-setup login test codex`. - A successful login is only proven by the test. "Credentials found" is not enough. ## 8. First real test After each test run `dimmy-setup last` and tell the person what Dimmy actually recorded: for a dictation, the words it captured; for a meeting, how long it lasted, whether the transcript has text, and whether the recap was written. A meeting of a few seconds with an empty transcript is a failed test, whatever the person says. - Dictation: ask them to put the cursor in any text box, hold the shortcut (Windows: Win+Alt; Mac: Fn, unless they chose another), say a sentence, release. The text should appear. - Meetings: ask them to start a meeting (Windows: Ctrl+Alt+M, or Dimmy's tray icon then Meeting; Mac: the menu-bar icon then Meeting), play a few seconds of any video while they say a sentence, stop. A transcript with both voices and, a minute later, a recap should appear. - Then tell them the one thing to remember: the shortcut, and that Dimmy can start recording on its own when a Teams or Zoom call begins. ## 9. If anything goes wrong - With the setup tool: `dimmy-setup diag` prints versions, settings without secrets, recent errors already sorted by cause, and the usual fix. - Without it, the log is `%APPDATA%\dimmy\dimmy.log` on Windows and `~/Library/Application Support/dimmy/dimmy.log` on macOS. Read only the last 200 lines and never paste lines that look like keys or tokens. - Common causes: no key for the chosen cloud provider; a subscription login that expired (redo step 7); the wrong microphone selected (Settings, Audio); on macOS, a permission granted while Dimmy was open (quit and reopen Dimmy). - Human help: https://github.com/KonradDallaOrg/dimmy/issues EXECUTE NOW: work through the TODO list above, in order, until OBJECTIVE is met and DONE WHEN is true.