### Clone Repository and Install Dependencies

Source: https://github.com/cyanheads/repo-map/blob/main/README.md

Clone the repo-map repository and install its dependencies using Poetry. This is the initial setup step.

```bash
git clone https://github.com/cyanheads/repo-map.git
cd repo-map
poetry install
```

--------------------------------

### Install and Run repo-map CLI

Source: https://context7.com/cyanheads/repo-map/llms.txt

Instructions for installing the tool using Poetry and running basic commands. Includes examples for setting API keys, performing a basic analysis, skipping the disclaimer, overriding the LLM model, and increasing concurrency.

```bash
# Install
git clone https://github.com/cyanheads/repo-map.git && cd repo-map
poetry install

# Set API key (required)
export OPENROUTER_API_KEY=sk-or-...

# Basic run — analyzes /path/to/myproject, writes myproject_repo_map.md inside it
poetry run repo-map /path/to/myproject

# Skip interactive disclaimer prompt
poetry run repo-map /path/to/myproject -y

# Override LLM model
poetry run repo-map /path/to/myproject --model "openai/gpt-4o"

# Increase concurrent LLM calls (default: 3)
poetry run repo-map /path/to/myproject --concurrency 8

# Expected console output (truncated):
# INFO  Generating repository summary...
# INFO  Pre-enhancement structure saved to '.repo_map_structure.json'.
# INFO  Enhancing repository summary with descriptions using OpenRouter LLM...
# Enhancing files: 100%|████████████████| 12/12 [00:18<00:00]
# INFO  Updated Repository Map:
# INFO  / (Root Directory)
# INFO  ├── src/
# INFO  │   └── repo_map/
# INFO  │       ├── main.py (Python)
# INFO  │       │   ├── Description: Primary entrypoint ...
# INFO  Your repo-map has been saved to 'myproject_repo_map.md'.
```

--------------------------------

### repo-map Command Examples

Source: https://github.com/cyanheads/repo-map/blob/main/README.md

Examples demonstrating how to use repo-map with different options, including specifying a model and auto-accepting the disclaimer.

```bash
# Basic usage
repo-map /path/to/your/repo
```

```bash
# Use a specific model
repo-map /path/to/your/repo --model "anthropic/claude-sonnet-4.6"
```

```bash
# Auto-accept disclaimer
repo-map /path/to/your/repo -y
```

--------------------------------

### Install Dependencies and Set API Key

Source: https://github.com/cyanheads/repo-map/blob/main/CLAUDE.md

Install project dependencies using Poetry and set the required OpenRouter API key as an environment variable.

```bash
# Install dependencies
poetry install

# Set required environment variable
export OPENROUTER_API_KEY=your_key_here
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Installs all dependencies listed in the `pyproject.toml` file. If a `poetry.lock` file exists, it installs the exact versions specified there.

```bash
poetry install
```

--------------------------------

### Show Project Dependencies

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Lists all direct and indirect dependencies of the project, along with their installed versions.

```bash
poetry show
```

--------------------------------

### Configure repo-map Settings

Source: https://context7.com/cyanheads/repo-map/llms.txt

Example of a `.env` file for configuring repo-map settings, including API keys and LLM model names. Demonstrates how to access these settings within Python code and includes a check for the API key's presence.

```python
# .env file example
OPENROUTER_API_KEY=sk-or-v1-abc123
OPENROUTER_MODEL_NAME=anthropic/claude-sonnet-4.6
API_SEMAPHORE_LIMIT=5

# Accessing settings in code
from repo_map.config import settings

print(settings.openrouter_model_name)   # "anthropic/claude-sonnet-4.6"
print(settings.api_semaphore_limit)     # 5
print(settings.has_api_key())           # True

# Checking key presence before making API calls
if not settings.has_api_key():
    raise RuntimeError("OPENROUTER_API_KEY is not set")

# Settings fields and defaults:
# openrouter_api_key:      str | None  = None          (required for LLM calls)
# openrouter_model_name:   str         = "anthropic/claude-sonnet-4.6"
# openrouter_api_url:      str         = "https://openrouter.ai/api/v1/chat/completions"
# http_referer:            str         = "https://github.com/cyanheads/repo-map"
# app_name:                str         = "repo-map"
# api_semaphore_limit:     int         = 3

