🚀 Repo Intelligence

A lightweight context-economy tooling hub for AI-assisted software development. This repository serves as a canonical distribution center and shared configuration point for context compression, code reuse guidance, and token optimization tools.

---

💡 Key Tools Distributed

1. headroom — Compresses large tool outputs, build logs, and git diffs before they enter model context (typically yielding 60–90% token savings).
2. ponytail-mcp — A structured code-reuse guidance tool (evaluates YAGNI $\rightarrow$ existing repo code $\rightarrow$ standard library $\rightarrow$ dependencies $\rightarrow$ one-liner $\rightarrow$ custom code).
3. rtk (Rust Token Killer) — A high-performance CLI utility that prefixes and compresses verbose shell command output for token-efficient agent interactions.

---

🎯 Purpose & Architecture

This repository operates as a central tooling hub across multiple projects:

• Shared Disk Installation: Hosts .data/ as a central, gitignored staging area for tool binaries and dependencies, avoiding gigabytes of duplicate local installs.
• Canonical .mcp.json: Offers a ready-to-use Model Context Protocol configuration that sister projects or IDEs can copy or reference directly.

Note

There is no runnable web app in this repository. It is a configuration, installation, and coordination hub for agent context-economy tooling.

---

⚡ Quick Start

1. Prerequisites

• Node.js (v18.0.0 or higher)
• Git
• An MCP-compatible agent or IDE (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code with Continue or Roo Code)

2. Installation

# 1. Clone the repository
git clone https://github.com/atifkhan-583/Repo-Intelligence.git
cd Repo-Intelligence

# 2. Run the automated setup script
npm run setup

The npm run setup script automatically:

• Creates required directory structures in .data/
• Validates .mcp.json configuration
• Clones and builds ponytail-mcp if missing
• Checks availability of headroom and rtk executables

3. Connect to Your AI Tool / IDE

# Copy canonical configuration into your workspace
cp .mcp.json /path/to/your/project/

For detailed setup instructions across Claude Desktop, Cursor, Windsurf, Claude Code CLI, and VS Code, see the Friends & Team Onboarding Guide (SHARING_GUIDE.md).

---

🛠️ Tool Usage Guide

1. Ponytail (Code-Reuse Guidance)

Invoke Ponytail to evaluate whether writing new code is truly necessary:

• MCP Prompt: ponytail
• MCP Tool: ponytail_instructions

Question Hierarchy:

1. Does this need to exist? (YAGNI principle)
2. Can we reuse existing code in this codebase?
3. Is this available in the language standard library?
4. Should this be an established third-party dependency?
5. Can this be implemented cleanly in a single line?
6. Only then: Write custom code.

2. Headroom (Context Compression)

Compress large CLI outputs or diffs before feeding them to an AI model:

# One-off command compression
headroom wrap claude -- git diff
headroom wrap claude -- grep pattern .

# Start local proxy server (optional, manual start)
headroom proxy --port 8787

3. RTK (Rust Token Killer)

Prefix shell commands to strip noise and compress output:

# Wraps common CLI commands for reduced token footprint
rtk git status
rtk pytest --verbose
rtk grep "function" src/

# Analytics & Diagnostics
rtk gain              # Display total token savings analytics
rtk gain --history    # View historical command usage breakdown
rtk discover          # Analyze agent history for optimization opportunities

---

📁 Repository Structure

repo-intelligence/
├── .data/                      # Central tool installation & caches (gitignored)
│   ├── headroom/               # Headroom binaries & workspace cache
│   ├── ponytail-tool/          # ponytail-mcp source & modules
│   └── rtk/                    # rtk binary & configuration rules
├── .mcp.json                   # Canonical MCP server configuration
├── setup.js                    # Cross-platform automated setup script
├── package.json                # Node dependencies & npm scripts
├── START_HERE.txt              # Quick documentation navigation index
├── README.md                   # Project overview & quick start
├── SHARING_GUIDE.md            # Onboarding & IDE integration guide
├── CLAUDE.md                   # Developer & agent integration notes
├── ARCHITECTURE.md             # In-depth system design & data flows
├── TECHNICAL_DEBT.md           # Known limitations & improvement backlog
├── CHANGELOG.md                # Release notes & migration guides
└── ADR/                        # Architecture Decision Records
    ├── README.md               # ADR process & index
    ├── 0001-retire-graphify-mcp.md
    └── 0002-canonical-mcp-distribution.md

---

⚙️ Environment Configuration

The following environment variables control local tool behavior (configured in .mcp.json):

Variable	Description	Default Path / Value
HEADROOM_WORKSPACE_DIR	Directory for Headroom cached output	./.data/headroom/workspace
HF_HOME	Hugging Face cache location	./.data/headroom/hf-cache
XDG_CONFIG_HOME	Ponytail configuration path	./.data/ponytail-tool/config
PONYTAIL_DEFAULT_MODE	Ponytail analysis intensity (full or lite)	full

---

❓ Troubleshooting

command not found: rtk

• Verify RTK installation: where rtk (Windows) or which rtk (Linux/macOS).
• Ensure .data/rtk/bin/ is included in your system PATH.

Headroom Proxy Not Running

• Headroom proxy does not autostart in background. Start manually when desired: headroom proxy --port 8787.
• MCP stdio integration works independently of proxy mode.

Ponytail MCP Server Not Responding

• Verify Node.js version ($\ge 18.0.0$): node --version.
• Confirm .data/ponytail-tool/repo/ponytail-mcp/index.js exists.
• Re-run setup: npm run setup.

---

📖 Documentation Links

• 🚀 Sharing & Onboarding Guide
• 📘 System Architecture
• 📋 Technical Debt & Backlog
• 📜 Changelog
• 📑 Architecture Decision Records

---

📄 License

This repository is licensed under the MIT License.