> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# Symbolic and LLM routing pipeline

> How Arka's layered pipeline routes natural language to 120+ skill patterns using symbolic offline matching before falling back to an LLM.

Arka routes every request through a layered pipeline. Most requests never touch an LLM — symbolic rules in `config.fish` match 120+ skill patterns offline.

Important: if you type a plain shell command, the shell runs it normally. Arka only gets a chance to route the request when you invoke it through `arka` or an alias like `agent_route`.

## Routing pipeline

<Steps>
  <Step title="Direct skill name">
    If the first token matches a registered skill, Arka runs it immediately. Zero tokens.

    ```bash theme={null}
    arka weather
    arka calc 2+2
    demo_echo hello    # third-party plugin by name
    ```
  </Step>

  <Step title="Plugin triggers">
    Arka checks third-party skills in `~/.config/arka/skills/` next. Each plugin declares `triggers` in `skill.json`.
  </Step>

  <Step title="Offline symbolic rules">
    The default path. `_agent_guess_route` and `_agent_offline_route_cmd` in `config.fish` match regex patterns for 120+ skills. No LLM call. You'll see `💡 [Offline routing]` and `→ Interpreted: …` when this fires.
  </Step>

  <Step title="LLM route">
    When offline rules don't match, Arka sends a compact skill catalog to the LLM with `task=route`. The model picks the best skill.
  </Step>

  <Step title="Correction layer">
    A deterministic correction layer fixes weak LLM picks without a second LLM call (e.g. `search_web` → `web_answer` for factual questions).
  </Step>

  <Step title="Dispatch">
    `dispatch.py` executes the chosen skill script.
  </Step>
</Steps>

## Token usage by layer

| Layer                | LLM tokens                       |
| -------------------- | -------------------------------- |
| Direct skill name    | **0**                            |
| Symbolic routing     | **0**                            |
| Plugin triggers      | **0**                            |
| LLM route (fallback) | **small** (compact catalog only) |

Default mode is `ROUTE_MODE=symbolic` — offline rules first, AI only when needed.

## Ambiguous routing

When two or more offline patterns could apply (common with play/media), Arka detects the collision and asks the LLM to choose:

```text theme={null}
💡 [AI routing — ambiguous play/media request]
→ Interpreted: play_movie bohemian rhapsody
```

Clear one-sided requests still use offline routing with zero tokens.

## Route modes

| Mode            | Behavior                                                                                              |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| `symbolic`      | Offline rules first, LLM only when needed (default)                                                   |
| `ai`            | Prefer LLM routing                                                                                    |
| `symbolic_only` | Never call LLM for routing; Python symbolic extras run before fish, and fish LLM previews are ignored |
| `ai_only`       | Always use LLM for routing                                                                            |

```env theme={null}
ROUTE_MODE=symbolic
```

## Inspect routing

Preview what skill Arka would pick without running it:

```bash theme={null}
arka route "summarize my unread emails"
agent_route "play bohemian rhapsody on spotify"
agent_trace          # last routing decision
agent_why            # explain skill choice
arka help            # full skill list
arka tell your skills   # voice-friendly summary + active model
```

## Python fallback (no fish)

When fish is not installed, Arka uses `src/arka/routing/symbolic.py` for the same offline-first behavior. The portable CLI still supports chat, web answers, passwords, calc, weather, sports, and plugins.

Install [fish shell](https://fishshell.com) to unlock the full 70+ skill router.

The self-improve workflow is also routed as a dedicated skill, so phrases like `self improve routing` can stay local and deterministic while still opening the repo analysis path.

Developer tooling now follows the same offline-first path: `arka ci`, `arka review staged`, `route audit`, and `skill new my_tool --template dev` are handled by symbolic routing before any LLM fallback.

For UI work, `build this project from screenshot.png` and similar phrases route to the screenshot-to-design brief skill, which analyzes the image first and then produces an implementation-oriented build plan.

If you want Arka to look at its own frontend output and iterate, phrases like `review this frontend`, `retry 3 loops`, or `check the UI screenshot and rebuild` route to the frontend visual loop skill. It captures the rendered result, critiques it, and can run another build command before the next pass.

## Skill router vs orchestrator

The **skill router** decides *which skill runs*. The **LLM orchestrator** (see [LLM orchestration](/concepts/llm)) powers completions *inside* skills — summarize, chat, research, PDF, predictions — with provider failover. They are separate systems.

## Related

<CardGroup cols={2} />


## Related topics

- [Arka — AI terminal agent documentation](/index.md)
- [How to code with Arka](/guides/code-with-arka.md)
- [Skills catalog: 70+ built-in Arka commands](/guides/skills.md)
- [MCP integration for Cursor and Claude](/guides/mcp.md)
- [Operation modes](/guides/operation-modes.md)