```

--------------------------------

### Scan Repository and Load Cache

Source: https://context7.com/cyanheads/repo-map/llms.txt

Example of how to use `summarize_repo` to scan a directory and load a cache connection. The function returns a list of dictionaries representing files and directories, enriched with metadata.

```python
import sqlite3
from repo_map.file_scanner import summarize_repo
from repo_map.cache_manager import load_cache

cache_conn: sqlite3.Connection = load_cache("/path/to/myproject")
structure = summarize_repo("/path/to/myproject", cache_conn)

# Each file entry looks like:
# {
#   "name": "main.py",
#   "path": "/path/to/myproject/src/main.py",
#   "level": 2,
#   "type": "file",
#   "language": "Python",
#   "hash": "e3b0c44298fc1c149afb...",
#   "imports": ["asyncio", "logging", "repo_map.cli_handler.RepoMapApp"],
#   "functions": ["run_main"],
#   "classes": {},
#   "constants": [],
# }
```

--------------------------------

### Add a Library to Project Dependencies

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Installs a library and adds it to your project's `pyproject.toml` file. Replace `<library>` with the name of the package you want to add.

```bash
poetry add <library>
```

--------------------------------

### Sample Snake Game Repository Map

Source: https://github.com/cyanheads/repo-map/blob/main/README.md

An example of a repo-map generated for a Python Snake game. It illustrates the tree-like structure and AI-generated descriptions for files.

```markdown
/ (SSSnakeGame)
├── main.py (Python)
│   ├── Description: Entry point for the Snake game; initializes Pygame and runs the main event loop.
│   ├── Developer Consideration: The game loop is tightly bound to Pygame's event system; significant changes require Pygame familiarity.
│   ├── Maintenance Flag: Stable
│   ├── Architectural Role: Entrypoint
│   ├── Refactoring Suggestions: Isolate game state from rendering to improve testability and reduce complexity.
│   ├── Critical Dependencies:
│   └──   - pygame: Game loop, input handling, and rendering.
├── config.py (Python)
│   ├── Description: Centralizes static configuration (screen dimensions, colors, snake speed).
│   ├── Developer Consideration: Changing screen dimensions may require adjustments to food spawning to keep it in bounds.
│   ├── Maintenance Flag: Volatile
│   └── Architectural Role: Configuration
├── assets/
│   ├── images/
│   │   ├── snake_head.png (Image)
│   │   └── food.png (Image)
│   └── sounds/
│       ├── eat.wav (Audio)
│       └── game_over.mp3 (Audio)
├── requirements.txt (Text)
│   └── Description: Lists Python package dependencies required to run the project, such as `pygame`.
└── README.md (Markdown)
    └── Description: Project overview including setup instructions, gameplay details, and contribution guidelines.
└──────────────
```

--------------------------------

### Activate Project's Virtual Environment

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Activates the project's virtual environment, making its Python interpreter and installed packages available in your current shell session.

```bash
poetry shell
```

--------------------------------

### Get Virtual Environment Python Path

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Prints the absolute path to the Python executable within the project's virtual environment. Useful for locating the environment.

```bash
poetry run which python
```

--------------------------------

### Extract JavaScript Code Structure

Source: https://context7.com/cyanheads/repo-map/llms.txt

Extracts structural metadata like classes, functions, and constants from JavaScript files. This example shows the expected output format for JavaScript class extraction.

```JavaScript
# --- JavaScript file ---
js_classes, js_funcs, js_consts = get_structure("/path/to/app/index.js", "JavaScript")
# js_classes = {"UserService": ["getUser", "createUser"]}
```

--------------------------------

### Create a New Project with Poetry

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Use this command to initialize a new Python project managed by Poetry. Replace `<project-name>` with your desired project name.

```bash
poetry new <project-name>
```

--------------------------------

### Run repo-map CLI

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Execute the repo-map tool from the project root. Provide the path to the repository you want to analyze.

```bash
poetry run repo-map /path/to/repository
```

--------------------------------

### List Poetry Configuration Settings

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Displays all current Poetry configuration settings, including global and project-specific options.

```bash
poetry config --list
```

--------------------------------

### Run repo-map CLI Tool

Source: https://github.com/cyanheads/repo-map/blob/main/CLAUDE.md

Execute the repo-map CLI tool to analyze a target repository. Options include specifying the LLM model and concurrency level.

```bash
# Run repo-map on a target repository
poetry run repo-map /path/to/repository

