Skip to main content
pdd auto-deps scans a directory for candidate dependency files, determines which ones are relevant to a given prompt, and inserts <include> directives for them. It also removes redundant inline content in the prompt that duplicates what the newly included files already provide. The pdd sync command calls auto-deps automatically as its first step.

​
Usage

pdd [GLOBAL OPTIONS] auto-deps [OPTIONS] PROMPT_FILE DIRECTORY_PATH

​
Arguments

​
PROMPT_FILE
string
required
The prompt file to analyze and update with dependency references.
​
DIRECTORY_PATH
string
required
Directory or glob pattern to search for dependency and example files. Supports wildcards such as *.py and **/*.py.
  • A plain directory (e.g., examples/) is scanned recursively by default, equivalent to examples/**/*.
  • A glob (e.g., examples/**/*.py) limits the search to matching files.

​
Options

​
--output
string
Where to save the modified prompt file. Default: <basename>_with_deps.prompt. Also reads from PDD_AUTO_DEPS_OUTPUT_PATH.
​
--csv
string
default:"project_dependencies.csv"
Path to the CSV file that stores or will store dependency metadata. Also reads from PDD_AUTO_DEPS_CSV_PATH.
​
--force-scan
boolean
default:"false"
Force rescanning of all candidate files even if they are already recorded in the CSV cache.
​
--include-docs
boolean
default:"false"
Include documentation files (.md, .txt, .rst) in dependency discovery. Disabled by default.
​
--no-dedup
boolean
default:"false"
Skip the redundant inline content removal pass. The deduplication pass is enabled by default.
​
--concurrency
integer
default:"1"
Maximum number of parallel LLM calls for dependency analysis. Also reads from PDD_AUTO_DEPS_CONCURRENCY.

​
How it works

auto-deps uses a two-stage retrieval pipeline when the number of candidate files exceeds 50:
  1. Embedding search — Embeds the prompt and all candidate files, then retrieves the top 50 candidates by cosine similarity. Controlled by PDD_EMBEDDING_MODEL (default: text-embedding-3-small).
  2. LLM reranking — Uses an LLM-as-judge to select the most relevant dependencies from those 50 candidates.
After inserting <include> directives, the command performs a deduplication pass that identifies and removes inline content in the prompt that semantically duplicates what an included document already provides. Use --no-dedup to skip this step.

​
Dependency metadata CSV

auto-deps maintains a CSV file with the following columns:
ColumnDescription
full_pathFull path to the dependency file
file_summaryOne-sentence summary of the file’s content and purpose
key_exportsKey exports (functions, classes, constants) from the file
dependenciesModules or packages the file depends on
dateTimestamp of when the file was last analyzed
Existing CSV files using the old 3-column format (without key_exports and dependencies) are automatically re-summarized on the next run.

​
Examples

# Search code examples and documentation files
pdd auto-deps --include-docs my_module_python.prompt "context/"

# Search only Python examples (skip documentation discovery)
pdd auto-deps my_module_python.prompt "context/*_example.py"

# Force rescan with increased concurrency
pdd auto-deps --force-scan --concurrency 30 my_module_python.prompt "context/"

# Skip redundant content removal
pdd auto-deps --no-dedup my_module_python.prompt "docs/"

​
Integration with pdd sync

pdd sync calls auto-deps as its first step automatically. You do not need to run auto-deps manually when using sync. Run it directly when you want to update a single prompt’s dependencies without running the full sync cycle.
  • pdd sync — Calls auto-deps automatically as step 1 of the full workflow.
  • pdd preprocess — Expands <include> directives inserted by auto-deps to preview the final prompt.

Build docs developers (and LLMs) love

Get started for freeTalk to us