# Getting started

akou runs on Macs with Apple silicon and macOS 14.4 or later. Every release on the [releases page](<https://github.com/GeiserX/akou/releases>) has these files:

| File | What it is |
| --- | --- |
| `akou-<version>-macos-arm64.dmg` | The app, to drag into Applications |
| `akou-<version>-macos-arm64.zip` | The same app, zipped |
| `akou-cli-<version>-darwin-arm64.tar.gz` | The `akou` command line for macOS |
| `akou-cli-<version>-linux-x64.tar.gz`, `akou-cli-<version>-linux-arm64.tar.gz`, `akou-cli-<version>-windows-x64.zip` | The command line alone, for Linux and Windows. The app for those systems is not released yet, so these can manage models, the skill and the settings, but cannot record |
| `akou-diarize-<version>-darwin-arm64.tar.gz` | The speaker-label helper on its own, for a server run from a source checkout on a Mac ([server.md](<https://geiserx.github.io/akou/server/#a-mac-as-the-server>)) |
| `SHA256SUMS` | A checksum for every file above |

To check a download, put it next to `SHA256SUMS` and run:

```
shasum -a 256 -c SHA256SUMS --ignore-missing
```

## The app

1. Open the DMG and drag akou into Applications. Or install it with Homebrew: `brew install --cask geiserx/akou/akou`, then go on from step 2.
2. Open akou. The first open takes a few seconds while the app unpacks itself in place.

### Signed and notarized

Since 0.6.1 the app and the `akou` command line are signed with a Developer ID and notarized by Apple, so macOS opens them like any other app. The `SHA256SUMS` check above confirms the file matches the published checksum; `gh attestation verify <file> -R GeiserX/akou` confirms this repository's release workflow built it.

0.6.0 and older carry an ad-hoc signature only, and macOS refuses their first open:

- On macOS 14, Control-click akou in Applications, choose Open, then Open again.
- On macOS 15 and later, open System Settings after the refusal, then Privacy &amp; Security. Near the bottom it says akou was blocked. Click Open Anyway and confirm with your password.

## The speech models

akou transcribes on your Mac, with speech models it does not ship. The first time the window opens it shows a card: **Download speech models**. It is one download into `~/Library/Application Support/akou/models` of the models your setup uses: the voice-activity model, the two speaker models (Nemotron 3 Diarization and TitaNet), and the speech models. On a Mac with a GPU and 16 GB of memory those are streaming Nemotron for the live transcript and Qwen3-ASR with its llama-server for the transcript after the call, about 3.7 GB in all. With less memory, Parakeet does both, about 3.0 GB. With `asr.diarizer` set to `embeddings`, pyannote takes Nemotron 3 Diarization's place. Parakeet stays one Download away on the Models page, and any model no setup uses can be removed there. Every file is checked against a SHA-256 written into akou's code, and a file that does not match is thrown away. Nothing else is sent anywhere.

From a terminal it is the same download, with progress per file:

```
akou models pull
```

On a machine without internet, copy the files from another machine and run `akou models import DIR`. `akou models list` shows what is there. The files and their checksums are listed in [src/main/asr/models.ts](<https://github.com/GeiserX/akou/blob/main/src/main/asr/models.ts>).

Until the models are there, akou does not start a recording: `akou start` answers `503 models_missing` and says to run `akou models pull`. If you need to record right away, `akou start --without-models` records the audio only, with no live transcript.

## Permissions

The first time you record, macOS asks two questions: may akou use the **microphone**, and may it record **system audio** (the other side of the call). Answer Allow to both. Both grants belong to the akou app, whichever way you started the recording.

**After an update, macOS should keep the grants.** macOS remembers a grant for an app by its signature, and every release since 0.6.1 carries the same Developer ID. That an update between two signed releases keeps them is still to be checked on hardware. Coming from 0.6.0 or older, which were ad-hoc signed, macOS treats the update as a different app and asks once more. If a recording after an update is silent on one side, open System Settings, then Privacy &amp; Security, then Microphone or Screen &amp; System Audio Recording, remove akou with the minus button, and record again so macOS asks.

## The command line

The app is all you need to record. The `akou` command lets you and your coding agent drive it from a terminal.

With the app installed, the quickest way is the akou menu: **Install Command-Line Tool…** links the app's own `akou` into `/usr/local/bin`. macOS asks for your password only when that folder needs it. Open a new terminal and run `akou --version`. The link follows the app, so an update updates the command too.

Without the app, use the release archive for your system. On a Mac:

```
tar -xzf akou-cli-<version>-darwin-arm64.tar.gz
mkdir -p ~/.local/bin
mv akou-cli-<version>-darwin-arm64/akou ~/.local/bin/
akou --version
```

On Linux it is the same with `linux-x64` in place of `darwin-arm64`. On Windows, unzip `akou-cli-<version>-windows-x64.zip` and move `akou.exe` into a folder on your `PATH`.

`~/.local/bin` must be on your `PATH`. The macOS binary is signed and notarized, so it runs even when a browser downloaded it. For 0.6.0 and older, which macOS refuses to run after a browser download, clear the download mark once:

```
xattr -d com.apple.quarantine ~/.local/bin/akou
```

If the app is not running, a command that needs it opens `/Applications/akou.app` (or `~/Applications/akou.app`) in the background, with no window. `akou doctor` checks the setup: settings, the token, the models, the capture helper and the local API. The capture helper ships inside the app, so doctor asks the running app about it; with the app closed that line is a warning, not a failure.

To let Claude Code or Codex start, follow and question your calls, install the akou skill or the Claude Code plugin: see [Agents and the command line](<https://geiserx.github.io/akou/agents/index.md>).

## The server

akou also runs as a self-hosted transcription server in Docker. See [Server mode](<https://geiserx.github.io/akou/server/index.md>).

## Uninstalling

1. If you turned on "Open at login", turn it off in akou's Settings first, or delete `~/Library/LaunchAgents/io.github.geiserx.akou.login.plist`.
2. Quit akou: `akou quit`, or "Quit akou" in the menu bar item.
3. Delete `/Applications/akou.app` and the `akou` command, if you installed it: `/usr/local/bin/akou` from the menu (`sudo rm /usr/local/bin/akou` if the folder is root's), or `~/.local/bin/akou` from the release archive.
4. Delete what akou keeps for itself:
5. `~/.config/akou`: settings, vocabulary and the API token;
6. `~/Library/Application Support/akou`: the speech models;
7. `~/Library/Application Support/io.github.geiserx.akou`, if it is there: the app's unpacking and update folder.
8. Your recordings are in `~/Recordings/akou` (or the folder you chose). Keep or delete them as you like.
9. To remove the grants, open System Settings, then Privacy &amp; Security, and remove akou from Microphone and from Screen &amp; System Audio Recording.

## Your first call

1. Open akou.
2. On the first screen, pick **Calls** or **Both** (Both adds dictation), and continue.
3. At **Speech models**, click **Download speech models** and wait until it says the models are ready.
4. Finish the setup, then click **Record**.
5. Allow the microphone and system audio when macOS asks.
6. Speak for ten seconds, then click **Stop**.

It worked when the sidebar lists the call and the transcript shows your words with your name from Settings.
