repository-cognition-engine 0.1.0

Repository Cognition Engine (rce) - A Python CLI project

Repository Cognition Engine (rce)

A premium command-line engine for semantic understanding, AST analysis, Git-based coupling, and structural reasoning over code repositories. Built with tree-sitter, rich, and Claude-powered semantic synthesis.

---

Features

• Multi-language AST Parser: Analyzes symbols, functions, classes, imports, and exports using Tree-sitter.
• Git Coupling Matrix: Computes file churn, co-change coupling scores, and author activity.
• Structural Codebase Model: Automatically detects project frameworks, languages, entrypoints, and architectural layers.
• AI-Powered Synthesis: Leverages Claude to summarize codebase architecture, key workflows, conventions, and coupling insights.
• Offline Mode (--no-llm): Runs entirely locally without network requests, creating a structural index.
• Agent Context Packager: Generates high-density context blocks to feed downstream LLMs or coding agents.

---

Installation

Prerequisites

• Python 3.10+
• Git

Development Installation

1. Clone or navigate to the repository directory:

   cd Repository-Cognition-Engine
   

2. Create a virtual environment and install the package in editable mode:

   python -m venv .venv
   .venv\Scripts\activate
   pip install -e .
   

Standalone Packaging & Global Distribution

To package the CLI into standalone distribution archives (.whl and .tar.gz) or install it globally on another system or project, refer to the comprehensive Packaging & Distribution Guide.

---

Environment Setup & Configuration

You can configure the Repository Cognition Engine (rce) using standard production-grade methods: shell environments, workspace .env files, or a central configuration.

1. Global Production Config (Recommended)

You can set and manage your API keys globally across all projects using the built-in rce config manager. Settings are securely stored in your user profile folder at ~/.rce/config.json.

Step-by-Step Setup:

1. Set your Default Gemini API Key (Required for reasoning & Q&A):

   rce config set GEMINI_API_KEY "your_gemini_api_key_here"
   

2. Set your Anthropic API Key (Optional):

   rce config set ANTHROPIC_API_KEY "your_anthropic_api_key_here"
   

3. Verify the global configuration is written securely:

   rce config show
   

   Secrets will automatically be masked in the terminal output to prevent security leaks.

4. Retrieve or verify individual keys if needed:

   rce config get GEMINI_API_KEY
   

5. Delete or unset key configurations:

   rce config unset GEMINI_API_KEY
   

2. Shell Environment Variables

Production systems and CI/CD pipelines can directly export API keys into the environment:

# Windows (PowerShell)
$env:GEMINI_API_KEY="your_api_key"

# Linux / MacOS
export GEMINI_API_KEY="your_api_key"

3. Local Workspace & User Directory .env Files

rce automatically scans and loads configuration from the following .env files in order of priority:

1. Local Workspace: Current working directory (.env).
2. User Home Directory: ~/.env and ~/.rce/.env for system-wide dotenv files.

To set up a local workspace .env file, copy the provided template:

copy .env.example .env

And specify the keys:

GEMINI_API_KEY=your_gemini_api_key_here
# Optional if using Anthropic models instead
ANTHROPIC_API_KEY=your_anthropic_api_key_here

---

CLI Command Usage

Once installed, the rce command is globally available in your environment.

1. rce analyze

Orchestrates structural analyzers to build a comprehensive codebase cognitive index.

• Usage: rce analyze [PATH]
• Arguments:
  • PATH: Path to the repository directory (default: .)
• Options:
  • --force: Force a full rebuild of the index (bypassing the cache).
  • --no-llm: Skip LLM synthesis entirely (Offline / Structural-only mode, no API key required).
  • --format [human|agent|json]: Specify the output format (default: human).

Examples:

# Standard analysis with LLM synthesis
rce analyze .

# Offline/Local AST-only analysis
rce analyze . --no-llm

# Force rebuild
rce analyze . --force

# Output as agent-digestible text block
rce analyze . --format agent

---

2. rce ask

Answers conceptual and architectural questions about your codebase, leveraging AI-powered reasoning over relevant files.

• Usage: rce ask [QUESTION]
• Arguments:
  • QUESTION: The conceptual or implementation question to ask.
• Options:
  • --path PATH: Path to the repository directory (default: .)
  • --format [human|agent|json]: Specify the output format (default: human).

Example:

rce ask "How does the index builder store data?" --path .

---

3. rce similar

Ranks and displays matching codebase files based on multi-dimensional similarity metrics (shared AST patterns, imports, parent folders, and historical co-changes).

• Usage: rce similar [FILEPATH]
• Arguments:
  • FILEPATH: Path to the file to find similarities for.
