Jeff Smith da387289f3 chore: add venv setup script and update CLAUDE.md for optional deps

- setup_env.sh creates ~/luminos-env venv and installs all AI packages
- CLAUDE.md updated to reflect the new dependency model: base tool is
  zero-dep, --ai requires packages installed via venv
- Documents the capabilities module and updated ai.py architecture

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-30 12:14:13 -06:00

3.4 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Running Luminos

# Basic scan
python3 luminos.py <target_directory>

# With AI analysis (requires ANTHROPIC_API_KEY env var)
python3 luminos.py --ai <target_directory>

# JSON output to file
python3 luminos.py --json -o report.json <target_directory>

# Watch mode (re-scans every 30s, shows diffs)
python3 luminos.py --watch <target_directory>

There is no build step, no test suite, and no linter configured.

Architecture

The base tool is a zero-dependency Python CLI (stdlib only). The --ai flag requires optional pip packages installed in a venv. The entry point luminos.py defines scan() which orchestrates all analysis modules and returns a report dict, and main() which handles argument parsing and output routing.

Each analysis capability lives in its own module under luminos_lib/:

Module	Purpose	External commands used
`tree.py`	Recursive directory tree with file sizes	None (uses `os`)
`filetypes.py`	Classifies files into 7 categories (source, config, data, media, document, archive, unknown)	`file --brief`
`code.py`	Language detection, LOC counting, large file flagging	`wc -l`
`recency.py`	Finds N most recently modified files	`find -printf`
`disk.py`	Per-directory disk usage	`du -b`
`report.py`	Formats the report dict as human-readable terminal output	None
`ai.py`	Multi-pass agentic directory analysis via Claude API (streaming, token counting, caching)	Requires `anthropic`, `tree-sitter`, `python-magic`
`capabilities.py`	Optional dependency detection, cache cleanup	None
`watch.py`	Continuous monitoring loop with snapshot diffing	None (re-uses `filetypes.classify_files`)

Data flow: scan() builds a report dict → optional analyze_directory() adds AI fields → format_report() or json.dumps() produces output.

Optional Dependencies (--ai flag only)

The base tool requires zero pip packages. The --ai flag requires:

# One-time setup
bash setup_env.sh

# Or manually:
python3 -m venv ~/luminos-env
source ~/luminos-env/bin/activate
pip install anthropic tree-sitter tree-sitter-python \
            tree-sitter-javascript tree-sitter-rust \
            tree-sitter-go python-magic

Check current status with python3 luminos.py --install-extras.

Always activate the venv before using --ai:

source ~/luminos-env/bin/activate
python3 luminos.py --ai <target_directory>

Key Constraints

Base tool: no pip dependencies. The base scan (tree, file types, code, disk, recency, report, watch) uses only stdlib and GNU coreutils. It must always work on a bare Python 3 install.
AI deps are gated. The anthropic, tree-sitter, and python-magic packages are imported lazily, only when --ai is used. Missing packages produce a clear error with the install command.
Subprocess for OS tools. Line counting, file detection, disk usage, and recency all shell out to GNU coreutils. Do not reimplement these in pure Python.
AI is opt-in. The --ai flag gates all Claude API calls. Without it (or without ANTHROPIC_API_KEY), the tool must produce a complete report with no errors.
Graceful degradation everywhere. Permission denied, subprocess timeouts, missing API key — all handled without crashing.