Certifiedunder the Multi-Agent System module in the Mastering AI Agents program.
A comprehensive code analysis tool that combines multiple scanning engines (SemGrep, Trivy, AI) with automated fixing capabilities using LangGraph orchestration.
Modern codebases mix application logic, third‑party libraries, infrastructure as code, and configuration spread across many files and services. Traditional single‑tool scanners catch some classes of issues but often miss others, and they rarely offer actionable fixes. Codetective approaches the problem as a coordinated, multi‑agent system: specialized agents analyze code through different lenses (pattern‑based SAST, dependency and misconfiguration scanning, and AI‑assisted review), while an orchestrator stitches their findings into a coherent story and can automatically suggest or apply improvements. The result is a practical workflow that not only detects problems, but also helps teams remediate them quickly.
In other words, Codetective is designed to be useful during day‑to‑day development and code review. It integrates cleanly into CLI and GUI flows, produces a standard JSON output you can consume in CI, and—when enabled—uses a local LLM to generate comments or edits that explain “why” and “how” to fix issues in context.
Codetective merges a few core ideas into one developer‑friendly workflow. It combines specialized agents (SemGrep, Trivy, and an AI reviewer) to surface issues from different angles, and it uses an orchestrator to sequence and aggregate results. In practice, you run a scan on your repository, review the unified findings, and optionally apply automated fixes or insert concise explanatory comments. Everything is available from the command line and a streamlined web interface.
Key capabilities include multi‑agent scanning, automated fixing, a JSON results format for downstream tooling, and a configurable runtime that can execute agents sequentially or in parallel. The system is built to be practical: it can run with or without AI features, and it aims to provide explanations that are short enough to be helpful in code reviews.
Before installing Codetective, ensure you have the following tools installed:
pip install semgrep
ollama pull codellamaollama start# Clone the repository git clone https://github.com/codetective/codetective.git cd codetective # Install the package pip install -e . # OR make install # Or install from PyPI pip install codetective
ollama start
codetective info
This will show you which tools are available and their versions.
# Scan current directory with all agents codetective scan . # Scan specific paths with selected agents codetective scan /path/to/code --agents semgrep,trivy --timeout 600 # Custom output file codetective scan . --output my_scan_results.json
# Apply automatic fixes codetective fix codetective_scan_results.json
# Add explanatory comments instead codetective fix codetective_scan_results.json --agent comment
# Launch NiceGUI interface codetective gui # Custom host and port codetective gui --host 0.0.0.0 --port 7891
Then open your browser to http://localhost:7891 (NiceGUI)
codetective infoCheck system compatibility and tool availability.
codetective scan [paths]Execute multi-agent code scanning.
Options:
-a, --agents: Comma-separated agents (semgrep,trivy,ai_review)-t, --timeout: Timeout in seconds (default: 900)-o, --output: Output JSON file (default: codetective_scan_results.json)Examples:
codetective scan . codetective scan src/ tests/ --agents semgrep,trivy --timeout 600 codetective scan . --output security_scan.json
codetective fix <json_file>Apply automated fixes to identified issues.
Options:
-a, --agent: Fix agent (comment,edit) (default: edit)--keep-backup: Keep backup files after fix completion--selected-issues: Comma-separated list of issue IDs to fixExamples:
codetective fix scan_results.json codetective fix scan_results.json --agent comment
Codetective offers a modern web interface:
A modern, responsive web interface with better state management and real-time updates.
Codetective always outputs results in a standardized JSON format:
{ "timestamp": "2024-01-01T12:00:00", "scan_path": "/path/to/project", "semgrep_results": [ { "id": "semgrep-rule-file-line", "title": "Issue title", "description": "Detailed description", "severity": "high", "file_path": "/path/to/file.py", "line_number": 42, "rule_id": "rule.id", "fix_suggestion": "Suggested fix", "status": "detected" } ], "trivy_results": [...], "ai_review_results": [...], "total_issues": 15, "scan_duration": 45.2 }
SemGrepAgent (agents/scan/semgrep_agent.py)
Issue list with rule_id, severity, file_path, line_number, and optional autofix hint as fix_suggestion.TrivyAgent (agents/scan/trivy_agent.py)
Issue list synthesized from Trivy JSON: Vulnerabilities (VulnerabilityID), Secrets, and Misconfigurations.DynamicAIReviewAgent (agents/scan/dynamic_ai_review_agent.py)
Issue entries summarizing key risks and recommendations (consolidated per file).CommentAgent (agents/output/comment_agent.py)
Issue list (from scan results).Issue list (status remains detected/failed) and modified files (if applicable).EditAgent (agents/output/edit_agent.py)
Issue list (from scan results).Issue list with statuses (FIXED/FAILED) and list of modified files.Codetective is built to fail safely and keep you informed. The orchestrator in core/orchestrator.py records per‑agent errors without halting the entire run: during sequential scans, _run_all_agents() wraps each agent in try/except and appends human‑readable messages to error_messages; during parallel scans, the ThreadPoolExecutor loop captures exceptions from futures and prints a clear note while still aggregating results from successful agents. This means a transient failure in, say, Trivy, won’t prevent SemGrep or the AI reviewer from completing.
External processes are executed through utils/process_utils.py::run_command(), which applies timeouts (configurable via Config.agent_timeout) and attempts graceful termination (SIGTERM) before forceful termination when supported by the OS. Output is always captured as text with replacement for invalid characters so logs remain readable. On timeout, the function returns a failed status with a descriptive message rather than raising, allowing upstream code to handle it predictably.
Agents check their own readiness. For example, SemGrepAgent.is_available() and TrivyAgent.is_available() verify tool availability via utils/system_utils.py; the AI‑based agents inherit from agents/ai_base.py, where is_ai_available() verifies Ollama connectivity and call_ai() centralizes error handling. When Ollama is unreachable, users see a specific, actionable error string (e.g., model not found, connection refused).
When modifying files, safety comes first. The CommentAgent and EditAgent can create backup files prior to changes and respect the keep_backup setting in Config. The comment agent formats annotations using the host language’s comment style, preserves indentation, and handles edge cases such as unknown line numbers by placing notes at the file head. The edit agent processes issues in stable batches to avoid line‑shift hazards and writes back only when a meaningful change has been produced by the model.
Input scope is bounded to keep runs stable and fast. utils/file_utils.py validates paths, respects .gitignore, enforces maximum file size (Config.max_file_size), and allows inclusion/exclusion patterns, while utils/git_utils.py can focus on tracked or changed files. Together, they reduce noise and resource usage on large repositories.
Finally, results are standardized. Both scan and fix operations serialize their outputs (models/schemas.py) with timestamps, durations, and per‑agent summaries. This makes failures auditable and performance measurable across runs, even when some agents are temporarily unavailable.
Codetective uses a multi-agent architecture orchestrated by LangGraph:
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ CLI/GUI │ │ Orchestrator │ │ Config │
│ Interface │───▶│ (LangGraph) │◀───│ Management │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───────▼──────┐ ┌──────▼──────┐ ┌──────▼───────┐
│ Scan Agents │ │Output Agents│ │ Utils │
│ │ │ │ │ │
│ • SemGrep │ │ • Comment │ │ • File I/O │
│ • Trivy │ │ • Edit │ │ • Validation │
│ • AI Review │ │ │ │ • System │
└──────────────┘ └─────────────┘ └──────────────┘
Three-Layer Defense Architecture - Complete security refactoring with clear separation of concerns:
Contributions to the Codetective are welcome. Follow the CONTRIBUTING.md for contribution guidelines.
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)This application is open-source and is released under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. See the LICENSE file for details.
Shield: 
This work is licensed under a
Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
