Transcript App Skill

Work with audio recordings from the Transcript App. Regenerate transcripts, search by tags, and manage recording sessions.

Important: All script commands (npx tsx ...) must be run from the scripts/ directory of this skill. If node_modules/ is missing, run npm install first. If a script fails with an API key error, check for GEMINI_API_KEY in scripts/.env.

Recording Structure

Recordings are stored in ~/Documents/Transcript-App/ organized by date:

~/Documents/Transcript-App/
└── YYYY/MM/DD/HH-mm-ss/
    ├── recording.m4a   # Original audio (.m4a for new, .wav for old recordings)
    ├── summary.md      # AI-generated summary
    ├── transcript.md   # Verbatim transcript (optional)
    ├── metadata.json   # Processing metadata (includes linked calendar event)
    └── tags.txt        # Tags, one per line

Calendar Event Linking

When Auto-link is enabled, recordings are automatically linked to Google Calendar events. The metadata.json includes a calendarEvent object with eventId, title, startDate, endDate, attendees, and linkMethod. See ../../references/file-formats.md for the full schema.

Glossary / Vocabulary

An optional global file ~/Documents/Transcript-App/glossary.txt (not per-session — shared across all recordings) improves spelling of names, companies, and domain-specific terms. One term per line, lines starting with # are comments. Both regenerate.ts and the macOS app read it automatically and inject a <vocabulary> section into the Gemini prompt. If the file doesn’t exist or is empty, nothing is injected. See ../../references/file-formats.md for format details.

Tagging Recordings

When asked to tag a recording session:

1. Learn existing patterns first: Check existing tags to understand the user’s tagging conventions

   grep -rh "" ~/Documents/Transcript-App/**/tags.txt 2>/dev/null | sort | uniq -c | sort -rn
   

2. Understand the content:

   • Read summary.md to understand the meeting content
   • If more context is needed, read transcript.md (if it exists)

3. Check for similar existing tags: Before suggesting a new tag, search if a similar one exists to maintain consistency:

   # Example: before suggesting "bausch and lomb", check existing tags
   grep -rhi "bausch" ~/Documents/Transcript-App/**/tags.txt 2>/dev/null | sort -u
   

   If “Bausch & Lomb” already exists, use that exact format instead of creating a new variation.

4. Suggest tags and ask the user: Present tag suggestions based on:

   • Existing tags with same/similar names (use exact existing format)
   • Patterns from existing tags
   • Meeting type: meeting, call, interview, brainstorm, standup
   • Participants/clients: client-name, team-name
   • Projects: project-name
   • Priority: urgent, important, followup-required
   • Topics discussed: extract key themes

5. Wait for user confirmation before writing any tags

6. Write tags only after user approval:

   echo -e "tag1\ntag2\ntag3" > ~/Documents/Transcript-App/YYYY/MM/DD/HH-mm-ss/tags.txt
   

Common Tasks

Browse Recent Recordings

To find recent recordings, use native tools (Glob, Read) rather than bash:

• List today’s sessions — Use the Glob tool with pattern ~/Documents/Transcript-App/YYYY/MM/DD/*/metadata.json (substitute the current date)
• List sessions for a month — Use the Glob tool with pattern ~/Documents/Transcript-App/YYYY/MM/*/*/metadata.json
• Read a session’s summary — Use the Read tool on ~/Documents/Transcript-App/YYYY/MM/DD/HH-mm-ss/summary.md

List Sessions for a Date

npx tsx scripts/regenerate.ts --list 2026/02/03

Regenerate a Transcript

# Default (detailed summary)
npx tsx scripts/regenerate.ts 2026/02/03/10-42-34

# With verbatim transcript
npx tsx scripts/regenerate.ts 2026/02/03/10-42-34 --with-transcript

# Simple summary
npx tsx scripts/regenerate.ts 2026/02/03/10-42-34 --template simple

# Transcript only (with timestamps and speakers)
npx tsx scripts/regenerate.ts 2026/02/03/10-42-34 --template transcript

Ask Questions About a Recording

# Ask a direct question to the audio
npx tsx scripts/ask.ts 2026/02/03/10-42-34 "What was the main topic?"

# Get specific information
npx tsx scripts/ask.ts 2026/02/03/10-42-34 "Who were the participants?"
npx tsx scripts/ask.ts 2026/02/03/10-42-34 "What action items were mentioned?"

# Translate or summarize
npx tsx scripts/ask.ts 2026/02/03/10-42-34 "Summarize in Spanish"

Search by Tags

Prefer using the Grep tool directly over bash commands:

• Find sessions with a specific tag — Use the Grep tool with the tag as pattern, path=~/Documents/Transcript-App, glob="**/tags.txt"
• Count sessions by tag (bash needed for aggregation):

  grep -rh "" ~/Documents/Transcript-App/**/tags.txt 2>/dev/null | sort | uniq -c | sort -rn
  

Search Content in Summaries

