flagrant 0.1.0__tar.gz

flagrant-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+venv/
+__pycache__/
+*.pyc
+.env
+demo/

flagrant-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 parrwiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flagrant-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: flagrant
+Version: 0.1.0
+Summary: Local AI code reviewer for pre-commit checks.
+Project-URL: Homepage, https://github.com/flagrant/flagrant
+Project-URL: Repository, https://github.com/flagrant/flagrant
+Author: Flagrant
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cli,code-review,developer-tools,linting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer[all]>=0.9.0
+Description-Content-Type: text/markdown
+
+# flagrant
+
+CLI tool that reviews your code before you commit. Uses LLMs to catch bugs, security issues, and bad patterns the same way a senior dev would in a PR review.
+
+```
+$ flagrant --staged
+
+───────────────────────────────────
+ flagrant | 3 issues flagged  (1 high | 1 medium | 1 low)
+───────────────────────────────────
+
+  ● HIGH    auth.py line 34
+             SQL query built with string concatenation
+             Fix: use parameterized queries
+
+  ● MEDIUM  utils.py line 12
+             Function has no error handling
+             Fix: wrap in try/except, handle edge cases
+
+  ● LOW     main.py line 5
+             Unused import os
+             Fix: remove it
+───────────────────────────────────
+```
+
+Exits with code 1 on high-severity issues. Works as a pre-commit hook.
+
+## install
+
+```bash
+pip install flagrant
+```
+
+## usage
+
+```bash
+flagrant .                  # review entire repo
+flagrant --staged           # only staged changes (fast, cheap)
+flagrant --file app.py      # single file
+flagrant --strict           # security-focused pass
+flagrant --explain          # explain why each issue matters
+```
+
+First run prompts for your API key. Supports **Claude**, **OpenAI**, **Gemini**, and **DeepSeek**.
+
+```bash
+flagrant config             # switch provider or update key
+```
+
+## git hook
+
+```bash
+flagrant install-hook       # auto-review on every commit
+flagrant remove-hook        # undo
+```
+
+Blocks commits with high-severity issues. Skip with `git commit --no-verify`.
+
+## project config
+
+Drop a `.flagrant` file in your repo root:
+
+```json
+{
+  "ignore": ["migrations/", "tests/", "vendor/"],
+  "strict": true,
+  "explain": false,
+  "language": "python"
+}
+```
+
+## how it works
+
+1. Reads your files or git diff
+2. Chunks large files to fit context windows
+3. Sends to your configured LLM with a review-focused system prompt
+4. Parses structured JSON issues from the response
+5. Prints results, returns exit code 1 if anything is high severity
+
+No telemetry. No accounts. Your code goes straight to whichever LLM provider you pick and nowhere else.
+
+## providers
+
+| Provider | Default model | Env var |
+|----------|--------------|---------|
+| Claude | claude-sonnet-4-20250514 | `ANTHROPIC_API_KEY` |
+| OpenAI | gpt-4o | `OPENAI_API_KEY` |
+| Gemini | gemini-2.5-flash | `GEMINI_API_KEY` |
+| DeepSeek | deepseek-chat | `DEEPSEEK_API_KEY` |
+
+## license
+
+MIT

flagrant-0.1.0/README.md

@@ -0,0 +1,93 @@
+# flagrant
+
+CLI tool that reviews your code before you commit. Uses LLMs to catch bugs, security issues, and bad patterns the same way a senior dev would in a PR review.
+
+```
+$ flagrant --staged
+
+───────────────────────────────────
+ flagrant | 3 issues flagged  (1 high | 1 medium | 1 low)
+───────────────────────────────────
+
+  ● HIGH    auth.py line 34
+             SQL query built with string concatenation
+             Fix: use parameterized queries
+
+  ● MEDIUM  utils.py line 12
+             Function has no error handling
+             Fix: wrap in try/except, handle edge cases
+
+  ● LOW     main.py line 5
+             Unused import os
+             Fix: remove it
+───────────────────────────────────
+```
+
+Exits with code 1 on high-severity issues. Works as a pre-commit hook.
+
+## install
+
+```bash
+pip install flagrant
+```
+
+## usage
+
+```bash
+flagrant .                  # review entire repo
+flagrant --staged           # only staged changes (fast, cheap)
+flagrant --file app.py      # single file
+flagrant --strict           # security-focused pass
+flagrant --explain          # explain why each issue matters
+```
+
+First run prompts for your API key. Supports **Claude**, **OpenAI**, **Gemini**, and **DeepSeek**.
+
+```bash
+flagrant config             # switch provider or update key
+```
+
+## git hook
+
+```bash
+flagrant install-hook       # auto-review on every commit
+flagrant remove-hook        # undo
+```
+
+Blocks commits with high-severity issues. Skip with `git commit --no-verify`.
+
+## project config
+
+Drop a `.flagrant` file in your repo root:
+
+```json
+{
+  "ignore": ["migrations/", "tests/", "vendor/"],
+  "strict": true,
+  "explain": false,
+  "language": "python"
+}
+```
+
+## how it works
+
+1. Reads your files or git diff
+2. Chunks large files to fit context windows
+3. Sends to your configured LLM with a review-focused system prompt
+4. Parses structured JSON issues from the response
+5. Prints results, returns exit code 1 if anything is high severity
+
+No telemetry. No accounts. Your code goes straight to whichever LLM provider you pick and nowhere else.
+
+## providers
+
+| Provider | Default model | Env var |
+|----------|--------------|---------|
+| Claude | claude-sonnet-4-20250514 | `ANTHROPIC_API_KEY` |
+| OpenAI | gpt-4o | `OPENAI_API_KEY` |
+| Gemini | gemini-2.5-flash | `GEMINI_API_KEY` |
+| DeepSeek | deepseek-chat | `DEEPSEEK_API_KEY` |
+
+## license
+
+MIT