# With options
poetry run repo-map /path/to/repo --model "anthropic/claude-sonnet-4.6" --concurrency 3 -y
```

--------------------------------

### Create a Script File for Custom Commands

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Create a Python file (e.g., `scripts.py`) in your project's root directory to house the functions for your custom scripts defined in `pyproject.toml`.

```python
import subprocess

def test():
    """
    Run all unittests. Equivalent to:
    `poetry run python -u -m unittest discover`
    """
    subprocess.run(
        ['python', '-u', '-m', 'unittest', 'discover']
    )
```

--------------------------------

### Manage Supported Languages

Source: https://context7.com/cyanheads/repo-map/llms.txt

Illustrates how to query the `SUPPORTED_LANGUAGES` dictionary for file extensions and how to add new languages dynamically. Permanent additions require modifying the source files.

```Python
from repo_map.models import SUPPORTED_LANGUAGES

# Look up a language by extension
print(SUPPORTED_LANGUAGES.get(".py"))    # "Python"
print(SUPPORTED_LANGUAGES.get(".ts"))    # "TypeScript"
print(SUPPORTED_LANGUAGES.get(".tf"))    # "Terraform"
print(SUPPORTED_LANGUAGES.get(".xyz"))   # None  → file still scanned, language=None

# All recognized code/config extensions (subset):
code_exts = [ext for ext, lang in SUPPORTED_LANGUAGES.items()
             if lang in ("Python","Java","JavaScript","TypeScript","C#","Go","Ruby","PHP")]
print(code_exts)
# ['.py', '.java', '.js', '.jsx', '.ts', '.tsx', '.cs', '.rb', '.go', '.php']

# Adding a new language at runtime (persists only for the process lifetime):
SUPPORTED_LANGUAGES[".zig"] = "Zig"
print(SUPPORTED_LANGUAGES.get(".zig"))  # "Zig"
# For permanent addition, edit src/repo_map/models.py and add parsing logic
# to src/repo_map/code_parser.py's get_structure() dispatch.
```

--------------------------------

### Basic repo-map Usage

Source: https://github.com/cyanheads/repo-map/blob/main/README.md

Run repo-map from the project root to analyze a specified repository path. This command generates a map of the codebase.

```bash
poetry run repo-map <repository_path> [options]
```

--------------------------------

### Sync Skills to Agent Mirrors

Source: https://github.com/cyanheads/repo-map/blob/main/skills/maintenance/SKILL.md

Run this command to synchronize skills from the canonical source to read-only agent mirrors. The script is idempotent and only copies missing or content-drifted files.

```bash
poetry run sync-skills
```

```bash
python3 scripts/sync_skills.py
```

--------------------------------

### Load and Manage SQLite Cache

Source: https://context7.com/cyanheads/repo-map/llms.txt

Opens or creates the SQLite cache database at `<repo_root>/.repo-map-cache.db`, automatically handling schema migrations for compatibility. The cache stores structural metadata like path, hash, and descriptions.

```Python
import sqlite3
from repo_map.cache_manager import load_cache

# Opens/creates .repo-map-cache.db inside the target repo
conn: sqlite3.Connection = load_cache("/path/to/myproject")

# Cache table schema:
# CREATE TABLE cache (
#   path                   TEXT PRIMARY KEY,
#   hash                   TEXT,           -- SHA-256 of file bytes
#   description            TEXT,
#   developer_consideration TEXT,
#   imports                TEXT,           -- JSON array
#   functions              TEXT,           -- JSON array
#   maintenance_flag       TEXT,           -- Stable|Volatile|Generated|Unknown
#   critical_dependencies  TEXT,           -- JSON object {import: reason}
#   architectural_role     TEXT,
#   refactoring_suggestions TEXT,
#   security_assessment    TEXT
# )

# Manual cache inspection
cursor = conn.cursor()
cursor.execute("SELECT path, hash, maintenance_flag FROM cache LIMIT 3")
for row in cursor.fetchall():
    print(row)
# ('/path/to/myproject/src/main.py', 'a3f5c2...', 'Stable')
# ('/path/to/myproject/src/config.py', 'b91dc4...', 'Volatile')

# Delete cache to force full re-analysis on next run
import os
os.remove("/path/to/myproject/.repo-map-cache.db")

