CodeSentry

AI-assisted code review for local projects and public GitHub repositories.

CodeSentry is an interactive terminal agent and desktop-ready review system that scans source code, detects supported languages, runs a safe AI review pipeline, suggests fixes, and generates structured Markdown reports.

CodeSentry is designed as a language-agnostic code review system with initial support for Python, JavaScript, TypeScript, Java, C/C++, Rust, and Go, and an extensible architecture for adding more languages later.

Why CodeSentry?

Most code review tools are either static linters or chatbots. CodeSentry sits in the middle: it behaves like a coding agent, but keeps the review engine reusable, testable, and safe.

You can use it from:

• An interactive terminal agent
• A local FastAPI backend
• A Tauri desktop app

All interfaces call the same Python core engine.

Features

• Interactive terminal session with natural-language commands
• Local project review
• Public HTTPS GitHub repository review
• Temporary GitHub clone workspace with cleanup
• Multi-language scanning and language detection
• Language-aware review prompts
• Six-stage LangGraph review pipeline
• Mock, OpenAI, Anthropic, Gemini, Ollama, and NVIDIA provider abstraction
• Markdown report generation
• Local-only FastAPI backend for desktop integration
• Tauri v2 desktop frontend in development mode
• Safe Review Mode by default

Supported Languages

Language	Extensions
Python	.py
JavaScript	.js, .jsx, .mjs, .cjs
TypeScript	.ts, .tsx
Java	.java
C	.c, .h
C++	.cpp, .cc, .cxx, .hpp, .hh, .hxx
Rust	.rs
Go	.go

Language detection is extension-based first, with project config hints such as package.json, tsconfig.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, and CMakeLists.txt.

Safety Model

CodeSentry runs in Safe Review Mode.

It does not:

• Execute reviewed project code
• Install dependencies
• Run tests, package scripts, build tools, or pre-commit hooks
• Compile C/C++/Rust/Go/Java projects
• Modify source files
• Auto-apply fixes
• Ask for GitHub tokens
• Delete user project directories
• Send huge files blindly to cloud LLM providers

It does:

• Read supported source files
• Skip generated, minified, binary, lock, and oversized files
• Clone only validated public HTTPS GitHub repositories
• Use temporary workspaces for cloned repositories
• Ask before saving reports
• Warn before using cloud LLM providers

Quick Start

Install dependencies with uv:

uv sync

Run the terminal agent with the offline mock provider:

uv run codesentry --provider mock

Review the current project:

CodeSentry > scan this project
CodeSentry > show language breakdown
CodeSentry > review all supported languages
CodeSentry > generate markdown report
CodeSentry > exit

Installation

Requirements

• Python 3.10+
• uv
• Git
• Optional: Ollama for local model review
• Optional for desktop development: Node.js, pnpm, Rust, and Cargo

Environment

Copy .env.example to .env and configure your provider:

CODESENTRY_PROVIDER=mock
CODESENTRY_MODEL=

OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_API_KEY=
GEMINI_API_KEY=
NVIDIA_API_KEY=

OLLAMA_BASE_URL=http://localhost:11434
NVIDIA_BASE_URL=

Provider priority:

1. Launch argument
2. Environment variable
3. mock

Terminal Agent

Launch CodeSentry:

uv run codesentry --provider mock

Launch with a specific project:

uv run codesentry --path . --provider mock

Launch with a cloud provider:

uv run codesentry --provider openai --model gpt-4o-mini

Example session:

CodeSentry > scan this project
CodeSentry > show language breakdown
CodeSentry > review only TypeScript
CodeSentry > find bugs in Rust files
CodeSentry > suggest fixes
CodeSentry > show high severity bugs
CodeSentry > generate markdown report
CodeSentry > exit

Slash shortcuts are available for common actions:

/help
/languages
/scan
/review
/review --language typescript
/bugs --language rust
/fix --language go
/report
/files
/skipped
/unsupported
/findings
/provider
/model
/clear
/exit

GitHub Repository Review

CodeSentry can review public GitHub repositories without GitHub tokens.

Supported URL formats:

https://github.com/user/repo
https://github.com/user/repo.git

Example:

CodeSentry > review this repo https://github.com/user/project
CodeSentry > review branch dev of https://github.com/user/project
CodeSentry > show repo info
CodeSentry > generate report
CodeSentry > cleanup repo

GitHub review rules:

• Public HTTPS repositories only
• No SSH URLs
• No private repo authentication
• No dependency installation
• No code execution
• Temporary clone workspace by default
• Safe cleanup through the workspace manager

If a repository has no supported files, CodeSentry reports that clearly instead of failing.

LLM Providers

Mock Provider

MockProvider is the default safe option for local testing. It requires no API key and sends no code anywhere.

uv run codesentry --provider mock

Ollama

Ollama is the local/offline model option.

ollama serve
uv run codesentry --provider ollama --model qwen2.5-coder

Other model names such as llama3, codellama, and deepseek-coder can be used if they are available locally.

OpenAI

OPENAI_API_KEY=...
uv run codesentry --provider openai --model gpt-4o-mini

Anthropic Claude

ANTHROPIC_API_KEY=...
uv run codesentry --provider anthropic --model claude-3-5-haiku-latest

Google Gemini

GOOGLE_API_KEY=...
uv run codesentry --provider gemini --model gemini-1.5-flash

GEMINI_API_KEY is also supported.

NVIDIA Build/NIM

NVIDIA_API_KEY=...
uv run codesentry --provider nvidia --model meta/llama-3.1-70b-instruct

Set NVIDIA_BASE_URL when using a custom NVIDIA-compatible endpoint.

Privacy

When using OpenAI, Anthropic, Gemini, or NVIDIA, selected source code snippets may be sent to the selected external LLM provider for analysis. CodeSentry shows a confirmation prompt before cloud-provider review.

