amhuppert/shama-init-config

Initialize Shama Project Config

Create a local voice.json config, a voice-vocabulary.md vocabulary file, and a voice-context.md context file in the current directory, then register the project in Shama's app-level registry.toml so the app can find it. These cover the clipboard-mode baseline (Control+Option+Space); advanced options — cleanup instructions and shell-command mode (Control+Option+S) — are listed in Step 3 and can be added later via /shama-add-context.

Shama is the resident macOS voice-to-text app. You don't run it per-directory: it runs in the background and switches between projects you've registered in registry.toml, selected from its tray menu.

How Shama uses these files

• Transcription step (OpenAI) — uses voice-vocabulary.md as vocabulary hints to help the transcription model accurately recognize domain-specific words.
• Cleanup step (Claude, clipboard mode) — uses voice-context.md for project knowledge (descriptions, terminology, naming conventions). The vocabulary file is included as additional reference.

Step 1: Gather project information

Research the current project to collect:

1. Project purpose — What is being built? (1-2 sentences from README, package.json, or similar)
2. Technologies and libraries — Language, runtime, frameworks, key dependencies with their names exactly as written (e.g., "Bun" not "bun", "Commander.js" not "commander")
3. Domain terminology — Non-obvious terms, acronyms, abbreviations, or jargon found in the codebase (variable names, function names, class names, config keys that a speech transcriber might misspell)
4. Naming conventions — camelCase, PascalCase, snake_case patterns and specific examples of important identifiers
5. Key concepts — Architectural patterns, custom abstractions, or domain entities that appear frequently
6. Claude Code commands, skills, and agents — All slash commands, plugin skills, and agents available in the project. The user may reference these by name while dictating.

Sources to check (read what exists, skip what doesn't):

• README.md, package.json, Cargo.toml, pyproject.toml, or equivalent
• CLAUDE.md, .kiro/steering/product.md, .kiro/steering/tech.md
• Source file headers and type definitions for domain terminology
• Config files for tool names and conventions

For Claude Code commands, skills, and agents, scan these locations:

• .claude/commands/*.md — Project-level slash commands. Read YAML frontmatter for name and description.
• Find plugin directories by globbing for **/.claude-plugin/plugin.json (skip node_modules, dist, and other build artifact directories). For each plugin found:
  • {plugin-dir}/skills/*/SKILL.md — Plugin skills. Read YAML frontmatter for name and description.
  • {plugin-dir}/agents/**/*.md — Plugin agents. Read YAML frontmatter for name and description. Use the filename (without .md) as the agent name if no name field exists.

Step 2a: Generate voice-vocabulary.md

Write voice-vocabulary.md in the current directory: a flat list of terms, one per line, with no markdown structure, headers, or descriptions — just each bare term with its exact spelling and capitalization. Include:

• Technology and library names
• Key type names, function names, and identifiers from the codebase
• Acronyms and abbreviations
• Slash command names (e.g., /shama-init-config)
• Domain terms the transcription model might mishear or misspell

Example:

TypeScript
Zod
Bun
Commander.js
Claude Code
CLAUDE.md
ResolvedFileRef
ConfigSchema
/shama-init-config
/shama-add-context

Step 2b: Generate voice-context.md

Write voice-context.md in the current directory with the following structure:

# Voice Context

## Project

{1-2 sentence description of the project}

## Technologies

{Bulleted list of technologies, libraries, and tools with exact spelling. Include the name as it should appear in text.}

## Terminology

{Bulleted list of project-specific terms, acronyms, and jargon. Format: **Term** - brief definition. Focus on words a speech transcriber is likely to mishear or misspell.}

## Naming Conventions

{Brief note on casing conventions and important identifiers that should be preserved exactly.}

## Claude Commands & Skills

{List all slash commands, skills, and agents available in the project. Group by type (Commands, Skills, Agents). Format each as: **/{name}** - one-line description.}

Guidelines for both files:

• Focus on terms that are ambiguous when spoken aloud (e.g., "Zod" might be transcribed as "zod", "god", or "sod"); omit widely known terms (JavaScript, React, Git) unless they have unusual capitalization in the project
• List acronyms with their expansions in the context file
• Keep the context file concise — the entire file is injected into every cleanup prompt. Aim for under 80 lines across the project sections (Technologies, Terminology, Naming Conventions); the Claude Commands & Skills section may exceed this as needed

Step 3: Generate voice.json

Write voice.json in the current directory:

{
  "contextFile": "./voice-context.md",
  "vocabularyFile": "./voice-vocabulary.md"
}

This sets the context and vocabulary file paths for clipboard mode. Any keys not set here fall back to the global config at ~/.voice/voice.json, then to Shama's built-in defaults.

Additional optional keys (not scaffolded by default — add via /shama-add-context if and when needed):

• instructionsFile — formatting rules controlling how clipboard cleanup formats text (bullet style, code preservation, structural rules)
• shellContextFile, shellVocabularyFile, shellInstructionsFile — for voice-driven shell-command mode (Control+Option+S)
• claudeModel / shellClaudeModel — override the cleanup model for each mode
• maxRecordingDuration (seconds), beepEnabled, notificationEnabled — per-project scalar overrides (local wins over global)

Step 4: Register the project in Shama's registry

Shama only sees projects listed in its app-level registry. Add this project to it.

1. Locate the registry file:
   • macOS: ~/Library/Application Support/Shama/registry.toml
   • Linux: $XDG_CONFIG_HOME/shama/registry.toml (fallback ~/.config/shama/registry.toml)
2. Derive the entry fields:
   • id — a unique, stable, kebab-case identifier. Default to the project directory name (e.g., my-ai-resources).
   • name — a human-readable name shown in the tray menu (e.g., from package.json name, the repo name, or a title-cased directory name).
   • project_root — the absolute path to the current directory (Shama resolves <project_root>/voice.json). Use ~/-prefixed or absolute; ~ and env vars are expanded.
3. Read the existing registry.toml if it exists:
   • If a [[project]] entry already points at this project (same id, or a project_root/voice_json resolving here), do not add a duplicate. Tell the user it's already registered; offer to update its name if it changed. (Shama ignores duplicate ids — it keeps the first and logs a warning.)
   • If the file or its parent directory does not exist, create them (mkdir -p the parent, then create the file).
4. Append a [[project]] entry:

   [[project]]
   id = "my-ai-resources"
   name = "My AI Resources"
   project_root = "/Users/alex/github/my-ai-resources"
   

   Each entry must specify exactly one of project_root or voice_json. Use project_root here since voice.json lives at the project root. Use voice_json = "/abs/path/voice.json" instead only when the config lives elsewhere.

Shama polls registry.toml by mtime every ~5 seconds while idle, so the project appears in the tray menu within seconds — no app restart needed.

Step 5: Confirm

After creating the files and registering the project, display:

• The generated voice-vocabulary.md and voice-context.md content
• Confirmation that voice.json was created
• Confirmation that the project was registered in registry.toml (show the [[project]] entry), or that it was already registered
• A note that cleanup instructions and shell-mode files are not scaffolded — point to /shama-add-context for adding them later
• Remind the user: select this project from Shama's tray menu to make it active, then record with Control+Option+Space