Skip to content

README.md

Latest commit

 

History

History
284 lines (200 loc) · 9.04 KB

README.md

File metadata and controls

284 lines (200 loc) · 9.04 KB
Raw

Chirp

Chirp Logo

Chirp is a local-first CLI for recording meetings, transcribing audio, generating notes, and searching past conversations from your terminal.

Features

  • Record audio into a new note workspace
  • Stream live transcription in a Rich dashboard while recording
  • Transcribe recordings with mlx-whisper (Metal-accelerated on Apple Silicon)
  • Generate structured notes with a local MLX model (via the bundled chirpd daemon)
  • Shape notes with editable templates that are selected by a note's tags
  • Browse, edit, tag, and delete saved notes from the terminal
  • Ask questions or run keyword search across your note history, scoped by tag

Prerequisites

Chirp currently targets macOS 13.0 (Ventura) or later for audio capture. The bundled Chirp.app helper uses ScreenCaptureKit's audio-only mode, which requires macOS 13+.

  • macOS 13.0+ on Apple Silicon (M1/M2/M3/M4 or newer — chirpd runs models on MLX)
  • Python 3.11+

Note generation and retrieval run on-device through the bundled chirpd daemon (MLX) — no separate model server to install. You register a model once with chirp models add (see Setup below).

Install

pip install chirp-notes-ai

Quick start

  1. Run the guided setup:

    chirp init

  2. Record a meeting:

    chirp record --title "Team Standup" --live-transcribe

  3. Transcribe audio and generate notes:

    chirp transcribe

  4. Browse or edit saved notes:

    chirp notes
chirp notes view 1
chirp notes edit 1

  5. Search or chat across your history:

    chirp search "timeline" --since 14d
chirp ask -q "What action items did we capture?"

Command overview

Command What it does
chirp record Capture audio to a new note, optionally with live transcription
chirp transcribe [N] Process pending recordings into transcripts and notes
chirp notes List saved notes; view, edit, tag, and delete are subcommands
chirp ask Ask questions about your meetings, or open interactive chat
chirp search Run keyword or regex search across transcripts and notes
chirp init Guided setup, daemon readiness, and model recommendation
chirp about Show the animated bird and version info

Common workflows

Recording

# Timed recording
chirp record --duration 30 --title "Customer Interview"

# Auto-stop after a timeframe
chirp record --title "Sprint Planning" --timeframe 45m

# Add tags at capture time
chirp record --title "Roadmap Review" --tag roadmap --tag planning

# Pick a note template explicitly (otherwise tags select one)
chirp record --title "Daily Sync" --tag dsu --template standup

Transcription and notes

# Process all pending notes
chirp transcribe

# Process only the oldest 5 pending notes
chirp transcribe 5

# Rebuild notes from existing transcripts
chirp transcribe --regen

# Regenerate one note with a different template (persisted to its meta.toml)
chirp transcribe --regen --note daily-sync-2026-07-08 --template standup

# Override the Whisper model for one run
chirp transcribe --model medium

Notes, search, and chat

# Filter note list by tags
chirp notes --tag roadmap,planning

# Retag an existing note (then regenerate to apply a tag-linked template)
chirp notes tag daily-sync-2026-07-08 --add standup --remove roadmap

# Open interactive chat
chirp ask

# Ask with a time filter
chirp ask -q "What changed this week?" --when "last week"

# Ask or search only within tagged notes
chirp ask -q "Any blockers this week?" --tag standup
chirp search "pricing" --tag roadmap,planning

# Regex or JSON search output
chirp search "action item" --since 30d
chirp search "owner: .*" --regex --json

Note templates

Generated notes are shaped by markdown templates. Chirp ships with meeting (the default), standup, one-on-one, and brainstorm; chirp init scaffolds editable copies into ~/.chirp/templates/, and a file there with the same name replaces the built-in.

