Context Summaries - Vectra Guard

Context summaries help you and AI agents quickly understand codebases by extracting key highlights from files. Perfect for onboarding, code reviews, and giving agents context about your project.

How It Works

Vectra Guard analyzes files and extracts:

Code mode: Functions, classes, imports, key logic
Docs mode: Headings, key points, examples
Advanced mode: Deeper analysis including dependencies and patterns

Results are cached for fast repeated access.

Core Command

The main command is context summarize with three modes:

vg context summarize <mode> <path> [flags]

Modes:

code - Summarize source code files
docs - Summarize documentation files
advanced - Deep analysis of code structure

Code Mode

Summarize source code to extract functions, classes, and key logic:

Single File

vg context summarize code cmd/root.go --max 5

Example output:

CLI entry point, subcommand routing
Defines root command with validate, exec, session subcommands
Initializes config and logger
Handles version flag
Sets up signal handling for graceful shutdown

Entire Repository

vg context summarize code . --max 5

Example output:

📄 cmd/root.go
────────────────────────────────────────────────────────────
  CLI entry point, subcommand routing
  Defines root command with validate, exec, session subcommands
  Initializes config and logger
  Handles version flag
  Sets up signal handling for graceful shutdown

📄 internal/sandbox/sandbox.go
────────────────────────────────────────────────────────────
  Execution mode decision logic
  Determines if command should run in sandbox
  Implements Docker, Podman, and namespace runtimes
  Cache mounting for fast dependency installs
  Trust store integration

📄 internal/cve/scanner.go
────────────────────────────────────────────────────────────
  Manifest parsing + OSV lookup
  Scans package.json, requirements.txt, go.mod
  Queries OSV API for vulnerabilities
  Generates CVE reports
  Caches vulnerability data

When summarizing a directory, Vectra Guard automatically walks the tree and processes all relevant files.

Docs Mode

Summarize documentation files (Markdown, text files):

Single Doc File

vg context summarize docs README.md --max 3

Example output:

Security guard for AI coding agents & development workflows
Blocks dangerous commands like rm -rf /, curl | sh
Provides CVE scanning, sandbox execution, and audit trails

All Documentation

vg context summarize docs . --max 3

Processes:

.md files (Markdown)
.txt files (plain text)
.rst files (reStructuredText)
README, LICENSE, CHANGELOG (any extension)

Advanced Mode

Deeper analysis including dependencies and architectural patterns:

vg context summarize advanced internal/ --max 3

Example output:

📄 internal/sandbox/executor.go
────────────────────────────────────────────────────────────
  Depends on: config, logging, analyzer packages
  Implements ExecutorInterface with Docker/Podman backends
  Uses builder pattern for command construction

Use advanced mode when you need to understand dependencies and architectural patterns.

JSON Output for Agents

Perfect for AI agents that need structured data:

vg context summarize code . --output json --max 10

Example output:

{
  "mode": "code",
  "path": ".",
  "fileCount": 45,
  "files": [
    {
      "path": "cmd/root.go",
      "summary": [
        "CLI entry point, subcommand routing",
        "Defines root command with validate, exec, session subcommands",
        "Initializes config and logger",
        "Handles version flag",
        "Sets up signal handling for graceful shutdown"
      ]
    },
    {
      "path": "internal/sandbox/sandbox.go",
      "summary": [
        "Execution mode decision logic",
        "Determines if command should run in sandbox",
        "Implements Docker, Podman, and namespace runtimes"
      ]
    }
  ]
}

JSON output includes fileCount for tracking and files array with path + summary for each file.

Filter Changed Files

Only process files changed since a commit or date - perfect for PR reviews:

Since Commit

vg context summarize code . --since HEAD~1

Summarizes only files changed in the last commit.

Since Date

vg context summarize code . --since 2024-01-01

Summarizes files changed since January 1, 2024.

Since Commit Hash

vg context summarize code . --since abc123def

Summarizes files changed since commit abc123def.

Git detects changed files

Uses git diff --name-only to find changed files.

Only changed files are processed

Skips unchanged files for faster processing.

Cache is still used

If a changed file was previously cached, cache is used.

Caching Behavior

Summaries are automatically cached for faster subsequent runs.

Cache Location

Repo-local cache (preferred):

.vectra-guard/cache/context-summaries/

Global cache (fallback):

