Routing Rules

Routing rules determine which agent handles each task. Kavi uses a layered strategy: path ownership rules are checked first, then keyword heuristics, and finally an AI-powered fallback.

All routing rules are configured in the [routing] section of your project config at .kavi/config.toml.

Path Ownership

Define glob patterns that claim file paths for each agent:

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

When a task mentions or touches files matching these patterns, Kavi routes to the owning agent with high confidence. Path ownership is the strongest routing signal.

Glob Syntax

Path patterns use standard glob syntax:

Examples:

codex_paths = [
  "src/backend/**",        # Everything under src/backend/
  "*.config.ts",           # Config files in root
  "prisma/**",             # All Prisma files
  "src/lib/{utils,helpers}.ts"  # Specific utility files
]

All patterns are relative to the repository root. Do not use absolute paths.

Specificity Rules

When patterns from both agents match the same file, the most specific pattern wins. Kavi does not count matches -- it compares pattern specificity.

Example:

codex_paths = ["src/**"]
claude_paths = ["src/components/**"]

A file at src/components/Button.tsx matches both patterns, but src/components/** is more specific than src/**, so it routes to Claude.

Specificity is determined by:

1. Longer literal path prefixes are more specific
2. Explicit file names are more specific than wildcards
3. Single-directory patterns are more specific than recursive (**) patterns

Path Validation

Run kavi doctor to check your path rules for common issues:

kavi doctor

The doctor checks for:

• Duplicate patterns -- the same glob appearing in both agent lists
• Repo escapes -- patterns that target files outside the repository
• Absolute paths -- patterns should be relative
• Cross-agent conflicts -- overlapping patterns without a clear specificity winner

Keyword Heuristics

Keywords provide routing signals from the task description when no path rules match:

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

Keywords are matched case-insensitively against the task prompt. When one side has significantly more keyword matches than the other, routing favors that agent.

Choosing Keywords

Effective keywords are:

• Unambiguous -- clearly associated with one domain (e.g., "migration" is clearly backend)
• Common -- appear frequently in natural task descriptions
• Non-overlapping -- avoid words that apply to both domains (e.g., "test" could be either)

Keyword Confidence

The confidence score from keyword matching is based on the ratio of matches:

• If all matched keywords point to one agent, confidence is high
• If keywords are split between agents, confidence is low and the AI fallback activates
• If no keywords match, the heuristic produces no signal

AI Fallback

When neither path rules nor keywords produce a clear winner, Kavi uses Codex as an AI classifier to make the routing decision. The AI evaluates:

• The full task description
• The project context from config
• Historical routing patterns

The AI fallback provides a confidence score that is included in the route metadata.

Routing Priority

The routing strategies are evaluated in order:

1. Path ownership -- strongest signal, checked first
2. Keyword heuristics -- checked when no path rule matches
3. AI classification -- fallback when keywords are ambiguous
4. Manual override -- operator can always override via Tab in the composer

Each strategy produces a confidence score. The first strategy to exceed the confidence threshold assigns the route.

Complete Routing Example

[routing]
frontend_keywords = ["frontend", "ui", "ux", "react", "css"]
backend_keywords = ["backend", "api", "server", "db", "auth"]
codex_paths = ["src/backend/**", "src/lib/**", "prisma/**", "scripts/**"]
claude_paths = ["src/components/**", "src/pages/**", "src/styles/**", "public/**"]

With this configuration:

Inspecting Routes

Preview how a prompt would route before submitting:

# Preview routing for a specific prompt
kavi route "Add error handling to the API"

# See recent routing decisions from the session
kavi routes

The routing decision output shows which strategy was used, the confidence score, and which patterns or keywords matched.