4.3 KiB
CLAUDE.md
STOP. Before producing ANY output, pull
docs/wiki/, fetch open Forgejo issues forarcheious/luminos, and present them as suggested tasks. Then ask: "What's the one thing we're shipping?" No preamble. No acknowledgment. Just the suggested tasks and the question. Everything else comes after the user answers.
Current Project State
- Phase: Active development — Phase 1 + 2 + 2.5 complete; Phase 3 (investigation planning) ready to start
- Last worked on: 2026-04-07
- Last commit: merge: fix/issue-54-write-cache-tool-desc
- Blocking: None
Project Overview
Luminos is a file system intelligence tool — a zero-dependency Python CLI that
scans a directory and produces a reconnaissance report. With --ai it runs a
multi-pass agentic investigation via the Claude API.
Module Map
| Module | Purpose |
|---|---|
luminos.py |
Entry point — arg parsing, scan(), main() |
luminos_lib/ai.py |
Multi-pass agentic analysis via Claude API |
luminos_lib/ast_parser.py |
tree-sitter code structure parsing |
luminos_lib/cache.py |
Investigation cache management |
luminos_lib/capabilities.py |
Optional dep detection, cache cleanup |
luminos_lib/code.py |
Language detection, LOC counting |
luminos_lib/disk.py |
Per-directory disk usage |
luminos_lib/filetypes.py |
File classification (7 categories) |
luminos_lib/prompts.py |
AI system prompt templates |
luminos_lib/recency.py |
Recently modified files |
luminos_lib/report.py |
Terminal report formatter |
luminos_lib/tree.py |
Directory tree visualization |
luminos_lib/watch.py |
Watch mode with snapshot diffing |
Details: wiki — Architecture | Development Guide
Key Constraints
- Base tool: no pip dependencies. tree, filetypes, code, disk, recency, report, watch use only stdlib and GNU coreutils. Must always work on bare Python 3.
- AI deps are lazy.
anthropic,tree-sitter,python-magicimported only when--aiis used. Missing packages produce a clear install error. - Subprocess for OS tools. LOC counting, file detection, disk usage, and recency shell out to GNU coreutils. Do not reimplement in pure Python.
- Graceful degradation everywhere. Permission denied, subprocess timeouts, missing API key — all handled without crashing.
Running Luminos
# Base scan
python3 luminos.py <target>
# With AI analysis (requires ANTHROPIC_API_KEY)
source ~/luminos-env/bin/activate
python3 luminos.py --ai <target>
# Common flags
python3 luminos.py -d 8 -a -x .git -x node_modules <target>
python3 luminos.py --json -o report.json <target>
python3 luminos.py --watch <target>
python3 luminos.py --install-extras
Project-Specific Test Notes
Run tests with python3 -m unittest discover -s tests/. Modules exempt from
unit testing: ai.py (requires live API), ast_parser.py (requires
tree-sitter), watch.py (stateful events), prompts.py (string templates
only).
(Development workflow, branching discipline, and session protocols live in
~/.claude/CLAUDE.md.)
Naming Conventions
| Context | Convention | Example |
|---|---|---|
| Functions / variables | snake_case | classify_files, dir_path |
| Classes | PascalCase | _TokenTracker, _CacheManager |
| Constants | UPPER_SNAKE_CASE | MAX_CONTEXT, CACHE_ROOT |
| Module files | snake_case | ast_parser.py |
| CLI flags | kebab-case | --clear-cache, --install-extras |
| Private functions | leading underscore | _run_synthesis |
Session Log
| # | Date | Summary |
|---|---|---|
| 6 | 2026-04-07 | Extracted shared workflow/branching/protocols from project CLAUDE.md to global ~/.claude/CLAUDE.md; moved externalize.md and wrap-up.md to ~/.claude/protocols/ |
| 7 | 2026-04-07 | Phase 1 audit — closed #1 (only #54 remains); gitea MCP credential overhaul: dedicated claude-code Forgejo user, admin on luminos, write+delete verified end-to-end |
| 8 | 2026-04-07 | Closed #54 — added confidence/confidence_reason to write_cache tool schema description; Phase 1 milestone now 4/4 complete |
Full log: wiki — Session Retrospectives