Skip to main content

ctx smart

Intelligently select files relevant to a task description using embeddings and call graph analysis.

Synopsis​

ctx smart <TASK> [PATTERNS]... [OPTIONS]

Description​

The smart command analyzes your task description and automatically selects the most relevant files from your codebase. It combines:

  • Semantic search - Finds symbols related to your task using embeddings
  • Call graph expansion - Includes callers and callees of matched symbols
  • Token budgeting - Fits selection within your token limit

Optional positional patterns scope the entire selection pipeline. Literal files, directories, and globs are ORed together; semantic matches and call-graph expansion both stay within that scope. With no patterns, . selects the whole repository.

Prerequisites​

Before using ctx smart, you must:

  1. Index your codebase: ctx index
  2. Generate embeddings: ctx embed

Options​

OptionDescriptionDefault
--max-tokens <N>Maximum tokens in output8000
--depth <N>Call graph expansion depth2
--top <N>Top semantic matches to consider10
--explainShow why each file was selectedfalse
--dry-runShow selection without file contentsfalse
--provider <local|openai|ollama>Embedding backend for the query (must match how the index was embedded); --openai is a deprecated alias for --provider openailocal
-f, --format <FORMAT>Output format (xml, markdown, md, plain, json)xml
--show-sizesShow file sizes in the project treefalse
--no-treeDisable the project tree in outputfalse
--count-onlyCount the selected, budgeted files without preview or context outputfalse
--encoding <ENCODING>Tokenizer used for selection and counting (cl100k_base, o200k_base, or p50k_base)cl100k_base
--statsPrint count timing to stderr with --count-onlyfalse

Examples​

Basic Usage​

# Select files for adding a new feature
ctx smart "add user authentication"

# Review files for fixing a bug
ctx smart "fix the login timeout issue"

# Search and expand only within Rust source and one contract file
ctx smart "change request validation" "src/**/*.rs" tests/contracts.rs

With Token Budget​

# Limit to 4000 tokens for smaller context
ctx smart "implement caching" --max-tokens 4000

# Measure exactly that selected pack using the target model's tokenizer
ctx smart "implement caching" --max-tokens 4000 --count-only --encoding o200k_base

--count-only prints its count summary on stdout and diagnostics on stderr. It takes precedence over --dry-run and --explain, so those combinations do not emit a selection preview or formatted context.

Explain Selection​

# See why each file was selected
ctx smart "add logging" --explain

Output:

Selected 5 files (3,245 tokens):

src/logger.rs (1,200 tokens)
  - semantic: 0.92 - "logger" matches task
  - calls: referenced by main.rs

src/config.rs (845 tokens)
  - semantic: 0.78 - "configuration" related
  - callee: called by logger.rs
...

Dry Run​

# Preview selection without outputting file contents
ctx smart "refactor error handling" --dry-run

Output:

Would select 4 files (2,891 tokens):
  src/error.rs       1,245 tokens
  src/handlers.rs      892 tokens
  src/validation.rs    512 tokens
  src/response.rs      242 tokens

Deep Call Graph Analysis​

# Expand call graph further for complex changes
ctx smart "optimize database queries" --depth 4

How It Works​

  1. Semantic Search: Embeds your task description and finds matching symbols
  2. Graph Expansion: For each matched symbol, follows call edges up to --depth levels
  3. Scoring: Ranks files by semantic similarity and call graph relevance
  4. Selection: Picks highest-scoring files that fit within --max-tokens

Output​

By default, outputs in the same format as ctx (XML, Markdown, etc.):

# Get markdown output
ctx smart "add tests" --format markdown

Tips​

  • Use specific task descriptions for better results
  • Start with --dry-run to preview selection
  • Use --explain to understand and tune selection
  • Increase --depth for changes with wide impact
  • Decrease --max-tokens when context window is limited

See Also​