minutes
Distill any conversation into structured knowledge.
Local-first CLI for extracting decisions, ideas, questions, action items, concepts, and key terms from any conversation transcript. Works with Claude Code sessions, meeting transcripts, plain text, and markdown. Runs entirely offline with a local LLM—nothing leaves your machine.
Quick Start
# Using uv (recommended)
uv tool install take-minutes
# Or with pip
pip install take-minutes
# Run it
minutes process my-session.jsonl
See output in ./output/:
- Markdown file with structured knowledge
- SQLite index for future searches
- Optionally: semantic embeddings for cross-session discovery
What It Extracts
| Category | Description | Example |
|---|---|---|
| Decisions | What was decided and why | "Use SQLite instead of PostgreSQL for MVP (reason: no schema migrations needed)" |
| Ideas | Concepts, suggestions, opportunities | "Implement quiet hours to prevent 2am notifications" |
| Questions | Open issues needing resolution | "What's the deployment target—Raspberry Pi or cloud?" |
| Action Items | Tasks assigned with owners | "Write health endpoint monitor (owner: ops-pragmatist, deadline: Phase 1)" |
| Concepts | Key technical or business ideas | "3-tiered autonomy model: tier 1 (audit), tier 2 (approval), tier 3 (confirmation)" |
| Terms | Abbreviations, jargon, domain terms | "EDA = Event-Driven Architecture" |
Prerequisites
minutes uses a local LLM for extraction. You need an OpenAI-compatible inference endpoint:
- Ollama: ollama.com — simple local LLM runner
- LM Studio: lmstudio.ai — GUI-based local inference
- vLLM: docs.vllm.ai — high-throughput serving engine
- OpenAI API or any OpenAI-compatible provider (set
GATEWAY_URLenv var)
For best results: use a 4B–7B model (e.g., Qwen 2.5 7B, Llama 3 8B).
Installation
Core (extraction only)
# Using uv (recommended)
uv tool install take-minutes
# Or with pip
pip install take-minutes
With semantic search
# Using uv
uv tool install "take-minutes[search]"
# Or with pip
pip install "take-minutes[search]"
One-line setup (downloads embedding model)
minutes setup
The setup command pre-downloads the embedding model (~420MB) so you aren't surprised by a mid-run download.
Usage
Process a single file
# Extract from Claude Code session
minutes process session.jsonl
# Extract from meeting transcript
minutes process meeting.txt -o ./my-minutes
# Skip deduplication check (force reprocess)
minutes process session.jsonl --no-dedup
# Verbose output for debugging
minutes process session.jsonl -v
Output:
output/YYYY-MM-DD-HH-MM-SS.md— structured knowledge in markdownoutput/minutes.db— SQLite index with full-text searchoutput/sessions.json— metadata log for easy inspection
Batch process Claude Code sessions
Scan ~/.claude/projects/ and extract from all main-thread sessions:
# Process sessions from last 2 weeks, sorted by date (newest first)
minutes batch
# Filter by project key (substring match)
minutes batch --project persistence
# Change time range (ISO date or relative: 7d, 2w, 1m)
minutes batch --since 2w --sort size
# Dry run: show what would be processed
minutes batch --dry-run --min-size 100KB
# Skip embedding generation
minutes batch --no-embed
Output:
~/.claude/minutes/{project_key}/— project-specific minutes~/.claude/minutes/{project_key}/minutes.db— indexed extractions
Search across all processed sessions
# Keyword search
minutes search "budget decision"
# Filter by category (decision, idea, question, action_item, concept, term)
minutes search "authentication" --category decision
# Vector (semantic) search
minutes search "how do we handle failures?" --mode vector
# Hybrid (keyword + vector) search
minutes search "persistence strategy" --mode hybrid --limit 5
# Search specific project
minutes search "deployment" --project persistence
Returns ranked results with scores, context, and source session.
View configuration
minutes config
minutes config --env
Shows active settings: gateway URL, model, output directory, chunking parameters.
Supported Formats
- Claude Code JSONL (native) —
~/.claude/projects/*/session.jsonl - Plain text / Markdown — conversation transcripts, meeting notes
- Coming soon: ChatGPT export, Codex CLI, Cline, Cursor
Auto-detection: process command detects format by file extension or content. Override with --format:
minutes process transcript.srt --format text
Configuration
Create a .env file in your working directory:
# LLM backend
GATEWAY_URL=http://localhost:8800/v1
GATEWAY_MODEL=qwen3-4b
# Output
OUTPUT_DIR=./minutes-output/
# Chunking (for long transcripts)
MAX_CHUNK_SIZE=12000 # tokens per chunk
CHUNK_OVERLAP=200 # token overlap between chunks
# Retry logic
MAX_RETRIES=3
# Glossary (optional YAML file for cross-referencing)
GLOSSARY_PATH=./glossary.yaml
# Prompts (optional file paths for custom extraction prompts)
SYSTEM_PROMPT=./prompts/system.txt
EXTRACTION_PROMPT=./prompts/extraction.txt
# Debug
VERBOSE=true
View active config:
minutes config
Architecture
Input (JSONL / TXT / MD)
↓
Parser (extract messages/text)
↓
Chunker (split into LLM-friendly chunks)
↓
LLM Extraction (local model extracts structured data)
↓
Deduplication (fuzzy match across chunks)
↓
SQLite Index (FTS5 full-text search)
↓
Embeddings (sentence-transformers, optional)
↓
Semantic Search (FAISS + embeddings)
How It Works
- Parse: Read input file (JSONL, plaintext, markdown) and extract dialogue or transcript text
- Chunk: Split text into overlapping chunks to fit LLM context window (~12K tokens by default)
- Extract: Send each chunk to local LLM with structured schema; collect decisions, ideas, questions, action items, concepts, terms
- Deduplicate: Fuzzy-match extracted items across chunks; keep unique items
- Index: Store in SQLite with FTS5 indexing for keyword search; optionally generate embeddings for semantic/hybrid search
Output is a single markdown file with all extractions, plus a queryable SQLite database.
Example Workflow
Scenario: Strategic planning sessions
-
Extract from session:
minutes process 2026-02-22-strategy.jsonl -o ./strategy-minutes
-
Review markdown:
cat ./strategy-minutes/2026-02-22-07-32-38.md -
Cross-reference with glossary (if provided):
# Your GLOSSARY_PATH contains definitions for SRE, NIST AI RMF, EU AI Act # Output markdown shows which extracted concepts are in glossary vs unknown
-
Batch process all recent sessions:
minutes batch --since 1m --project strategy --sort date
-
Search for related decisions across all sessions:
minutes search "idempotency" --category decision --mode hybrid
Requirements
- Python 3.10+
- Local LLM running on
GATEWAY_URL(default:http://localhost:8800/v1) - Optional: Sentence Transformers for semantic search (
pip install "take-minutes[search]")
Tips
- Cold start: First extraction takes longer due to model loading. Subsequent runs are faster.
- Large transcripts: Automatically chunks long inputs; adjust
MAX_CHUNK_SIZEif needed. - Private data: All processing is local; nothing sent to external APIs (unless you configure
GATEWAY_URLto an external provider). - Incremental indexing: Reprocessing same file is skipped unless you use
--no-dedup. - Searching: Use
--mode hybridfor best results (combines keyword + semantic search).
License
MIT
Metadata
Release files for take-minutes 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| take_minutes-0.4.0.tar.gz | 66.6 kB | With provenance | Details for take_minutes-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| take_minutes-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for take_minutes-0.4.0-py3-none-any.whl |
Total release size: 118.8 kB
Release files / take_minutes-0.4.0.tar.gz
| Download URL | take_minutes-0.4.0.tar.gz |
|---|---|
| Size | 66.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5770df85bd5a7efca53627d2b40f9541ed838af49076d5eb69d8cbc4fa19018b
|
|
BLAKE2b-256 checksum How to use checksums |
b7761d4ab1be2437cc23eda690752e126182e458d234aa961568f31cdf9190ca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 25, 2026.
Transparency logRelease files / take_minutes-0.4.0-py3-none-any.whl
| Download URL | take_minutes-0.4.0-py3-none-any.whl |
|---|---|
| Size | 52.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
db2803f32e0bebcf3f8ff2161e807a85a94c1324d878b6f90849c75801b7d049
|
|
BLAKE2b-256 checksum How to use checksums |
b0108b660dbf391e619c6ed38cb9ac107ea9e76d051e79cc0a73e700637636b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 25, 2026.
Transparency logSecurity for take-minutes 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for take_minutes-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.