• Find sessions mentioning a topic — Use the Grep tool with the topic as pattern, path=~/Documents/Transcript-App, glob="**/summary.md"
• Search with context — Same as above, with output_mode="content" and context=2

Search by Calendar Event

• Find recordings by meeting title — Use the Grep tool with the title as pattern, path=~/Documents/Transcript-App, glob="**/metadata.json"
• Find recordings with an attendee — Same approach with the attendee’s email as pattern

Templates

All templates live in ~/Documents/Transcript-App/prompts.json. The file looks like:

{
  "active": "detailed",
  "transcript": "...",
  "simple": "...",
  "detailed": "...",
  "transcriptSuffix": "..."
}

To customize or add a template: add a new key with the prompt text as the value (e.g. "my-custom": "Your prompt here..."). It will appear as a new option automatically.

To change which template is used by default: set the active key to the name of the desired template (e.g. "active": "my-custom"). Both the macOS app and regenerate.ts read this value.

The --template flag on regenerate.ts overrides the file’s active value for that run.

Setup

Before using the regenerate script:

1. Navigate to the skill’s scripts folder
2. Install dependencies: npm install
3. Set API key via environment variable or .env file:

   export GEMINI_API_KEY="your-key-here"
   # Or create scripts/.env with: GEMINI_API_KEY=your-key-here
   

File Format Reference

For detailed file format specifications, see ../../references/file-formats.md.

Automation Watcher

The watcher monitors ~/Documents/Transcript-App/ for new metadata.json files and executes configurable rules automatically.

Quick Start

cd scripts && npm install

# Edit rules
vim scripts/rules.yaml

# Test with an existing session
npx tsx scripts/watcher.ts --process 2026/02/05/10-04-00

# Start watcher in foreground
npx tsx scripts/watcher.ts

# Check status
npx tsx scripts/watcher.ts --status

Configuring Rules (scripts/rules.yaml)

Rules match against metadata.json fields and execute actions:

rules:
  - name: "Log all recordings"
    action:
      type: shell
      command: "echo '{{recordedAt}} — {{sessionPath}}' >> /tmp/transcript-app.log"

  - name: "Webhook for long meetings"
    match:
      durationSeconds: { gte: 60 }
    action:
      type: webhook
      url: "https://my-api.com/meetings"
      method: POST
      body:
        sessionPath: "{{sessionPath}}"
        title: "{{calendarEvent.title}}"

  - name: "Custom script for specific account"
    match:
      calendarEvent.accountEmail: "user@example.com"
    action:
      type: script
      path: "/path/to/my-processor.ts"

Matching:

• Simple equality: field: "value"
• Numeric operators: { gte: 60 }, { lte: 300 }, { gt: 0 }, { lt: 100 }
• Dot notation for nested fields: calendarEvent.accountEmail
• No match clause = runs for every recording

Template variables: Use {{field}} syntax — {{sessionPath}}, {{recordedAt}}, {{calendarEvent.title}}, etc.

Action types:

Testing a Script Against a Session

Run any .ts script directly against a recording session, without needing rules in YAML:

npx tsx scripts/watcher.ts --run-script ./my-processor.ts 2026/02/05/11-20-04

The script receives --session <path> and --metadata <json> as arguments. Example script:

const args = process.argv.slice(2);
const sessionIdx = args.indexOf("--session");
const metadataIdx = args.indexOf("--metadata");
const session = args[sessionIdx + 1];
const metadata = JSON.parse(args[metadataIdx + 1]);

console.log(`Processing ${session}: ${metadata.calendarEvent?.title ?? "no event"}`);

Watcher CLI

# Start watcher (foreground, logs to console)
npx tsx scripts/watcher.ts

# Process a session via rules (for testing/replay)
npx tsx scripts/watcher.ts --process 2026/02/05/10-04-00

# Force re-process (ignores idempotency)
npx tsx scripts/watcher.ts --process 2026/02/05/10-04-00 --reprocess

# Run a script directly against a session (no rules needed)
npx tsx scripts/watcher.ts --run-script ./my-script.ts 2026/02/05/10-04-00

# Show status (processed sessions, active rules, service state)
npx tsx scripts/watcher.ts --status

# Install as macOS launchd service (starts on login)
npx tsx scripts/watcher.ts --install

# Uninstall service
npx tsx scripts/watcher.ts --uninstall

# Tail service logs
npx tsx scripts/watcher.ts --logs

Idempotency

Processed sessions are tracked in scripts/state.json. A session is only processed once unless --reprocess is used.

Scripts

• scripts/regenerate.ts – Regenerate transcripts with different templates
• scripts/ask.ts – Ask questions directly to an audio recording
• scripts/watcher.ts – Rule-based automation watcher for new recordings
• scripts/rules-engine.ts – Matching and action execution engine
• scripts/rules.yaml – User-configurable automation rules
• scripts/prompts.json – Prompt templates for different output formats