a1b17300e8
Adding a tool used to require updating two parallel structures in
ai.py: a name->handler entry in _TOOL_DISPATCH and a schema dict in
_DIR_TOOLS (or _SYNTHESIS_TOOLS or _SURVEY_TOOLS). Forgetting one half
was silent. Internals.md §9.1 documented this as a 5-step process.
Replaced both with a single register_tool() call per (tool, scope):
register_tool(
name="read_file",
description="...",
schema={...},
scopes=["dir"],
handler=_tool_read_file,
)
The function appends the schema to one or more scope lists
(_DIR_TOOLS / _SYNTHESIS_TOOLS / _SURVEY_TOOLS) and lands the handler
in _TOOL_DISPATCH. Tools intercepted by the loop body (submit_report,
submit_survey) register schema only with handler=None.
Tools whose schema differs by scope (submit_report has different shapes
in dir vs synthesis loops) get one register_tool() call per scope.
flag is also registered twice because it appears in dir + synthesis at
different positions in each list — the order is preserved with two
calls rather than reordered for fewer calls.
Verification:
- _DIR_TOOLS, _SYNTHESIS_TOOLS, _SURVEY_TOOLS contain the same names
in the same order as before.
- _TOOL_DISPATCH contains the same 10 handlers as before.
- 164 tests pass.
No behavior change. Phase 3.5 (#39) MCP backend will eventually replace
this with dynamic discovery from the connected MCP server, at which
point register_tool() collapses to a one-line forward.
|
||
|---|---|---|
| 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.