Getting Started

What is gnaw?

gnaw is a versatile tool designed to bridge the gap between your codebase and Large Language Models (LLMs). It intelligently extracts relevant code snippets, applies powerful filtering, and formats the information into structured prompts optimized for LLM consumption. This simplifies tasks like code documentation, bug detection, refactoring, and more.

gnaw offers different integration points:

A core Rust library (gnaw-core) that provides the foundation for code ingestion and prompt generation.

A user-friendly command-line and terminal interface for quick prompt generation. Ideal for interactive use and one-off tasks.

Python bindings for seamless integration into your Python projects. Perfect for automating prompt generation within larger workflows.

A planned REST interface for advanced integration with browser extensions and other clients, enabling real-time interactions with your codebase.

📥 Installation

For detailed installation instructions, please refer to the comprehensive Installation Guide.

🏁 Generating Prompts: A CLI Example

Let's start with a simple example using the CLI. Create a sample project:

bash

mkdir -p my_project/{src,tests}
touch my_project/src/main.rs my_project/tests/test_1.rs
echo 'fn main() { println!("Hello, world!"); }' > my_project/src/main.rs

Now, generate a prompt:

bash

gnaw my_project

This copies a prompt to your clipboard. You can customize this:

Filtering: gnaw my_project --include="*.rs" --exclude="tests/*" (includes only .rs files, excludes tests directory)
Output File: gnaw my_project --output-file=my_prompt.txt
JSON Output: gnaw my_project -F json (structured JSON output; -F chooses the format, -O chooses the destination)
Custom Templates: gnaw my_project -t my_template.hbs (requires creating my_template.hbs)

See the Learn Context Filtering and Learn Handlebar Templates tutorials to learn more advanced usages.

🐍 Python Integration

For programmatic control, use the Python bindings. The API is a fluent builder: construct a session over a path, chain configuration calls, then generate().

from gnaw import PyGnawSession

prompt = (
    PyGnawSession("my_project")
    .include(["*.rs"])
    .exclude(["tests/*"])
    .generate()
)
print(prompt)

# Token count without rendering the full prompt:
tokens = PyGnawSession("my_project").include(["*.rs"]).token_count()
print(tokens)