~/.vectra-guard/cache/context-summaries/

Run vg init --local to set up repo-local caching. This is much faster for team collaboration.

How Caching Works

First run: Compute and cache

vg context summarize code . --max 5
# Analyzes all files, caches results
# Time: 5-10 seconds for 50 files

Subsequent runs: Load from cache

vg context summarize code . --max 5
# Loads from cache
# Time: <1 second ⚡

Changed files: Re-compute only changed

vg context summarize code . --since HEAD~1
# Re-computes only changed files
# Uses cache for unchanged files
# Time: <2 seconds ⚡

Cache Keys

Cache keys are SHA-256 hashes of:

filePath + ":" + mode

This ensures:

Unique cache per file and mode
Different modes don’t conflict
Fast lookup by hash

Use Cases

Onboarding New Developers

# Get overview of codebase
vg context summarize code . --max 5 > CODEBASE_OVERVIEW.txt

# Share with new team members
cat CODEBASE_OVERVIEW.txt

AI Agent Context

Give agents structured context about your project:

# Generate JSON for agent
vg context summarize code . --output json --max 10 > context.json

# Agent reads context.json to understand codebase structure

PR Review Workflow

# Summarize only changed files
vg context summarize code . --since main

# Review what changed

Use --since main to see summaries of all files changed in your feature branch.

Documentation Updates

# Check which docs changed recently
vg context summarize docs . --since "2024-01-01" --max 3

# Ensure docs are up to date

Configuration

Control max items globally in config.yaml:

context:
  max_items: 5  # Default max items per file
  cache_enabled: true  # Enable caching

Supported File Types

Code Mode

.go, .js, .ts, .py, .java, .cpp, .c, .h, .rs, .rb, .php, .swift, .kt, .scala
.sh, .bash, .zsh, .fish
Makefile, Dockerfile

Docs Mode

.md, .txt, .rst, .adoc, .org, .tex
README, LICENSE, CHANGELOG (any extension)

Advanced Mode

Same as code mode, with deeper analysis.

Examples

Basic Usage

# Summarize single file
vg context summarize code cmd/root.go --max 5

# Summarize entire repo
vg context summarize code . --max 5

# Summarize docs
vg context summarize docs . --max 3

# Deep analysis
vg context summarize advanced internal/ --max 3

JSON for Agents

# Full repo context
vg context summarize code . --output json --max 10 > context.json

# Changed files only
vg context summarize code . --output json --since HEAD~1 > changes.json

PR Review

# What changed in this PR?
vg context summarize code . --since main

# JSON for automated review
vg context summarize code . --output json --since main > pr-summary.json

Performance

Files	First Run	Cached Run	With —since
10	1-2s	<0.5s	<0.5s
50	5-10s	<1s	1-2s
200	20-30s	<2s	2-5s
500	60-90s	<5s	5-10s

Caching makes repeated runs 10-20x faster!

Trust Store - Manage trusted commands
Roadmap Planning - Plan agent tasks
Metrics - Track execution stats

Get Started

Core Features

Security

Configuration

Advanced

Integrations

​How It Works

​Core Command

​Code Mode

​Single File

​Entire Repository

​Docs Mode

​Single Doc File

​All Documentation

​Advanced Mode

​JSON Output for Agents

​Filter Changed Files

​Since Commit

​Since Date

​Since Commit Hash

​Caching Behavior

​Cache Location

​How Caching Works

​Cache Keys

​Use Cases

​Onboarding New Developers

​AI Agent Context

​PR Review Workflow

​Documentation Updates

​Configuration

​Supported File Types

​Code Mode

​Docs Mode

​Advanced Mode

​Examples

​Basic Usage

​JSON for Agents

​PR Review

​Performance

​Related Features

Build docs developers (and LLMs) love

How It Works

Core Command

Code Mode

Single File

Entire Repository

Docs Mode

Single Doc File

All Documentation

Advanced Mode

JSON Output for Agents

Filter Changed Files

Since Commit

Since Date

Since Commit Hash

Caching Behavior

Cache Location

How Caching Works

Cache Keys

Use Cases

Onboarding New Developers

AI Agent Context

PR Review Workflow

Documentation Updates

Configuration

Supported File Types

Code Mode

Docs Mode

Advanced Mode

Examples

Basic Usage

JSON for Agents

PR Review

Performance

Related Features