Luminos

Luminos is a file system intelligence tool. Point it at a directory and it runs a multi-pass agentic investigation via the Claude API: a survey pass, isolated dir-loop agents per directory, and a synthesis pass that produces a project-level verdict with severity-ranked flags. A lightweight base scan runs first to feed the agent its initial picture of the target.

Current State

Phase: Active development — Phases 1-3 complete. Phase 3 added planning pass with dynamic turn allocation and quality instrumentation.
Last worked on: 2026-04-12
Last commit: feat(ai): Phase 3 investigation planning (#75)
Blocking: None

Quick Links

Page	Contents
Architecture	Module breakdown, data flow, AI pipeline
Internals	Code-level tour: dir loop, cache, prompts, where to make changes
Planning Pass	Phase 3 design sketch: dynamic turn allocation, quality metrics
Development Guide	Setup, git workflow, testing, commands
Roadmap	Phase status — pointer to PLAN.md and open issues
Session Retrospectives	Full session history

At a Glance

python3 luminos.py <target>                            # full investigation
python3 luminos.py --fresh <target>                    # ignore cached results
python3 luminos.py -x .git -x node_modules <target>    # exclude dirs
python3 luminos.py --json -o report.json <target>      # JSON output
python3 luminos.py --clear-cache                       # wipe /tmp/luminos/

Repository

https://forgejo.labbity.unbiasedgeek.com/archeious/luminos