<p align="center">
  <img src="docs/assets/mark.jpg" width="96" height="96" alt="Ultra-Eye mark">
</p>

<h1 align="center">Ultra-Eye</h1>

<p align="center">
  Cheap eyes for coding agents.<br>
  <a href="https://zhihong0321.github.io/Ultra-Eye/">Homepage</a>
  ·
  <a href="https://github.com/Zhihong0321/Ultra-Eye">GitHub</a>
</p>

The main model asks a question. This MCP server reads the files, command
output, page, or image with **quota-plan flash models** (OpenCode GO, GLM
Coding Plan) and returns a short answer plus verified pointers or quotes.
The raw dump never enters the main model's context. Never calls an Anthropic
API.

The thing being protected is the main model's quota. A multi-file question
or a long test log should be delegated, not ingested. Judge a call from its
receipt: `read` is what the eye processed, `returned` is what the caller got.

```
[Ultra-Eye · read 11,497 tokens → returned 181 · flash 10,520 in / 181 out · glm-5.3-flash · 7.9 s]
```

`model=none` calls show `flash 0 in / 0 out · no model`. `eye_task` appends
`· N steps`. The word `saved` does not appear.

## Tools

| Tool | Use |
|---|---|
| `eye_task` | **Delegate** a multi-file question or a long command. One to three minutes. Do not poll. |
| `eye_scan` | Single-shot codebase lookup. Answer + verified `file:line` pointers. |
| `eye_run` | Run a command and triage large output. Exit, verbatim failures, RAW path. |
| `eye_fetch` | GET a page and answer a question. Quotes are the model's selections, validated, not padded. |
| `eye_look` | Mechanical read of a local PNG/JPEG/WebP. Text, presence, error dialogs. Not design judgement. |

Tiny scopes skip the model and return raw (scan under ~2k tokens, run under ~1.5k).

## Tell your agent

Paste into a project `CLAUDE.md` or `AGENTS.md` (same text as [`AGENT-GUIDANCE.md`](AGENT-GUIDANCE.md)):

- When a question spans several files, or a command will print more than a screen, delegate to `eye_task` in one call and answer from its result.
- When a page or an image needs reading, use `eye_fetch` or `eye_look`.
- For a lookup one grep would answer, do it yourself.
- Expect one to three minutes for a delegation; do not poll or retry within that window.
- After any Ultra-Eye call, repeat its receipt line (the last line, starting `[Ultra-Eye ·`) at the end of your reply.

Usage over a week: `python -m ultraeye.report`

## Install

Python 3.11+, Windows-native stdio, no WSL. Version **1.0.0**.

```
git clone https://github.com/Zhihong0321/Ultra-Eye.git
cd Ultra-Eye
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .
copy ultraeye.example.json ultraeye.json
```

Set `vault_path` in `ultraeye.json` to your credential store. Credentials are
read by name on every call. No telemetry.

Start command (from the clone):

```
.venv\Scripts\python.exe ultraeye\server.py
```

### Grok

```
grok mcp add ultra-eye -- "<clone>\.venv\Scripts\python.exe" "<clone>\ultraeye\server.py"
grok mcp enable ultra-eye
```

Then `/mcps` → enable, or start a new session. Five tools should appear.

### Claude Code (global)

```
claude mcp add ultra-eye -- "<clone>\.venv\Scripts\python.exe" "<clone>\ultraeye\server.py"
```

### Codex

`~/.codex/config.toml`:

```toml
[mcp_servers.ultra-eye]
command = "C:\\path\\to\\Ultra-Eye\\.venv\\Scripts\\python.exe"
args = ["C:\\path\\to\\Ultra-Eye\\ultraeye\\server.py"]
```

### Cursor

`.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ultra-eye": {
      "command": "C:/path/to/Ultra-Eye/.venv/Scripts/python.exe",
      "args": ["C:/path/to/Ultra-Eye/ultraeye/server.py"]
    }
  }
}
```

### OpenCode

`opencode.json`:

```json
{
  "mcp": {
    "ultra-eye": {
      "type": "local",
      "command": ["C:/path/to/Ultra-Eye/.venv/Scripts/python.exe", "C:/path/to/Ultra-Eye/ultraeye/server.py"],
      "enabled": true
    }
  }
}
```

### This machine

Already cloned at `D:\Tools\Ultra-Eye`:

```
D:\Tools\Ultra-Eye\.venv\Scripts\python.exe D:\Tools\Ultra-Eye\ultraeye\server.py
```

## Providers

Text (`providers` in `ultraeye.json`): OpenCode GO `glm-5.3-flash` then
`qwen3.8-flash`, then GLM Coding Plan `glm-5.3-flash`. Reasoning:
`default` | `low` | `high` (shipped `low`). `default` is the OpenCode
endpoint default, not “off”.

Vision (`vision_providers`): OpenCode GO `deepseek-v4-flash-vision-exp`.
Text calls do not use this list.

## Response shapes

Every response ends with the receipt.

- `eye_scan` — ANSWER / POINTERS / CONFIDENCE / receipt
- `eye_run` — EXIT / FAILURES / SUMMARY / RAW / receipt
- `eye_task` — RESULT / EVIDENCE / STEPS / CONFIDENCE / receipt
- `eye_fetch` — ANSWER / QUOTES / SOURCE / CONFIDENCE / receipt
- `eye_look` — ANSWER / TEXT_FOUND / CONFIDENCE / receipt

## Call log

`ultraeye.log` — one JSON line per call. Per-model incidents:
`ultraeye.incidents.jsonl`.

```
python -m ultraeye.patches
python selftest.py
```

## License

MIT. See [LICENSE](LICENSE).