agentra

---

Agentra is a DevSecOps control plane for AI coding assistants. It auto-detects your project stack, enforces 32 security policies across 8 categories (including the OWASP Top 10), routes each task to the best model via capability-class routing, manages context token budgets, generates tailored instruction files for every major agent platform, and gates builds against real vulnerability scans.

Quick Start

# Install
pip install agentra

# Initialize — auto-detect stack, generate agent instruction files
ag init --mode quick

# Minimal-token setup — generate lean instructions and turn token-saver on in one step
ag init --mode token-saver --agents copilot

# Run security vulnerability scan (OWASP Top 10 + SAST + CVE)
ag scan

# Security gate: scan then build only if clean
ag prebuild "docker build ."

# Run security governance checks
ag enforce

# Check a command before running it
ag simulate "rm -rf /tmp/build"

# Install git hooks (pre-commit + pre-push security gates)
ag hooks install

# Generate a Claude Code plugin package
ag plugin

# Run benchmarks and generate reports
ag benchmark

# List available skills and generate agent-invokable prompt files
ag skills list
ag skills generate

# Enable token-saver mode for leaner instruction files
ag token-saver on
ag token-saver status

# Classify a task and route to the best model (RouteSmith mode)
ag route "implement a distributed caching layer with Redis"
ag route "design the authentication system architecture" --platform copilot
ag route "review this code for security vulnerabilities" --format json

Features

CLI Commands

Usage Examples

# Enterprise mode with SOC2 + ISO27001 compliance
ag init --mode enterprise --agents claude,copilot

# Build the code knowledge graph index (run once, then keep updated)
ag index                            # Full index build
ag index --force                    # Force rebuild from scratch
ag index --format json              # Machine-readable output
ag rag "database connection pooling"  # Find similar code with BM25 retrieval

# Detect code smells and anti-patterns
ag patterns                         # Whole project (requires ag index)
ag patterns --file src/api.py       # Single file (no index needed)
ag patterns --severity high         # Filter by severity

# Full vulnerability scan — OWASP + SAST + deps
ag scan

# Incremental scan (only changed files since last ag index)
ag scan --incremental               # Default when index exists
ag scan --no-incremental            # Force full scan

# Scan with specific targets
ag scan --owasp --deps              # OWASP patterns + dependency CVEs
ag scan --sast                     # SAST only (requires bandit or semgrep)
ag scan --format json > report.json  # Machine-readable output

# Security gate before any build
ag prebuild "docker build ."
ag prebuild "python -m pytest" --block-high

# Git hooks
ag hooks install
ag hooks status
ag hooks ci --ci github --output .github/workflows/security.yml

# Generate Claude Code plugin
ag plugin --output my-plugin/
# Then in Claude Code: /plugin add my-plugin/

# Explain a specific policy rule
ag explain DB-001
#   DB-001 — no-auto-drop
#   Severity: CRITICAL │ Category: database
#   Never auto-execute DROP TABLE/DATABASE without explicit approval

# Full validation pipeline
ag validate
#   Governance:  4 violations │ Risk: 29.0 │ Blast Radius: high
#   Compliance:  SOC2: 3 findings │ PCI_DSS: 2 findings
#   Optimization: 3,840 → 2,112 tokens (45.0% reduction)

# Token-saver controls after init
ag token-saver on
ag token-saver status
ag token-saver compress-context
ag token-saver init-rtk
ag token-saver caveman

# Smart model routing — view and manage per-agent model preferences
ag model list                          # Show active model + 9-purpose routing table
ag model set claude claude-opus-4-7    # Override model for one agent
ag model set copilot gpt-5.5 --purpose reasoning  # Override a specific purpose

# Enterprise / restricted environments
ag model set claude --interactive      # Pick from a numbered menu of known models
ag model set claude some-model --auto-fallback  # Auto-pick next best if restricted

# Detect which model is currently active (reads env vars + settings files)
ag model detect

# RouteSmith — classify a task and route it to the best model
ag route "implement a REST endpoint for user auth"
# Purpose: coding  │ Capability: coding  │ Complexity: medium
# Recommended Models:
#   copilot  →  gpt-5.3-codex
#   claude   →  claude-sonnet-4-6
#   cursor   →  gpt-5.3-codex

ag route "architect a distributed event-driven payment system" --platform copilot
# Purpose: planning  │ Capability: deep_reasoning  │ Complexity: high
# copilot  →  gpt-5.5

