Intent Sensing

Intent sensing lets you skip specifying a role file entirely. Pass --sense and describe your task — InitRunner scores every role in your library and runs the best match automatically.

initrunner run --sense -p "analyze this CSV and find trends"

╭─────────────────────────── Intent Sensing ───────────────────────────╮
│ Name   csv-analyst                                                   │
│ File   roles/csv-analyst.yaml                                        │
│ Tags   csv, data-analysis, trends, spreadsheet, tabular              │
│ Method keyword match (score: 3.50, gap: 3.00)                        │
│ Reason keyword match (score: 3.50, gap: 3.00)                        │
╰──────────────────────────────────────────────────────────────────────╯

The panel names the agent that was picked, then that agent runs with your prompt.

Why It Exists

As your role library grows, remembering which file to pass to initrunner run becomes friction. Intent sensing removes that friction: describe the task in plain language and the right agent finds itself.

The Two-Pass Algorithm

Sensing runs in two passes:

1. Keyword scoring — Each role's metadata is tokenized and scored against the prompt. Scores are weighted by field:

   Field	Weight
   tags	3×
   name	2×
   description	1.5×

2. LLM tiebreaker — If the top two candidates are within the gap threshold of each other, InitRunner calls a small LLM (controlled by INITRUNNER_DEFAULT_MODEL) with the prompt and the candidates' metadata to break the tie.

Selection Thresholds

A role is auto-selected when both conditions are met:

If neither condition is met, InitRunner prints the top candidates and exits, asking you to name a role explicitly.

CLI Flags

initrunner run --sense -p "summarize last week's sales report"

--sense confirms the role it picked whenever it has a terminal, and searches the default directories below.

Changed in v2026.8.11: --role-dir and --confirm-role were removed with nothing to replace them, because --sense already does both. To sense over roles in another directory, run from it, or keep them in ~/.initrunner/roles/.

Dry Run (Keyword-Only Mode)

Passing --dry-run alongside --sense disables the LLM tiebreaker. Scoring is keyword-only and no API calls are made. Useful for debugging which role would be selected without spending tokens:

initrunner run --sense --dry-run -p "analyze CSV trends"

Role Discovery Order

InitRunner searches for roles in this order:

1. The current working directory
2. ./examples/roles/, when that directory exists
3. ~/.initrunner/roles/, the global role store, when it exists. Set INITRUNNER_HOME to move it, or set XDG_DATA_HOME to use $XDG_DATA_HOME/initrunner/roles/
4. The starter agents bundled with the package

Directories are scanned recursively for valid agent YAML files. Each file is only considered once, so the first directory in the list that yields it wins.

Writing Roles That Sense Well

The tags field carries the most weight (3×). Keep tags specific and task-oriented:

name: csv-analyst
description: Analyze CSV files, summarize data, and find trends
tags:
  - csv
  - data-analysis
  - trends
  - spreadsheet
  - tabular

Tagging guide:

• Use nouns and verbs that match how you'd naturally describe the task (summarize, analyze, email, draft, search)
• Include the data format if relevant (csv, pdf, json, markdown)
• Add domain terms (sales, support, research, code)
• Avoid generic tags like agent or assistant — they add noise without signal
• Aim for 4–8 tags per role

A well-tagged role will win cleanly (gap ≥ 0.15) without needing the LLM tiebreaker.

Tiebreaker Model

The LLM tiebreaker uses the model set in the INITRUNNER_DEFAULT_MODEL environment variable:

export INITRUNNER_DEFAULT_MODEL=openai:gpt-4o-mini

Or, to persist across sessions, add it to ~/.initrunner/.env:

INITRUNNER_DEFAULT_MODEL=openai:gpt-4o-mini

If unset, it falls back to openai:gpt-4o-mini. The tiebreaker call is a single low-token request — typically under 200 tokens — and only fires when the top two candidates are too close to separate by keyword score alone.

Flow Integration

Intent Sensing can also auto-route messages between agents in a flow pipeline. Set strategy: keyword or strategy: sense on a multi-target delegate sink:

triager:
  use: roles/triager.yaml
  then:
    strategy: sense
    to: [researcher, responder, escalator]

The same two-pass scoring (keyword + optional LLM tiebreak) runs on each message, using the target agents' role metadata (name, description, tags) as candidates. See Flow — Routing Strategy for full details.