vector

README

vector

Vector is a local model router for AI coding harnesses. It sends the subagents your harness spawns to cost-efficient open models while keeping frontier planning on the Claude and Codex subscriptions you already pay for. One local gateway resolves every request to a provider, base URL, and API key, so your plan quota goes to the work that needs it.

Beta: Vector is under active development. Interfaces, configuration, and behavior may change between releases. Shape translation between Anthropic and OpenAI wire formats is not yet implemented; requests that need it return 501 rather than being sent incorrectly. See Status.

Vector supports macOS and Linux on Apple Silicon, Intel, and ARM.

Install

One-line installer — downloads the release, verifies its checksum, installs to ~/.local/bin, and adds that directory to your shell's PATH if needed:

curl -fsSL https://raw.githubusercontent.com/anunay999/vector/main/install.sh | sh

With a Go toolchain:

go install github.com/anunay999/vector/cmd/vector@latest

From source:

git clone https://github.com/anunay999/vector && cd vector
make build          # produces ./bin/vector

Confirm the install and see the full guide at any time:

vector --version
vector guide        # setup guide + current machine state

Quick start

vector init                         # config, API key, optional harness wiring
vector up                           # start the local gateway
vector doctor                       # verify config, keys, gateway, and wiring

init writes ~/.config/vector/config.yaml, stores your OpenRouter key in the private env file, and can wire your harnesses. It never overwrites an existing configuration. up starts the gateway in the background; run vector service install to start it at login. doctor inspects the full path and reports the first problem with a concrete fix. Watch it live with vector top.

For automation, the same setup runs non-interactively:

vector setup --key "$OPENROUTER_API_KEY" --wire claude,codex --start --json

What you can do

Vector is a pass-through — you keep using Claude Code or Codex exactly as you do today. Only the model behind a request changes.

Keep the plan on your subscription; send the busywork to a cheap model. Wire the harness once, then use it normally.

vector claude on      # or: vector codex on

The main session stays on your Claude/Codex plan. When the frontier model spawns a subagent — vector-worker, vector-scout, vector-reviewer — it runs on an open model (DeepSeek-V4.1-Flash, GLM-5.3-Flash, Kimi-K3), picked by role.

Redirect any existing model to another one. Applied live at the gateway; no harness changes.

vector models map "claude-haiku*"  openrouter/z-ai/glm-5.3-flash
vector models map "claude-sonnet*" openrouter/deepseek/deepseek-v4.1-flash
vector models map "claude-opus*"   openrouter/deepseek/deepseek-v4.1-flash   # moves the trunk too

Repoint an agent you already have.

vector claude route scout            # scout    -> the scout role
vector codex  route explorer worker  # explorer -> the worker role

See which model each role uses — and change it. vector models prints every role and the target it resolves to (PREFER, first match wins); models use edits it live and persists it.

vector models                                             # roles + the model each resolves to
vector models use worker openrouter/z-ai/glm-5.3-flash    # change the worker role
vector models use scout  openrouter/deepseek/deepseek-v4.1-flash --append   # add a fallback

Listing a native provider keeps that role on your subscription — that's why architect and escalate stay on Claude/Codex.

Your prompts, tools, and MCP servers (Trove, Linear, and the rest) keep running natively — vector only chooses which model answers.

Setup with your agent

Paste this into Claude Code, Codex, OpenCode, or any coding agent. It installs vector, configures it, wires your harnesses, and verifies — no manual steps.

Set up vector, a local model router for coding agents (github.com/anunay999/vector).

1. Install it:
     curl -fsSL https://raw.githubusercontent.com/anunay999/vector/main/install.sh | sh
   If that fails (no release yet), use: go install github.com/anunay999/vector/cmd/vector@latest

2. Read the self-describing guide and current machine state:
     vector guide --json
     vector schema

3. Configure it. Use my OpenRouter key from $OPENROUTER_API_KEY if it is set;
   otherwise ask me for the key before continuing:
     vector setup --key "$OPENROUTER_API_KEY" --wire claude,codex --start --json
   Drop harnesses I don't use from --wire (claude, codex, opencode).

