query

The query command lets you search xtarterize tasks using natural language - no need to remember exact task IDs. It uses a pure algorithmic scoring engine (no AI) to rank tasks by relevance to your query.

Usage

xtarterize query "<query>" [options]

A query is any natural language description of the tooling setup you’re looking for.

Options

Option	Description	Default
`--json`	Output machine-readable JSON	`false`
`--limit <n>`	Maximum number of results to show	`20`
`--threshold <n>`	Minimum relevance score (0-1)	`0.1`
`--timing`	Show detailed per-task timing breakdown	`false`
`--cwd <path>`	Target directory	current directory

Global options

This command does not support global formatting or output flags (--quiet, --format). Use --json for machine-readable output.

Examples

Find tasks by description

xtarterize query "strict typescript"

Outputs tasks grouped by domain bundle with per-group actionable add commands:

✻ xtarterize query "strict typescript" - 2 groups · 4 tasks

  TypeScript
  ts/strict                80%  tsconfig - strict: true             tsconfig.json
  ts/paths                 52%  tsconfig - path aliases             tsconfig.json
  ts/incremental           24%  tsconfig - incremental: true        tsconfig.json
  gitignore/tsbuildinfo    14%  .gitignore - tsbuildinfo             .gitignore

  xtarterize add ts/strict ts/paths ts/incremental gitignore/tsbuildinfo
  xtarterize add scripts/package-scripts

Search for linting and formatting

xtarterize query "linting and formatting tool" --limit 5

Machine-readable output

xtarterize query "ci pipeline" --json

{
  "type": "query",
  "query": "ci pipeline",
  "count": 3,
  "results": [
    {
      "taskId": "ci/ci",
      "label": "GitHub CI workflow",
      "group": "CI/CD",
      "relevance": 0.85,
      "signals": [
        { "name": "label", "score": 1.0 },
        { "name": "id", "score": 0.85 },
        { "name": "keywords", "score": 0.9 },
        { "name": "config", "score": 1.0 },
        { "name": "group", "score": 1.0 }
      ]
    }
  ]
}

Compose an init plan

Combine query with the init workflow to get a ranked task plan:

xtarterize init --compose "react project with ci and linting"

This reorders tasks so the most relevant ones appear first in the interactive plan, without excluding any applicable tasks.

How It Works

The scoring engine operates in five steps:

Tokenize - The query is split into words; stopwords (a, the, want, need, project, etc.) and short words are filtered out
Expand - Content words are expanded through a domain-specific synonym map with bidirectional transitive reverse-lookup (e.g. “lint” → “linter”, “static-analysis”, “check”; “typescript” → “ts”, “type-safe”, “strict”)
Score - For each original token, find the best match across all 5 signals (label, id, group, keywords, config targets) using the highest signal score among all terms (original + expanded synonyms). Uses tiered match levels: exact (1.0), stem-match (0.95), fuzzy (0.85), prefix (0.75), substring (0.55)
Aggregate - Signal scores are weighted and averaged; multi-token queries receive a coverage bonus that increases with the proportion of tokens matched
Group - Results are organized by task group/domain bundle, with per-group actionable xtarterize add commands