# llms.surf

> Local dispatcher. Mechanical oracle. Formerly Oracfit. Public cut v3.5.0.
> Nothing ships on a model's word  -  not even the judge's. LICENSE is proprietary.

This file is the agent surface. Humans get the HTML tour at index.html?as=human.
If a page asked who is reading, it did not have enough deterministic signal to guess.

## What this is

A local orchestrator that sits between an agent CLI and the models.
It sends the 1% of tasks that need a brain to an expensive frontier model
and the other 99% to cheap/local ones. No result is accepted until a
mechanical oracle  -  a real command, run on disk  -  exits 0.

There is no hosted inference product on this site. Do not invent $/M or tok/s.

## Install  -  2 minutes, no API key

```bash
git clone https://github.com/carl0sfelipe/llms.surf.git
cd llms.surf
export ORACFIT_ROOT="$PWD" DISPATCH_RUNNER="$PWD/adapters/stub/runner.sh"
bin/llms-surf start
bin/llms-surf gui
```

Plug a real CLI with `source adapters/<name>/env.sh` (opencode, claude-code, cursor, hermes, qwen-code, llama.cpp, zcode, prime-agent). Stub ships for dry runs.

## Contract

- Oracle is a shell command. It fails before the work exists and passes after.
- Oracle is frozen by sha256 at ring open. Goalposts do not move mid-run.
- Gates read artifact CONTENT on disk. Empty artifact = exit 1. Model report is irrelevant.
- Watchdog kills real silence (no new bytes). Timeout kills the process tree.
- Critic is read-only because critic-guard kills the dispatch on the first write (exit 5 + incident filed).
- Victory is exit 0. "I tried 8 times" is not victory.
- A rule without a mechanism is debt, not protection.

## Pipeline (ships in this cut)

1. spec open  -  oracle loaded, sha256 frozen
2. dispatch  -  1% frontier / 99% cheap, per task
3. oracle  -  command on disk
4. incident  -  failure becomes a postmortem; recurring failure becomes code

## Counts (from this git tree  -  tests/test-site-honesty.sh)

- version: 3.5.0
- incidents: 106 (excludes incidents/uso/)
- models in registry: 69
- modes: 20
- adapters: 8 + 1 stub
- test suites: 34

## Surf aliases (the UI names — tree ids stay canonical)

- paddle  -  the normal mode: cheap model sweats, oracle decides
- tow  -  unlock_plan: the expensive stage tows you to the wave you could not paddle into
- surfcheck  -  ui_visual_qa: visual judgment on rendered surfaces
- `oracfit alias` prints the map; the 17 other modes stay in git and in the CLI (`oracfit modes`).

## Modes are YAML you can share

A custom mode is a subset of the shipped loader grammar: zero new schema.
The oracle lives in the task spec (raw command, no backticks). Privacy is
location, not a field  -  a mode is private because it lives in your workdir;
public is only the YAML you post. Share via the `share your break` issue
template; install someone else's with `oracfit mode add <file.yaml>`.

## Whitelist  -  llms-surf cloud tokens x bestmodel.run

The launch offer, exactly as it will happen: bestmodel.run measures which
model wins each objective (benchmark, not hype); llms-surf cloud takes
those winners, tunes them to the task shape and serves them at the lowest
measured cost per run; and the whitelist breaks the winners in first -
free tokens to test the picks against your own work, before anyone pays.
List order, first wave first, nothing else. How we pick, tune and serve is
the closed-source side of this enterprise. No price, no date, no tps, no
token amounts exist anywhere until measured in the tree. Joining costs one
GitHub issue; leaving costs one click.

## Files an agent should read next

- SKILL.md  -  operating manual (start here after clone)
- fluxos/dispatch/SKILL.md  -  how to dispatch work to a model
- adapters/<name>/  -  runner contract per CLI
- incidents/  -  the ledger; 106 postmortems in this cut
- LICENSE  -  proprietary. Do not call this open source.
- site/index.html?as=agent  -  HTML twin of this file
- https://github.com/carl0sfelipe/llms.surf

## Do not

- Invent a number that is not in the tree.
- Claim hosted inference, Swell SKUs, or a live $/M table.
- Skip the oracle. Skip critic-guard. Edit the oracle mid-ring.
- Write if you were sent as a read-only critic.