4. Verify and report back:
     vector doctor --json
     vector top --once
   Summarize: config path, which harnesses are wired, gateway status, providers,
   roles, and any warnings. If a check fails, run `vector guide` and fix it.

Rules: never print, log, or commit the API key — it belongs only in
~/.config/vector/env (mode 600). Never edit ~/.codex/config.toml; vector uses a
managed overlay. Subagents must keep running natively in their own harness.

If I already have agents in ~/.claude/agents (or Codex roles), list them with
`vector agents` and tell me which ones still pin a native model, then offer to
route them, e.g. `vector claude route scout`.

Or run the whole thing yourself in one command:

vector setup --key "$OPENROUTER_API_KEY" --wire claude,codex --start --json

Claude Code

vector claude on
vector claude status

claude on points new Claude Code sessions at the gateway, enables model discovery, re-enables Claude Code's deferred MCP tool loading (ENABLE_TOOL_SEARCH=auto, which the CLI turns off behind any non-Anthropic URL), and installs native subagent definitions under ~/.claude/agents. It backs up the values it changes. Planner traffic is reverse-proxied to Anthropic with your own credential; subagent traffic goes to the cheap pool. Restart Claude Code after enabling or disabling the integration.

Behind a gateway Claude Code also stops treating the account as 1M-entitled, and a claude-opus-5 session on the resulting 200k auto-compact window will loop if its tool schemas alone exceed ~150k tokens. vector doctor flags both conditions, and the gateway's guard.thrash breaker warns or blocks a session caught in that loop. Read docs/claude-code-context.md before wiring a Claude Code with many MCP servers.

Controls:

vector claude on
vector claude off
vector claude status

Codex CLI

Codex support writes a managed profile overlay and never touches your ~/.codex/config.toml. The main session stays fully native; only spawned agents use the router.

vector codex on
vector codex status
codex --profile vector

Start Codex without --profile vector to keep native OpenAI routing. Remove the overlay with vector codex off.

OpenCode

vector opencode on
vector opencode status

Adds a vector provider and per-role subagents to opencode.json. Remove them with vector opencode off.

Agents

Vector installs its own vector-* agents and never rewrites the ones you already have. But an existing agent that pins model: opus (Claude Code) or model = "..." (a Codex role file) overrides CLAUDE_CODE_SUBAGENT_MODEL, so it would keep using the native plan. Inspect and repoint them:

vector agents                              # every agent across harnesses + routed?
vector claude agents
vector claude route scout                  # routes scout -> the scout role
vector claude route worker reviewer        # agent worker -> role reviewer
vector claude route scout --model opus     # or an explicit model / native alias
vector codex  route explorer worker
vector claude route --all --dry-run

With no target, an agent is routed to the role of the same name, so you never write route scout scout. route edits only the model binding (frontmatter for Claude, the role file for Codex), backs the file up once, and leaves the prompt untouched. To route (or stop routing) all detected subagents as a group, use the subagents.route switch.

Dashboard

vector top

A live, refreshing dashboard over local telemetry: 30-minute request and cost sparklines, a model-mix bar chart, a 14-day cost-per-day histogram, an off-plan gauge, per-role latency percentiles and average output tok/s, and the most recent requests.

An efficiency line answers "what did routing buy me": estimated saving against the API list price of the model each request asked for (a built-in table covers current Claude and Codex models; vector models reference shows it, reference_prices in config overrides it), tokens kept off the subscription, prompt-cache hit ratio, share of requests using Claude Code's deferred tool loading, and any circuit-breaker events. A sessions table ranks client sessions by cost with their off-plan share, cache hit ratio, smallest cold prompt (the session's fixed payload floor), and guard flag, so a session caught in a compaction loop is visible at a glance. vector spend prints the same efficiency figures, also as --json.

Keys: q quit, p pause, r refresh, f filter by role, v filter by provider, a clear filters. vector top --once prints a single frame for screenshots or CI logs; --since and --interval tune the window and refresh.