flagrant-0.1.0/flagrant/__init__.py

@@ -0,0 +1,3 @@
+"""Flagrant: Flagrant is a local AI code reviewer that saves you from embarassing mistakes."""
+
+__version__ = "1.0.1"

flagrant-0.1.0/flagrant/config.py

@@ -0,0 +1,174 @@
+"""Project config and API key management."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from dotenv import load_dotenv
+from rich.console import Console
+from rich.prompt import Prompt, Confirm
+
+console = Console()
+
+CONFIG_DIR = Path.home() / ".config" / "flagrant"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+PROVIDERS = {
+    "claude": {
+        "name": "Claude (Anthropic)",
+        "env_var": "ANTHROPIC_API_KEY",
+        "models": ["claude-sonnet-4-20250514", "claude-3-5-sonnet-20241022"],
+    },
+    "openai": {
+        "name": "OpenAI",
+        "env_var": "OPENAI_API_KEY",
+        "models": ["gpt-4o", "gpt-4o-mini"],
+    },
+    "gemini": {
+        "name": "Gemini (Google)",
+        "env_var": "GEMINI_API_KEY",
+        "models": ["gemini-2.5-pro", "gemini-2.5-pro"],
+    },
+    "deepseek": {
+        "name": "DeepSeek",
+        "env_var": "DEEPSEEK_API_KEY",
+        "models": ["deepseek-chat", "deepseek-chat"],
+    },
+}
+
+
+@dataclass
+class ProjectConfig:
+    """Per-project .flagrant config."""
+    ignore: list[str] = field(default_factory=list)
+    strict: bool = False
+    explain: bool = False
+    language: str = "auto"
+
+
+@dataclass
+class AppConfig:
+    """Global app config (API key + provider)."""
+    provider: str = "claude"
+    api_key: str = ""
+    model: Optional[str] = None
+
+    @property
+    def effective_model(self) -> str:
+        if self.model:
+            return self.model
+        return PROVIDERS[self.provider]["models"][0]
+
+
+def load_project_config(repo_root: Path) -> ProjectConfig:
+    """Load .flagrant config from repo root, or return defaults."""
+    config_path = repo_root / ".flagrant"
+    if not config_path.exists():
+        return ProjectConfig()
+
+    try:
+        with open(config_path) as f:
+            data = json.load(f)
+        return ProjectConfig(
+            ignore=data.get("ignore", []),
+            strict=data.get("strict", False),
+            explain=data.get("explain", False),
+            language=data.get("language", "auto"),
+        )
+    except (json.JSONDecodeError, OSError) as e:
+        console.print(f"[yellow]warning: could not parse .flagrant config: {e}[/yellow]")
+        return ProjectConfig()
+
+
+def _save_app_config(config: AppConfig) -> None:
+    """Write config to disk."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    data = {
+        "provider": config.provider,
+        "api_key": config.api_key,
+        "model": config.model,
+    }
+    with open(CONFIG_FILE, "w") as f:
+        json.dump(data, f, indent=2)
+
+
+def _load_saved_config() -> Optional[AppConfig]:
+    """Load config from disk, if it exists."""
+    if not CONFIG_FILE.exists():
+        return None
+    try:
+        with open(CONFIG_FILE) as f:
+            data = json.load(f)
+        return AppConfig(
+            provider=data.get("provider", "claude"),
+            api_key=data.get("api_key", ""),
+            model=data.get("model"),
+        )
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _check_env_key() -> Optional[AppConfig]:
+    """Check environment variables for API keys."""
+    load_dotenv()
+    for provider_id, info in PROVIDERS.items():
+        key = os.getenv(info["env_var"])
+        if key:
+            return AppConfig(provider=provider_id, api_key=key)
+    return None
+
+
+def setup_api_key_interactive() -> AppConfig:
+    """Run the interactive API key setup prompt."""
+    console.print()
+    console.print("[bold cyan]flagrant setup[/bold cyan]")
+    console.print()
+    console.print("Choose your AI provider:")
+    console.print("  [bold]1[/bold]  Claude (Anthropic)")
+    console.print("  [bold]2[/bold]  OpenAI")
+    console.print("  [bold]3[/bold]  Gemini (Google)")
+    console.print("  [bold]4[/bold]  DeepSeek")
+    console.print()
+
+    choice = Prompt.ask("Provider", choices=["1", "2", "3", "4"], default="1")
+    provider_map = {"1": "claude", "2": "openai", "3": "gemini", "4": "deepseek"}
+    provider = provider_map[choice]
+
+    info = PROVIDERS[provider]
+    console.print()
+    api_key = Prompt.ask(f"Paste your {info['name']} API key")
+
+    if not api_key.strip():
+        console.print("[red]error: no API key provided[/red]")
+        raise SystemExit(1)
+
+    config = AppConfig(provider=provider, api_key=api_key.strip())
+    _save_app_config(config)
+
+    console.print(f"[green]saved. using {info['name']}[/green]")
+    console.print(f"[dim]Config stored at {CONFIG_FILE}[/dim]")
+    console.print()
+    return config
+
+
+def get_app_config(require_key: bool = True) -> AppConfig:
+    """Resolve API config. Checks env, then saved config, then prompts."""
+    # 1. Environment variable
+    env_config = _check_env_key()
+    if env_config and env_config.api_key:
+        return env_config
+
+    # 2. Saved config
+    saved = _load_saved_config()
+    if saved and saved.api_key:
+        return saved
+
+    # 3. Interactive setup
+    if not require_key:
+        return AppConfig()
+
+    return setup_api_key_interactive()

