How Routing Works

oxicrab routes each message through a simple layered policy: deterministic first, constrained LLM next, full LLM last.

On this page

Flow

Each inbound message is evaluated in order. As soon as one layer can confidently handle it, routing stops and execution proceeds with a strict tool policy.

User Message session + context 1) Deterministic Router buttons / directives / rules 2) Constrained LLM strict allow/block tool policy 3) Full LLM semantic prefilter optional Tool Execution policy enforced again State Update session metadata + replay first match wins

Layers

1) Deterministic Router (first)

Fast, rule-based dispatch for high-confidence actions: button clicks, active directives, prefix commands, and configured static rules.

Example: User clicks a button payload mapped to todoist → immediate direct tool call, no LLM needed.

2) Constrained LLM (second)

When context is tool-focused, the LLM runs with a strict RoutingPolicy: exact allowed_tools, blocked_tools, and reason.

Example: In a cron-focused thread, only cron-related tools + interaction helpers are exposed.

3) Full LLM (last)

Fallback when deterministic and constrained routing do not apply. Semantic filtering can reduce the tool set first; if confidence is low, it falls back to unconstrained full LLM.

Example: “Plan my day from calendar + weather + tasks” may trigger semantic narrowing before the model reasons.

Context State

Router context is stored in session metadata with an explicit state machine:

  1. Idle: no active tool context.
  2. ToolFocused(tool, directives, ttl): directed flow with expiry and explicit transitions.
Important: execution enforces route policy even if a model tries calling an out-of-policy tool.

Simple Usage Examples

  1. “Run my daily briefing cron job”: deterministic route can dispatch directly to cron when a static rule/directive matches.
  2. “Show me cron failures from yesterday”: constrained LLM in a cron-focused context with strict tool allowlist.
  3. “What should I do this afternoon?”: full LLM path, optionally narrowed by semantic tool selection.
  4. Button follow-up flow: button payload routes direct, then context can remain tool-focused for next turns until TTL/override.

Router Configuration

Common routing controls in router config:

[router]
prefix = "!"
semanticTopK = 6
semanticPrefilterK = 16
semanticThreshold = 0.35

[[router.rules]]
trigger = "briefing"
tool = "cron"
params = { action = "list" }

[[router.rules]]
trigger = "todos"
tool = "todoist"
params = { action = "list" }
Example: with prefix = "!", typing !briefing lists cron jobs and !todos lists tasks. Both are deterministic dispatches with no LLM call.

See Config for full schema and defaults.

Related guides: CLI Reference and Workspace Docs.