A template is YAML frontmatter plus a markdown body. The frontmatter tags list links the template to note tags: when a note carries any of those tags, the template is used automatically (the template sharing the most tags wins; --template and a template key in the note's meta.toml take precedence). Untagged or unmatched notes use meeting.

---
description: "Daily standup"
tags:
- dsu
- standup
---
## {title}

**Time:** {time}
**Duration:** {duration}

### Yesterday

{yesterday}

### Today

{today}

### Blockers

{blockers}

---

The body drives everything: each {placeholder} under a heading becomes a section the LLM extracts from the transcript and renders in that exact layout. {title}, {time}, and {duration} are built-ins. Sections render as bullet lists by default; name placeholders under a frontmatter prose: list (or call one summary/executive_summary) for paragraph output, and an action_items placeholder captures task/owner/deadline structure.

How search works

chirp ask and chirp search run on a lexical (BM25) index by default — fast, exact-term matching over your transcripts and notes, with no embedding model to download. This is the out-of-the-box behavior; nothing else is required.

Semantic search is opt-in. Enable it to also match on meaning (paraphrases, related concepts) using on-device embeddings:

# Enable: registers a small embed model, verifies chirpd can load it, then
# rebuilds the index. `chirp ask` then blends lexical and semantic hits.
chirp config --semantic

# Disable: return to lexical-only. Add --purge to also delete the vector store.
chirp config --no-semantic
chirp config --no-semantic --purge

While semantic search is off, embed models stay hidden from chirp models list (pass --all to see them) and can't be added until you enable it.

Setup details

chirp init is the recommended setup path. It checks for Apple Silicon, confirms the bundled chirpd daemon is reachable, reports whether a default chat model is registered, and checks the screen-recording permission — then helps install anything missing and offers to start chirpd at login. The bundled Chirp.app helper records system audio and microphone directly via ScreenCaptureKit; no virtual audio driver is required.

If you prefer to set things up manually on macOS (chirp itself is pip-installed; no extra system packages are required):

  1. Register a chat model (downloaded to the local HF cache, served on-device by chirpd):

    # Chat — strong quality (~4.3 GB)
chirp models add mlx-community/Qwen2.5-7B-Instruct-4bit
# ...or a smaller-footprint variant for tighter RAM:
chirp models add mlx-community/gemma-4-e2b-it-8bit

    Search works out of the box on the lexical (BM25) index — no embedding model needed. To also match on meaning, opt into semantic search; this registers the embed model and rebuilds the index for you (see How search works):

    chirp config --semantic

  2. Re-check your environment:

    chirp init --recheck

Configuration and storage

  • Config file: ~/.chirp/config.toml
  • Note templates: ~/.chirp/templates/ (see Note templates)
  • Default notes root: ~/Documents/chirp

Each note is stored in its own directory:

~/Documents/chirp/<note-slug>/
├── audio.wav
├── transcript.txt
├── notes.md
└── meta.toml

For advanced maintenance, Chirp also exposes hidden commands such as:

chirp config --list
chirp devices
chirp index --force

Troubleshooting

Recording fails immediately Grant Chirp access to Screen Recording and Microphone in System Settings → Privacy & Security, then retry. The first run will prompt for both; later denials require toggling the entries manually.

Transcription or notes generation fails Check the daemon with chirp daemon status and your registered models with chirp models list. chirp init --recheck will show what is missing; chirp models add <hf-repo> registers a model if none is set.

No notes found Run chirp transcribe first, or check chirp config --list to confirm the notes root you are using.

Model download fails with CERTIFICATE_VERIFY_FAILED / self-signed certificate in certificate chain Your network has a TLS-intercepting proxy (common on corporate machines). Chirp verifies downloads against your operating system trust store, which already trusts that proxy's root CA, so this usually resolves itself. If you still hit it, set CHIRP_DISABLE_TRUSTSTORE=1 to fall back to the bundled CA list, or point REQUESTS_CA_BUNDLE and SSL_CERT_FILE at your proxy's root CA.

Development

Contributor docs live in AGENTS.md and .docs/DEVELOPMENT.md.

Chirp Footer