flagrant-0.1.0/flagrant/formatter.py

@@ -0,0 +1,91 @@
+"""Terminal output formatting."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from flagrant.reviewer import Issue
+
+console = Console()
+
+SEVERITY_STYLES = {
+    "high": ("bold red", "●", "HIGH  "),
+    "medium": ("bold yellow", "●", "MEDIUM"),
+    "low": ("bold blue", "●", "LOW   "),
+}
+
+
+def display_issues(issues: list[Issue], explain: bool = False) -> None:
+    """Print review issues to the terminal."""
+    if not issues:
+        console.print()
+        console.print("[bold green]no issues found[/bold green]")
+        console.print()
+        return
+
+    # Sort: high first, then medium, then low
+    severity_order = {"high": 0, "medium": 1, "low": 2}
+    issues.sort(key=lambda i: severity_order.get(i.severity, 3))
+
+    # Count by severity
+    counts = {}
+    for issue in issues:
+        counts[issue.severity] = counts.get(issue.severity, 0) + 1
+
+    # Header
+    total = len(issues)
+    header_parts = []
+    if counts.get("high"):
+        header_parts.append(f"[bold red]{counts['high']} high[/bold red]")
+    if counts.get("medium"):
+        header_parts.append(f"[bold yellow]{counts['medium']} medium[/bold yellow]")
+    if counts.get("low"):
+        header_parts.append(f"[bold blue]{counts['low']} low[/bold blue]")
+
+    summary = " | ".join(header_parts)
+
+    console.print()
+    console.rule(style="dim")
+    console.print(
+        f" [bold]flagrant[/bold] | {total} issue{'s' if total != 1 else ''} flagged  ({summary})",
+    )
+    console.rule(style="dim")
+
+    # Issues
+    for issue in issues:
+        style, bullet, label = SEVERITY_STYLES.get(
+            issue.severity, ("dim", "○", "???   ")
+        )
+
+        line_str = f" line {issue.line}" if issue.line else ""
+        location = f"{issue.file}{line_str}"
+
+        console.print()
+        console.print(f"  [{style}]{bullet} {label}[/{style}]  [bold]{location}[/bold]")
+        console.print(f"           {issue.issue}")
+        if issue.fix:
+            console.print(f"           [dim]Fix: {issue.fix}[/dim]")
+
+        if explain and issue.explanation:
+            console.print(f"           [italic cyan]{issue.explanation}[/italic cyan]")
+
+    console.print()
+    console.rule(style="dim")
+    console.print()
+
+
+def display_error(message: str) -> None:
+    """Print an error."""
+    console.print(f"\n[bold red]error: {message}[/bold red]\n")
+
+
+def display_info(message: str) -> None:
+    """Print an info message."""
+    console.print(f"\n[dim]{message}[/dim]\n")
+
+
+def display_success(message: str) -> None:
+    """Print a success message."""
+    console.print(f"\n[green]{message}[/green]\n")

flagrant-0.1.0/flagrant/git_utils.py

@@ -0,0 +1,151 @@
+"""Git helpers."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from git import Repo, InvalidGitRepositoryError
+from rich.console import Console
+
+console = Console()
+
+
+BINARY_EXTENSIONS = {
+    ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".svg", ".webp",
+    ".mp3", ".mp4", ".avi", ".mov", ".wav", ".flac",
+    ".zip", ".tar", ".gz", ".bz2", ".7z", ".rar",
+    ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
+    ".exe", ".dll", ".so", ".dylib", ".o", ".a",
+    ".pyc", ".pyo", ".class", ".wasm",
+    ".ttf", ".otf", ".woff", ".woff2", ".eot",
+    ".sqlite", ".db",
+}
+
+def get_git_root(path: str = ".") -> Optional[Path]:
+    """Find the git repo root from the given path."""
+    try:
+        repo = Repo(path, search_parent_directories=True)
+        return Path(repo.working_dir)
+    except InvalidGitRepositoryError:
+        return None
+
+
+def _is_binary_path(filepath: str) -> bool:
+    """Check if a file is likely binary based on extension."""
+    return Path(filepath).suffix.lower() in BINARY_EXTENSIONS
+
+
+def _is_binary_content(filepath: Path) -> bool:
+    """Check for null bytes."""
+    try:
+        with open(filepath, "rb") as f:
+            chunk = f.read(8192)
+            return b"\x00" in chunk
+    except OSError:
+        return True
+
+
+def get_staged_diff(repo_path: str = ".") -> Optional[str]:
+    """Get the unified diff of all staged changes."""
+    try:
+        repo = Repo(repo_path, search_parent_directories=True)
+        diff = repo.git.diff("--cached", "--unified=3")
+        return diff if diff.strip() else None
+    except Exception:
+        return None
+
+
+def get_staged_files(repo_path: str = ".") -> list[dict]:
+    """Get staged file contents. Skips binaries."""
+    files = []
+    try:
+        repo = Repo(repo_path, search_parent_directories=True)
+        root = Path(repo.working_dir)
+
+        # Get list of staged file paths
+        staged = repo.git.diff("--cached", "--name-only").strip()
+        if not staged:
+            return files
+
+        for rel_path in staged.splitlines():
+            rel_path = rel_path.strip()
+            if not rel_path or _is_binary_path(rel_path):
+                continue
+
+            full_path = root / rel_path
+            if not full_path.exists() or _is_binary_content(full_path):
+                continue
+
+            try:
+                content = full_path.read_text(encoding="utf-8", errors="replace")
+                files.append({"path": rel_path, "content": content})
+            except OSError:
+                continue
+
+    except Exception:
+        pass
+
+    return files
+
+
+def get_repo_files(
+    path: str = ".",
+    ignore_patterns: list[str] | None = None,
+) -> list[dict]:
+    """Get all tracked non-binary files in the repo."""
+    files = []
+    ignore_patterns = ignore_patterns or []
+
+    try:
+        repo = Repo(path, search_parent_directories=True)
+        root = Path(repo.working_dir)
+
+        tracked = repo.git.ls_files().strip()
+        if not tracked:
+            return files
+
+        for rel_path in tracked.splitlines():
+            rel_path = rel_path.strip()
+            if not rel_path or _is_binary_path(rel_path):
+                continue
+
+            # Check ignore patterns
+            if any(_matches_ignore(rel_path, pat) for pat in ignore_patterns):
+                continue
+
+            full_path = root / rel_path
+            if not full_path.exists() or _is_binary_content(full_path):
+                continue
+
+            try:
+                content = full_path.read_text(encoding="utf-8", errors="replace")
+                files.append({"path": rel_path, "content": content})
+            except OSError:
+                continue
+
+    except Exception:
+        pass
+
+    return files
+
+
+def read_single_file(filepath: str) -> Optional[dict]:
+    """Read a single file, returning {path, content} or None."""
+    p = Path(filepath)
+    if not p.exists():
+        return None
+    if _is_binary_path(filepath) or _is_binary_content(p):
+        return None
+    try:
+        content = p.read_text(encoding="utf-8", errors="replace")
+        return {"path": str(p), "content": content}
+    except OSError:
+        return None
+
+
+def _matches_ignore(filepath: str, pattern: str) -> bool:
+    """Check if filepath matches an ignore pattern."""
+    pattern = pattern.rstrip("/")
+    return filepath.startswith(pattern) or f"/{pattern}" in filepath

