.-""""-.
          .'  .--.  '.
         /   /_  _\   \
        |   (o)(o)    |
        |   / __ \    |   LiBrainian
         \  \____/   /    codebase brain for agents
          '._`--`_.'
             /||\
            /_||_\

Overview

LiBrainian is a codebase intelligence tool for coding agents and developers. It indexes a repository, builds structural and semantic context, and answers questions with ranked files, evidence, and explicit health signals.

Use it when you want a better first pass than grep alone, but still want answers you can inspect and debug.

Core outcomes:

• Faster orientation in unfamiliar codebases
• Better refactor and blast-radius planning
• Better retrieval than plain grep or naive vector search
• More honest failure and freshness reporting than "works until it doesn't"

Installation

npm install librainian

CLI binaries:

• librainian (primary)
• librarian (compatibility alias)

From a GitHub source checkout, build before running the CLI:

npm install
npm run build

Recommended Path Today

If you are new to LiBrainian, start with the CLI first. It is the most direct way to verify that indexing, retrieval, and diagnostics are healthy in your workspace.

Requirements And Modes

• Node.js 18+
• npm 9+
• A repository you want to index
• Provider API keys are optional:
  • without keys, LiBrainian still supports indexing, repo maps, structural retrieval, and diagnostics
  • with keys, queries can use richer synthesis and provider-backed ranking paths
• Local-only modes:
  • --offline disables remote provider calls
  • --local-only forces fully local behavior

Healthy first-run signs:

• quickstart finishes without bootstrap failure
• query returns a summary, ranked files, and confidence metadata
• status and doctor agree on workspace state

If the workspace is stale or partially indexed, prefer fixing that first with librainian doctor or librainian bootstrap --force --mode fast.

Quick Start

This is the recommended first-run path:

# 1) Build an index and repair obvious setup problems
npx librainian quickstart

# 2) Ask a real repo question
npx librainian query "What are the core modules and how do they connect?"

# 3) Inspect readiness and diagnostics
npx librainian status --json
npx librainian doctor --json

Healthy output includes:

• a non-empty answer or summary
• relevant file paths
• confidence or quality metadata
• no contradiction between status and doctor

More guided onboarding:

• Start Here
• Documentation Index
• MCP Setup

MCP (Recommended Agent Integration)

For Claude Code, Cursor, Windsurf, VS Code, or Gemini CLI:

npx librainian mcp --print-config

Then follow the client-specific guide in docs/mcp-setup.md.

Recommended MCP flow:

1. Run quickstart in the target repo first.
2. Confirm status or doctor is healthy.
3. Register the MCP server with your client.
4. Use query, get_context_pack, find_symbol, and find_usages as the default tool path.

Source Checkout Workflows

Contributor-only validation, dogfood, and release scripts live in a source checkout. They are not part of the shipped npm package contract.

Use CONTRIBUTING.md for contributor setup, maintainer validation, and release qualification.

Programmatic (Node / TypeScript)

import { initializeLibrarian } from 'librainian';

const session = await initializeLibrarian(process.cwd());
const context = await session.query('Add request-id tracing to API handlers');

console.log(context.summary);
console.log(context.relatedFiles);
console.log(context.confidence);

Compatibility API:

import { initializeLibrarian } from 'librainian';

const session = await initializeLibrarian(process.cwd());
const result = await session.query('Explain the deployment pipeline');

Integration Decision Tree

Choose the path that matches your runtime:

• MCP-compatible IDE/client (Claude Code, Cursor, Windsurf, Cline, Gemini CLI)
  • docs/integrations/mcp.md
• Shell automation or CI/CD
  • docs/integrations/cli.md
• Node / TypeScript application code
  • import from librainian

Recommended integration docs:

• Universal integration guide
• CLI integration guide
• MCP integration guide

Preview adapter notes remain in the GitHub source tree, but they are not part of the shipped npm surface for the first public release.

Why LiBrainian

What You Get From query(...)

• Summarized answer for the current intent
• Relevant files and pack IDs
• Confidence score and uncertainty metadata
• Evidence anchors for auditability
• Context suitable for downstream planning/edit loops

Language Coverage

Built-in parsers and extraction paths cover major ecosystems, including:

• TypeScript / JavaScript / TSX / JSX
• Python, Go, Rust, Java, C/C++, C#
• Ruby, PHP, Kotlin, Swift, Dart, Scala, Lua
• SQL, JSON, YAML, Bash, CSS, HTML

LiBrainian auto-detects what is present and indexes only what is available in the workspace.

Performance Characteristics

LiBrainian tracks explicit SLA targets for query latency, indexing throughput, and memory budgets.

• Query latency target: p50 < 500ms, p95 < 2000ms, p99 < 5000ms
• Incremental indexing target: 10 changed files < 10s
• Runtime memory target: < 512MB RSS

Maintainer-only performance diagnostics remain available in a source checkout, but they are not part of the first public CLI surface.

SLA reference:

• https://github.com/nateschmiedehaus/LiBrainian/blob/main/docs/performance-sla.md

MCP Tool Trigger Compliance

LiBrainian ships an explicit tool-trigger compliance gate for MCP descriptions.

• Test: src/mcp/__tests__/tool_triggering_compliance.test.ts
• Method: baseline (tool name only) vs treatment (tool name + description)
• Coverage: all core MCP tools, 5 natural-language prompt variants per tool

Current CI pass criteria:

• Overall treatment compliance >= 70%
• Treatment must be >= baseline compliance
• At least 5 tools must each score >= 70% treatment compliance

Run locally:

npm test -- --run src/mcp/__tests__/tool_triggering_compliance.test.ts

CLI Command Map

# Day 0 / onboarding
npx librainian quickstart
npx librainian bootstrap --mode fast
npx librainian uninstall --dry-run
npx librainian doctor --heal
npx librainian check-providers --json

# Day 1 / normal work
npx librainian query "How is auth wired across API and middleware?"
npx librainian status
npx librainian index --force --incremental
npx librainian repo-map --json

Editing Experience (Contributor Loop)

If you are working from a source checkout, follow the contributor loop in CONTRIBUTING.md. The shipped package supports runtime usage; contributor validation and release qualification remain source-checkout workflows.

CI / Non-Interactive Mode

LiBrainian now auto-detects CI/non-interactive runtime when:

• CI=true or GITHUB_ACTIONS=true
• stdout/stderr is not a TTY
• --ci is passed explicitly

In non-interactive mode, LiBrainian automatically:

• disables progress UI
• disables ANSI color output
• assumes non-interactive confirmations (--yes behavior)

Useful global flags:

npx librainian status --json --ci --quiet
npx librainian bootstrap --mode fast --yes --no-progress --no-color

GitHub Actions example:

- name: Check index freshness (machine-readable)
  run: npx librainian status --json --quiet | jq -e '.freshness.staleFiles == 0 and .freshness.missingFiles == 0'

- name: Refresh index non-interactively
  run: npx librainian index --force --incremental --yes --quiet

- name: Run health diagnostics
  run: npx librainian doctor --json --quiet | jq -e '.summary.status != "ERROR"'

Pre-Commit Hook Integration

LiBrainian supports staged-file incremental indexing for commit-time freshness:

# index only staged files
npx librainian index --force --staged

# index explicit changed files (lint-staged style)
npx librainian index --force src/api/query.ts src/cli/index.ts

Built-in integration options:

• lint-staged (already configured in package.json): runs librainian index --force --staged with staged filenames
• lefthook (already configured in lefthook.yml): runs librainian index --force --staged {staged_files}
• Python pre-commit users: use the repo-level .pre-commit-hooks.yaml hook librainian-update-staged

These hook integrations are best-effort and non-blocking for known setup failures (for example, repo not bootstrapped yet).

Development and Validation

Development and release validation commands are intentionally documented in the source-checkout contributor guide, not as part of the runtime package contract.

• Contributor setup and local validation: CONTRIBUTING.md
• Package-shipped runtime docs: docs/START_HERE.md

GitHub Action (CI Index Refresh)

Use the first-party composite action to restore cache, run incremental index refresh, and optionally upload index artifacts:

steps:
  - uses: actions/checkout@v4
  - name: Index codebase with LiBrainian
    uses: nateschmiedehaus/LiBrainian/.github/actions/librainian@main
    with:
      workspace-root: ${{ github.workspace }}
      cache-key: librainian-${{ runner.os }}-${{ hashFiles('**/*.ts', '**/*.js', 'package-lock.json') }}
      restore-keys: |
        librainian-${{ runner.os }}-
      upload-artifact: true
      artifact-name: librainian-index

The composite action is published as part of the repository contract; maintainer-only release validation for it happens outside the public Actions surface.

Release Provenance

Public runtime trust surfaces:

• npx librainian status --json includes provenance and readiness summaries
• npx librainian doctor --json is the supported public diagnostic surface

Publish provenance checks, tagged releases, and strict qualification remain maintainer-only source-checkout workflows documented in CONTRIBUTING.md.

Examples

Examples are GitHub-only source references, not part of the published npm tarball:

• https://github.com/nateschmiedehaus/LiBrainian/blob/main/examples/quickstart_programmatic.ts
• https://github.com/nateschmiedehaus/LiBrainian/blob/main/examples/agentic_task_loop.ts
• https://github.com/nateschmiedehaus/LiBrainian/blob/main/examples/feedback_loop_example.ts

Documentation Map

• Fast onboarding: docs/START_HERE.md
• Docs index: docs/README.md
• Core docs (GitHub/source checkout): docs/librarian/README.md
• Milestone brief (GitHub/source checkout): docs/librarian/MILESTONE_BRIEF.md
• Universal integration guide: docs/integrations/README.md
• MCP setup: docs/mcp-setup.md
• MCP design principles: docs/mcp-design-principles.md
• Package-shipped docs: docs/START_HERE.md, docs/README.md, docs/mcp-setup.md, docs/mcp-design-principles.md, docs/integrations/README.md, docs/integrations/cli.md, docs/integrations/mcp.md
• GitHub-only deep reference: https://github.com/nateschmiedehaus/LiBrainian/tree/main/docs/librarian
• Architecture notes: https://github.com/nateschmiedehaus/LiBrainian/blob/main/ARCHITECTURE.md
• Contribution workflow: https://github.com/nateschmiedehaus/LiBrainian/blob/main/CONTRIBUTING.md
• Troubleshooting and health checks: https://github.com/nateschmiedehaus/LiBrainian/blob/main/docs/CRASH_DIAGNOSIS.md

Support and Feedback

• Usage questions: GitHub Discussions
• Bugs: GitHub Issues
• Security reports: Security Advisories

Community Standards

• Code of Conduct
• Security Policy
• Security Threat Model
• Contributing Guide

Roadmap Focus

• Public-release doc and help consistency
• Stronger query/result trust for first-run dogfooding
• Clearer separation of public surface vs maintainer-only workflows
• Continued UX improvements for CLI and npm onboarding

License

MIT License — see LICENSE.