ag route "write pytest unit tests and mock the database" --format json
# {"purpose": "testing", "capability_class": "coding", "complexity": "medium", ...}

# Visualize the call graph as an interactive HTML report
ag graph                               # Generate code-graph.html, open in browser
ag graph --output reports/graph.html   # Custom output path
ag graph --max-nodes 500               # Show more nodes (default: 300)
ag graph --no-open                     # Generate without opening browser
ag graph --include-orphans             # Include isolated nodes (hidden by default)
#   Platform  │ Model              │ Source
#   ──────────┼────────────────────┼──────────────────────
#   claude    │ claude-sonnet-4-6  │ CLAUDE_MODEL env var
#   aider     │ claude-opus-4-7    │ AIDER_MODEL env var
#   copilot   │ unknown            │ not found in env or settings

Security Policies

32 built-in policies across 8 categories:

Agent Adapters

Generates native instruction files for each platform:

Architecture

agentra/
├── cli/             # Typer CLI with Rich output
├── detection/       # Stack detection engine (40+ technologies)
├── governance/      # Security policy engine (32 rules, 8 categories)
├── scanner/         # Vulnerability scanning: OWASP patterns, SAST, deps CVE
├── index/           # Persistent code knowledge graph (SQLite + tree-sitter)
├── rag/             # BM25 RAG engine + anti-pattern library (12 patterns)
├── compress/        # Context-file compressor and RAG chunk deduplicator
├── hooks/           # Git hook management + CI template generation
├── plugin/          # Claude Code plugin generator
├── optimizer/       # Token optimization (dedup, prioritize, compress, budget-fit)
├── routing/         # RouteSmith task classifier + model router
├── adapters/        # Agent platform adapters (7 platforms)
├── skills/          # Domain skill packs (14 built-in)
├── execution/       # Execution safety engine (risk classify, sandbox, approve)
├── onboarding/      # Project initialization (5 modes)
├── compliance/      # Compliance mapping (SOC2, ISO27001, PCI DSS, HIPAA, NIST)
├── benchmarks/      # Skill benchmarking with before/after metrics
├── renderers/       # HTML + Markdown report generation
├── risk/            # Risk scoring and blast radius estimation
├── telemetry/       # Local-only JSON audit logging
└── models.py        # Pydantic data models

Onboarding Modes

Benchmarking & Reports

Every skill is benchmarked with before/after metrics:

• Instruction Token Cost — tokens consumed by skill instructions
• Security Policy Coverage — policies activated by the skill
• Context Relevance — stack-match relevance score (0–1)
• Instruction Compression — compression ratio achieved

ag benchmark --output reports/
# ✓ Benchmark report (MD):   reports/benchmark-report.md
# ✓ Benchmark report (HTML): reports/benchmark-report.html

The HTML report is a self-contained dark-themed dashboard with stat cards, metric bars, and tables. Open it directly in a browser.

Configuration

Agentra uses .agentra.yml:

project:
  name: my-project
  languages: [python]
  frameworks: [fastapi]
  sdks: [openai]

security:
  mode: enterprise
  edr_safe: true
  compliance: [SOC2, ISO27001]

optimization:
  minimal_context: true
  token_budget:
    input: 12000
    output: 4000

agents: [claude, copilot, cursor]
skills: [fastapi, postgresql, karpathy]
karpathy_guidelines: true   # Embed behavioral coding guidelines in all agent files
scanner_enabled: true       # Enable pre-build vulnerability scanning

Pre-Build Security Gates

Agentra intercepts builds before they run and gates on vulnerability findings:

# Manual gate
ag prebuild "docker build ."
# → Runs OWASP + SAST + deps scan
# → Blocks if CRITICAL findings (exit 1)
# → Warns on HIGH findings (continues)

# Git hook gate (auto-runs on every commit/push)
ag hooks install
# → pre-commit: OWASP scan (fast, <5s)
# → pre-push:   full scan (OWASP + SAST + deps)

# CI pipeline gate
ag hooks ci --ci github --output .github/workflows/security.yml
ag hooks ci --ci gitlab --output .gitlab-ci.yml

Scanner degrades gracefully — bandit, semgrep, pip-audit, npm audit, and cargo audit are all optional. The built-in OWASP regex scanner works with no extra dependencies.

