babel-fish

Gives your AI coding assistant instant, accurate knowledge of every route, model, service, feature, and infrastructure element in your codebase.

[!NOTE] Pairs with semantic-memory (formerly semantic-sidekick). When both are installed, semantic-memory consumes babel-fish's auto-generated .babel-fish/ output as a project-map corpus AND extracts 01-vocabulary.md into a structured glossary.json side-channel. That gives your AI a deterministic translate("deals page") → "features/deal-pipeline/DealPipeline.tsx" MCP verb instead of relying on semantic-search-luck. See docs/glossary-contract.md for the producer/consumer data contract and docs/integration-with-semantic-memory.md for the setup walkthrough. babel-fish standalone behavior is unchanged — semantic-memory is purely additive.

What Does This Do?

Babel Fish creates a translation layer between a human and an LLM. It provides a natural feature-based conversation for the human, and a direct mapping to tools, targets, models, and file paths for the AI. Babel Fish auto-generates a living project map for your codebase and teaches your AI assistant your vocabulary — so you spend zero time re-explaining your project every session.

In short: Your AI assistant knows your codebase cold from the first message.

What Gets Generated

A 19-section project map, split into focused files so the AI loads only what's relevant per task:

Plus:

• PROJECT_MAP.md — TOC and quick routing guide (always loaded first)
• project-vocabulary.md — auto-loaded every session
• operational-runbook.md — gotchas and deploy procedures, grows over time
• Developer skill — loads only the 2-3 sections relevant to your current task

Install

Option 1: npx (recommended — no curl, verified by npm registry)

# Preview all changes before applying (nothing is modified)
npx @theglitchking/babel-fish dry-run

# Install
npx @theglitchking/babel-fish init

# Or target a specific project
npx @theglitchking/babel-fish init /path/to/your/project

Option 2: Curl one-liner (checksum-verified)

Always preview before running anything from the internet:

# Preview first — shows every file that will be created, nothing is modified
curl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash -s -- --dry-run

# Install
curl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash

# Or target a specific path
curl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash -s -- /path/to/your/project

The remote installer verifies a SHA256 checksum against checksums.json before executing anything. If the file has been tampered with in transit, the installer aborts.

Option 3: Via Glitch Kingdom Marketplace (Claude Code)

Run these inside a Claude Code session:

/plugin marketplace add TheGlitchKing/glitch-kingdom-of-plugins
/plugin install TheGlitchKing/babel-fish

The first command registers the Glitch Kingdom marketplace. You only need to run it once — after that, /plugin install works for all Glitch Kingdom plugins.

Option 4: Clone and run

git clone https://github.com/TheGlitchKing/babel-fish.git
bash babel-fish/.claude/install.sh --dry-run /path/to/your/project  # preview first
bash babel-fish/.claude/install.sh /path/to/your/project

Update management (2.0.0+)

Every install ships with an update policy controlling what happens at session start when a newer version is available on npm. Default is nudge (one-liner notification, no automatic changes).

babel-fish status          # installed / latest / policy / hook state
babel-fish policy auto     # auto-update on session start
babel-fish policy nudge    # one-liner nudge only (default)
babel-fish policy off      # silent
babel-fish update          # update now

Slash-command parity: /babel-fish:status, /babel-fish:policy <mode>, /babel-fish:update, /babel-fish:relink.

See CHANGELOG.md for the full 2.0.0 release notes, breaking-change details, and env-var opt-outs.

What the Installer Does

1. Checks for Python ≥ 3.8 (installs if missing)
2. Detects your stack (language, framework, database, ORM, auth, infra)
3. Runs generate.py → grades with grader.py (iterates up to 3× until 90%+ quality)
4. Renders your developer skill and rules files
5. Installs the pre-commit hook (auto-regenerates map on source file changes)
6. Updates CLAUDE.md with a project map pointer
7. Prints a full quality report

Quality Grading

Every install is graded 0–100% across 7 categories. Must score ≥ 90% to pass (up to 3 iterations):

A full report is written to .claude/project-map/reports/install-report.md.

Using the Developer Skill

After install, a skill is available:

/<your-project-slug>-developer

It reads PROJECT_MAP.md and uses the Quick Routing table to load only the 2-3 sections relevant to your current task — typically 5–20KB of context instead of 100KB+.

Keeping the Map Current

The pre-commit hook regenerates the map automatically whenever source files change. To force a manual regeneration:

python .claude/project-map/generate.py --force

To re-grade the current output:

python .claude/project-map/grader.py

Learned Vocabulary

Every AI session is mined for vocabulary. When you say "the numbers page" and the AI opens DealAnalyzerV2.tsx, that alias is recorded with a score (frequency × recency). Aliases with a score ≥ 5 appear in 17-learned-vocabulary.md automatically.

Run the miner manually:

python .claude/project-map/mine-sessions.py

Operational Runbook

.claude/rules/operational-runbook.md is loaded every session and grows over time. When you encounter a non-obvious operational issue, the developer skill prompts:

"This looks like operational knowledge worth documenting. Want me to add it to the runbook? (Y/n)"

Entries follow a simple format: symptom → cause → fix. This is the anti-drift mechanism — knowledge that can't be derived from code lives here.

File Structure

.claude/
├── project-map/
│   ├── generate.py              # Introspection script
│   ├── grader.py                # Quality grader
│   ├── mine-sessions.py         # Session vocabulary miner
│   ├── PROJECT_MAP.md           # TOC + quick routing guide
│   ├── sections/                # 19 focused section files
│   ├── reports/                 # Install and iteration reports
│   ├── checksums.json           # Skip regeneration if unchanged
│   └── learned-vocabulary.json  # Persisted session aliases
├── rules/
│   ├── project-vocabulary.md    # Auto-loaded every session
│   └── operational-runbook.md   # Auto-loaded every session
└── skills/
    └── <project>-developer-skill/
        └── SKILL.md
.githooks/
├── pre-commit                   # Auto-regenerates map on commit
└── install.sh                   # Register hooks: bash .githooks/install.sh

Supported Stacks

Requirements

• AI coding assistant (Claude Code, Cursor, or compatible)
• Python ≥ 3.8 (auto-installed if missing)
• Bash
• Optional: pip install pyyaml for docker-compose YAML parsing (regex fallback included)

Commands

License

MIT — see LICENSE

Made by TheGlitchKing