Brainstack

Brainstack Capabilities

Brainstack capabilities install useful local or worker-backed powers such as voice transcription without changing the harness surface.

What a capability is

A capability is an installable Brainstack-managed power that can run on a selected machine and be used from existing surfaces. The current reference capability is local voice transcription for Telegram voice notes.

The important part is the lifecycle:

  1. Discover the capability from CLI, Telegram, or the Mac app.
  2. Install it on the right machine.
  3. Verify it with a deterministic test.
  4. Use it without switching harnesses.
  5. Uninstall Brainstack-owned artifacts when you no longer want it.

Voice transcription

Voice lets a Telegram voice note become normal text in the same topic. The processing machine can be the control host, the Mac client, or a stronger worker. The default backend is local Whisper via Mozilla whisperfile, so voice notes do not need to go through OpenAI APIs when that backend is installed.

List available capabilities first:

brainctl capabilities list \
  --config ~/.config/brainstack/brainstack.yaml

Replace WORKER_NAME with the Brainstack machine that should run transcription.

brainctl capabilities install voice \
  --target WORKER_NAME \
  --config ~/.config/brainstack/brainstack.yaml

brainctl capabilities doctor voice \
  --target WORKER_NAME \
  --config ~/.config/brainstack/brainstack.yaml

brainctl capabilities test voice \
  --target WORKER_NAME \
  --config ~/.config/brainstack/brainstack.yaml

Reset or retest from scratch:

brainctl capabilities uninstall voice \
  --target WORKER_NAME \
  --remove-files \
  --config ~/.config/brainstack/brainstack.yaml

If you use the Telegram control surface, you can ask for the same thing in normal language from a Brainstack topic:

install voice on WORKER_NAME
install transcription on WORKER_NAME
uninstall voice on WORKER_NAME
/voice status

Brainstack should pick the target machine, check prerequisites, install or verify the transcription stack, restart the Telegram runtime when needed, and tell you how to test it with a real voice note. Long installs should show progress instead of leaving the chat looking idle.

Safety expectations

  • A capability should say what it installs and where.
  • A capability should report progress for long downloads or builds.
  • A capability should test itself before claiming success.
  • CLI, Mac app, and Telegram surfaces should call the same canonical brainctl lifecycle underneath.
  • Uninstall should remove Brainstack-owned artifacts and config, not unrelated system packages.
  • Docs should say whether processing is local, worker-backed, or API-backed.
  • Capability docs should state uninstall behavior, including what Brainstack-owned files are removed and what system packages are left alone.

Next candidates

The next high-value bundled capabilities are likely OCR/document intake and first-run knowledge import. Both fit the same pattern: pick a machine, install dependencies, verify with a sample, then feed normal text or proposal evidence into Brainstack.