Scan → Understand → Act
25,000 files scanned in 55 seconds. Zero dependencies. 197 tests.
Quick Start · Install · Commands · Dashboard · Architecture
You use AI coding agents (Claude Code, Cline, Codex, Continue, Roo). They need to understand your codebase — but dumping raw files wastes tokens and misses context.
Sentinel solves this. It's a local, zero-dependency scanner that turns any repo into structured, token-efficient intelligence:
Point → Scan → AI-ready context pack (~2,500 tokens)
It maps architecture, scores maintainability, surfaces risk hotspots, identifies entry points, and generates ready-to-use prompts for your AI agent — all in seconds, entirely offline. No uploads. No API keys. No dependencies beyond Python stdlib.
flowchart LR
A["📂 Any Repo"] -->|scan| S["🛡️ Sentinel"]
S --> B["💊 Health Score"]
S --> C["🔥 Hotspots & Risks"]
S --> D["🎯 Entry Points"]
S --> E["🤖 Agent Prompt"]
S --> F["📦 Context Pack"]
S --> G["💡 Next Actions"]
B & C & D & E & F & G --> H["🧠 AI Coding Agent"]
pip install -e .
python sentinel.py scan . --fast
╔══════════════════════════════════════════════════════════════╗
║ 🛡️ SENTINEL — Repo Intelligence ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ Project kubernetes ║
║ Type container orchestration platform ║
║ Health ████████████████░░░░ 74% ║
║ Files 25,432 ║
║ Lines 6,007,991 ║
║ Time 55s ║
║ ║
║ ⚠️ Top risk: 3 oversize files exceeding 5K lines ║
║ 💡 Next action: Split kubelet.go into focused modules ║
║ ║
║ 197 tests · 0 failures · no external dependencies ║
╚══════════════════════════════════════════════════════════════╝
| Target | Files | Lines | Time | Health |
|---|---|---|---|---|
| Python library | ||||
| 234 | 42K | 0.16s | 🟢 86% | |
| FastAPI web framework | ||||
| ~1K | ~200K | 4.56s | 🟡 74% | |
| Kubernetes (k8s.io/kubernetes) | ||||
| 25,432 | 6,007,991 | 55s | 🟡 74% | |
| Ladybird browser engine | ||||
| ~40K | ~1.4M | ~40s | — |
💡
No cloud. No external services. Pure Python.Every scan runs entirely on your machine.
| | Name, type, archetype, purpose, language, frameworks, workflow — resolved through a 5-tier ranked fallback system that never returns garbage. | | | Maintainability, runtime complexity, test signal, security — with a detailed breakdown so you know | | | Primary runtime, API surfaces, examples, build tools, generators — with intelligent scoring (Go binaries get +80 bonus). | | | Runtime, build, test runner, documentation, vendor — ranked by risk so you attack the worst problems first. | | | Oversized files, TODO density, documentation drift, test gaps — every signal is actionable. | | | Suggestions ranked by | | | Ready-to-use prompt for | | | Compact, token-efficient project brief — ~2,500 tokens that replace hours of file reading. | | | Components, dependencies, archetype, patterns — the big picture at a glance. | | | Per-file scoring with deduplicated factors and test coverage — no noise, no duplicates. |
| Suite | Tests | Scope |
|---|---|---|
test_archetype_regressions |
||
| 11 | Archetype detection, entry point filtering, vendor classification | |
test_auditor |
||
| 18 | Checkpoints, file classification, maintainability, test signals | |
test_classification_regressions |
||
| 36 | File roles, risk surfaces, generated code, i18n, monorepo detection | |
test_ladybird_regressions |
||
| 37 | Risk surface classification, hotspot filtering, focus files | |
test_regression_fixtures |
||
| 28 | Full pipeline, identity resolution, purpose inference, HTML cleaning | |
test_report_quality |
||
| 40 | Project name extraction, entry points, health scoring, LLVM/rust detection | |
test_sentinel + misc |
||
| 27 | CLI commands, HTML report, dashboard, cache, MCP, knowledge base |
python -m unittest discover -s tests -v
Sentinel resolves project names through a 5-tier ranked fallback — no more "Sponsors" as a project name when scanning FastAPI:
┌─ Tier 1: Known repo names (22 entries)
│ FastAPI · Kubernetes · TensorFlow · Flask · Django · React
│ PyTorch · NumPy · Pandas · Vite · Express · Tailwind CSS · …
│
├─ Tier 2: Package manifests
│ Cargo.toml · pyproject.toml · package.json · setup.py · go.mod · CMakeLists.txt
│
├─ Tier 3: Manifest descriptions
│ Extracted from the same manifests
│
├─ Tier 4: README body
│ First real paragraph after headings
│
└─ Tier 5: README heading
Validated against blocked section keywords (Installation, Usage, Sponsors, …)
A 6-step fallback chain that never returns a placeholder — no more ----
as project purpose:
| Step | Source | What It Does |
|---|---|---|
| 1 | Manifest description | Stripped of HTML/badges |
| 2 | README body | First real paragraph, skip badges/tables/HTML |
| 3 | README summary | Already-cleaned summary field |
| 4 | README doc_title subtitle | Extracts subtitle after colon or em-dash |
| 5 | Component-based generation | Built from non-test/doc component roles |
| 6 | Final fallback | "Purpose could not be confidently inferred from README." |
🎯
Example:"Kubernetes: Production-Grade Container Orchestration"
→"Production-Grade Container Orchestration"
Go binaries are detected even when not named main.go
:
cmd/kube-apiserver/apiserver.go → runtime entry point (+80 score)
cmd/kubelet/kubelet.go → runtime entry point (+80 score)
cmd/cloud-controller-manager/main.go → runtime entry point
Major Go binaries get a +80 score bonus: kube-apiserver
, kubelet
, kube-controller-manager
, kube-scheduler
, kubectl
, kube-proxy
, kubeadm
.
Sentinel filters out the noise from all identity fields (project name, type, purpose, summary):
- ❌ HTML tags · Markdown links · Badges · Images
- ❌ Sponsor keywords · Section headings · Table artifacts
- ❌ Decorative separators (
----
,====
, etc.)
The generated HTML report is a single self-contained page — no external assets, no build step:
| Element | Description |
|---|---|
| 🟢 SVG health ring | Donut chart color-coded by score (green/gold/red) |
| 📊 Stats bar | Files, lines, issues, signals, TODOs at a glance |
| 🏷️ Project identity + risk | Definition lists in two-column card layout |
| 🔥 Top risk insight | Accent-bordered card with the single most important finding |
| 💡 Next actions | Grid of suggestion cards with impact/effort/confidence badges |
| 🎯 Hotspots + entry points | Grouped file pills by category |
| 📋 Components table | Path, role, file count, line count |
| By surface with level, score, and factors | |
| 🚨 Review signals | Severity, message, file |
| 🤖 Agent prompt | Terminal-styled $ -prefixed block on dark background |
| 📱 Responsive | Degrades gracefully from desktop to 500px viewport |
Dark-theme browser command centre at ** http://127.0.0.1:8765**:
Features: Stats row · Project identity + risk cards · Shared inputs (query, repo URL, budget, goal, flags) · Toggle pills (fast scan, dry-run, apply, verify, adapters) · Tool cards (Understand, Ask, Reports, Quality, Memory, Maintenance, Analyze URL) · Output terminal · Suggestions + prompt · Focus/hotspots/frameworks · File risks + review signals tables · Health timeline · Auto-refresh (3s)
| Command | What It Does |
|---|---|
scan |
|
| Analyse project structure, risks, hotspots | |
brief |
|
| One-line summary with the top suggestion | |
overview |
|
| Full project description with components, hotspots, workflow | |
context |
|
| Token-efficient project brief for AI agents | |
prompt |
|
| Focused next-step prompt with goal selection | |
retrieve |
|
| Find files, symbols, and snippets matching a query | |
ask |
|
| Answer a natural-language question about the project | |
analyze-url |
|
| Clone a git URL and generate a complete report bundle | |
graph |
|
| Extract AST symbols, import graph, call graph | |
verify |
|
| Preview or run focused tests for changed files | |
dashboard |
|
| Launch the live browser GUI | |
report |
|
| Save a Markdown or HTML report | |
pr |
|
| Summarise changes, risks, and suggested tests | |
release-check |
|
| Open-source readiness checklist | |
coverage |
|
| Identify weakly tested areas from coverage.xml | |
timeline |
|
| Show scan history, task memory, and token savings | |
memory |
|
| Record or list task memory | |
savings |
|
| Show estimated token savings | |
autofix |
|
| Plan or apply small safe fixes | |
doctor |
|
| Validate configuration and paths | |
mcp |
|
| Run as a stdio MCP server | |
mcp-health |
|
| Validate MCP tool availability | |
kilo-setup |
|
| Configure Kilo with Sentinel-first rules | |
kilo-bridge |
|
| Set up the no-MCP file bridge | |
kilo-refresh |
|
| Refresh Kilo context files before a task | |
watch |
|
| Continuously scan at an interval |
One-liner (any platform):
pip install git+https://github.com/Ntooxx/Sentinel.git
From source (for development):
git clone https://github.com/Ntooxx/Sentinel.git
cd Sentinel
pip install -e .
Windows users: double-click install.ps1
or run:
powershell -ExecutionPolicy Bypass -File install.ps1
After install, the project-sentinel
command is available globally.
project-sentinel scan . --fast
project-sentinel dashboard . --fast
project-sentinel report . --format html
project-sentinel report . --format markdown
project-sentinel prompt . --goal next --budget small --fast
project-sentinel ask . --question "where is authentication handled?" --fast
project-sentinel analyze-url https://github.com/user/repo --fast
Maximize your AI agent's effectiveness while minimizing token spend:
project-sentinel overview . --fast --quiet
project-sentinel context . --budget small --fast --quiet
project-sentinel prompt . --goal next --budget small --fast --quiet
What the agent receives:
| Output | Tokens | Value |
|---|---|---|
| Project overview | ~1,500 | Full project understanding |
| Compact context pack | ~2,500 | Replace hours of file reading |
| Focused next-step prompt | ~800 | Actionable direction |
| High-value focus files | ~500 | Narrowed verification path |
| Total | ||
| ~5,300 | ||
| Complete project intelligence |
python -m unittest discover -s tests -v
┌─────────────────────────────────────────────────────────┐
│ Test Results │
│ │
│ ████████████████████████████████████████████████ 100% │
│ │
│ 197 passed · 0 failed · 9.3s │
│ No flaky tests · No external dependencies │
└─────────────────────────────────────────────────────────┘
Run Sentinel against all bundled fixture repos to verify performance claims on your own machine:
project-sentinel benchmark . --fast
Example output from a real run:
SENTINEL BENCHMARK
Benchmarked 7 fixture(s)
cpp_repo files= 2 lines= 6 time= 0.007s health=85%
docs_heavy files= 2 lines= 6 time= 0.006s health=85%
generated_heavy files= 2 lines= 8 time= 0.008s health=85%
go_service files= 2 lines= 6 time= 0.007s health=85%
node_app files= 2 lines= 19 time= 0.006s health=85%
python_app files= 3 lines= 14 time= 0.007s health=95%
rust_cli files= 2 lines= 8 time= 0.007s health=85%
Benchmarks run entirely offline with zero external dependencies.
See the examples/ directory for ready-to-run scripts:
project-sentinel scan . --fast
project-sentinel report . --format html
project-sentinel dashboard . --fast
project-sentinel benchmark . --fast