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"

[sense] Scanning ./roles/, ~/.config/initrunner/roles/
[sense] Scored 4 candidates
[sense] Selected: csv-analyst  (score 0.87, gap +0.41)

Agent: csv-analyst
Running...

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
   metadata.tags	3×
   metadata.name	2×
   metadata.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 with a prompt to specify a role explicitly or use --confirm-role.

CLI Flags

These flags are used with initrunner run:

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

# Add an extra role directory
initrunner run --sense --role-dir ~/work/roles -p "draft a cold outreach email"

# Always confirm before running
initrunner run --sense --confirm-role -p "clean up the CSV headers"

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. ./roles/ — roles directory next to the current working directory
2. ~/.config/initrunner/roles/ — user-level role store
3. Any paths added with --role-dir

Directories are scanned recursively for *.yaml files with kind: Agent.

Writing Roles That Sense Well

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

apiVersion: initrunner/v1
kind: Agent
metadata:
  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.