Seedling-tools 2.4.2

A high-performance CLI toolkit designed for codebase exploration, intelligent analysis, and LLM context aggregation.

Seedling-tools

Seedling-tools is a high-performance CLI toolkit designed for codebase exploration, intelligent analysis, and LLM context aggregation.

Core Capabilities:

1. SCAN: Export directory trees to Markdown, TXT, JSON, or Images.
2. FIND & GREP: Perform exact/fuzzy file searches and regex-based content matching.
3. ANALYZE: Auto-detect project architecture, dependencies, and entry points.
4. SKELETON: Extract Python AST structures (stripping implementation logic).
5. POWER MODE: Aggregate full repository source code for LLM prompts.
6. BUILD: Reconstruct physical file systems from text-based blueprints.

Powered by a unified, single-pass caching traversal engine.

Read this document in other languages: 简体中文

---

Installation

Seedling-tools is designed to be installed globally via pipx for a clean, isolated environment.

pipx install Seedling-tools

One-Click Setup

• Windows: Run ./install.bat
• macOS / Linux: Run bash install.sh

Developer / Manual Install

If you are modifying the source code, use Editable Mode:

pipx install -e . --force

---

Python Library Usage

You can now use Seedling's core features directly in your Python code via the ScanConfig engine:

import seedling
from seedling.core.filesystem import ScanConfig

# 1. Initialize configuration (Set quiet=True to suppress CLI progress bars)
config = ScanConfig(max_depth=2, quiet=True)

# 2. Generate directory tree lines
stats = {"dirs": 0, "files": 0}
lines = seedling.scan_dir_lines("./src", config, stats)
print("\n".join(lines))

# 3. Search for specific items programmatically
exact, fuzzy = seedling.search_items(".", keyword="utils", config=config)

# 4. Reconstruct a project from a blueprint
seedling.build_structure_from_file("blueprint.md", "./new_project")

---

CLI Reference

Seedling-tools uses a clean, explicit argument system.

1. scan - The Explorer

Used for scanning directories, extracting code skeletons, or searching for items. Note: --full and --skeleton are mutually exclusive.

Argument	Description
target	Target directory for scanning or searching (Defaults to .).
--find, -f	Search Mode. Fast CLI search (Exact & Fuzzy). Combine with --full to export a code report.
--format, -F	Output format: md (default), txt, json, or image.
--name, -n	Custom output filename.
--outdir, -o	Where to save the result.
--showhidden	Include hidden files in the scan.
--depth, -d	Maximum recursion depth.
--exclude, -e	List of items to ignore. Smart parse: auto-reads .gitignore files or accepts globs.
--include	[NEW] Only include files/directories matching patterns (e.g., --include "*.py").
--type, -t	[NEW] Filter by file type: py, js, ts, cpp, go, java, rs, web, json, yaml, md, shell, all.
--regex	[NEW] Treat -f pattern as regular expression.
--grep, -g	[NEW] Search inside file contents (Content Search Mode).
-C, --context	[NEW] Show N lines of context around grep matches.
--analyze	[NEW] Analyze project structure, type, dependencies, and architecture.
--full	Power Mode. Appends the full text content of all scanned source files.
--skeleton	[Experimental] AST Code Skeleton extraction. Strips logic, retains signatures.
--text	Smart Filter. Only scan text-based files (ignores binary/media).
--delete	Cleanup Mode. Permanently delete items matched by --find (Interactive TTY only).
--dry-run	[NEW] Preview deletions without executing (use with --delete).
--verbose / -q	Verbose mode (-v) or Quiet mode (-q).

2. build - The Architect

Turn a text-based tree into a real file system, or restore a project from a snapshot.

Argument	Description
file	The source tree blueprint file (.txt or .md).
target	Where to build the structure (Defaults to current directory).
--direct, -d	Direct Mode. Bypass prompts to instantly create a specific path.
--check	Dry-Run. Simulate the build and report missing/existing items.
--force	Force Mode. Overwrite existing files without skipping.

---

New in v2.4 - Bug Fixes & Improvements

Security

• --dry-run Mode: Preview deletions before executing with --delete:

  scan . -f "temp_*" --delete --dry-run
  

Compatibility

• Python 3.9+ Required for --skeleton: Clear error message for Python 3.8 users
• Pillow as Optional Dependency: Install with pip install Seedling-tools[image] only if you need image export

Performance

• Accurate Memory Calculation: Fixed memory tracking to prevent OOM crashes on high-Unicode files
• Conservative Memory Threshold: Reduced to 80% for additional safety

JSON Output Mode

Export directory structures as structured JSON for programmatic consumption:

scan . -F json -o structure.json

File Type & Include Filters

Filter by file type or custom patterns:

scan . --type py -d 3
scan . --include "*.md" --include "*.txt"

Regex Search Mode

Use regular expressions in search:

scan . -f "test_.*\.py" --regex

Content Search (Grep Mode)

Search inside file contents with context:

scan . --grep "TODO" -C 3 --type py
scan . -g "def main" -C 2

Project Analysis

Analyze project structure and dependencies:

scan . --analyze

---

Project Structure (v2.4)

Seedling/
├── docs/                      # Documentation & Changelogs
│   ├── CHANGELOG.md           # English version history
│   ├── CHANGELOG_zh.md        # Chinese version history
│   └── README_zh.md           # Chinese documentation
├── seedling/                  # Core Package
│   ├── commands/              # CLI Command Routers
│   │   ├── build/             # Build logic (Reverse engineering)
│   │   │   ├── __init__.py    # Build CLI router & validation
│   │   │   └── architect.py   # Blueprint parsing & safe construction
│   │   └── scan/              # Scan logic (Exploration & Extraction)
│   │       ├── __init__.py    # Central Router & Single-pass trigger
│   │       ├── analyzer.py    # Project architecture & dependency analysis
│   │       ├── exclude.py     # .gitignore-style exclusion rule parser
│   │       ├── explorer.py    # Tree rendering & generic format export
│   │       ├── full.py        # Power Mode (LLM context aggregation)
│   │       ├── grep.py        # In-memory content search & context extraction
│   │       ├── json_output.py # Nested JSON structured export
│   │       ├── search.py      # File search (Exact/Fuzzy) & safe deletion
│   │       └── skeleton.py    # Python AST extraction (Implementation stripping)
│   ├── core/                  # Shared Core Engines
│   │   ├── config.py          # Configuration dataclasses & global constants
│   │   ├── detection.py       # File type & binary content probe
│   │   ├── io.py              # File R/W, Fence collision & Overwrite protection
│   │   ├── logger.py          # Centralized CLI formatter & log levels
│   │   ├── patterns.py        # Glob/Regex path matching engine
│   │   ├── sysinfo.py         # Hardware RAM probe & depth limits
│   │   ├── traversal.py       # Unified single-pass caching engine
│   │   └── ui.py              # Interactive prompts & progress bars
│   ├── __init__.py            # Public API & Metadata exposure
│   └── main.py                # CLI Entry Point Router
├── tests/                     # Unit Tests (Core, Edge Cases, IO)
├── install.bat                # Windows one-click installer
├── install.sh                 # Linux/macOS one-click installer
├── LICENSE                    # MIT License
├── pyproject.toml             # Build configuration & Package metadata
├── pytest.ini                 # Pytest configuration file
├── README.md                  # Main documentation
└── test_suite.sh              # Automated E2E tests

---

Changelog

Detailed changes for each release are documented in the docs/CHANGELOG.md file.