The coding agent. Open-Source, with Subagents, Planning, Web-Searches, Skills, Hooks, Great Tools, Animations, Compaction, Recoverability, and much more.
Documentation · Releases · Architecture · Skills
Works with:
- OpenRouter (DeepSeek, Gemini, OpenAI, Anthropic, GLM, Qwen, Kimi, MiniMax, …)
- Anthropic (direct)
- OpenAI (direct)
- DeepSeek (direct — full reasoning round-trip on V4 Pro / V4 Flash)
- Ollama (local —
http://localhost:11434, no API key required for local models)
Prebuilt binaries per platform — grab the latest from GitHub Releases:
macOS (arm64)
curl -fsSL https://github.com/TimAnthonyAlexander/ye/releases/latest/download/ye-macos -o ye && chmod +x ye && sudo mv ye /usr/local/bin/ye
Linux (x64)
curl -fsSL https://github.com/TimAnthonyAlexander/ye/releases/latest/download/ye-linux -o ye && chmod +x ye && sudo mv ye /usr/local/bin/ye
Windows (x64, PowerShell)
$dest = "$env:LOCALAPPDATA\Programs\ye"; New-Item -ItemType Directory -Force $dest | Out-Null; Invoke-WebRequest https://github.com/TimAnthonyAlexander/ye/releases/latest/download/ye-windows.exe -OutFile "$dest\ye.exe"; [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path","User") + ";$dest", "User")
Restart the shell after install.
git clone git@github.com:TimAnthonyAlexander/ye.git && cd ye
bun install
bun run build
ye
Ye opens in the current directory, streams model output, prompts before state-modifying tool calls.
@-mention files from the project index:
Watch edits stream in as the model works:
Tool calls run with live status:
End-to-end: ask Ye to build a site, get a finished result:
Modes — cycle with Shift+Tab:
- NORMAL — default. State-modifying tools prompt (y/n); read-only auto-allow.
- AUTO — every tool auto-allows. For trusted projects and long sessions. Bash has no sandbox yet.
- PLAN — read-only plus
ExitPlanMode. Model proposes a plan, you accept it, mode flips back to NORMAL. Plans persist under~/.ye/projects/<hash>/plans/.
Per-session override: ye --mode AUTO (or NORMAL / PLAN).
CLI flags:
ye --resume [sessionId]— resume the last session (or a specific one).ye --mode AUTO|NORMAL|PLAN— start in a specific mode.ye -p "<prompt>"— headless one-shot. Streams to stdout, exits when done. No TTY needed.ye --update— self-update to the latest release binary for this platform.
Project notes — reads YE.md if present, otherwise also CLAUDE.md if present.
Project memory and sessions under ~/.ye/projects/<hash>/, keyed by a stable hash of the project root.
Fifteen built-in tools:
| Tool | What it does |
|---|---|
| Read | Read a file (default 2000 lines, offset + limit for slicing). Absolute paths only. |
| Edit | Exact-string replace. Requires a prior Read of same file. replace_all flag. |
| Write | Create or overwrite. If the file exists, prior Read is required. |
| Bash | Run a shell command via sh -c. 2-min default timeout, 15-min max. |
| Grep | Wraps rg. Three modes: content, files-with-matches, count. Type/glob filters. |
| Glob | File pattern match, sorted by mtime. Skips noise dirs (node_modules, .git, etc.). |
| TodoWrite | Lightweight task list. Exactly one in_progress at a time. |
| Task | Spawn an isolated subagent (explore, general, or verification). Sidechain transcript, summary returned. |
| WebFetch | Fetch URL, HTML→markdown, small-model summarise. 15-min cache. Cross-host redirect detection. |
| WebSearch | Search the web. Anthropic server-side, Brave, or DuckDuckGo fallback. Title + URL only. |
| Skill | Invoke a named user/project skill for specialised instructions. Read-only metadata load. |
| SaveMemory | Persist a memory note. Writes to project memory store, auto-selected in future sessions. |
| AskUserQuestion | Ask the user a structured 2-4 option question with an optional multi-select. |
| EnterPlanMode | Request a switch INTO PLAN mode. Triggers a permission prompt. |
| ExitPlanMode | Write plan and prompt to leave PLAN mode. Only state-modifying tool allowed in PLAN. |
Read-only tools (Read, Grep, Glob, WebFetch, WebSearch, Skill, AskUserQuestion) auto-allow in NORMAL mode. Everything else prompts.
One canonical Provider interface; vendor differences live behind it. Tool-call format normalization happens in the provider module — the rest of Ye never sees vendor-shaped data.
- OpenRouter — default. Streams via SSE, OpenAI-compatible tool calls, context window discovered via the
/modelsendpoint. Per-model reasoning preservation policy (required/preserve/reject) with consistency-strip-all enforcement. Routing strategy via/routing—cheapest(default),fastest,latency, orsticky(pins to first-responding upstream per model). - Anthropic direct — native tool-use blocks, prompt caching at the static/dynamic boundary. Uses
ANTHROPIC_API_KEY. - OpenAI — latest Responses API v1 (GPT-4.1/5 family). Interleaved reasoning & strict schema. Uses
OPENAI_API_KEY. - DeepSeek direct — native V4 Pro / V4 Flash at
api.deepseek.com. Full 1M context, fullreasoning_contentround-trip on tool-call sub-loops (the canonical path for V4 Pro reasoning; OpenRouter strips reasoning fields on every V4 Pro upstream except DeepInfra at 66k ctx — seedocs/REASONING_STORING.mdfor the empirical matrix). UsesDEEPSEEK_API_KEY. - Ollama — local models via
http://localhost:11434. NDJSON streaming, native tool calling on supported models (qwen3, llama3.1+, mistral-nemo, etc.), context size discovered via/api/show./modellists locally pulled models via/api/tags. No API key required for local;OLLAMA_API_KEYhonored for cloud routes. Local models receive a compact system prompt (~5.8× smaller) tuned for their tighter instruction-following budget. - Anthropic (Subscription) — Claude on a Pro/Max plan instead of a per-token API bill, through dario. No API key. See below.
Set the active provider and model in ~/.ye/config.json, or switch mid-session with /provider and /model. Reasoning traces captured from any provider are persisted as Message.reasoning_details in the session transcript and replayed on /resume and /rewind; stripped on /model and /provider switches because signatures and encrypted blobs are model-version-bound.
If you already pay for Claude Pro or Max, /provider → Anthropic (Subscription) runs Ye on that plan rather than on a separate per-token API bill.
It works through dario, a local proxy that speaks the standard Anthropic Messages API on http://localhost:3456 and re-authenticates each request with your own subscription OAuth token. Because its client-facing surface is the standard API, Ye reuses the Anthropic adapter and stream parser unchanged — the provider differs only in base URL, key handling, model namespace, context sizes and capabilities.
Selecting it walks the whole setup, one confirmation per step:
/provider → Anthropic (Subscription)
dario missing? → install it (npm install -g @askalf/dario)
proxy not running? → start it (dario proxy, detached)
no usable account? → log in (dario login, terminal handed over)
Nothing is installed, started or authenticated without an explicit yes, and every step shows the exact command first. If dario already has credentials — it reads Claude Code's, from ~/.claude/.credentials.json or your OS keychain — the login step never fires. Declining the install cancels the switch; declining anything after it still switches and leaves you a one-line hint, the same way Ye treats a dead Ollama daemon. The install goes to your global npm prefix rather than ~/.ye, because dario has to be on your PATH to be usable outside Ye.
Models are dario's namespace, not the raw API's: Fable 5, Opus 5, Opus 4.8, Sonnet 5 and Haiku 4.5, each of the non-Haiku families also offered as a [1m] long-context variant. [1m] is a client-side label — the proxy strips it and rides the context-1m beta — so a plain id is 200K and a [1m] id is 1M.
Two deliberate differences from the API-key provider. WebSearch falls through to Ye's own Brave/DuckDuckGo engines, because the subscription OAuth path carries no server-side web_search tool. And these turns are absent from the pricing table on purpose: a flat-fee plan has no per-token dollars, so /cost and /usage record nothing rather than inventing a number, and /cost says why.
Verifying it's actually on your subscription. Anthropic classifies every response with an anthropic-ratelimit-unified-representative-claim header, and dario surfaces it:
dario usage
# or, for just the number that matters:
curl -s localhost:3456/analytics | jq .allTime.billingBucketBreakdownsubscription counts requests billed to your 5h/7d plan window. api and extra_usage are the two you want pinned at zero. dario's overage guard is on by default and halts the proxy with a 503 on the first overage response until dario resume or a 30-minute cooldown, so a drift into paid billing stops traffic instead of quietly running up a bill.
dario is independent, unofficial and third-party — not an Anthropic product, and not affiliated with Ye. Using a subscription from tools other than Claude Code is outside what Anthropic's own client does, and only Anthropic can say whether that carries account risk. Ye states this in the consent prompt before installing anything.
~/.ye/config.json controls the default provider, default model, permission rules, the auto-compact threshold (default 50% of the context window), and the env-var name to read each provider's key from. Permission rules use a small glob — Bash(rm:*) style — and deny always overrides allow.
Everything Ye writes lives under ~/.ye/:
- Notes hierarchy — managed (
/etc/ye/CLAUDE.md) → user (~/.ye/CLAUDE.md) → project (CLAUDE.mdorYE.md) → local (YE.local.md, gitignored). Concatenated into context in order. - Auto-memory — LLM-based selection of relevant memory files at turn start. No embeddings, no vector DB. Plain Markdown, version-controllable.
- Sessions — append-only JSONL per session under
~/.ye/projects/<hash>/sessions/. One event per line; replays are exact. - Plans — saved as
<word>-<word>.mdfor memorability. - Cross-session prompt history —
~/.ye/history.jsonl, scrollable with up-arrow.
Disk is never destructively edited. Compaction records boundary markers and patches the chain at load time; the original transcript stays intact.
Ye's defense against context blowup. Subagents run the same pipeline with isolated state, write their own sidechain transcript, and return a single summary string to the parent — full subagent history never enters parent context.
- Explore — codebase search, read-only (Read/Glob/Grep). Takes a
thoroughnessparam (quick/medium/very_thorough). - General — full toolset, runs in AUTO mode. Spawned via the Task tool with
kind: "general". - Verification — narrow, post-change verification subagent. Used to sanity-check a finished change without polluting the main transcript.
Skills are pre-written procedural recipes that extend Ye's behavior for specialised tasks — frontend design conventions, release workflows, language-specific patterns.
They live as markdown files under ~/.ye/skills/ (per-user) or .ye/skills/ (per-project, committed to git).
Ye ships with built-in skills and consumes externally-authored ones from GitHub marketplaces.
Installing a skill copies its SKILL.md and supporting files into the skills directory; a restart loads it into the registry.
You can ask Ye to find a skill online and to install it. Or also to create one from your preferences or descriptions.
Ye is under active development. The last 50 commits were done with Ye itself.