flagrant-0.1.0/flagrant/main.py

@@ -0,0 +1,306 @@
+"""CLI entry points."""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+import typer
+from rich.console import Console
+from rich.spinner import Spinner
+from rich.live import Live
+
+from flagrant.config import (
+    get_app_config,
+    load_project_config,
+    setup_api_key_interactive,
+    AppConfig,
+    PROVIDERS,
+)
+from flagrant.git_utils import (
+    get_git_root,
+    get_staged_diff,
+    get_staged_files,
+    get_repo_files,
+    read_single_file,
+)
+from flagrant.reviewer import review_code, review_diff, Issue
+from flagrant.formatter import (
+    display_issues,
+    display_error,
+    display_info,
+    display_success,
+)
+
+console = Console()
+
+_SUBCOMMANDS = {"config", "install-hook", "remove-hook"}
+
+
+def _run_review(
+    files: list[dict],
+    app_config: AppConfig,
+    strict: bool,
+    explain: bool,
+    diff_mode: bool,
+    language: str,
+    diff_text: Optional[str] = None,
+) -> list[Issue]:
+    """Run the review, show a spinner while waiting."""
+    provider_name = PROVIDERS[app_config.provider]["name"]
+    model = app_config.effective_model
+
+    with Live(
+        Spinner("dots", text=f"  [dim]Reviewing with {provider_name} ({model})...[/dim]"),
+        console=console,
+        transient=True,
+    ):
+        if diff_mode and diff_text:
+            issues = review_diff(
+                diff_text=diff_text,
+                app_config=app_config,
+                strict=strict,
+                explain=explain,
+                language=language,
+            )
+        else:
+            issues = review_code(
+                files=files,
+                app_config=app_config,
+                strict=strict,
+                explain=explain,
+                diff_mode=diff_mode,
+                language=language,
+            )
+
+    return issues
+
+
+def do_review(
+    path: Optional[str] = None,
+    staged: bool = False,
+    file: Optional[str] = None,
+    strict: bool = False,
+    explain: bool = False,
+) -> None:
+    """Run a review based on CLI args."""
+    # Default to current dir
+    if path is None and not staged and file is None:
+        path = "."
+
+    # Load configs
+    try:
+        app_config = get_app_config()
+    except SystemExit:
+        raise typer.Exit(1)
+
+    repo_root = get_git_root(path or ".")
+    project_config = load_project_config(repo_root) if repo_root else None
+
+    # Merge project config with CLI flags
+    if project_config:
+        strict = strict or project_config.strict
+        explain = explain or project_config.explain
+        language = project_config.language
+        ignore_patterns = project_config.ignore
+    else:
+        language = "auto"
+        ignore_patterns = []
+
+    # Determine what to review
+    files: list[dict] = []
+    diff_text: Optional[str] = None
+    diff_mode = False
+
+    if file:
+        # Single file mode
+        result = read_single_file(file)
+        if not result:
+            display_error(f"Cannot read file: {file}")
+            raise typer.Exit(1)
+        files = [result]
+    elif staged:
+        # staged changes -- review the diff
+        diff_text = get_staged_diff(path or ".")
+        if not diff_text:
+            display_info("nothing staged")
+            raise typer.Exit(0)
+        diff_mode = True
+    else:
+        # Full repo/directory scan
+        target = path or "."
+        target_path = Path(target)
+
+        if target_path.is_file():
+            result = read_single_file(str(target_path))
+            if not result:
+                display_error(f"Cannot read file: {target}")
+                raise typer.Exit(1)
+            files = [result]
+        else:
+            files = get_repo_files(target, ignore_patterns=ignore_patterns)
+            if not files:
+                display_info("no reviewable files found")
+                raise typer.Exit(0)
+
+            # limit how much we send to the api
+            if len(files) > 50:
+                console.print(
+                    f"[yellow]{len(files)} files found, reviewing first 50. "
+                    f"use --file or --staged to narrow scope.[/yellow]"
+                )
+                files = files[:50]
+
+    # Run review
+    try:
+        issues = _run_review(
+            files=files,
+            app_config=app_config,
+            strict=strict,
+            explain=explain,
+            diff_mode=diff_mode,
+            language=language,
+            diff_text=diff_text,
+        )
+    except RuntimeError:
+        display_error("review failed. check your API key and account balance.")
+        raise typer.Exit(1)
+
+    # Display results
+    display_issues(issues, explain=explain)
+
+    # Exit code 1 if high severity issues found
+    if any(i.severity == "high" for i in issues):
+        raise typer.Exit(1)
+
+
+
+
+class FlagrantCLI(click.Group):
+    """Routes bare args to the review subcommand."""
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        if args:
+
+            first_non_opt = None
+            for a in args:
+                if not a.startswith("-"):
+                    first_non_opt = a
+                    break
+
+            if first_non_opt is None or first_non_opt not in self.commands:
+                args = ["review"] + args
+
+        if not args:
+            args = ["review"]
+
+        return super().parse_args(ctx, args)
+
+
+@click.group(cls=FlagrantCLI)
+def app():
+    """flagrant - local AI code reviewer."""
+    pass
+
+
+@app.command("review")
+@click.argument("path", required=False, default=None)
+@click.option("--staged", "-s", is_flag=True, help="Only review staged git changes.")
+@click.option("--file", "-f", "file_path", default=None, help="Review a single file.")
+@click.option("--strict", is_flag=True, help="Security-focused review pass.")
+@click.option("--explain", "-e", is_flag=True, help="Include teaching explanations.")
+def review_cmd(path, staged, file_path, strict, explain):
+    """Review code for issues like a senior developer would."""
+    do_review(path=path, staged=staged, file=file_path, strict=strict, explain=explain)
+
+
+@app.command("config")
+def configure():
+    """Reconfigure API key and provider settings."""
+    setup_api_key_interactive()
+
+
+PRE_COMMIT_HOOK = """#!/bin/sh
+# flagrant pre-commit hook
+# Installed by: flagrant install-hook
+
+flagrant --staged
+exit_code=$?
+
+if [ $exit_code -ne 0 ]; then
+    echo ""
+    echo "flagrant: commit blocked (high severity issues found)"
+    echo "   Fix the issues above, or commit with --no-verify to skip."
+    echo ""
+fi
+
+exit $exit_code
+"""
+
+
+@app.command("install-hook")
+def install_hook():
+    """Install a pre-commit git hook that runs flagrant --staged."""
+    repo_root = get_git_root(".")
+    if not repo_root:
+        display_error("Not inside a git repository.")
+        raise SystemExit(1)
+
+    hooks_dir = repo_root / ".git" / "hooks"
+    hook_path = hooks_dir / "pre-commit"
+
+    if hook_path.exists():
+        content = hook_path.read_text()
+        if "flagrant" in content.lower():
+            display_info("Flagrant pre-commit hook is already installed.")
+            return
+        else:
+            display_error(
+                f"A pre-commit hook already exists at {hook_path}.\n"
+                "  Back it up or remove it, then try again."
+            )
+            raise SystemExit(1)
+
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook_path.write_text(PRE_COMMIT_HOOK)
+    hook_path.chmod(hook_path.stat().st_mode | stat.S_IEXEC)
+
+    display_success(f"Pre-commit hook installed at {hook_path}")
+    console.print(
+        "[dim]  It will run [bold]flagrant --staged[/bold] before every commit.\n"
+        "  Use [bold]git commit --no-verify[/bold] to skip.[/dim]\n"
+    )
+
+
+@app.command("remove-hook")
+def remove_hook():
+    """Remove the flagrant pre-commit hook."""
+    repo_root = get_git_root(".")
+    if not repo_root:
+        display_error("Not inside a git repository.")
+        raise SystemExit(1)
+
+    hook_path = repo_root / ".git" / "hooks" / "pre-commit"
+
+    if not hook_path.exists():
+        display_info("no pre-commit hook found.")
+        return
+
+    content = hook_path.read_text()
+    if "flagrant" not in content.lower():
+        display_error(
+            "The existing pre-commit hook was not installed by Flagrant.\n"
+            "  Remove it manually if needed."
+        )
+        raise SystemExit(1)
+
+    hook_path.unlink()
+    display_success("Pre-commit hook removed.")
+
+
+if __name__ == "__main__":
+    app()

