README
An agentic CLI coding harness for
DeepSeek
models (
deepseek-chat
V3,
deepseek-coder
V2.5, and
deepseek-reasoner
R1), built in
Elixir & Erlang/OTP
.
OpenRouter
and local models are also supported.
Derived from José Valim's architectural framework for process-isolated AI agents, DeepSeek V3/R1 model architecture , Google Antigravity , and Warp Terminal TUI patterns .
Table of Contents
- Architectural Foundation
- Key Features & Capabilities
- Installation & Setup
- Getting Started & Customization Guide
- REPL Slash Commands & Shortcuts
- Configuration
- Documentation
- License
Architectural Foundation: José Valim's Vision & DeepSeek Model Integration
Yoke (Yoke) bridges modern LLM reasoning capabilities with Erlang/OTP's battle-tested fault tolerance and process concurrency model.
José Valim's Actor-Driven Harness Architecture
In traditional AI harnesses (typically single-threaded Node.js or Python runtimes), a tool execution error or unhandled exception can crash the entire interactive session, wiping out conversation context and active state. Yoke implements José Valim's vision for agentic harnesses on the BEAM virtual machine:
-
Decoupled Brain & Hands Architecture
: The agent's cognitive state ("Brain") runs as an isolated GenServer process (
Yoke.Brain.Session). Tool execution ("Hands") is cleanly separated (Yoke.Hands.Executor), allowing commands to execute locally, on remote Erlang nodes, or inside isolated Docker containers. - Fault-Tolerant Supervision : If a tool execution or sub-task process fails, the OTP supervision tree isolates the failure without impacting the user's interactive REPL session.
-
Spatiotemporal Checkpoints & Instant Rollback
: State snapshots record conversation history, model configurations, and context state before each tool execution turn, providing temporal undo capabilities (
/undo) and state branching. -
Live Hot-Code Tool Reloading
: Tools and plugins can be compiled, hot-swapped, or reloaded live (
/plugins reload) without losing conversation memory or resetting GenServer process state. -
Lightweight Parallel Subagents
: Sub-tasks can be delegated to child session processes (
SessionSupervisor.start_session), running parallel agentic loops concurrently across BEAM worker threads. -
Concurrent OTP Task Engine
: Batches of tool calls (
Yoke.TaskEngine.Orchestrator) run concurrently under aTask.Supervisor, with per-file write locks and a real-time "N running" badge on the status bar ruler. -
Distributed Erlang Node Clustering
: Hands execution can target the local host, a remote Erlang node (
/mode remote), or a Docker container (/mode docker), decoupling where the Brain thinks from where the Hands act.
DeepSeek Model Selection & Best Practices
Yoke supports the full suite of official DeepSeek models, local open-weights models, and third-party API aggregators. Switch models anytime via
/model
or
--model
:
| Model | ID / Alias in Yoke | Best Used For | Strengths & Characteristics |
|---|---|---|---|
| DeepSeek-V3 |
deepseek-chat
/model chat
|
Agentic workflows & multi-tool tasks (Default) | 671B MoE model. Offers high general reasoning and highest tool-calling precision across multi-turn agent loops. |
| DeepSeek-Coder-V2.5 |
deepseek-coder
/model coder
|
Direct code generation, syntax completion & refactoring | Trained specifically on 338+ programming languages . Produces idiomatic Elixir/C++/Rust code with high precision on syntax and language conventions. |
| DeepSeek-R1 |
deepseek-reasoner
/model reasoner
|
Complex debugging & architectural design |
Reinforcement Learning (RL) reasoning model. Yoke captures and streams
[DeepSeek-R1 Reasoning]
Chain-of-Thought output live before tool execution.
|
OpenRouter, OpenCode Go & Local Model Integration (SGLang, Ollama, LM Studio, vLLM)
While
yoke
defaults to the official remote
DeepSeek API
(
https://api.deepseek.com/chat/completions
with
deepseek-chat
), it provides native support for
OpenRouter
,
OpenCode Go (Console Go)
, and local inference engines (
SGLang
,
Ollama
,
LM Studio
,
vLLM
).
A. OpenRouter Configuration
Connect
yoke
to OpenRouter endpoints (such as
meta-llama/llama-3.3-70b-instruct:free
,
qwen/qwen-2.5-coder-32b-instruct:free
, or
deepseek/deepseek-r1:free
):
Environment Variables :
export OPENROUTER_API_KEY="sk-or-v1-..."
export DEEPSEEK_ENDPOINT="https://openrouter.ai/api/v1/chat/completions"
export DEEPSEEK_MODEL="meta-llama/llama-3.3-70b-instruct:free"
yoke
CLI Flags :
yoke -e openrouter -m meta-llama/llama-3.3-70b-instruct:free
Live REPL Commands :
/endpoint openrouter
/model openrouter-free
B. OpenCode Go (Console Go) Configuration
Connect
yoke
to OpenCode Go / Zen endpoints:
Automatic
x-opencode-session
Routing Header
:
OpenCode Go requires the
x-opencode-session
header on every request for backend routing and prompt caching optimization. Yoke automatically attaches this header using the session's unique identifier.
Environment Variables :
export OPENCODE_API_KEY="your-opencode-key"
# Optional custom base URL (defaults to OpenCode Go endpoint when using shortcut):
export OPENCODE_BASE_URL="https://opencode.ai/zen/go/v1/chat/completions"
yoke
CLI Flags & REPL :
yoke -e opencode -m deepseek-chat
# Or switch live in REPL:
/endpoint opencode
C. Local Models (SGLang, Ollama, LM Studio, vLLM)
Run
yoke
completely offline against local LLM servers without requiring API keys:
SGLang (
http://localhost:30000
)
:
yoke -e http://localhost:30000/v1 -m deepseek-ai/DeepSeek-V3
Ollama (
http://localhost:11434
)
:
# 1. Start Ollama model
ollama run qwen2.5-coder:14b
# 2. Launch yoke with local endpoint
yoke -e ollama -m qwen2.5-coder:14b
# Or via environment variables:
export OLLAMA_HOST="http://localhost:11434"
export DEEPSEEK_MODEL="qwen2.5-coder:14b"
yoke
LM Studio (
http://localhost:1234
) & vLLM (
http://localhost:8000
)
:
yoke -e lmstudio -m qwen2.5-coder-32b-instruct
# OR
yoke -e vllm -m deepseek-r1-distill-qwen-32b
Automatic Reasoning &
[Reasoning]
output.
API Key Bypass
: Local loopback endpoints (
localhost
,
127.0.0.1
,
::1
,
192.168.*
) do not require API keys and automatically bypass offline mock mode.
Key Features & Capabilities
Persistent Session Resumption (
yoke -c
&
/resume
)
-
Every session is assigned a unique UUID (e.g.
df97eb34-cb33-4f21-bada-2e9c3cf75d46). -
On exit,
yokeprints your conversation ID:Resume with -c (or command below): yoke --conversation=df97eb34-cb33-4f21-bada-2e9c3cf75d46
-
Resume any conversation across restarts with
yoke -cor interactively pick past sessions in the REPL via/resume. -
Conversations are stored in
lmml(a Markdown-superset markup for LLM conversations) as.lmml .yoke/sessions/— plain, self-contained Markdown that any Markdown viewer renders sensibly, yet round-trips every structured message losslessly through its inline-embed model. Legacy.jsonsession files from earlier versions are still read transparently on resume.
Scoped Rule Engine (
/rules
)
- Manage prompt preambles and execution constraints.
- Scopes :
-
all:— Applied to all user prompt turns (e.g.all: typographic quotes “” mean the exact quote). -
: cr: format table cells multiline to fit in 80 symbols widthfor/cr). -
Use
/rulesto list rules,/rules addto add rules, and/rules deleteto launch the interactive checkbox modal.
Context Reference Expansion (
@
) & Smart Error Resolution
-
Type
@filename,@/path,@file://..., or@https://...anywhere in user prompts to attach contents. -
@triggers an interactive TUI file picker filtered by.gitignorerules (excluding_build,deps,.elixir_ls). -
Intelligently expands ambiguous error references ("error above",
@error) and tracks:openvs:resolvedissue status across tool calls.
Interactive Question TUI Modal (
ask_question
)
- Allows the AI model to request user feedback, clarify requirements, or present multi-choice design decisions with keyboard navigation and OK/Cancel buttons.
Model Context Protocol (MCP) & First-Class Ragex Integration
-
Mount external Model Context Protocol (MCP) servers via
stdio(JSON-RPC) or HTTP/SSE. -
Native integration with
Ragex
for SCIP code indexing, AST refactoring, and semantic code search (
/ragex).
One-Command Global Installation & Updates
-
Install globally to
~/.local/bin/yokeviamix yoke.installorinstall.sh. -
Run
yokesmoothly from any workspace directory. -
Perform background in-place self-updates anytime using
yoke --updateor/update.
Pure Console Mode (
!!
)
-
Type
!!on its own line to flipyokecompletely out of the way: no Brain/Hands actors, no LLM turns, no slash-command dispatch -- just a baresh -cpassthrough with live-streamed output. -
cdis applied toyoke's own process, exactly like a real shell builtin, so navigation persists across commands. -
Type
!!again (orCtrl+D) to flip straight back into the harness REPL -- no need to open a second terminal tab for a quick burst of plain shell commands.
Concurrent OTP Task Engine
-
Tool call batches execute concurrently under
Yoke.TaskEngine.Orchestrator, each in its own supervisedTask, with automatic per-file write locking to prevent concurrent edit races. - The idle status bar surfaces a live "N running" badge with per-task summaries whenever background tool work is in flight.
Native Elixir Static Analysis (
/linter
,
/lint
)
-
Runs
oeditus_credo,propwise,credo, ordialyzeragainst the full project, a git diff, or a branch code review via/linter.[project|diff|cr] [args...]
Configurable Prompt Styles & Status Bar (
/config
)
-
Switch prompt layout with
/config styleor supply a fully custom template via/config prompt. -
Toggle UI features (
enable_autosuggestions,enable_syntax_highlighting,enable_context_gauge,compact_status_bar, and more) with/config toggle.
Customizable Multi-Step Workflows (
/workflow
)
-
Runs a named, customizable, multi-step process on top of the ordinary agent loop: branch off
main/master(with a warn/confirm gate), summarize the task, propose a non-clashing split for parallel execution, require tests + docs, lint, and commit -- with the entire run persisted under.yoke/workflows/. -
Parallel subtasks each get their own isolated
git worktreeand branch, so concurrent agent processes can never clash on disk. -
Ships with a built-in
elixirworkflow; scaffold your own with/workflow init. Full reference:[--from ] docs/WORKFLOW_ENGINE.md.
Idea Lifecycle Pipeline & Strategic Memory Engine (
/sweep
,
/spar
,
/thought
,
/backlog
)
-
Implements an idea-lifecycle pipeline (
thoughts/ → backlog/ → active/ → completed/) with git-ignored derived maps (_MAP.md,_DEPS.md) parsed from YAML frontmatter metadata. -
Multi-Corpus Prior-Art Sweep (
/sweep) : Searches active pipeline, reference docs, operational lessons, and local knowledge vault to prevent repeating past work. -
Socratic & Adversarial Sparring (
/spar [soc|adv]) : Pressure-tests new feature designs turn-by-turn with Socratic requirement probing and blunt Adversarial counter-arguments. -
Structured Memory Architecture
: Transient scratch notes (
/scrap), operational lessons learned (/lessons), and automated close-out gates.
Installation & Setup
This guide provides step-by-step instructions to get
Yoke (
yoke
)
up and running on your system, along with its database backend
dllb
(which powers
Ragex
code analysis and knowledge graph indexing).
Prerequisites (What You Need First)
Before installing
yoke
or
dllb
, ensure your machine has the following tools installed:
- Elixir & Erlang/OTP :
-
yokeis built using the Elixir programming language on top of the Erlang runtime engine. -
Required versions
: Elixir
1.19+and Erlang/OTP27+. -
How to install
: Use your system package manager (e.g.
brew install elixiron macOS orsudo apt install elixiron Ubuntu) or a version manager likeasdf/mise. - Git : Required to download the project source code.
- C/C++ Build Tools & Libraries (Linux only) :
-
Required for compiling native code dependencies:
build-essentialandlibgit2-dev. -
Ubuntu/Debian command
:
sudo apt-get install -y build-essential libgit2-dev
Installing
yoke
(Yoke)
Choose one of the two installation methods below:
Option A: Quick Automated Installer (Recommended)
Run this single command in your terminal to automatically clone, build, and install
yoke
:
curl -fsSL https://raw.githubusercontent.com/Oeditus/yoke/main/install.sh | bash
Option B: Manual Installation from Source
If you prefer installing manually from the source code:
# 1. Clone the repository
git clone https://github.com/Oeditus/yoke.git
cd yoke
# 2. Fetch project dependencies
mix deps.get
# 3. Compile and install yoke globally to ~/.local/bin/yoke
mix yoke.install
Adding
~/.local/bin
to Your System
$PATH
After installation, ensure
~/.local/bin
is included in your shell path so you can run
yoke
from any terminal directory:
export PATH="$HOME/.local/bin:$PATH"
Tip: Add the line above to your shell configuration file (e.g.
~/.bashrcor~/.zshrc) so it is available automatically in every new terminal window.
Installing
dllb
for
ragex
Code Indexing
What is
dllb
and why do I need it?
yoke
features a powerful code intelligence engine called
Ragex
(
/ragex
). To store code symbol relationship graphs, perform fast full-text code searches, and cache project metadata across restarts, Ragex uses a lightweight, high-performance database server called
dllb-server
(written in Rust).
Installing
dllb-server
enables persistent, per-project database indexing.
Option A: Download Pre-Compiled Binary (Easiest)
-
Go to the
dllbGitHub Releases page. -
Download the
dllb-serverbinary for your platform (e.g., Linux or macOS). -
Move the binary into your
~/.local/bindirectory (or any directory in your system$PATH) and make it executable:
# Move to local bin directory
mv dllb-server ~/.local/bin/
# Make executable
chmod +x ~/.local/bin/dllb-server
Option B: Compile
dllb-server
from Source (Rust / Cargo)
If you have the
Rust toolchain
installed (
cargo
):
# 1. Clone the dllb repository
git clone https://github.com/Oeditus/dllb.git
cd dllb
# 2. Build the optimized release binary
cargo build --release -p dllb-server
# 3. Option i: Copy the compiled binary to your PATH
cp target/release/dllb-server ~/.local/bin/
# OR Option ii: Leave it in sibling directory `../dllb/target/release/dllb-server`
How Ragex Finds
dllb-server
(Path Resolution Precedence)
When you run
/ragex
inside
yoke
, Ragex looks for the
dllb-server
executable automatically in this order:
-
Custom Environment Variable
:
DLLB_SERVER_BIN=/path/to/dllb-server -
System
$PATH: Directories in your$PATH(e.g.~/.local/bin/dllb-serveror/usr/local/bin/dllb-server). -
Sibling Repository Path
: Relative path
../dllb/target/release/dllb-serveror../dllb/target/debug/dllb-server.
Verifying Your Installation
-
Check
yokeCLI :yoke --version
-
Start
yokein any project :cd /path/to/your/project yoke
-
Test Ragex Code Indexing
:
Inside the
yokeREPL session, type:/ragex
You should see confirmation that Ragex and the
dllb
knowledge graph backend have been successfully initialized!
Getting Started & Customization Guide
For complete, step-by-step instructions on onboarding, teaching Yoke language idiomatics, driving multi-step workflows, writing custom plugins, setting scoped rules, and tuning the iterative feedback loop, refer to the full
Getting Started & Customization Guide
(also accessible inside the REPL via
/guide
or
/docs
).
Onboarding & Customization Summary
- Core Architecture & Quickstart
- BEAM actor isolation (Brain GenServer decoupled from Hands executor).
-
Basic CLI invocation (
yoke,yoke "prompt"), inline@file/@urlcontext references, and spatiotemporal/checkpoint&/undo. -
Teaching Yoke New Language Idiomatics (
.yoke/practices) -
LMML practice manifests in
.yoke/practices/..lmml -
Run
/practices teachto automatically inspect exemplary codebases and extract team-specific coding conventions. -
Starting & Driving Workflows (
/workflow) -
Run built-in engineering pipelines (
/workflow run elixir ")." -
Parallel subtasks execute in physically isolated Git worktrees under
.yoke/workflows/. - Tuning Workflows for Your Team's Needs
-
Scaffold custom JSON workflow definitions via
/workflow init my-team-flow --from elixir. -
Writing Custom Elixir Plugins (
Plugin.Behaviour) -
Expose domain-specific tools by implementing
Yoke.Plugin.Behaviourand hot-reloading live with/plugins reload. - Managing Scoped Rules, Custom Skills & Ragex MCP
-
Set prompt preambles via
/rules add, add modular skill packages in: .yoke/skills/, and mount/ragexfor SCIP/AST symbol graph search. - The Iterative Feedback Loop: Fitting Expectations 100%
-
4-step tuning cycle: Observe → Codify (
.yoke/practices) → Automate (.yoke/workflows) → Snapshot & Replicate (version control.yoke/).
REPL Slash Commands & Shortcuts
The full reference lives in
docs/cheat_sheet.md
; the essentials are grouped below.
Shell & Console
| Command | Action |
|---|---|
!command
|
Execute shell command directly (e.g.
!git status
,
!mix test
)
|
!!
|
Flip into/out of pure console mode (plain shell passthrough, no AI/tooling) |
/git
|
Run a raw
git
subcommand and print colorized output
|
Session, History & Persistence
| Command | Action |
|---|---|
/resume [id]
|
Resume specific session ID or open interactive conversation picker modal |
/session [list\|switch\|cleanup]
|
Inspect, switch, or prune persisted workspace sessions |
/status
|
Alias for
/session
-- active session & system status
|
/checkpoint [label]
|
Create a manual temporal state snapshot |
/undo
|
Roll back state to previous temporal checkpoint |
/compact
|
Compress conversation context to save tokens |
/export [json\|markdown]
|
Export full session transcript to disk |
/history [search
|
Show or search persistent REPL input history |
/cost
|
/tokens
|
Display token usage breakdown and cumulative session cost |
Git & Code Review
| Command | Action |
|---|---|
/review [
|
Interactive Human-in-the-Loop PR Code Review with finding triage (
[i] Include
,
[e] Edit
,
[d] Drop
), atomic inline diff comments, and living memory
|
/cr [base]
|
Fast shortcut to generate Code Review for current branch against
main
or custom base
|
/prboard
|
/review queue
|
Live Pull Request review queue board (CI state, approval thresholds, re-review readiness) |
/review next
|
Auto-advance and start reviewing the next recommended PR in the queue |
/review skip
|
/review unskip
|
Commit-pinned PR skip (hides PR until author pushes new commits) |
/review patterns
|
View living codebase review tripwires (
.yoke/review_patterns.md
)
|
/review help
|
Display comprehensive in-terminal review guide |
/diff [branch]
|
Display colorized git diff of workspace or against target branch |
/commit
|
Auto-stage and commit workspace changes |
/linter
|
Run
oeditus_credo
,
propwise
,
credo
, or
dialyzer
(alias:
/lint
)
|
Model, Execution & Rules
| Command | Action |
|---|---|
/model [chat\|coder\|reasoner\|openrouter-free\|ollama-qwen]
|
Switch active model (
deepseek-chat
,
deepseek-coder
,
deepseek-reasoner
, OpenRouter/Ollama shortcuts, or custom model string)
|
/endpoint [url\|default\|openrouter\|opencode\|ollama\|lmstudio]
|
Switch API base endpoint URL dynamically |
/mode [local\|remote\|docker]
|
Set Hands execution target |
/sandbox [on\|off]
|
Restrict file references & tools to the workspace directory |
/permissions [auto\|ask]
|
Set tool execution safety mode |
/rules [add\|delete\|toggle]
|
Manage scoped prompt preambles and launch deletion checkbox modal |
/nodes
|
View distributed Erlang node cluster status |
Tooling & Extensibility
| Command | Action |
|---|---|
/plugins [reload\|info]
|
List tools or hot-reload plugins live without dropping state |
/mcp [list\|add\|load]
|
Manage Model Context Protocol (MCP) servers and tools |
/ragex [stats\|reindex\|export]
|
Mount and drive the first-class Ragex code analysis & refactoring MCP server |
/skills [list\|show\|path\|edit\|new\|
|
/skill
|
List, inspect, scaffold, or execute skills (arguments may be passed to a skill) |
/subagent
|
Spawn a background subagent worker for sub-tasks |
/workflow [list\|run\|status\|resume\|abort\|init]
|
Run customizable multi-step workflows (branch, describe, split & parallelize, test/docs, lint, commit) |
/config [style\|prompt\|toggle]
|
Manage prompt styles and UI toggles |
/env
|
Show runtime environment (Elixir/OTP version, model, workspace) |
/update
|
Background self-update
yoke
release to latest code
|
Utility
| Command | Action |
|---|---|
/cb
|
/clipboard
|
Copy latest assistant response to system clipboard |
/clear
|
Clear terminal output |
/help
|
Display help menu |
/exit
|
/quit
|
Exit Yoke and print conversation resume banner |
Configuration
yoke
reads settings from
~/.yoke/config.json
(global) merged with
.yoke/config.json
(per-workspace override, taking precedence). Notable keys:
| Key | Default | Purpose |
|---|---|---|
model
|
"deepseek-chat"
|
Default LLM model identifier |
endpoint
|
"https://api.deepseek.com/chat/completions"
|
LLM API base endpoint URL (DeepSeek, OpenRouter, Ollama, etc.) |
prompt_style
|
"starship"
|
Prompt layout:
starship
,
extended
,
compact
, or
minimal
|
permission_mode
|
"ask_confirm"
|
Tool execution safety mode (
ask_confirm
or
auto_approve
)
|
sandbox_workspace
|
false
|
Restrict file references & tools to the workspace directory |
enable_autosuggestions
|
true
|
Fish-style ghost autosuggestions from input history |
enable_syntax_highlighting
|
true
|
Highlight
/commands
and
!shell
lines as you type
|
enable_context_gauge
|
true
|
Show the token/cost usage gauge on the idle status bar |
compact_status_bar
|
false
|
Swap the gauge for a compact
id + message count
line
|
max_context_tokens
|
64000
|
Assumed model context window used by the usage gauge |
max_tool_depth
|
1000
|
Consecutive tool-calling turns before pausing to confirm |
Manage most of these live from the REPL with
/config style
,
/config prompt
, and
/config toggle
-- or toggle permission mode, sandbox bounds, and the status bar mode instantly with
Ctrl+P
,
Ctrl+G
, and
Ctrl+B
.
Documentation
-
docs/GETTING_STARTED_GUIDE.md— Comprehensive Onboarding & Customization Guide (Practices, Workflows, Plugins, Rules, Skills & Ragex). -
docs/WORKFLOW_ENGINE.md— Multi-step Workflow Engine Reference (/workflow). -
docs/cheat_sheet.md— Full Slash Command & Shortcuts Cheatsheet.
Roadmap & Future Enhancements (TODO)
-
Sandboxed Code Mode over MCP
: Implement a sandboxed Lua expression surface over MCP tools (
lua_docs,lua_eval) allowing external and internal subagents to project, filter, and aggregate large data structures or file fields on the host without loading multi-megabyte raw context into model prompts. -
Enhanced Git Worktree Isolation & Multi-Lock Serialization
: Introduce dual-lock mechanics (
gate_lockfor CPU/testing serialization andland_lockfor branch advancement) alongside warm dependency cache copying (deps/_build) for git worktree subagents managed by the workflow engine.
License
MIT, see
LICENSE
-- with one additional restriction: this project may
not
be used, modified, or distributed as a harness, adapter, or integration layer for proprietary third-party models from OpenAI, Anthropic, or Google (e.g. GPT, Claude, Gemini), whether accessed directly or through an intermediary API, proxy, or aggregator.
Yoke (Yoke) -- Actors, Hot-Code Reloading, Distributed Brain/Hands, Spatiotemporal Checkpoints.