conn.close()
```

--------------------------------

### Verify Codebase with Linters and Tests

Source: https://github.com/cyanheads/repo-map/blob/main/skills/maintenance/SKILL.md

Execute these commands to check code quality using Ruff, ensure code formatting with Black, and run the project's test suite with Pytest. These steps are crucial for verifying that dependency updates have not introduced regressions.

```bash
poetry run ruff check src
```

```bash
poetry run black --check src
```

```bash
poetry run pytest
```

--------------------------------

### Run repo-map with Skip Disclaimer

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Use the -y or --yes flag to skip the interactive disclaimer prompt during execution.

```bash
poetry run repo-map -y /path/to/repository
```

--------------------------------

### Run repo-map with Custom Model

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Override the default OpenRouter model using the --model flag.

```bash
poetry run repo-map --model <model_name> /path/to/repository
```

--------------------------------

### Enhance One File with LLM Descriptions

Source: https://context7.com/cyanheads/repo-map/llms.txt

Demonstrates how to use `get_llm_descriptions` to enrich a file's metadata. It requires loading cache, summarizing the repository, selecting a target file, and then calling the LLM function. The target dictionary is mutated in-place with new fields.

```python
import asyncio
from repo_map.llm_service import get_llm_descriptions
from repo_map.file_scanner import summarize_repo
from repo_map.cache_manager import load_cache

async def enhance_one_file():
    conn = load_cache("/path/to/myproject")
    structure = summarize_repo("/path/to/myproject", conn)

    # Pick a file to enhance (must have imports or functions to be worthwhile)
    target = next(
        f for f in structure
        if f["type"] == "file" and f.get("functions")
    )

    print(f"Enhancing: {target['name']}")
    await get_llm_descriptions(
        structure=structure,
        file=target,
        model="anthropic/claude-sonnet-4.6",
        max_retries=3,
    )

    # target dict is mutated in-place:
    print(target["description"])
    # "Primary entrypoint for the repo-map CLI; initializes RepoMapApp and runs the async pipeline."
    print(target["maintenance_flag"])
    print(target["architectural_role"])
    print(target["developer_consideration"])
    # "run_main must be called via asyncio.run(); the inner RepoMapApp.run() is a coroutine."
    print(target["refactoring_suggestions"])
    print(target["security_assessment"])
    import json
    print(json.loads(target["critical_dependencies"]))
    # {"asyncio": "Executes the async application lifecycle."}

    conn.close()

asyncio.run(enhance_one_file())
```

--------------------------------

### Run an Application Script

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Executes a Python script within the project's virtual environment. Replace `app.py` with the name of your script.

```bash
poetry run python app.py
```

--------------------------------

### Test Changes During Development

Source: https://github.com/cyanheads/repo-map/blob/main/CLAUDE.md

Test changes by running the tool on a sample repository, especially useful when tests are not yet implemented.

```bash
poetry run repo-map /path/to/test/repo -y
```

--------------------------------

### Smoke Test Repo-Map Tool

Source: https://github.com/cyanheads/repo-map/blob/main/skills/maintenance/SKILL.md

Run a smoke test of the repo-map tool against a small sample repository. This helps catch runtime regressions that linters and unit tests might miss, ensuring the tool functions correctly with the updated dependencies.

```bash
poetry run repo-map /path/to/small/repo -y
```

--------------------------------

### Check API Key

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Ensure the OPENROUTER_API_KEY environment variable is exported before invoking the tool to avoid early exit due to a missing API key.

```bash
# confirm OPENROUTER_API_KEY is exported before invoking.
```

--------------------------------

### Run Tests with Poetry

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Executes tests using Python's built-in `unittest` module within the project's virtual environment.

```bash
poetry run python -m unittest discover
```

--------------------------------

### Survey Outdated Packages with Poetry

Source: https://github.com/cyanheads/repo-map/blob/main/skills/maintenance/SKILL.md

Use this command to list all outdated dependencies in your project. Pay attention to major version jumps, as Poetry's caret constraints may prevent automatic updates across major versions.

```bash
poetry show --outdated
```

--------------------------------

### Lint Code with Ruff

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Execute Ruff for code linting on the src directory.

```bash
poetry run ruff check src
```

--------------------------------

### Generate Repository Map Reports

Source: https://context7.com/cyanheads/repo-map/llms.txt

Shows how to generate repository map reports using save_markdown_map, save_json_map, and print_tree. Assumes a pre-populated `structure` list. The `format_tree_lines` function can be used to iterate over the report lines programmatically.

```Python
from repo_map.report_generator import (
    save_markdown_map,
    save_json_map,
    print_tree,
    format_tree_lines,
)