flagrant-0.1.0/flagrant/prompt.py

@@ -0,0 +1,83 @@
+"""Prompt construction."""
+
+from __future__ import annotations
+
+
+BASE_PROMPT = """You are a senior software engineer doing a code review. Be direct and blunt.
+You care about real, practical issues, not nitpicking style and formatting.
+
+For each issue found return a JSON array in this exact format:
+[
+  {
+    "severity": "high|medium|low",
+    "file": "filename",
+    "line": <line_number_or_null>,
+    "issue": "one sentence describing the problem",
+    "fix": "one sentence describing the solution"
+  }
+]
+
+Return ONLY the JSON array. No preamble. No markdown. No commentary.
+If you find no issues, return an empty array: []
+
+Severity rules:
+- high: security vulnerabilities, data loss risk, crashes, broken logic
+- medium: bad patterns, missing error handling, performance issues, race conditions
+- low: unused code, minor improvements, documentation gaps
+
+Be selective. Only flag things that actually matter. Do NOT flag:
+- Style preferences or formatting
+- Missing type hints (unless causing bugs)
+- Things that are obviously intentional
+- Test files unless they have actual bugs"""
+
+
+STRICT_ADDON = """
+
+STRICT MODE - security-focused review. Prioritize:
+- SQL injection, XSS, command injection, path traversal
+- Hardcoded secrets, credentials, API keys in code
+- Insecure crypto, weak hashing, cleartext passwords
+- SSRF, open redirects, insecure deserialization
+- Missing input validation on user-facing endpoints
+- Overly permissive file/network access
+Flag ALL security concerns as HIGH severity."""
+
+
+EXPLAIN_ADDON = """
+
+For EVERY issue, include an additional field:
+  "explanation": "2-3 sentences teaching why this matters and what could go wrong"
+
+This is for educational purposes - explain like you're mentoring a junior developer."""
+
+
+DIFF_MODE_ADDON = """
+
+You are reviewing a git diff. Focus ONLY on the changed lines (lines starting with +).
+The file paths and line numbers are shown in the diff headers.
+Do not flag issues in unchanged code (context lines) unless a change introduced a bug that interacts with existing code."""
+
+
+def build_system_prompt(
+    strict: bool = False,
+    explain: bool = False,
+    diff_mode: bool = False,
+    language: str = "auto",
+) -> str:
+    """Build the full system prompt with optional addons."""
+    prompt = BASE_PROMPT
+
+    if language != "auto":
+        prompt += f"\n\nThe codebase is primarily written in {language}."
+
+    if diff_mode:
+        prompt += DIFF_MODE_ADDON
+
+    if strict:
+        prompt += STRICT_ADDON
+
+    if explain:
+        prompt += EXPLAIN_ADDON
+
+    return prompt

