Roteiro

Use it from an agent platform.

Roteiro serves your codebase knowledge to an AI agent platform through one endpoint that exposes both a graph-grounded /v1 model API and the /mcp graph tools, across many projects at once. This guide wires it into Omnigent, using the polly orchestrator as a worked example, with a cheap→foundation model cascade that keeps grounding at every tier.

The shape: one endpoint, two surfaces, many projects

A Roteiro graph is per-repo. A single serve process holds your model once and hosts every registered repo, opening each project's graph on demand (ADR-0008). It exposes two surfaces on the same port:

Every tool takes an optional project argument, so one endpoint answers about any of your repos. This is why you only need one Roteiro process: /v1 and /mcp are just path prefixes on the same server.

Run Roteiro

Point it at a directory of checkouts; each git repo under it becomes a project. Serving both surfaces from one process (the --models --mcp command below) needs a build with --features serve,mcp; each surface alone needs only its own feature (serve for /v1, mcp for /mcp).

# One process, one port (127.0.0.1:8017): both /v1 and /mcp, every repo under ~/code
roteiro serve --models --mcp --workspace ~/code

# A client (your router) discovers projects with a plain GET — no model round-trip
curl -s http://127.0.0.1:8017/v1/projects
#   {"object":"list","data":[{"id":"roteiro","object":"project"},{"id":"omnigent",…}]}

# Ask a grounded question, scoped to one project via the URL prefix
curl -s http://127.0.0.1:8017/v1/roteiro/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"qwen3-8b","messages":[{"role":"user","content":"Where is the git-native store?"}]}'

The cascade: cheap-first, grounded at every tier

The pattern you want is a router that tries the cheapest capable tier and escalates only when needed — and, crucially, keeps the model grounded in the graph the whole way up. The key move is to make Roteiro's local model the cheapest tier, not a foundation-model call.

Wire it into polly

polly is Omnigent's coding orchestrator: it plans and delegates to a roster of coding sub-agents and has a different-vendor reviewer double-check the work. Its config is a config.yaml bundle — the parts that matter here are the executor brain, the tools.agents roster, and an mcp_servers block that hands tools to the agent.

Give polly (and its investigators) the Roteiro graph by registering the one endpoint as an MCP server — so explore / search dispatches are graph-grounded rather than blind greps:

# polly's config.yaml — the relevant parts (roster trimmed)
spec_version: 1
name: polly
executor:
  type: omnigent
  config:
    harness: claude-sdk          # the orchestrator "brain"

# Register Roteiro's one endpoint as an MCP server: the streamable-HTTP
# transport at /mcp. Now search/explain/path/debt (scoped by `project`)
# are available to polly for grounded investigation.
mcp_servers:
  - name: roteiro
    transport: streamable-http
    url: http://127.0.0.1:8017/mcp

tools:
  agents: [claude_code, codex, opencode, cursor, hermes, agy, pi]

Add the cheap grounded tier by registering Roteiro's /v1 as an OpenAI-compatible provider (one entry, or one per project via the /v1/<project> base URL). polly's read-mostly worker, pi — "the only worker that can run ANY gateway model" — is the natural place to route a Tier-1 grounded lookup before spending a frontier dispatch:

# In your Omnigent provider config, add Roteiro as an OpenAI gateway.
# base_url is Roteiro's /v1 (optionally /v1/<project> to pre-bind a repo).
provider: openai
base_url: http://127.0.0.1:8017/v1
model: qwen3-8b                   # local, graph-grounded, free

# Then a dispatch can name it as the worker's model for a cheap grounded pass:
#   sys_session_send(title="explore-auth", args={purpose:"explore", model:"qwen3-8b"})
# escalating to a Claude model only when the local answer is weak.

Operating it