Need to tell which of your running sessions is talking? vector sessions groups the same telemetry by client session — session id, checkout, roles, providers, cost, and last activity:

vector sessions                 # last 6h, most-recent first
vector sessions --since 24h --json
vector telemetry --project space2 --since 30m

How it works

A request's model name resolves, strongest signal first, to a (provider, base_url, api_key, upstream_model) triple, in one of two modes:

1. Agent routing (automatic) — an explicit role (vector-worker, or header X-Vector-Role); otherwise a structurally detected subagent routes to the worker agent while subagents.route is on (the default).
2. Model routing (explicit) — a model_map rule matches the inbound model (e.g. claude-haiku*) and forces it to a role, a registry model, or a provider.
3. otherwise native passthrough on your subscription.

There is no fallback pool: a routed request is served as asked or the upstream error surfaces, and the harness retries.

Roles are installed as native subagents in each harness, so the frontier model chooses one by name using its own spawn tool:

Role	Use for	Default backend
vector-architect	understand, plan, decompose (primary)	native Claude/Codex
vector-lead	coordinate medium multi-step work	native / GLM-5.3
vector-reviewer	code review, tests, PR comments	Kimi-K3 / GLM-5.3
vector-worker	scoped edits, mechanical fixes	DeepSeek-V4.1-Flash
vector-scout	read-only search and summarization	GLM-5.3-Flash
vector-researcher	long-context reading	Kimi-K3 / Gemini
vector-escalate	hard or repeated-failure tasks	native Claude/Codex

These are defaults. Run vector models for the live mapping, and vector models use <role> <target> to change one — it applies immediately.

Vector never hosts, sandboxes, or monitors a subagent. Subagents run natively in the harness; the router only chooses the model and translates wire formats.

Subagent traffic is detected structurally, not by model name: Claude Code tags spawned agents with x-claude-code-agent-id / cc_is_subagent=true, and Codex names the agent in x-codex-turn-metadata. So a subagent routes to the cheap role even when the harness asks for a frontier model. Every request is also attributed to its client session via X-Claude-Code-Session-Id (Claude Code) or session-id (Codex).

Self-describing CLI

The commands above emit machine-readable output, so both you and an agent can drive them:

vector guide --json     # step-by-step guide + live state and next actions
vector schema           # JSON Schema for config.yaml
vector setup --json     # non-interactive one-shot setup

Every command supports --json (doctor, status, models, spend, guide, setup), and AGENTS.md is read automatically by Claude Code, Codex, and OpenCode.

Status and troubleshooting

vector status
vector doctor
vector doctor --json

vector top                       # live dashboard: sparklines, mix bars, roles
                                 # keys: q quit, p pause, r refresh, f role, v provider, a clear
vector top --once                # a single frame
vector logs                      # tail the gateway log
vector logs --follow             # stream it
vector logs --path               # just print the path

vector telemetry --since 24h     # raw request records
vector telemetry --json --limit 0
vector telemetry --role worker --provider openrouter
vector telemetry --follow        # stream new records as JSONL

vector spend --since 24h         # aggregated cost / off-plan share

status summarizes the gateway, harness wiring, and spend. doctor inspects the same path without changing it and exits non-zero on a failed check. Logs and telemetry live beside the active config file (so --config /path keeps them together):

<config dir>/config.yaml
<config dir>/env                 # secrets, mode 0600
<config dir>/logs/gateway.log    # every start method writes here
<config dir>/telemetry/requests-YYYY-MM-DD.jsonl

With the default config that is ~/.config/vector/. Telemetry records metadata only — models, provider, role, tokens, cost, latency, status — never prompts, responses, headers, or bodies.

Symptom	Fix
unresolved env vars	vector env set VAR value
gateway not reachable	vector up, then vector status
harness shows off	vector claude on / vector codex on
requests return 501	provider lacks an Anthropic shape; set anthropic_base_url or use OpenRouter
Codex children still use the plan	confirm vector codex on, then run codex --profile vector

Configuration

Two files, both mode 0600:

File	Holds
~/.config/vector/config.yaml	providers, models, roles, model_map, subagents, budget
~/.config/vector/env	secrets referenced as ${VAR}