# Assume `structure` is the enriched list from summarize_repo + LLM enhancement
structure = [
    {"name": "src", "path": "/repo/src", "level": 0, "type": "directory"},
    {
        "name": "main.py", "path": "/repo/src/main.py", "level": 1, "type": "file",
        "language": "Python", "description": "CLI entrypoint.",
        "developer_consideration": "Must run via asyncio.run().",
        "maintenance_flag": "Stable", "architectural_role": "Entrypoint",
        "refactoring_suggestions": "None", "security_assessment": "None",
        "critical_dependencies": '{"asyncio": "Async runtime."}'
    },
]

# Print ASCII tree to console (uses logger.info)
print_tree(structure)
# INFO  / (Root Directory)
# INFO  └── src/
# INFO      └── main.py (Python)
# INFO          ├── Description: CLI entrypoint.
# INFO          ├── Developer Consideration: Must run via asyncio.run().
# INFO          ├── Maintenance Flag: Stable
# INFO          ├── Architectural Role: Entrypoint
# INFO          └── Critical Dependencies:
# INFO            └── - asyncio: Async runtime.

# Save pre-enhancement JSON snapshot (written before LLM calls)
save_json_map(structure, "/repo/.repo_map_structure.json")

# Save final Markdown report
save_markdown_map(structure, repo_root="/repo", output_path="/repo/myrepo_repo_map.md")
# Writes:  # Repository Map\n```markdown\n/ (myrepo)\n└── src/\n    └── main.py ...

# Iterate tree lines programmatically
for line in format_tree_lines(structure):
    print(repr(line))
# '└── src/'
# '    └── main.py (Python)'
# '        ├── Description: CLI entrypoint.'
# ...
```

--------------------------------

### Run repo-map with Custom Concurrency

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Throttle simultaneous LLM calls using the --concurrency flag. The default matches settings.api_semaphore_limit.

```bash
poetry run repo-map --concurrency <number> /path/to/repository
```

--------------------------------

### Code Formatting and Linting

Source: https://github.com/cyanheads/repo-map/blob/main/CLAUDE.md

Format code using Black and lint code using Ruff. These commands are executed via Poetry.

```bash
# Format code (Black)
poetry run format
# or
poetry run black src

# Lint code (Ruff)
poetry run ruff check src
```

--------------------------------

### Set OpenRouter API Key

Source: https://github.com/cyanheads/repo-map/blob/main/README.md

Configure the OpenRouter API key by setting the OPENROUTER_API_KEY environment variable. This is required for AI-powered features.

```bash
export OPENROUTER_API_KEY=your_api_key_here
```

--------------------------------

### Set OpenRouter API Key

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Export your OpenRouter API key as an environment variable. This is required before running the tool.

```bash
export OPENROUTER_API_KEY=<token>
```

--------------------------------

### Apply Dependency Updates with Poetry

Source: https://github.com/cyanheads/repo-map/blob/main/skills/maintenance/SKILL.md

Run this command to update dependencies within their specified constraints. For updates that cross major versions or pre-1.0 minor versions, you may need to manually edit `pyproject.toml` first or use `poetry add <package>@latest`.

```bash
poetry update
```

--------------------------------

### Run Pytest Tests

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Execute pytest tests. Ensure new tests are added under the tests/ directory. Pytest is already bundled with the project.

```bash
poetry run pytest
```

--------------------------------

### Run Tests

Source: https://github.com/cyanheads/repo-map/blob/main/CLAUDE.md

Execute project tests using pytest. This command is run via Poetry.

```bash
# Run tests (if/when added)
poetry run pytest
```

--------------------------------

### Run a Custom Script

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Execute a custom script defined in `pyproject.toml` and implemented in a Python file. This command runs the script within the project's virtual environment.

```bash
poetry run test
```

--------------------------------

### Inspect Generated Structure

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Inspect the generated .repo_map_structure.json file before LLM enhancement to confirm scanner output when encountering incorrect tree contents.

```bash
# inspect generated .repo_map_structure.json before LLM enhancement to confirm scanner output.
```

--------------------------------

### Rate-Limited API Call to OpenRouter

Source: https://context7.com/cyanheads/repo-map/llms.txt

Shows how to make a direct, rate-limited API call to OpenRouter using `rate_limited_api_call`. It includes setting up messages, specifying the model, and handling potential errors or successful responses. The global concurrency limit can be adjusted.

```python
import asyncio
from repo_map.llm_service import rate_limited_api_call, update_api_semaphore_limit

