Seedling-tools

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

Core Capabilities:

1. SCAN: Serialize and export directory tree structures to Markdown, TXT, JSON, XML, or high-definition image formats.
2. FIND & GREP: Perform exact or fuzzy filename searches, as well as cross-file full-text content matching based on regular expressions.
3. ANALYZE: Automatically detect project architecture patterns, core dependency package matrices, and program command entry points.
4. SKELETON: Extract Python code skeletons based on AST, automatically stripping underlying implementation logic to retain only the top-level signatures of classes and functions.
5. POWER MODE: Fully aggregate the source code of the target codebase, with a built-in heuristic Token consumption estimation engine to provide an extremely pure context for LLMs.
6. TEMPLATE: Prompt template engine, enabling automated context assembly and LLM review instruction injection via the {{SEEDLING_CONTEXT}} placeholder.
7. REMOTE: Supports remote Git URLs, instantly completing repository cloning, parsing, and secure destruction in an independent sandbox.
8. BUILD: Parse plaintext topology blueprints, perform conflict-free pre-checks, and reverse-engineer/build a real physical file system with one click.

Read this document in other languages: 简体中文

Installation

Seedling-tools is recommended to be installed globally via pipx to ensure 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 need to modify the source code, please use Editable Mode:

pipx install -e . --force

Python Library Usage

You can now use Seedling's core features directly in your Python code:

import seedlingtools
from pathlib import Path
from seedlingtools.core import ScanConfig, DepthFirstTraverser, StandardTreeRenderer

# Initialize configuration
config = ScanConfig(max_depth=2, quiet=True)

# Take memory snapshot
traverser = DepthFirstTraverser()
result = traverser.traverse(Path("./src"), config)

# Render tree lines
renderer = StandardTreeRenderer()
lines = renderer.render(result, config)
print("\n".join(lines))

Command Line Usage

The core advantage of Seedling-tools is its ability to cleanly and efficiently aggregate complex codebases into structured text that LLMs can directly digest.

Scenario 1: Providing the Entire Backend Context to an LLM

If you are a Python developer and need an LLM to help you review or refactor backend business logic, you can use a combined command to accurately grab all Python files, excluding unnecessary cache and test files:

scan . -t py -e .gitignore --full

This generates a Markdown file with the directory tree and full source code, while automatically filtering out multimedia files and non-Python code, saving valuable Tokens.

Scenario 2: Automated Review Based on Prompt Templates

You can write a prompt file in advance. Leave a {{SEEDLING_CONTEXT}} placeholder in the template, and Seedling will automatically inject the generated context into that position after the scan is complete. For example, using the official example template provided in this project docs/prompt_example.md:

scan . --full --template docs/prompt_example.md -o ./reports -n output_report.md -e ".gitignore"

Scenario 3: Instant Scanning of Open-Source Projects

No need to manually clone the entire repository. Pass the remote Git URL directly to Seedling, and it will clone, analyze, and aggregate the context in a temporary directory, automatically destroying and cleaning it up when finished:

scan https://github.com/bbpeaches/Seedling.git -t py --analyze --full

CLI Reference

Seedling-tools uses a clean, explicit argument system.

1. scan

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

2. build

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

v2.5 Core Features

Smart Interaction & Filtering

• Smart Garbage File Interceptor: Introduced heuristic detection logic to automatically identify and intercept project noise like node_modules, .DS_Store, __pycache__, etc.
• Intent-Aware & Interactive Downgrade: The system can automatically distinguish between "expert mode" and "normal mode". In single search modes or non-interactive environments, it automatically downgrades to silent warnings without blocking the core workflow.

Modular Plugins & Symmetrical Orchestration System

• Scan Pipeline: Advanced scanning modes are now fully modularized via the ScanOrchestrator engine.
• Build Pipeline: The reverse-build mode has been comprehensively upgraded to the BuildOrchestrator symmetrical orchestration architecture, completely decoupling topology parsing, pre-flight interception, and physical writing.

LLM Enhanced Context Engine

• Structured XML Export: Added -F xml format support.
• Token Estimation: After each full scan and aggregation, automatically appends a heuristic algorithm-based Token consumption estimate to the terminal and the top of the output report, helping developers accurately control the context window limits of LLMs.
• Prompt Templates: Added the --template parameter. Allows developers to pass in a custom review prompt file; Seedling will automatically and accurately inject the full code context into the {{SEEDLING_CONTEXT}} placeholder after scanning, generating a Prompt ready to be fed directly.
• Remote Repository Scanning: CLI supports passing in Git HTTPS/SSH links directly.

Unified Infrastructure

• Centralized low-level file I/O, security boundary validation, Git lifecycle scheduling, and system interactions into robust global singleton instances.
• Introduced a unified exception hierarchy, providing more precise domain-level error report interception containing debugging context.

Project Structure (v2.5)

Seedling/
├── docs/                      # Documentation & Changelogs     
├── seedlingtools/             # Core Package
│   ├── commands/              # CLI Command Routers
│   │   ├── build/             # Reverse build pipeline
│   │   └── scan/              # Scan & analyze pipeline
│   ├── core/                  # Shared Core Engines     
│   ├── utils/                 # Global Infrastructure   
│   ├── __init__.py            # API & Package Metadata
│   └── main.py                # CLI Entry Dispatcher
├── tests/                     # Unit Test & E2E Automated Tests 
├── install.bat                
├── install.sh                 
├── LICENSE                    
├── pyproject.toml             
├── pytest.ini                 
├── README.md                  
└── run.sh                     # UT + E2E Automated Test Suite Entrypoint

Changelog

Detailed change history for each release is documented in the docs/CHANGELOG.md file.