427f66b488
_run_dir_loop was ~160 lines holding four conceptual layers in one function: pre-loop setup, budget check + partial-flush, API call + response printing, and tool dispatch + done detection. Phase 3 dynamic turn allocation will inject more state into the same code path, so this debt is paid before that lands. Three new helpers above _run_dir_loop: - _build_dir_loop_context(): pure setup. Builds the dir context, child summaries, survey block, filtered tool list, system prompt, and seed user message. Returns a _DirLoopContext namedtuple. - _flush_partial_dir_entry(): idempotent partial-cache writer for the budget-exceeded path. Returns the partial summary string. Idempotent via cache.has_entry() guard, so callers can call it without checking. - _handle_turn_response(): per-turn response processing. Prints text blocks and tool decisions, appends the assistant message, dispatches tools (or nudges the agent to call submit_report), appends tool_results. Returns (done, summary). _run_dir_loop is now a ~25-line coordinator: build context, then for-loop calls budget check, API, and turn handler in sequence. No behavior change. 164 tests pass. Internals.md §4 updated for the new structure and the file:line refs that drifted. |
||
|---|---|---|
| luminos_lib | ||
| tests | ||
| .gitignore | ||
| CLAUDE.md | ||
| LICENSE | ||
| luminos.py | ||
| PLAN.md | ||
| README.md | ||
| requirements.txt | ||
| setup_env.sh | ||
Luminos
A file system intelligence tool. Point it at a directory and it runs an agentic Claude investigation that figures out what the directory is, what's in it, and what might be worth your attention.
Luminos is built around a harder question than "what files are here?" It is built around "what is this, and should I be worried about any of it?" To answer that, it runs a multi-pass agentic investigation against the Claude API: a survey pass to orient on the target, an isolated dir-loop agent per directory with a small toolbelt (read files, run whitelisted coreutils commands, write cache entries), and a final 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. The base scan is not a standalone product, it is the first step of the investigation.
Features
- Agentic AI investigation. Multi-pass, leaves-first analysis via Claude. Survey then dir loops then synthesis.
- Investigation cache. Per-file and per-directory summaries are cached under
/tmp/luminos/so repeat runs on the same target are cheap. - Severity-ranked flags. Findings are sorted so
criticalitems are the first thing you see. - Context budget guard. Per-turn
input_tokensis watched against a budget so a rogue directory can't blow the context and silently degrade quality. - Graceful degradation. Permission denied, subprocess timeouts, missing API key: all handled without crashing.
- JSON output. Pipe reports to other tools or save for comparison.
Installation
Luminos is a normal Python project. Clone, create a venv, and install from requirements.txt. The repository ships a helper script that does this for you:
git clone https://github.com/archeious/luminos.git
cd luminos
./setup_env.sh
source ~/luminos-env/bin/activate
Or do it by hand:
python3 -m venv ~/luminos-env
source ~/luminos-env/bin/activate
pip install -r requirements.txt
You also need an Anthropic API key exported as an environment variable:
export ANTHROPIC_API_KEY=your-key-here
The base scan shells out to a handful of GNU coreutils (wc, file, grep, head, tail, stat, du, find), so you also need those on $PATH. They are installed by default on every mainstream Linux distribution and on macOS via Homebrew.
Usage
python3 luminos.py /path/to/project
That is the whole interface. The investigation runs end to end and prints a report.
Common flags
# Deeper tree, include hidden files, exclude build and vendor dirs
python3 luminos.py -d 8 -a -x .git -x node_modules -x vendor /path/to/project
# JSON output to a file
python3 luminos.py --json -o report.json /path/to/project
# Force a fresh investigation, ignoring the cache
python3 luminos.py --fresh /path/to/project
# Clear the investigation cache
python3 luminos.py --clear-cache
Run python3 luminos.py --help for the full flag list.
How the investigation works
A short version of what happens on every run:
- Base scan. Builds the directory tree, classifies files into seven categories, counts lines of code, finds large and recently modified files, computes per-directory disk usage. This is the agent's initial picture of the target.
- Survey pass. A short agent loop (max 3 turns) reads the base scan, describes the target in plain language, and decides which investigation tools are relevant. Tiny targets skip the survey.
- Dir loops. Every directory gets its own isolated agent loop, leaves-first, with up to 14 turns. The agent has read-only access to the filesystem and a toolbelt of
read_file,list_directory,run_command,parse_structure,write_cache,think,checkpoint,flag, andsubmit_report. - Cache. Each file and directory summary is written to
/tmp/luminos/so subsequent runs on the same target don't re-derive what hasn't changed. - Context budget guard. Per-turn
input_tokensis watched against a budget (currently 70% of the model's context window) so a rogue directory can't blow the context window. - Final synthesis. A short agent loop reads the directory-level cache entries (not the raw files) and produces the project-level brief, the detailed analysis, and the severity-ranked flags.
Development
Run the test suite:
python3 -m unittest discover -s tests/
Modules that are intentionally not unit tested:
luminos_lib/ai.py: requires a live Anthropic API, exercised in practiceluminos_lib/ast_parser.py: requires tree-sitter grammars installedluminos_lib/prompts.py: string templates only
License
Apache License 2.0. See LICENSE for the full text.
Source of truth
The canonical home for this project is the Forgejo repository. The GitHub copy is a read-only mirror, pushed automatically from Forgejo. Issues, pull requests, and the project wiki live on Forgejo.