# Optionally tighten or loosen the global concurrency limit (default: 3)
update_api_semaphore_limit(5)

async def direct_api_call():
    messages = [
        {"role": "system", "content": "You are a helpful assistant. Respond in JSON."},
        {"role": "user",   "content": '{"task": "Summarize this module: import os"}'},
    ]
    response = await rate_limited_api_call(
        messages=messages,
        model="anthropic/claude-sonnet-4.6",
        temperature=0.0,
    )
    # response is the raw OpenRouter JSON response dict
    if "error" in response:
        print("API error:", response["error"])
    elif response.get("choices"):
        content = response["choices"][0]["message"]["content"]
        print(content)
    # {"description": "Single-import utility module using the os standard library."}

asyncio.run(direct_api_call())
```

--------------------------------

### Normalize Maintenance Flag and Architectural Role

Source: https://context7.com/cyanheads/repo-map/llms.txt

Demonstrates the usage of normalization functions for maintenance flags and architectural roles. Note the expected output for known and unknown values, and case sensitivity.

```Python
from repo_map.llm_service import _normalize_maintenance_flag, _normalize_architectural_role

print(_normalize_maintenance_flag("auto-generated"))  # "Generated"
print(_normalize_maintenance_flag("unstable"))        # "Volatile"
print(_normalize_maintenance_flag("unknown_value"))   # "Unknown"

print(_normalize_architectural_role("Service Layer"))  # "Other"  (not in enum)
print(_normalize_architectural_role("service"))        # "Service" (case-insensitive)
print(_normalize_architectural_role("API Route"))      # "API Route"
```

--------------------------------

### Define a Custom Script in pyproject.toml

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Configure custom scripts that can be executed via `poetry run`. This involves editing the `[tool.poetry.scripts]` section in `pyproject.toml`.

```toml
[tool.poetry.scripts]
test = 'scripts:test'
```

--------------------------------

### Format Code with Black

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Run Black code formatter on the src directory. This command is also aliased to `poetry run format`.

```bash
poetry run black src
```

--------------------------------

### Handle Ignore Patterns with GitIgnoreSpec

Source: https://context7.com/cyanheads/repo-map/llms.txt

Builds a `pathspec.GitIgnoreSpec` by merging default patterns with repository-specific `.gitignore` rules. Use `spec.match_file()` to test if a relative path is ignored, ensuring Git-fidelity matching.

```Python
from repo_map.file_scanner import get_ignore_spec, DEFAULT_IGNORE_PATTERNS

spec = get_ignore_spec("/path/to/myproject")

# Test whether a relative path would be ignored
print(spec.match_file("node_modules/lodash/index.js"))  # True  (ignored)
print(spec.match_file("src/main.py"))                   # False (not ignored)
print(spec.match_file(".git/config"))                   # True  (ignored)
print(spec.match_file("build/output.js"))               # True  (ignored)

