Let an agent do the transcribing.

AFK gives a coding agent a local command, clean streams, and a small set of rules for handling files. Install the bundled Agent Skill explicitly, then let the agent call the CLI you already use.

Copy for your agent

In a hurry? Paste this into a coding agent that can run shell commands on your Mac, and put your file's path on the last line. The steps below explain each part.

Transcribe a local recording with AFK, a Mac app that is also a command-line tool.

1. Find the command. Use `afk` if it is on PATH. Otherwise call /Applications/AFK.app/Contents/MacOS/AFK directly. Run it with --help to confirm it works.
2. Install AFK's Agent Skill with `afk install-agent-skill`, then read ~/.agents/skills/afk-transcription/SKILL.md and follow it.
3. Transcribe one file per command, with the path in quotes: afk transcribe "FILE" > "FILE.txt". The transcript is on stdout. Progress and errors are on stderr.
4. Add --srt for subtitles or --json for words with timings. For a folder, loop over the files and run one command per file.
5. If a command exits with a non-zero status, show me what it printed on stderr, and do not present a partial transcript as complete.

Video must be MP4, MOV, or M4V with an audio track. Transcription runs on this Mac. Do not send the transcript to an online service unless I ask.

The file: 

Install the bundled skill

The signed AFK app includes a short afk-transcription Agent Skill. Install it with the button on the Automation screen, or from Terminal:

$ afk install-agent-skill

The command copies the skill to ~/.agents/skills/afk-transcription. An identical copy is left alone. A different existing copy is not overwritten unless you deliberately pass --force.

AFK Automation screen showing the shell alias, a command that transcribes an MP4 into a text file, the Install Agent Skill button, and two more example commands.
The Install Agent Skill button is on the Automation screen. Click the image to open a full-size view.

Download the bundled Agent Skill (SKILL.md) →

Give the agent a bounded workflow

  1. Pass one quoted local path to afk transcribe.
  2. Keep transcript output on stdout and diagnostics on stderr.
  3. Use --json or --srt when the next step needs structured output.
  4. Use a shell loop for a folder; AFK does not provide a batch flag or MCP server.
$ afk transcribe recording.m4a > recording.txt
$ afk transcribe lesson.mp4 --srt > lesson.srt

Check what came back

The exit status says how the command went, so an agent doesn't have to guess from the text:

  • 0 means the transcript on stdout is complete.
  • 1 means something failed. On a long recording, AFK can still print the parts it could transcribe; the warning on stderr gives the missing time range, and --json lists it in an issues array. Keep that warning with the result.
  • 2 means the command was written wrong: a missing file path or an unknown flag.

Respect the input boundary

The CLI accepts AFK's supported audio inputs and video as .mp4, .mov, or .m4v with an audio track. It extracts the video's audio into a temporary directory and removes it after the command. Other video containers such as MKV, WebM, or AVI are not supported. An agent should not promise another container or send a transcript to a networked tool without an explicit instruction.

Keep local and network steps distinct

First-run model preparation may need the network. Once the model is ready, recognition and file reading run locally. A shell command or agent may choose to send stdout somewhere else; that is a separate action outside AFK's transcription path.

Troubleshooting

The agent says afk: command not found

The afk alias in ~/.zshrc exists in your own Terminal windows. An agent's shell often doesn't load it. Tell the agent to call /Applications/AFK.app/Contents/MacOS/AFK directly. The Automation screen shows the exact path for your copy of the app.

The agent doesn't pick up the skill

The skill is installed at ~/.agents/skills/afk-transcription. If your agent reads skills from a different folder, copy that folder there, or paste the prompt at the top of this page instead.

The install says a different skill already exists

AFK won't replace a copy that differs from the bundled one, in case you edited it. Review the existing copy, then run afk install-agent-skill --force if you want to replace it.

The video is MKV, WebM, or AVI

AFK reads MP4, MOV, and M4V video. Convert other containers to one of those first, then transcribe the converted file.

The command exited with status 1 but printed a transcript

Part of a long recording couldn't be transcribed. The warning on stderr gives the missing time range. Treat the result as partial.

The first run is slow or needs the internet

The first command prepares the speech model, which may need a download. After that, transcription runs on your Mac. If setup fails, see model setup and CLI problems in troubleshooting.

Agent handoff: the CLI guide owns flags, streams, and exit behavior. This page owns the skill and the workflow around it.

See the folder-loop use case →

One command your agent can run.

One payment. macOS 15 or later on Apple Silicon.