Intelligent Instruction Merging

When you run ag init or ag model set on a project that already has instruction files, Agentra merges the new content instead of overwriting:

• Agentra-owned sections (## Detected Stack, ## Security & Governance, ## Active Skills, etc.) are always refreshed with the latest generated content.
• User-added ## sections are preserved verbatim in their original position.
• The Agentra header (preamble) is always updated to the latest version.
• Non-markdown files (.aider.conf.yml, .continue/config.json) are always replaced since they use structured formats.

# Safe to re-run — your custom sections are preserved
ag init

# Force a clean overwrite (no merge)
# (use write_agent_files(..., merge=False) in Python API)

Smart Model Routing (RouteSmith Mode)

Instead of letting Copilot's "auto" mode pick any model, Agentra classifies each task and routes it to the capability-matched model before the agent responds.

ag route "implement a distributed caching layer with Redis"
# Purpose: coding │ Capability: coding │ Complexity: high
# Upgraded to deep_reasoning — high-complexity signals detected.
#
# Recommended Models:
#   copilot  →  gpt-5.5        (deep_reasoning)
#   claude   →  claude-opus-4-7
#   cursor   →  claude-4-7

ag route "fix the typo in the README" --platform copilot
# Purpose: general │ Capability: balanced │ Complexity: low
# copilot  →  gpt-5.4

How it works

1. TaskClassifier scores 9 purpose categories (planning, reasoning, review, coding, testing, refactoring, documentation, general, formatting) using weighted keyword signals — zero latency, no ML required.
2. Complexity estimation upgrades coding → deep_reasoning when high-complexity signals appear (production, distributed, architecture, multi-tenant, etc.).
3. TaskRouter resolves the best model per platform using CAPABILITY_MODELS + CAPABILITY_FALLBACK_CHAINS, respecting per-purpose config overrides and enterprise model restrictions.
4. Decision table injected into every agent instruction file as a ## Smart Model Routing section — agents self-select the right model before responding.

# .agentra.yml — override routing decisions per purpose
model_purpose_preferences:
  copilot:
    review: gpt-5.5        # Always use deep model for security review
    formatting: gpt-5-mini # Use fast model for style fixes

# Restrict unavailable models (enterprise plan limits)
# TaskRouter skips restricted models and picks the next best from the fallback chain

Skills as Agent-Invokable Prompts

Skills are no longer just static text injected into every instruction file. Each skill is now materialized as a standalone prompt file that agents load on demand:

This keeps instruction files lean (only the active skills table is injected) while giving the model full, targeted guidance exactly when it's needed.

# Generate prompt files for all active skills
ag skills generate

# Generate for specific skills
ag skills generate --skills fastapi,postgresql,kubernetes

# List all skills with active status
ag skills list

# Skip one platform
ag skills generate --no-claude    # Copilot only
ag skills generate --no-copilot   # Claude Code only

The ## Active Skills block in every instruction file tells agents how to invoke each skill:

## Active Skills
| Skill       | Copilot    | Claude Code      | Description                    |
|-------------|------------|------------------|--------------------------------|
| **fastapi** | `#fastapi` | `/skill fastapi` | Production FastAPI patterns... |

Claude Code Plugin

Agentra ships as a distributable Claude Code plugin:

# Generate plugin package
ag plugin --output .agentra-plugin/

# Install in Claude Code
/plugin add .agentra-plugin/

The plugin includes:

• PreToolUse hook — intercepts bash, make, npm run, cargo, docker commands and runs ag scan --owasp automatically
• /agentra-scan — run a full vulnerability scan
• /agentra-enforce — run governance policy checks
• /agentra-prebuild — security gate before a build
• agentra-guardian — always-on skill with Karpathy coding guidelines + security baseline

Karpathy Coding Guidelines

All generated agent instruction files include Andrej Karpathy's 4 behavioral coding rules:

1. Think Before Coding — Read the full task before writing any code
2. Simplicity First — Prefer the simplest solution that works; complexity is a liability
3. Surgical Changes — Change only what is necessary; don't refactor opportunistically
4. Goal-Driven Execution — Every line must serve the stated task; delete code that doesn't

These are embedded in CLAUDE.md, .cursorrules, .github/copilot-instructions.md, .windsurfrules, and AGENTS.md by default (karpathy_guidelines: true).

Enterprise Features

Install optional extras depending on how much code intelligence and token accounting you want:

pip install "agentra[enterprise]"
pip install "agentra[rag]"

• enterprise adds the optional graph/index dependencies used for deeper code intelligence.
• rag adds tiktoken for more accurate token estimation while keeping BM25 retrieval available.

Code Knowledge Graph

Agentra builds and maintains a persistent SQLite knowledge graph (code_index.db) of your codebase using tree-sitter multi-language AST parsing. Once indexed, scans and agent context generation are incremental — only files changed since the last index run are reprocessed.

ag index                    # Build or update the knowledge graph
ag index --force            # Full rebuild from scratch

The index stores:

• All functions, classes, methods, and imports with line ranges and docstrings
• Call edges between symbols for dependency and hotspot analysis
• SHA-256 content hashes per file for change detection
• Code chunks for BM25 retrieval

Languages supported: Python, JavaScript, TypeScript, Rust, Go, Java, Ruby, C, C++, C# (via tree-sitter), with regex-based fallback for all other file types.

Call graph extraction uses the best available tool per language — pyan3 for whole-project Python analysis (cross-file, module-level calls), tree-sitter call_expression queries for all other supported languages. Both are optional and degrade gracefully if not installed. Import-only nodes and true orphans are filtered from the graph by default; pass --include-orphans to show them.

BM25 Code RAG

The RAG engine builds a BM25 index over tokenized code chunks using rank-bm25. When generating agent instruction files (CLAUDE.md, .cursorrules, etc.), Agentra injects a Codebase Patterns section with:

• Established patterns — the top-3 most prevalent idioms in the codebase
• Known code smells — the 5 highest-severity anti-patterns to avoid repeating

This gives coding agents targeted, project-specific context instead of generic boilerplate, reducing agent context tokens by ~60–80% in steady state.

Token-Saver Mode

ag token-saver is the dedicated low-token workflow for generated instruction files:

• ag init --mode token-saver generates leaner agent files up front and enables token-saver automatically.
• ag token-saver on compresses CLAUDE.md, AGENTS.md, and .github/copilot-instructions.md, writes backups to .agentra/backups/, and injects a brevity block where appropriate.
• ag token-saver off restores the original files from backup.
• ag token-saver status shows whether the mode is enabled and how many tokens each tracked context file uses.
• ag token-saver init-rtk and ag token-saver caveman print setup instructions for external token-reduction helpers and add usage blocks to the relevant instruction files.

Use ag init --mode token-saver when you want the leanest default setup from the start. Use ag token-saver on when you want to compress an existing project after a normal init.

Anti-Pattern Detection

12 built-in anti-pattern rules run on every file:

ag patterns                         # Scan whole project
ag patterns --file src/api.py       # Single file scan
ag patterns --severity high         # Filter by severity
ag patterns --format json           # Machine-readable output

Incremental Scanning

Once the knowledge graph is built, ag scan automatically uses incremental mode:

ag scan --incremental               # Default: only changed files
ag scan --no-incremental            # Force full scan

In steady state (10% of files change per run), this reduces scan token cost by ~90% and wall time proportionally.

Scan Efficiency Benchmark

ag benchmark now includes a Scan Efficiency benchmark that compares full scan vs knowledge-graph-incremental scan across four metrics: files traversed, content tokens scanned, agent context tokens, and scan wall time. Run without an index for projected values; run after ag index for real measurements.

Configuration

# .agentra.yml (enterprise sections)
index:
  path: .agentra          # Where to store code_index.db and RAG store
  enabled: true
  exclude:                # Patterns to exclude from indexing
    - "*.generated.*"
    - "migrations/"

rag:
  enabled: true
  top_k: 5               # Similar chunks to retrieve
  antipatterns: true     # Run anti-pattern detection during indexing
  include_in_agent_files: true  # Inject patterns block into CLAUDE.md etc.

Documentation

Full interactive documentation is available at docs/index.html — a storybook-style guide covering every feature, command, policy, skill, and adapter with usage examples. A Markdown version is at docs/index.md.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests (306 passed, 1 skipped)
pytest tests/ -v

# Lint
ruff check agentra/

# Type check
mypy agentra/

Acknowledgements

This project was inspired by agent-policykit by Siddharth Rathore. Thanks for the idea and the foundational work that sparked Agentra.

License

MIT