# Inspect built-in defaults:
# DEFAULT_IGNORE_PATTERNS includes: ".git/", "__pycache__/", "*.pyc", ".venv/",
# "node_modules/", "*.db", "*.log", ".repo-map-cache.db",
# ".repo_map_structure.json", "*_repo_map.md", and more.
print(DEFAULT_IGNORE_PATTERNS[:6])
# ['.git/', '.hg/', '.svn/', 'CVS/', '__pycache__/', '*.pyc']
```

--------------------------------

### Update a Library to the Latest Version

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Updates a specified library to its latest compatible version according to your `pyproject.toml` constraints. Replace `<library>` with the package name.

```bash
poetry update <library>
```

--------------------------------

### Expand Language Extraction Logic

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Provide language-specific structure and import extraction by expanding the switch logic in src/repo_map/code_parser.py.

```python
# Provide language-specific structure/import extraction by expanding switch logic in src/repo_map/code_parser.py.
```

--------------------------------

### Modify Settings Defaults

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Adjust concurrency or headers by modifying the Settings defaults in src/repo_map/config.py.

```python
# Adjust concurrency or headers by modifying Settings defaults in src/repo_map/config.py.
```

--------------------------------

### Add Supported Language

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

To add support for new file types, modify the SUPPORTED_LANGUAGES variable in src/repo_map/models.py.

```python
# Add new file types via SUPPORTED_LANGUAGES in src/repo_map/models.py.
```

--------------------------------

### Disable Virtual Environment Creation

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Configures Poetry to not automatically create a virtual environment for the project. This is useful if you manage environments externally.

```bash
poetry config virtualenvs.create false
```

--------------------------------

### Remove a Library from Project Dependencies

Source: https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md

Uninstalls a library and removes it from your project's `pyproject.toml` file. Replace `<library>` with the name of the package to remove.

```bash
poetry remove <library>
```

--------------------------------

### Adjust Concurrency for Rate Limits

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

The llm_service.py module retries with exponential backoff. Increase the --concurrency flag cautiously if encountering rate limits.

```bash
# increase --concurrency cautiously
```

--------------------------------

### Compute File Hash for Change Detection

Source: https://context7.com/cyanheads/repo-map/llms.txt

Computes a SHA-256 hex digest of a file's raw bytes in 8 KB chunks. Returns an empty string on `OSError` for unreadable files, triggering a cache miss and LLM re-analysis.

```Python
from repo_map.file_scanner import compute_file_hash

h = compute_file_hash("/path/to/myproject/src/main.py")
print(h)
# "a3f5c2d91b4e87f6c0123456789abcdef0123456789abcdef0123456789abcdef"

# Returns "" on OSError (file unreadable), which forces cache miss → LLM re-call
bad = compute_file_hash("/nonexistent/file.py")
print(bad)  # ""
```

--------------------------------

### Alter Cache Schema and Serialization

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

To persist additional metadata, alter both the cache schema in cache_manager.py and the tree serialization in main.py.

```python
# To persist additional metadata, alter both the cache schema (cache_manager.py) and tree serialization in main.py.
```

--------------------------------

### Parse LLM JSON Response

Source: https://context7.com/cyanheads/repo-map/llms.txt

Demonstrates the `parse_llm_response` function for normalizing LLM JSON output into a file metadata dictionary. It handles raw JSON strings, with or without ` ```json ` fences, and normalizes specific fields like `maintenance_flag` and `architectural_role`.

```python
from repo_map.llm_service import parse_llm_response

file_entry = {"path": "/repo/src/auth.py", "name": "auth.py"}

# Tolerates ```json fences
raw_response = '''```json
{
  "description": "Handles JWT authentication and token validation.",
  "developer_consideration": "Tokens expire after 15 min; ensure refresh logic is in place.",
  "maintenance_flag": "Volatile",
  "critical_dependencies": {"pyjwt": "Token encode/decode"},
  "architectural_role": "Service",
  "refactoring_suggestions": null,
  "security_assessment": "Tokens stored in memory only; no persistent secret leakage risk."
}
```'''

parse_llm_response(raw_response, file_entry)

print(file_entry["description"])
print(file_entry["maintenance_flag"])
print(file_entry["architectural_role"])
print(file_entry["refactoring_suggestions"])
```

--------------------------------

### Verify SSL Certificates

Source: https://github.com/cyanheads/repo-map/blob/main/AGENTS.md

Stale certificate stores on the host can cause SSLCertVerificationError. The certifi bundle is enforced.

```python
# certifi bundle is enforced; stale cert stores on the host can still cause SSLCertVerificationError.
```

--------------------------------

### Extract Python Code Structure

Source: https://context7.com/cyanheads/repo-map/llms.txt

Uses Python's `ast` module to extract classes, functions, and constants from a Python file. Also retrieves import statements and the module-level docstring.

```Python
from repo_map.code_parser import get_structure, get_imports, get_module_docstring

# --- Python file ---
classes, functions, constants = get_structure("/path/to/myproject/src/config.py", "Python")
print(classes)    # {"Settings": ["has_api_key"]}
print(functions)  # []
print(constants)  # []

imports = get_imports("/path/to/myproject/src/config.py", "Python")
print(imports)
# ["pydantic_settings.BaseSettings", "pydantic_settings.SettingsConfigDict"]

docstring = get_module_docstring("/path/to/myproject/src/config.py", "Python")
print(docstring)  # "Configuration settings for the repo-map application."
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.