flagrant-0.1.0/flagrant/reviewer.py

@@ -0,0 +1,299 @@
+"""Review logic."""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+from rich.console import Console
+
+from flagrant.config import AppConfig, PROVIDERS
+from flagrant.prompt import build_system_prompt
+
+console = Console()
+
+MAX_LINES_PER_CHUNK = 3000
+MAX_RETRIES = 1
+
+
+@dataclass
+class Issue:
+    """A single code review issue."""
+    severity: str  # high, medium, low
+    file: str
+    line: Optional[int]
+    issue: str
+    fix: str
+    explanation: Optional[str] = None
+
+
+def chunk_files(files: list[dict], max_lines: int = MAX_LINES_PER_CHUNK) -> list[str]:
+    """Split files into chunks that fit context limits."""
+    chunks = []
+    current_chunk_lines = 0
+    current_chunk_parts = []
+
+    for f in files:
+        content = f["content"]
+        lines = content.splitlines()
+        file_header = f"--- FILE: {f['path']} ---"
+
+        # If single file exceeds max, split it
+        if len(lines) > max_lines:
+            # Flush current chunk first
+            if current_chunk_parts:
+                chunks.append("\n".join(current_chunk_parts))
+                current_chunk_parts = []
+                current_chunk_lines = 0
+
+            for i in range(0, len(lines), max_lines):
+                slice_lines = lines[i:i + max_lines]
+                part_header = f"{file_header} (lines {i + 1}-{i + len(slice_lines)})"
+                chunks.append(part_header + "\n" + "\n".join(slice_lines))
+        else:
+            # Would adding this file exceed the limit?
+            if current_chunk_lines + len(lines) > max_lines and current_chunk_parts:
+                chunks.append("\n".join(current_chunk_parts))
+                current_chunk_parts = []
+                current_chunk_lines = 0
+
+            current_chunk_parts.append(file_header + "\n" + content)
+            current_chunk_lines += len(lines)
+
+    # Flush remaining
+    if current_chunk_parts:
+        chunks.append("\n".join(current_chunk_parts))
+
+    return chunks
+
+
+def _parse_issues(raw: str) -> list[Issue]:
+    """Parse JSON issues from LLM response. Handles messy output."""
+    raw = raw.strip()
+
+    # Try direct parse first
+    try:
+        data = json.loads(raw)
+        if isinstance(data, list):
+            return [_dict_to_issue(d) for d in data if isinstance(d, dict)]
+    except json.JSONDecodeError:
+        pass
+
+    # Try to extract JSON array from surrounding text
+    match = re.search(r"\[.*\]", raw, re.DOTALL)
+    if match:
+        try:
+            data = json.loads(match.group())
+            if isinstance(data, list):
+                return [_dict_to_issue(d) for d in data if isinstance(d, dict)]
+        except json.JSONDecodeError:
+            pass
+
+    # If we got markdown-wrapped JSON, strip it
+    cleaned = re.sub(r"```(?:json)?\s*", "", raw)
+    cleaned = cleaned.strip().rstrip("`")
+    try:
+        data = json.loads(cleaned)
+        if isinstance(data, list):
+            return [_dict_to_issue(d) for d in data if isinstance(d, dict)]
+    except json.JSONDecodeError:
+        pass
+
+    return []
+
+
+def _dict_to_issue(d: dict) -> Issue:
+    return Issue(
+        severity=d.get("severity", "low").lower().strip(),
+        file=d.get("file", "unknown"),
+        line=d.get("line"),
+        issue=d.get("issue", ""),
+        fix=d.get("fix", ""),
+        explanation=d.get("explanation"),
+    )
+
+
+def _call_claude(
+    app_config: AppConfig,
+    system_prompt: str,
+    user_content: str,
+) -> str:
+    """Call Anthropic Claude API."""
+    from anthropic import Anthropic
+
+    client = Anthropic(api_key=app_config.api_key)
+    response = client.messages.create(
+        model=app_config.effective_model,
+        max_tokens=4096,
+        system=system_prompt,
+        messages=[{"role": "user", "content": user_content}],
+    )
+    return response.content[0].text
+
+
+def _call_openai(
+    app_config: AppConfig,
+    system_prompt: str,
+    user_content: str,
+) -> str:
+    """Call OpenAI API."""
+    from openai import OpenAI
+
+    client = OpenAI(api_key=app_config.api_key)
+    response = client.chat.completions.create(
+        model=app_config.effective_model,
+        max_tokens=4096,
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content},
+        ],
+    )
+    return response.choices[0].message.content
+
+
+def _call_gemini(
+    app_config: AppConfig,
+    system_prompt: str,
+    user_content: str,
+) -> str:
+    """Call Google Gemini API."""
+    from google import genai
+
+    client = genai.Client(api_key=app_config.api_key)
+    response = client.models.generate_content(
+        model=app_config.effective_model,
+        contents=user_content,
+        config=genai.types.GenerateContentConfig(
+            system_instruction=system_prompt,
+            max_output_tokens=4096,
+        ),
+    )
+    return response.text
+
+
+def _call_deepseek(
+    app_config: AppConfig,
+    system_prompt: str,
+    user_content: str,
+) -> str:
+    """Call DeepSeek API (OpenAI-compatible)."""
+    from openai import OpenAI
+
+    client = OpenAI(
+        api_key=app_config.api_key,
+        base_url="https://api.deepseek.com",
+    )
+    response = client.chat.completions.create(
+        model=app_config.effective_model,
+        max_tokens=4096,
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content},
+        ],
+    )
+    return response.choices[0].message.content
+
+
+PROVIDER_CALLERS = {
+    "claude": _call_claude,
+    "openai": _call_openai,
+    "gemini": _call_gemini,
+    "deepseek": _call_deepseek,
+}
+
+
+def _call_llm(
+    app_config: AppConfig,
+    system_prompt: str,
+    user_content: str,
+) -> str:
+    """Call the configured provider. Retries once on failure."""
+    caller = PROVIDER_CALLERS.get(app_config.provider)
+    if not caller:
+        raise ValueError(f"Unknown provider: {app_config.provider}")
+
+    last_error = None
+    for attempt in range(MAX_RETRIES + 1):
+        try:
+            return caller(app_config, system_prompt, user_content)
+        except Exception as e:
+            last_error = e
+            if attempt < MAX_RETRIES:
+                console.print(f"[yellow]warning: API call failed, retrying... ({e})[/yellow]")
+                time.sleep(2)
+
+    raise RuntimeError(
+        f"API call failed after {MAX_RETRIES + 1} attempts: {last_error}"
+    )
+
+
+def review_code(
+    files: list[dict],
+    app_config: AppConfig,
+    strict: bool = False,
+    explain: bool = False,
+    diff_mode: bool = False,
+    language: str = "auto",
+) -> list[Issue]:
+    """Review files. Chunks large inputs, calls the LLM, parses results."""
+    if not files:
+        return []
+
+    system_prompt = build_system_prompt(
+        strict=strict,
+        explain=explain,
+        diff_mode=diff_mode,
+        language=language,
+    )
+
+    chunks = chunk_files(files)
+    all_issues: list[Issue] = []
+    has_error = False
+
+    for i, chunk in enumerate(chunks):
+        if len(chunks) > 1:
+            console.print(
+                f"[dim]  scanning chunk {i + 1}/{len(chunks)}...[/dim]"
+            )
+
+        user_msg = "Review the following code:\n\n" + chunk
+        try:
+            raw = _call_llm(app_config, system_prompt, user_msg)
+            issues = _parse_issues(raw)
+            all_issues.extend(issues)
+        except RuntimeError as e:
+            console.print(f"[red]error: {e}[/red]")
+            has_error = True
+
+    if has_error and not all_issues:
+        raise RuntimeError("Review failed, could not reach the API.")
+
+    return all_issues
+
+
+def review_diff(
+    diff_text: str,
+    app_config: AppConfig,
+    strict: bool = False,
+    explain: bool = False,
+    language: str = "auto",
+) -> list[Issue]:
+    """Review a git diff string."""
+    system_prompt = build_system_prompt(
+        strict=strict,
+        explain=explain,
+        diff_mode=True,
+        language=language,
+    )
+
+    user_msg = "Review the following git diff:\n\n" + diff_text
+
+    try:
+        raw = _call_llm(app_config, system_prompt, user_msg)
+        return _parse_issues(raw)
+    except RuntimeError as e:
+        console.print(f"[red]error: {e}[/red]")
+        raise

flagrant-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flagrant"
+version = "0.1.0"
+description = "Local AI code reviewer for pre-commit checks."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Flagrant" },
+]
+keywords = ["code-review", "ai", "cli", "linting", "developer-tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "typer[all]>=0.9.0",
+    "rich>=13.0.0",
+    "gitpython>=3.1.0",
+    "anthropic>=0.40.0",
+    "openai>=1.0.0",
+    "google-genai>=1.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.scripts]
+flagrant = "flagrant.main:app"
+
+[project.urls]
+Homepage = "https://github.com/flagrant/flagrant"
+Repository = "https://github.com/flagrant/flagrant"

flagrant-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+# tests