prompt-grapher 1.4.3

Generate repository-specific Cursor rules and AGENTS.md files from Graphify dependency graphs.

PromptGrapher

PromptGrapher turns a Graphify dependency graph into repository-specific Cursor rules. It is designed to work against arbitrary projects, not just a single language or framework.

What It Does

1. Reads graphify-out/graph.json or graphify-out/manifest.json.
2. Infers the project's primary languages, framework hints, architecture style, naming patterns, hotspots, entrypoints, and test presence.
3. Sends that summary to an OpenAI-compatible model.
4. Writes .cursor/rules/project-rules.mdc for Cursor and AGENTS.md as a root-level backup/source-of-truth.

Requirements

• Python 3.10+
• No separate Graphify install step. graphifyy is installed as a dependency.
• An OpenAI-compatible API key and model name

Installation

PromptGrapher is a CLI tool. End users do not need to create or activate a virtual environment just to run it.

Recommended global install with pipx:

pipx install prompt-grapher

Alternative global install with pip:

python -m pip install --upgrade prompt-grapher

After installation, verify the command is available:

prompt-grapher --help

Windows note

If prompt-grapher is not recognized after a global pip install, the Python Scripts directory is likely not on your PATH.

You can inspect the user scripts path with:

python -m site --user-base

Then ensure the corresponding Scripts folder is on PATH. Example:

%APPDATA%\Python\Python311\Scripts

Using pipx usually avoids this friction because it manages CLI exposure for you.

Configuration

From the root of the project you want to analyze, create a .env file:

prompt-grapher init

Then set:

• AI_API_KEY
• AI_MODEL_NAME
• AI_BASE_URL if you are using a non-default OpenAI-compatible endpoint such as Groq, OpenRouter, or Ollama

PromptGrapher also falls back to OPENAI_API_KEY, GROQ_API_KEY, and OPENROUTER_API_KEY.

Important: prompt-grapher init writes the .env file into your current working directory, so run it inside the repository you want to analyze.

Usage

From the project root, analyze the current repository and auto-run Graphify when needed:

prompt-grapher analyze .

Re-running prompt-grapher analyze refreshes the Graphify artifact by default before regenerating rules, so architecture and module changes are picked up automatically.

If you intentionally want to reuse the current graphify-out contents without refreshing them, use:

prompt-grapher analyze /path/to/project --reuse-graph

By default, PromptGrapher bootstraps Graphify with a code-only graph build that does not require a second LLM provider:

python -m graphify update /path/to/project --no-cluster

This mode is enough for PromptGrapher's architecture heuristics and works well for PyPI installs.

If you explicitly want Graphify's semantic extraction path, switch strategies:

prompt-grapher analyze /path/to/project --graphify-strategy semantic --graphify-backend openai --graphify-model gpt-4.1-mini

Semantic extraction requires a Graphify-supported backend and its API key.

Reuse an existing Graphify artifact:

prompt-grapher analyze /path/to/project --graph-input /path/to/project/graphify-out/graph.json

Override the model or output filename:

prompt-grapher analyze /path/to/project --model gpt-4.1-mini --output-file .cursor/rules/project-rules.mdc --agents-file AGENTS.md

Quick Start

pipx install prompt-grapher
cd /path/to/project
prompt-grapher init
# fill AI_API_KEY and AI_MODEL_NAME in .env
prompt-grapher analyze .

Development Setup

Use a virtual environment only if you are developing PromptGrapher locally:

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .[dev]

On Windows PowerShell:

.venv\Scripts\Activate.ps1
pip install -e .[dev]

Local Smoke Tests

pytest