Prefer the typed commands over direct edits; they validate as they write and reload the running gateway automatically (SIGHUP) — no restart, no reinstall:

vector config path
vector config get budget.daily_usd
vector config set budget.daily_usd 10
vector config unset budget.per_provider

vector models use worker openrouter/deepseek/deepseek-v4.1-flash   # change a role live
vector models set openrouter/z-ai/glm-5.3 --in 1.007 --out 3.41    # add/update a model
vector models remove openrouter/old/model
vector models map claude-sonnet-5 openrouter/z-ai/glm-5.3-flash     # redirect an inbound model
vector models map "claude-opus*"  openrouter/deepseek/deepseek-v4.1-flash

vector env set OPENROUTER_API_KEY sk-or-...
vector env list                 # values redacted
vector config validate

Providers are any OpenAI-compatible endpoint plus native Anthropic/OpenAI. Roles are ordered preference lists. Daily and per-provider budget ceilings and concurrency caps are configurable. There is no fallback pool: a routed request is served as asked or the upstream error surfaces. See docs/configuration.md for every field, or vector schema for the machine-readable schema.

To move the main session onto a cheap model, route its model explicitly with vector models map, or put a cheap model first in roles.architect.prefer. See docs/configuration.md.

CLI

vector init | setup | guide | schema
vector up | down | restart | serve | status | doctor
vector config init | show | path | get | set | unset | validate
vector env path | list | set | unset
vector service install | uninstall | status
vector upgrade
vector claude | codex | opencode   on | off | status
vector agents [--json]
vector claude | codex   agents | route <agent> [role]
vector models [--json]
vector models set <provider/model> [--tags …] [--context N] [--in F] [--out F]
vector models remove <provider/model>
vector models use <role> <target> [--append]
vector models map <from> <to> | --remove <from>
vector top [--once] [--since 24h] [--interval 1s]
vector logs [--follow] [--lines N] [--path]
vector sessions [--since 6h] [--json]
vector telemetry [--since 24h] [--json] [--follow] [--role R] [--provider P] [--session S] [--project P]
vector spend [--since 24h] [--json]

Upgrade

vector upgrade      # re-runs the installer, then restarts the service
vector doctor

vector upgrade pulls the current release (or go installs when no release is published) and restarts the login service automatically. To do it by hand:

curl -fsSL https://raw.githubusercontent.com/anunay999/vector/main/install.sh | sh
vector restart

Config-only changes never need this — vector config set and vector models use reload the running gateway in place.

Uninstall

vector service uninstall
vector down
vector claude off ; vector codex off ; vector opencode off
rm -rf ~/.config/vector
rm -f ~/.local/bin/vector

Uninstall never removes your harness credentials or provider API keys from the providers themselves.

Privacy and trust

Vector binds its gateway to the local loopback interface. It receives harness requests and credentials because it is in the selected request path. Request content leaves the machine only for the upstream chosen by the active routing policy: native credentials go only to their matching native provider, and configured provider keys go only to that provider.

Local telemetry contains request metadata — models, provider, role, token counts, cost, latency, and status — not prompts, responses, headers, or request bodies. Disable it with telemetry.enabled: false. The /admin/status endpoint is restricted to loopback even when the data plane is exposed. Secrets live only in ~/.config/vector/env (mode 0600) and are resolved from the environment first, then that file.

Build and test

make build      # bin/vector
make test       # go test ./...
make race       # go test -race ./...
make vet
make hooks      # install local git hooks

Layout and conventions are in AGENTS.md. The design is documented in docs/architecture-proposal.md.

Contributing

The default branch is protected: no pull request can merge without an approving review from the code owner (@anunay999), enforced via .github/CODEOWNERS and GitHub branch protection. Every PR must also pass the required status checks — fmt, tidy, vet, build, test, lint, vuln, shellcheck, and selfcheck; CodeQL runs as an advisory check. Install the local hooks for fast feedback with make hooks. See docs/governance.md. Never commit secrets.

License

Vector is available under the Apache License 2.0.