• Options:
  • --path PATH: Path to the repository directory (default: .)
  • --top INTEGER: Number of top similar files to retrieve (default: 10).
  • --format [human|json]: Specify the output format (default: human).

Example:

rce similar rce/indexer/builder.py --top 5

---

4. rce impact

Evaluates direct dependencies, dependents, co-change partners, and pattern couplings to assess regression risk when modifying a target file.

• Usage: rce impact [FILEPATH]
• Arguments:
  • FILEPATH: Target file to analyze impact on.
• Options:
  • --path PATH: Path to the repository directory (default: .)
  • --format [human|json]: Specify the output format (default: human).

Example:

rce impact rce/indexer/builder.py

---

5. rce build

Gets step-by-step implementation guidance using repository context.

• Usage: rce build [TASK]
• Arguments:
  • TASK: Description of the feature or bug to implement.
• Options:
  • --path PATH: Path to the repository directory (default: .)
  • --format [human|agent]: Specify the output format (default: human).
  • --copy: Automatically copy the generated agent prompt to the clipboard.
  • --save PATH: Save the output to a specified file.

Example:

rce build "Add a new command to the CLI" --copy --save guide.txt

---

6. rce status

Displays the active indexing status, last analyzed timestamp, repo info, file count, and environment configurations.

• Usage: rce status
• Options:
  • --path PATH: Path to the repository directory (default: .)

Example:

rce status --path .

---

7. rce docs

Generates comprehensive codebase documentation from the repository index.

• Usage: rce docs
• Options:
  • --path PATH: Path to the repository directory (default: .)
  • --output-dir / --output PATH: The output directory for the generated markdown files (default: docs/rce).
  • --type [all|architecture|agent-rules|api|onboarding|antigravity]: The type of documentation to generate (default: all).

Generates the following files:

• ARCHITECTURE.md: Technical breakdown of the project structure and patterns.
• CLAUDE.md: Quickstart instructions, design goals, and command mappings.
• API.md: Comprehensive API reference & contract specifications.
• ONBOARDING.md: Dev setup, local environment guides, and dependency walkthrough.
• ANTIGRAVITY.md: Antigravity rules and environment specific agent guidelines.
• antigravity_rules.json: Machine-readable agent rules and instruction profiles.

Example:

rce docs --output docs/rce

---

What is inside .rce/?

The rce analyze command synthesizes structural data and saves it under the .rce/ directory at your project root:

• meta.json: Tracking metadata including the repository path, indexing timestamp, and rce engine version.
• index.json: The main unified index containing framework details, entry points, architecture layers, and Claude-synthesized modules, workflows, and conventions.
• symbols.json: Extracted AST symbols (functions, classes, imports, exports, detected design patterns) for every file.
• cochange.json: Historical Git co-change coupling metrics and churn vectors.

---

MCP Server Configuration

The Repository Cognition Engine includes an official Model Context Protocol (MCP) server that exposes codebase intelligence directly to MCP-enabled clients (such as Claude Desktop or Cursor).

Add the following configuration blocks to connect rce as an MCP server.

Claude Desktop

Add this to your Claude Desktop configuration (~/.config/claude/claude_desktop_config.json on macOS/Linux or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "rce": {
      "command": "rce-mcp",
      "args": []
    }
  }
}

Cursor

Add this to your Cursor MCP settings or .cursor/mcp.json:

{
  "rce": {
    "command": "rce-mcp",
    "args": []
  }
}

Exposed MCP Tools

The rce-mcp server exposes the following tools directly to LLMs and agents to query your codebase natively:

Tool Name	Arguments	Description
analyze_repository	repo_path (str, absolute), force (bool, default False)	Builds or refreshes the structural and cognitive index for a codebase.
ask_repository	question (str), repo_path (str, absolute)	Answers questions regarding architecture, conventions, or design patterns.
trace_call_chain	method_name (str), class_name (str, optional), repo_path (str, optional)	Computes and traces call/flow chains for a specific method or function.
get_implementations	interface_name (str), repo_path (str, absolute)	Finds all concrete classes or functions implementing a given interface/abstract contract.
get_api_surface	repo_path (str, absolute), domain (str, optional)	Returns all endpoints, HTTP methods, controllers, and authorization schemas.
get_feature_context	task (str), repo_path (str, absolute)	Recommends context packs (files, patterns, changes) for starting a specific implementation task.
get_conventions	repo_path (str, absolute), category (str, optional)	Retrieves conventions used in the codebase (naming, error formats, validation, structural).
find_similar	filepath (str), repo_path (str, absolute), top_n (int, default 5)	Resolves files that are structurally or AST-similar to a target file.