{
  "markdown": "# babel-fish\n\n![babel-fish](babel.jpg)\n\n**Gives your AI coding assistant instant, accurate knowledge of every route, model, service, feature, and infrastructure element in your codebase.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Status: Production Ready](https://img.shields.io/badge/Status-Production%20Ready-green.svg)]()\n[![GitHub: TheGlitchKing/babel-fish](https://img.shields.io/badge/GitHub-TheGlitchKing%2Fbabel--fish-blue)](https://github.com/TheGlitchKing/babel-fish)\n\n> [!NOTE]\n> **Pairs with [`semantic-memory`](https://github.com/TheGlitchKing/semantic-sidekick) (formerly `semantic-sidekick`).** When both are installed, semantic-memory consumes babel-fish's auto-generated `.claude/project-map/` output as a `project-map` corpus AND reads the structured `glossary.json` babel-fish emits alongside it. That gives your AI a deterministic `translate(\"deals page\") → \"features/deal-pipeline/DealPipeline.tsx\"` MCP verb instead of relying on semantic-search-luck. See [`.documentation/api/glossary-contract.md`](./.documentation/api/glossary-contract.md) for the producer/consumer data contract and [`.documentation/quickstart/integration-with-semantic-memory.md`](./.documentation/quickstart/integration-with-semantic-memory.md) for the setup walkthrough. babel-fish standalone behavior is unchanged — semantic-memory is purely additive.\n\n---\n\n## What Does This Do?\n\nBabel 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.\n\n| Without Babel Fish | With Babel Fish |\n|-------------------|-----------------|\n| \"The deals page is at `features/deal-pipeline/DealPipeline.tsx`\" | *Already mapped* |\n| AI scans 200 files to find a route | *Loads 1 section, 5KB* |\n| Stale context after a refactor | *Pre-commit hook auto-regenerates* |\n| Re-explain your stack every session | *Vocabulary auto-loaded on start* |\n| \"Where is the background job for invoices?\" | *Checks section 08 directly* |\n\n**In short:** Your AI assistant knows your codebase cold from the first message.\n\n---\n\n## What Gets Generated\n\nA 19-section project map, split into focused files so the AI loads only what's relevant per task:\n\n| Section | What It Contains |\n|---------|-----------------|\n| `01-vocabulary.md` | Plain-English → exact file path mapping |\n| `02-service-topology.md` | How your services connect |\n| `03-environment.md` | Env vars (secrets redacted) |\n| `04-api-routes.md` | Every route with method, path, handler |\n| `05-data-models.md` | Models and their fields |\n| `06-schemas.md` | Validation schemas (Pydantic, Zod, etc.) |\n| `07-services.md` | Business logic layer |\n| `08-background-jobs.md` | Queues, workers, cron tasks |\n| `09-frontend-features.md` | Components and pages |\n| `10-tools-commands.md` | CLI commands and scripts |\n| `11-migrations.md` | Database migration history |\n| `12-import-chains.md` | Key import dependency trees |\n| `13-frontend-backend-map.md` | Which frontend calls which API |\n| `14-reverse-proxy.md` | Nginx/Caddy routing config |\n| `15-auth-config.md` | Auth strategy and guards |\n| `16-infra-profile.md` | Docker, Terraform, cloud config |\n| `17-learned-vocabulary.md` | Aliases mined from your sessions |\n| `18-dead-code.md` | Unused exports and orphaned files |\n| `19-doc-pointers.md` | Links to external docs |\n\nPlus:\n- **`PROJECT_MAP.md`** — TOC and quick routing guide (always loaded first)\n- **`project-vocabulary.md`** — auto-loaded every session\n- **`operational-runbook.md`** — gotchas and deploy procedures, grows over time\n- **Developer skill** — loads only the 2-3 sections relevant to your current task\n\n---\n\n## Install\n\n### Option 1: npx (recommended — no curl, verified by npm registry)\n\n```bash\n# Preview all changes before applying (nothing is modified)\nnpx @theglitchking/babel-fish dry-run\n\n# Install\nnpx @theglitchking/babel-fish init\n\n# Or target a specific project\nnpx @theglitchking/babel-fish init /path/to/your/project\n```\n\n---\n\n### Option 2: Curl one-liner (checksum-verified)\n\nAlways preview before running anything from the internet:\n\n```bash\n# Preview first — shows every file that will be created, nothing is modified\ncurl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash -s -- --dry-run\n\n# Install\ncurl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash\n\n# Or target a specific path\ncurl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash -s -- /path/to/your/project\n```\n\nThe remote installer verifies a SHA256 checksum against `checksums.json` before executing anything. If the file has been tampered with in transit, the installer aborts.\n\n---\n\n### Option 3: Via Glitch Kingdom Marketplace (Claude Code)\n\nRun these inside a Claude Code session:\n\n```\n/plugin marketplace add TheGlitchKing/glitch-kingdom-of-plugins\n/plugin install TheGlitchKing/babel-fish\n```\n\n> 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.\n\n---\n\n### Option 4: Clone and run\n\n```bash\ngit clone https://github.com/TheGlitchKing/babel-fish.git\nbash babel-fish/.claude/install.sh --dry-run /path/to/your/project  # preview first\nbash babel-fish/.claude/install.sh /path/to/your/project\n```\n\n---\n\n## Update management *(2.0.0+)*\n\nEvery 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).\n\n```bash\nbabel-fish status          # installed / latest / policy / hook state\nbabel-fish policy auto     # auto-update on session start\nbabel-fish policy nudge    # one-liner nudge only (default)\nbabel-fish policy off      # silent\nbabel-fish update          # update now\n```\n\nSlash-command parity: `/babel-fish:status`, `/babel-fish:policy <mode>`, `/babel-fish:update`, `/babel-fish:relink`.\n\nSee [CHANGELOG.md](./CHANGELOG.md) for the full 2.0.0 release notes, breaking-change details, and env-var opt-outs.\n\n---\n\n## What the Installer Does\n\n1. Checks for Python ≥ 3.8 (installs if missing)\n2. Detects your stack (language, framework, database, ORM, auth, infra)\n3. Runs `generate.py` → grades with `grader.py` (iterates up to 3× until 90%+ quality)\n4. Renders your developer skill and rules files\n5. Installs the pre-commit hook (auto-regenerates map on source file changes)\n6. Updates `CLAUDE.md` with a project map pointer\n7. Prints a full quality report\n\n---\n\n## Quality Grading\n\nEvery install is graded 0–100% across 7 categories. Must score ≥ 90% to pass (up to 3 iterations):\n\n| Category | Weight | What It Checks |\n|----------|--------|----------------|\n| Section completeness | 25% | All 19 sections generated |\n| Vocabulary accuracy | 20% | Entries map to real files |\n| Import chain validity | 15% | Chains trace to real modules |\n| Secret safety | 15% | No API keys, passwords, or tokens leaked |\n| Section size bounds | 10% | Each section 0.1–50KB |\n| Structural integrity | 10% | Valid markdown, working TOC links |\n| Checksum functionality | 5% | Re-run skips when nothing changed |\n\nA full report is written to `.claude/project-map/reports/install-report.md`.\n\n---\n\n## Using the Developer Skill\n\nAfter install, a skill is available:\n\n```\n/<your-project-slug>-developer\n```\n\nIt 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+.\n\n---\n\n## Keeping the Map Current\n\nThe pre-commit hook regenerates the map automatically whenever source files change. To force a manual regeneration:\n\n```bash\npython .claude/project-map/generate.py --force\n```\n\nTo re-grade the current output:\n\n```bash\npython .claude/project-map/grader.py\n```\n\n---\n\n## Learned Vocabulary\n\nEvery 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`.\n\nMining runs automatically at session start *(2.2.0+)*, detached and best-effort — it never delays or blocks a session. Only transcripts changed since the last run are read.\n\nTwo things to expect:\n\n- **Aliases land one session late.** A session's transcript isn't written until it ends, so what you say today is mined at the *next* session start.\n- **Operational sessions mine little.** The miner learns feature nouns — \"the deals page\", \"the billing workflow\". A session spent on refactoring or releases contains few of those and will correctly yield nothing. See [learned vocabulary is empty](./.documentation/troubleshooting/learned-vocabulary-empty.md).\n\nRun the miner manually:\n\n```bash\npython .claude/project-map/mine-sessions.py\n```\n\n---\n\n## Operational Runbook\n\n`.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:\n\n> \"This looks like operational knowledge worth documenting. Want me to add it to the runbook? (Y/n)\"\n\nEntries follow a simple format: symptom → cause → fix. This is the anti-drift mechanism — knowledge that can't be derived from code lives here.\n\n---\n\n## File Structure\n\n```\n.claude/\n├── project-map/\n│   ├── generate.py              # Introspection script\n│   ├── grader.py                # Quality grader\n│   ├── mine-sessions.py         # Session vocabulary miner\n│   ├── PROJECT_MAP.md           # TOC + quick routing guide\n│   ├── sections/                # 19 focused section files\n│   ├── reports/                 # Install and iteration reports\n│   ├── checksums.json           # Skip regeneration if unchanged\n│   └── learned-vocabulary.json  # Persisted session aliases\n├── rules/\n│   ├── project-vocabulary.md    # Auto-loaded every session\n│   └── operational-runbook.md   # Auto-loaded every session\n└── skills/\n    └── <project>-developer-skill/\n        └── SKILL.md\n.githooks/\n├── pre-commit                   # Auto-regenerates map on commit\n└── install.sh                   # Register hooks: bash .githooks/install.sh\n```\n\n---\n\n## Supported Stacks\n\n| Language | Frameworks |\n|----------|-----------|\n| Python | FastAPI, Django, Flask |\n| TypeScript / JavaScript | Next.js, NestJS, Express, React, Vue, Svelte |\n| Go | Gin, Echo, Chi, stdlib |\n| Java | Spring Boot |\n| Any | docker-compose, nginx, Caddy, Terraform, Prisma, SQLAlchemy, TypeORM |\n\n---\n\n## Requirements\n\n- AI coding assistant (Claude Code, Cursor, or compatible)\n- Python ≥ 3.8 (auto-installed if missing)\n- Bash\n- Optional: `pip install pyyaml` for docker-compose YAML parsing (regex fallback included)\n\n---\n\n## Commands\n\n| Command | What It Does |\n|---------|-------------|\n| `python .claude/project-map/generate.py --force` | Force-regenerate project map |\n| `python .claude/project-map/grader.py` | Grade map quality (0–100%) |\n| `python .claude/project-map/mine-sessions.py` | Mine session vocabulary |\n| `bash .githooks/install.sh` | (Re)install git hooks |\n| `bash .claude/install.sh` | Re-run full plugin installer |\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\n**Made by [TheGlitchKing](https://github.com/TheGlitchKing)**\n",
  "bytes": 11546,
  "sha": "a75419358de1a97329fb836a1c72cf3ffc9d6ece84bce913b16050892f09f426",
  "repo_slug": "theglitchking/babel-fish",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_theglitchking_babel_fish_babel_fish_3ce4e12d/readme"
}