{"slug": "sentinel-map-any-codebase-for-ai-agents-in-55s-no-cloud-zero-deps", "title": "Sentinel- map any codebase for AI agents in 55s, no cloud, zero deps", "summary": "Sentinel, a new open-source tool, scans codebases of up to 25,000 files in 55 seconds to generate structured, token-efficient context packs for AI coding agents. It operates entirely offline with zero dependencies, mapping architecture, scoring maintainability, and surfacing risk hotspots to improve agent performance.", "body_md": "**Scan → Understand → Act**\n\n25,000 files scanned in 55 seconds. Zero dependencies. 197 tests.\n\n[Quick Start](#quick-start) · [Install](#quick-start) · [Commands](#commands) · [Dashboard](#dashboard-gui) · [Architecture](#architecture)\n\n**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.**\n\nSentinel solves this. It's a **local, zero-dependency** scanner that turns any repo into structured, token-efficient intelligence:\n\n```\nPoint → Scan → AI-ready context pack (~2,500 tokens)\n```\n\nIt 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.\n\n``` php\nflowchart LR\n    A[\"📂 Any Repo\"] -->|scan| S[\"🛡️ Sentinel\"]\n    S --> B[\"💊 Health Score\"]\n    S --> C[\"🔥 Hotspots & Risks\"]\n    S --> D[\"🎯 Entry Points\"]\n    S --> E[\"🤖 Agent Prompt\"]\n    S --> F[\"📦 Context Pack\"]\n    S --> G[\"💡 Next Actions\"]\n    B & C & D & E & F & G --> H[\"🧠 AI Coding Agent\"]\n# Install\npip install -e .\n\n# Scan any project — fast\npython sentinel.py scan . --fast\n╔══════════════════════════════════════════════════════════════╗\n║  🛡️  SENTINEL  —  Repo Intelligence                         ║\n╠══════════════════════════════════════════════════════════════╣\n║                                                              ║\n║  Project    kubernetes                                       ║\n║  Type       container orchestration platform                 ║\n║  Health     ████████████████░░░░  74%                        ║\n║  Files      25,432                                           ║\n║  Lines      6,007,991                                       ║\n║  Time       55s                                              ║\n║                                                              ║\n║  ⚠️  Top risk: 3 oversize files exceeding 5K lines          ║\n║  💡  Next action: Split kubelet.go into focused modules     ║\n║                                                              ║\n║  197 tests · 0 failures · no external dependencies          ║\n╚══════════════════════════════════════════════════════════════╝\n```\n\n| Target | Files | Lines | Time | Health |\n|---|---|---|---|---|\nPython library |\n234 | 42K | 0.16s | 🟢 86% |\nFastAPI web framework |\n~1K | ~200K | 4.56s | 🟡 74% |\nKubernetes (k8s.io/kubernetes) |\n25,432 | 6,007,991 | 55s | 🟡 74% |\nLadybird browser engine |\n~40K | ~1.4M | ~40s | — |\n\n💡\n\nNo cloud. No external services. Pure Python.Every scan runs entirely on your machine.\n\n|\n|\nName, type, archetype, purpose, language, frameworks, workflow — resolved through a 5-tier ranked fallback system that never returns garbage. |\n|\n|\nMaintainability, runtime complexity, test signal, security — with a detailed breakdown so you know |\n|\n|\nPrimary runtime, API surfaces, examples, build tools, generators — with intelligent scoring (Go binaries get +80 bonus). |\n|\n|\nRuntime, build, test runner, documentation, vendor — ranked by risk so you attack the worst problems first. |\n|\n|\nOversized files, TODO density, documentation drift, test gaps — every signal is actionable. |\n|\n|\nSuggestions ranked by |\n|\n|\nReady-to-use prompt for |\n|\n|\nCompact, token-efficient project brief — ~2,500 tokens that replace hours of file reading. |\n|\n|\nComponents, dependencies, archetype, patterns — the big picture at a glance. |\n|\n|\nPer-file scoring with deduplicated factors and test coverage — no noise, no duplicates. |\n\n| Suite | Tests | Scope |\n|---|---|---|\n`test_archetype_regressions` |\n11 | Archetype detection, entry point filtering, vendor classification |\n`test_auditor` |\n18 | Checkpoints, file classification, maintainability, test signals |\n`test_classification_regressions` |\n36 | File roles, risk surfaces, generated code, i18n, monorepo detection |\n`test_ladybird_regressions` |\n37 | Risk surface classification, hotspot filtering, focus files |\n`test_regression_fixtures` |\n28 | Full pipeline, identity resolution, purpose inference, HTML cleaning |\n`test_report_quality` |\n40 | Project name extraction, entry points, health scoring, LLVM/rust detection |\n`test_sentinel` + misc |\n27 | CLI commands, HTML report, dashboard, cache, MCP, knowledge base |\n\n```\npython -m unittest discover -s tests -v\n# 197 tests · 0 failures · 9.3 seconds\n```\n\nSentinel resolves project names through a **5-tier ranked fallback** — no more \"Sponsors\" as a project name when scanning FastAPI:\n\n```\n┌─ Tier 1: Known repo names (22 entries)\n│   FastAPI · Kubernetes · TensorFlow · Flask · Django · React\n│   PyTorch · NumPy · Pandas · Vite · Express · Tailwind CSS · …\n│\n├─ Tier 2: Package manifests\n│   Cargo.toml · pyproject.toml · package.json · setup.py · go.mod · CMakeLists.txt\n│\n├─ Tier 3: Manifest descriptions\n│   Extracted from the same manifests\n│\n├─ Tier 4: README body\n│   First real paragraph after headings\n│\n└─ Tier 5: README heading\n    Validated against blocked section keywords (Installation, Usage, Sponsors, …)\n```\n\nA **6-step fallback chain** that never returns a placeholder — no more `----`\n\nas project purpose:\n\n| Step | Source | What It Does |\n|---|---|---|\n| 1 | Manifest description | Stripped of HTML/badges |\n| 2 | README body | First real paragraph, skip badges/tables/HTML |\n| 3 | README summary | Already-cleaned summary field |\n| 4 | README doc_title subtitle | Extracts subtitle after colon or em-dash |\n| 5 | Component-based generation | Built from non-test/doc component roles |\n| 6 | Final fallback | \"Purpose could not be confidently inferred from README.\" |\n\n🎯\n\nExample:`\"Kubernetes: Production-Grade Container Orchestration\"`\n\n→`\"Production-Grade Container Orchestration\"`\n\nGo binaries are detected even when not named `main.go`\n\n:\n\n```\ncmd/kube-apiserver/apiserver.go    →  runtime entry point  (+80 score)\ncmd/kubelet/kubelet.go             →  runtime entry point  (+80 score)\ncmd/cloud-controller-manager/main.go → runtime entry point\n```\n\nMajor Go binaries get a **+80 score bonus**: `kube-apiserver`\n\n, `kubelet`\n\n, `kube-controller-manager`\n\n, `kube-scheduler`\n\n, `kubectl`\n\n, `kube-proxy`\n\n, `kubeadm`\n\n.\n\nSentinel filters out the noise from *all* identity fields (project name, type, purpose, summary):\n\n- ❌ HTML tags · Markdown links · Badges · Images\n- ❌ Sponsor keywords · Section headings · Table artifacts\n- ❌ Decorative separators (\n`----`\n\n,`====`\n\n, etc.)\n\nThe generated HTML report is a **single self-contained page** — no external assets, no build step:\n\n| Element | Description |\n|---|---|\n| 🟢 SVG health ring | Donut chart color-coded by score (green/gold/red) |\n| 📊 Stats bar | Files, lines, issues, signals, TODOs at a glance |\n| 🏷️ Project identity + risk | Definition lists in two-column card layout |\n| 🔥 Top risk insight | Accent-bordered card with the single most important finding |\n| 💡 Next actions | Grid of suggestion cards with impact/effort/confidence badges |\n| 🎯 Hotspots + entry points | Grouped file pills by category |\n| 📋 Components table | Path, role, file count, line count |\n| By surface with level, score, and factors | |\n| 🚨 Review signals | Severity, message, file |\n| 🤖 Agent prompt | Terminal-styled `$` -prefixed block on dark background |\n| 📱 Responsive | Degrades gracefully from desktop to 500px viewport |\n\nDark-theme browser command centre at ** http://127.0.0.1:8765**:\n\n**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)\n\n| Command | What It Does |\n|---|---|\n`scan` |\nAnalyse project structure, risks, hotspots |\n`brief` |\nOne-line summary with the top suggestion |\n`overview` |\nFull project description with components, hotspots, workflow |\n`context` |\nToken-efficient project brief for AI agents |\n`prompt` |\nFocused next-step prompt with goal selection |\n`retrieve` |\nFind files, symbols, and snippets matching a query |\n`ask` |\nAnswer a natural-language question about the project |\n`analyze-url` |\nClone a git URL and generate a complete report bundle |\n`graph` |\nExtract AST symbols, import graph, call graph |\n`verify` |\nPreview or run focused tests for changed files |\n`dashboard` |\nLaunch the live browser GUI |\n`report` |\nSave a Markdown or HTML report |\n`pr` |\nSummarise changes, risks, and suggested tests |\n`release-check` |\nOpen-source readiness checklist |\n`coverage` |\nIdentify weakly tested areas from coverage.xml |\n`timeline` |\nShow scan history, task memory, and token savings |\n`memory` |\nRecord or list task memory |\n`savings` |\nShow estimated token savings |\n`autofix` |\nPlan or apply small safe fixes |\n`doctor` |\nValidate configuration and paths |\n`mcp` |\nRun as a stdio MCP server |\n`mcp-health` |\nValidate MCP tool availability |\n`kilo-setup` |\nConfigure Kilo with Sentinel-first rules |\n`kilo-bridge` |\nSet up the no-MCP file bridge |\n`kilo-refresh` |\nRefresh Kilo context files before a task |\n`watch` |\nContinuously scan at an interval |\n\n**One-liner (any platform):**\n\n```\npip install git+https://github.com/Ntooxx/Sentinel.git\n```\n\n**From source (for development):**\n\n```\ngit clone https://github.com/Ntooxx/Sentinel.git\ncd Sentinel\npip install -e .\n```\n\n**Windows users:** double-click `install.ps1`\n\nor run:\n\n```\npowershell -ExecutionPolicy Bypass -File install.ps1\n```\n\nAfter install, the `project-sentinel`\n\ncommand is available globally.\n\n```\n# Scan the current directory\nproject-sentinel scan . --fast\n\n# Launch the live dashboard\nproject-sentinel dashboard . --fast\n# Beautiful HTML report\nproject-sentinel report . --format html\n\n# Markdown report\nproject-sentinel report . --format markdown\n# Generate an agent-ready prompt\nproject-sentinel prompt . --goal next --budget small --fast\n\n# Ask a question about your codebase\nproject-sentinel ask . --question \"where is authentication handled?\" --fast\n\n# Analyse any GitHub repo\nproject-sentinel analyze-url https://github.com/user/repo --fast\n```\n\nMaximize your AI agent's effectiveness while minimizing token spend:\n\n```\n# Step 1: Get the big picture\nproject-sentinel overview . --fast --quiet\n\n# Step 2: Get a compact context pack (~2,500 tokens)\nproject-sentinel context . --budget small --fast --quiet\n\n# Step 3: Get a focused next-step prompt\nproject-sentinel prompt . --goal next --budget small --fast --quiet\n```\n\n**What the agent receives:**\n\n| Output | Tokens | Value |\n|---|---|---|\n| Project overview | ~1,500 | Full project understanding |\n| Compact context pack | ~2,500 | Replace hours of file reading |\n| Focused next-step prompt | ~800 | Actionable direction |\n| High-value focus files | ~500 | Narrowed verification path |\nTotal |\n~5,300 |\nComplete project intelligence |\n\n```\n# Run the full test suite\npython -m unittest discover -s tests -v\n\n# 197 tests · 0 failures · 9.3 seconds\n┌─────────────────────────────────────────────────────────┐\n│  Test Results                                           │\n│                                                         │\n│  ████████████████████████████████████████████████  100%  │\n│                                                         │\n│  197 passed  ·  0 failed  ·  9.3s                      │\n│  No flaky tests  ·  No external dependencies           │\n└─────────────────────────────────────────────────────────┘\n```\n\nRun Sentinel against all bundled fixture repos to verify performance claims on your own machine:\n\n```\nproject-sentinel benchmark . --fast\n```\n\nExample output from a real run:\n\n```\nSENTINEL BENCHMARK\nBenchmarked 7 fixture(s)\n  cpp_repo              files=    2  lines=     6  time=  0.007s  health=85%\n  docs_heavy            files=    2  lines=     6  time=  0.006s  health=85%\n  generated_heavy       files=    2  lines=     8  time=  0.008s  health=85%\n  go_service            files=    2  lines=     6  time=  0.007s  health=85%\n  node_app              files=    2  lines=    19  time=  0.006s  health=85%\n  python_app            files=    3  lines=    14  time=  0.007s  health=95%\n  rust_cli              files=    2  lines=     8  time=  0.007s  health=85%\n```\n\nBenchmarks run entirely offline with zero external dependencies.\n\nSee the [ examples/](/Ntooxx/Sentinel/blob/main/examples) directory for ready-to-run scripts:\n\n```\n# Scan the Sentinel repo itself\nproject-sentinel scan . --fast\n\n# Generate an HTML report\nproject-sentinel report . --format html\n\n# Launch the dashboard\nproject-sentinel dashboard . --fast\n\n# Run a benchmark on all fixture repos\nproject-sentinel benchmark . --fast\n```\n\n", "url": "https://wpnews.pro/news/sentinel-map-any-codebase-for-ai-agents-in-55s-no-cloud-zero-deps", "canonical_source": "https://github.com/Ntooxx/Sentinel", "published_at": "2026-06-18 14:46:26+00:00", "updated_at": "2026-06-18 14:53:38.574765+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents"], "entities": ["Sentinel", "Claude Code", "Cline", "Codex", "Continue", "Roo", "Kubernetes", "FastAPI"], "alternates": {"html": "https://wpnews.pro/news/sentinel-map-any-codebase-for-ai-agents-in-55s-no-cloud-zero-deps", "markdown": "https://wpnews.pro/news/sentinel-map-any-codebase-for-ai-agents-in-55s-no-cloud-zero-deps.md", "text": "https://wpnews.pro/news/sentinel-map-any-codebase-for-ai-agents-in-55s-no-cloud-zero-deps.txt", "jsonld": "https://wpnews.pro/news/sentinel-map-any-codebase-for-ai-agents-in-55s-no-cloud-zero-deps.jsonld"}}