Configuration¶

All configuration is through environment variables, with one CLI flag (--profile) that overrides GRIPPY_PROFILE.

Environment Variables¶

Transport Resolution¶

Grippy uses a three-tier priority to determine how it connects to the LLM:

1. Explicit parameter --- GRIPPY_TRANSPORT is set to one of: openai, anthropic, google, groq, mistral, local
2. Inferred from API key --- If OPENAI_API_KEY is present and GRIPPY_TRANSPORT is unset, transport is inferred as openai
3. Default --- Falls back to local

Provider Details¶

When transport is openai: - Uses OpenAIChat from the Agno framework - Reads OPENAI_API_KEY from the environment - GRIPPY_BASE_URL is ignored (OpenAI's endpoint is used directly) - Enables native structured outputs (structured_outputs=True) for wire-level JSON schema enforcement

When transport is local: - Uses OpenAILike from the Agno framework - Connects to GRIPPY_BASE_URL (default: http://localhost:1234/v1) - Accepts any API key (LM Studio, Ollama, and vLLM don't validate keys)

When transport is any other provider (anthropic, google, groq, mistral): - Uses the provider's native Agno model class - Reads the provider-specific API key from the environment - GRIPPY_BASE_URL is ignored

If GRIPPY_TRANSPORT is set to an unrecognized value, the agent exits with a config error.

Security Profiles¶

The GRIPPY_PROFILE environment variable controls the deterministic security rule engine. The --profile CLI flag overrides the env var.

Priority: CLI --profile > GRIPPY_PROFILE env var > default (security).

# Use the default (security) — rules ON, gate fails on ERROR+
grippy

# Stricter gating — gate also fails on WARN
grippy --profile strict-security

# LLM-only, no rules
GRIPPY_PROFILE=general grippy

When the rule engine activates, it runs 10 deterministic rules on the full diff before the LLM call. Rule findings are injected into the LLM context as confirmed facts. See Architecture --- Rule Engine for details.

Model Recommendations¶

Opinion: use a different vendor than your coding assistant. If your codebase is co-developed with an AI coding assistant, run Grippy on a model from a different vendor. Different model families have different training data, different biases, and different blind spots. A reviewer that shares the same priors as the author is more likely to miss the same classes of bugs. Cross-vendor review --- e.g., reviewing GPT-authored code with Claude, or Claude-authored code with GPT --- gives you a genuinely independent audit rather than an echo chamber.

Chat models¶

Embedding models¶

Set the embedding model with GRIPPY_EMBEDDING_MODEL. The embedding endpoint must be OpenAI-compatible (/v1/embeddings).

Persistence¶

GRIPPY_DATA_DIR stores two things:

1. LanceDB vector index (lance/) --- Codebase chunks embedded for semantic search during review. The agent uses this to understand code beyond the diff.
2. SQLite graph database (navi-graph.db) --- Nodes and edges tracking review entities (findings, patterns, files, authors) across review rounds. A separate grippy-session.db stores Agno agent session state.

Caching in CI¶

Cache GRIPPY_DATA_DIR between workflow runs to avoid re-indexing the codebase on every push. The workflow in this repo uses:

- name: Cache Grippy data
  uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306  # v5
  with:
    path: ./grippy-data
    key: grippy-data-${{ github.event.pull_request.number || 'manual' }}-${{ github.sha }}
    restore-keys: |
      grippy-data-${{ github.event.pull_request.number || 'manual' }}-

Important notes¶

• Data is repo-specific --- don't share a GRIPPY_DATA_DIR across different repositories.
• The vector index is rebuilt if the codebase_chunks table doesn't exist. Deleting the cache forces a full re-index.
• The graph database uses WAL mode and foreign keys for integrity. It is safe to cache and restore across runs.

MCP Server Configuration¶

When running as an MCP server (grippy serve or uvx grippy-mcp serve), the same environment variables apply. The server reads GRIPPY_TRANSPORT, GRIPPY_MODEL_ID, GRIPPY_BASE_URL, GRIPPY_API_KEY, and GRIPPY_PROFILE from its environment.

The grippy install-mcp command provides an interactive installer that configures these variables for your MCP client:

grippy install-mcp              # published mode (uvx grippy-mcp)
grippy install-mcp --dev        # dev mode (uv run --directory)

The installer detects Claude Code, Claude Desktop, and Cursor, and writes the appropriate server configuration.