Graphicle: Enhancing Coding Agents with Rust-Powered Code Graphs and Memory

Graphicle is a high-performance Rust implementation of Graphify, designed to provide coding agents with a comprehensive code graph and a persistent memory system. By mapping your entire repository, it allows agents to access cited excerpts from source code, documentation, and previous decision-making sessions.

Privacy First: Graphicle operates entirely on your local machine. It requires no API keys, no accounts, and performs no telemetry.

🛠 Compatibility

Graphicle integrates seamlessly with a wide array of MCP (Model Context Protocol) clients, including:

• Claude Code & Claude Desktop
• Cursor & Codex
• VS Code

---

🚀 Getting Started

Installation

Depending on your operating system, use one of the following methods:

Via Homebrew: brew install graphicle-ai/tap/graphicle

Via Shell Script (Non-Homebrew): curl -fsSL https://github.com/graphicle-ai/graphicle/releases/latest/download/install.sh | sh

Note: Windows users should utilize WSL2 for the Linux installation (currently untested).

Initial Setup

Once installed, navigate to your project directory and run: graphicle setup

What happens during setup?

1. Indexing: The tool scans your repository to build the code graph.
2. Agent Integration: It automatically detects and connects available coding agents.
3. Session Capture: Enables the recording of agent interactions.
4. Configuration: Redirects Claude Code searches to the graph and updates AGENTS.md.
5. Automation: Installs Git hooks to ensure the graph stays synchronized with your code.

Safety Feature: Graphicle backs up every file it modifies. To revert all changes, simply run graphicle disconnect.

---

🔍 Usage & Interaction

Querying your Codebase

You can ask questions directly from your terminal: graphicle ask "where is tax added to prices?"

Example Output:

Evidence for "where is tax added to prices?" 4 excerpts · 598 of 3,000 tokens
[1] shop/pricing.py:1-7 
price_with_tax() """Prices and tax.""" 
TAX_RATE = 0.2 
def price_with_tax(price): 
    """A price with the sales tax added.""" 
    return round(price * (1 + TAX_RATE), 2)

• Default Mode: Returns raw evidence (excerpts).
• AI Mode: To get synthesized written answers, configure a model: graphicle config set model anthropic (also supports openai or ollama).

Empowering your Agent

To let your agent handle the installation, provide it with this prompt:

Install Graphicle with brew install graphicle-ai/tap/graphicle (or curl -fsSL https://github.com/graphicle-ai/graphicle/releases/latest/download/install.sh | sh), then run graphicle setup --yes in this repository and list every file it changed.

---

🗺️ Feature Roadmap & Commands

Quick Action Guide

• Give agents memory: graphicle setup
• Terminal Query: graphicle ask "how are failed requests retried?"
• Visual Exploration: graphicle open (Opens browser view of graph/memory)
• Impact Analysis: graphicle graph extract --code-only $\rightarrow$ graphicle graph affected "retry()"
• System Health: graphicle doctor
• Full Reset: graphicle disconnect

Technical Architecture

Performance Comparison

Graphicle's transition to Rust provides a massive speed increase over Graphify.

The performance gain can be expressed as: $\text{Speedup} \approx \frac{1598\text{s}}{198\text{s}} \approx 8.07\text{x faster}$

---

🧠 Deep Dive: How it Works

The Code Graph

Using tree-sitter, Graphicle parses files, functions, classes, imports, and calls without requiring an LLM.

• Analysis: Use graphicle graph to explain symbols, trace paths, or export an interactive HTML visualization.
• Dependency Tracking: graphicle graph affected "symbol" identifies everything dependent on a specific piece of code.

The Memory System

Graphicle doesn't just track code; it tracks context:

• Sources: Supports Markdown, PDF, HTML, and Office documents.
• Knowledge: Stores reviewed decisions, procedures, and historical sessions from Codex or Claude Code.
• Intelligence: graphicle context and MCP tools provide cited excerpts within a strict token budget.

Advanced Logic

• Stale Memory: Memories are linked to specific functions. If the underlying code changes, the associated memory is marked as stale.
• Documentation Linking: Mentions of code within your docs are automatically linked to their definitions via graphicle call graph.doc_links.
• Workspace Awareness: Support for multi-repo environments using graphicle context --workspace.
• Continuous Sync:
  • Pre-answer: Syncs modified files before responding.
  • Post-commit: Git hooks trigger syncs after merges, checkouts, or commits.
• Session Continuity: Every new session is initialized with the latest reviewed memories and the most recent interaction turns.