Routing

Routing is the process of assigning a task to the right agent. Kavi uses a multi-strategy approach that combines deterministic rules with AI-powered classification.

Routing Pipeline

When a task arrives, Kavi evaluates routing strategies in order of specificity:

1. Path ownership rules -- glob patterns in your config that map file paths to agents
2. Keyword heuristics -- frontend/backend keyword matching against the task description
3. AI fallback -- Codex classifies the task when rules and heuristics are inconclusive

Each strategy produces a confidence score between 0 and 1. The first strategy to exceed the confidence threshold wins.

Path Ownership

Path ownership rules are the most specific routing mechanism. You define glob patterns in your project config that claim file paths for each agent:

[routing]
codex_paths = ["src/backend/**", "src/lib/**", "prisma/**"]
claude_paths = ["src/components/**", "src/pages/**", "src/styles/**"]

When a task references files matching these patterns, Kavi routes directly to the owning agent with high confidence. Path rules take priority over all other strategies.

If a task touches files owned by different agents, Kavi may split it into subtasks or use the AI fallback to determine the primary owner.

Keyword Heuristics

Keyword heuristics match terms in the task description against configurable keyword lists:

[routing]
frontend_keywords = ["frontend", "ui", "ux", "react", "css", "component", "layout", "styling"]
backend_keywords = ["backend", "api", "server", "db", "auth", "database", "migration", "endpoint"]

The heuristic counts keyword matches for each category and produces a confidence score based on the ratio of matches. This works well for tasks that clearly fall into one domain but lack specific file references.

AI Fallback

When path rules and keyword heuristics produce low confidence scores, Kavi falls back to Codex for classification. The AI evaluates the task description, considers the project context, and returns a routing decision with a confidence score.

The AI fallback is the most flexible strategy but also the slowest, so it only activates when deterministic methods are inconclusive.

Confidence Scores

Every routing decision includes a confidence score from 0 to 1:

When no strategy produces sufficient confidence, Kavi asks the operator to make the routing decision manually.

Route Metadata

Each routing decision is recorded with metadata including:

• Strategy used -- which routing method produced the decision
• Confidence score -- how confident the router is in the assignment
• Matched patterns -- which path globs or keywords triggered the match
• Agent assigned -- the selected agent (codex or claude)
• Timestamp -- when the decision was made

Decision Ledger

All routing decisions are persisted in a decision ledger, providing an audit trail of how tasks were assigned. This is useful for:

• Understanding why a task went to a particular agent
• Tuning your routing rules based on historical patterns
• Debugging unexpected routing behavior

You can review the decision ledger through the TUI or by inspecting the session event log.

Default Agent Roles

By default, Kavi assigns agents based on their strengths:

• Codex -- planning, backend development, architecture, code generation
• Claude -- frontend development, intent catching, code review, explanation

These defaults are reflected in the agent role configuration:

[agents.codex]
role = "planning-backend"

[agents.claude]
role = "frontend-intent"

You can customize these roles and the associated routing rules to match your project's needs.