DevTool: LLM Context Bridge

DevTool is a Python-based command-line utility designed to bridge the gap between your local development environment and Large Language Models (LLMs).

It solves two critical problems in AI-assisted coding:

1. Context Optimization: How to feed an LLM relevant code structure without consuming your entire token window.
2. Application Safety: How to accurately apply LLM-generated code changes back to your filesystem with verification.

Core Concepts

1. The "Skeleton" (AST Mapping)

Unlike standard copy-paste tools, DevTool uses Tree-sitter to parse your code. It generates "Skeletons"—condensed representations of your files that keep class definitions, function signatures, and docstrings, but strip out implementation details. This allows the LLM to understand your entire architecture while only "paying" tokens for the files actively being modified.

2. The .picks System

DevTool maintains a persistent selection state in a local .picks file. This allows you to curate a "Context Pack"—a specific set of files relevant to your current feature—without re-selecting them for every prompt.

3. Git Integration

DevTool is aware of your version control system:

• Context: It appends recent git history and status to the map output, giving the LLM awareness of recent changes.
• Automation: If the LLM includes a [[COMMIT: message]] tag in its response, DevTool can automatically stage and commit the applied changes.

Architecture

The tool is modularized into a core/ package:

• mapper.py (The Parser): Uses tree_sitter to query specific languages and extracts high-level structures. Now includes GitInterface for retrieving history.
• scanner.py (The File System): Recursively walks directories while respecting .gitignore.
• applier.py (The Writer): Parses Markdown code blocks, writes files, and handles the interactive "Apply & Commit" workflow.
• picker.py (The Selector UI): A Curses-based TUI for navigating the directory tree.
• paster.py (The Bridge): A TUI that scans pasted LLM text for filenames to auto-select them.

Usage Workflow

The typical workflow moves from Analysis (map) to Context Assembly (pack) to Execution (apply).

1. Map: Visualize & Select

Run map to see your project tree, AST skeletons, and Recent Git History.

python devtool.py map

• If no files are selected in .picks, this launches the Interactive Picker.
• Navigation: Arrow keys to move, Space to cycle selection, Enter to expand folders.
  • [x]: Selected. Full content will be sent to LLM.
  • [i]: Aware. Only the AST Skeleton will be sent.
  • [ ]: Ignored.

2. Pack: Generate Context

Generates the prompt payload. It outputs your System Prompt followed by the file contents.

Option A: ID Selection If you know the file IDs from the map command:

python devtool.py pack 1,4,10-12 > prompt.txt

Option B: Paste Mode If the LLM mentioned specific files in a previous chat, run pack without arguments:

python devtool.py pack

This opens a TUI. Paste the LLM's response. The tool will grep the text for filenames and pack those specific files.

3. Apply: Update & Commit

Takes a file containing the LLM's code response and applies changes.

python devtool.py apply response.md

• Interactive Review: The tool parses the markdown, finds ## filename headers, and presents a change list.
• Safety Check: You are prompted for every file: Apply 'src/main.py'? [y]es/[n]o/[a]ll.
• Auto-Commit: If the LLM response contained [[COMMIT: Refactored login logic]], after applying changes, you will be asked:

  Detected Commit Message: "Refactored login logic" Execute Git Commit? [C]ommit / [n]o

4. Utility Commands

• pick: Simply opens the file selector TUI to update your .picks file without generating output.
• prompt: Outputs the raw System Prompt (configured in core/config.py) to stdout.

Configuration

core/config.py

• SYSTEM_PROMPT: The master instruction set sent to the LLM. It enforces the ## filename and code block format required by the apply command.
• DEFAULT_IGNORE: List of patterns (e.g., __pycache__, node_modules) to exclude from scans.
• SUPPORTED_EXTENSIONS: Maps file extensions to Tree-sitter parsers.

core/languages.py

Contains the S-Expression queries used by Tree-sitter to extract structure from Python, TypeScript, JavaScript, etc. Modify this file to change how "Skeletons" are generated.