MockProvider sends no code anywhere. Ollama keeps model execution local.

Desktop App

CodeSentry includes a Tauri v2 desktop app that uses the same Python core engine through a local FastAPI backend.

Start the backend:

uv run codesentry-api

Start the desktop app:

cd desktop
pnpm install
pnpm tauri dev

The desktop app connects to:

http://127.0.0.1:8765

Desktop features:

• Dashboard
• Local folder selection
• GitHub repository input
• Provider and model settings
• Language selection
• Review progress
• Results grouped by severity, language, and file
• Markdown report export
• Review history metadata

Production sidecar packaging is planned. The current desktop flow is development mode.

Local API

The local API wraps the shared CodeSentry engine for desktop and future integrations.

Run:

uv run codesentry-api

Core endpoints:

Method	Endpoint	Purpose
GET	/health	Backend health check
GET	/providers	List supported providers
POST	/config/provider	Set provider and model
POST	/project/local	Set local project
POST	/project/github	Validate and prepare GitHub repo
POST	/scan	Scan selected project
POST	/review	Start review job
GET	/review/{job_id}/status	Poll job status
GET	/review/{job_id}/result	Fetch review result
POST	/report/export	Export Markdown report
GET	/history	Get review history

The API binds to 127.0.0.1 only.

Architecture

CodeSentry keeps interfaces separate from the review engine.

Terminal UI
Desktop UI
FastAPI API
    |
    v
Shared Python Core Engine
    |
    v
Project Loader / Repo Manager
    |
    v
Language-Aware Scanner and Reader
    |
    v
LangGraph Six-Agent Pipeline
    |
    v
LLM Provider Abstraction
    |
    v
Markdown Report Generator

Six-agent pipeline:

Scanner Agent
-> Reader Agent
-> Reviewer Agent
-> Bug Detector Agent
-> Fix Suggester Agent
-> Report Agent

The Rust desktop frontend does not reimplement scanning, cloning, language detection, LLM provider calls, review logic, or report generation.

Project Structure

codesentry/
  agents/        Six review pipeline agents
  api/           Local FastAPI backend for desktop integration
  cli/           Typer launch commands
  core/          Reusable scanner, engine, repo, language, and report logic
  llm/           Provider abstraction and provider implementations
  models/        Pydantic schemas
  prompts/       Language-aware prompt templates
  tui/           Interactive terminal interface
  utils/         Shared utilities

desktop/
  src/           React + TypeScript frontend
  src-tauri/     Tauri v2 Rust command layer

docs/
  desktop_architecture.md

tests/
  Python backend and engine tests

Important files:

• codesentry/core/engine.py: shared review engine
• codesentry/core/pipeline.py: LangGraph pipeline
• codesentry/core/scanner.py: language-aware scanner
• codesentry/core/repo_manager.py: safe GitHub clone manager
• codesentry/core/report_generator.py: Markdown reports
• codesentry/tui/app.py: terminal app
• codesentry/api/routes.py: local API routes
• desktop/src/App.tsx: desktop frontend shell
• desktop/src-tauri/src/commands.rs: Tauri command bridge

Reports

Reports are written only after user request or confirmation.

Default examples:

reports/codesentry_report.md
reports/github_user_project_codesentry_report.md

Reports include:

• Project or repository metadata
• Provider and model
• Supported languages reviewed
• Language breakdown
• Files scanned
• Skipped and unsupported files
• Code quality findings
• Bug findings
• Fix suggestions
• Cross-language observations
• Final recommendation
• Tool metadata

Testing

Run the Python test suite:

uv run pytest

Run frontend checks:

cd desktop
pnpm install
pnpm build

The test suite is designed to work without real API keys by using MockProvider.

Contributing

Contributions are welcome.

Good first contribution areas:

• Bug fixes
• Tests
• Documentation improvements
• UI polish
• Prompt improvements
• Additional provider error handling
• Safer scanner edge cases
• Desktop development-mode improvements

Development workflow:

1. Fork the repository.
2. Create a feature branch.
3. Install Python dependencies with uv sync.
4. Use MockProvider for local testing.
5. Run uv run pytest.
6. If editing the desktop app, run pnpm build inside desktop/.
7. Open a pull request with a clear description and test notes.

Please keep these rules in mind:

• Do not move review logic into the terminal UI or desktop UI.
• Keep the Python core engine as the source of truth.
• Do not add code execution, dependency installation, or auto-fix behavior without a separate safety design.
• Do not log API keys.
• Do not store source code in history by default.
• Add focused tests for scanner, engine, API, provider, and UI changes.

Development Notes

Optional future .codesentry.toml shape:

provider = "ollama"
model = "qwen2.5-coder"
max_file_size_kb = 200
max_lines_per_chunk = 250
review_languages = ["python", "typescript", "rust"]
ignore_generated = true
ignore_minified = true
output = "reports/codesentry_report.md"

Current known limitations:

• Language detection is extension and config based.
• CodeSentry does not compile or execute code.
• Findings are AI-assisted static review findings, not compiler-grade guarantees.
• Private GitHub repository authentication is not implemented.
• Production desktop sidecar packaging is not implemented yet.
• PDF export is planned, but Markdown export is the supported report format.

Roadmap

• Phase 1: Interactive terminal agent and reusable Python core engine
• Phase 2: Public GitHub repository review
• Phase 3: Language-aware multi-language review
• Phase 4: Tauri desktop app with local backend integration
• Future: production sidecar packaging
• Future: private repository authentication
• Future: AST-based analysis with Tree-sitter
• Future: optional PDF export
• Future: carefully designed auto-fix workflow

Documentation

• Desktop architecture

License

This project is intended to be open source. Add a LICENSE file before public release so contributors know the exact terms.