Core concepts

yothere has a small vocabulary. Learn these words and the rest of the docs read easily.

The one thing to hold onto: yothere is the cockpit and the attention router. It does not do the work. A brain does, on your machine, on the coding-agent subscription you already pay for.

Hail

A hail is how you start work. One line, typed into the cockpit command bar, spoken on a voice call, or run from the CLI.

scan our top 3 competitors
draft replies for the support inbox
research the SOC 2 options and compare them

The same thing from the CLI:

yothere spawn "scan our top 3 competitors"

A spoken hail and a CLI hail are verb-gated: the parser wants a task verb. Two families of verb spawn a thread:

• Read verbs, which produce something to look at: research, scan, draft, review, compare, write, find, check, plan, summarize, prep.
• Code verbs, which change a repo: fix, add, implement, refactor, create, update, change, extend, wire, remove, delete, rename, bump, test, debug, patch, migrate, port, rebuild, redesign, integrate. So fix the layout shift on the pricing page is a hail, not a rejected line.

A line with no task verb is refused rather than turned into a thread, which is what keeps ambient talk near an open mic from spawning work. The cockpit command bar deliberately relaxes that gate: typing is a deliberate act, so a verbless line is taken as one task.

ship, merge, deploy and push are deliberately not spawn verbs, and never will be. They are the words you say to approve something that already exists (“ship it”), not words that describe a task, so a spoken or CLI hail that leads with one of them is refused instead of becoming a thread. Nor could a thread carry them out: git push and gh can never be granted (see the send-gate).

Thread

A thread is one task. A hail creates a thread, and the thread carries that task to completion.

Each thread is a directory on disk (a dir-per-thread state machine). Its live state lives in a status.json written atomically, so a reader never sees a half-written file. A thread resumes across turns by its session id, so the brain keeps its own context and yothere just points at the same session again.

A thread moves through a fixed set of states:

The cockpit reads a smaller, normalized vocabulary derived from those states: running, ready (a finished thread), blocked (covers both blocked and stuck), and idle (a parked thread).

Running out of steps is not a failure. When a turn hits its step ceiling mid-task, the thread stays running and the runner advances it again on the next tick. It does not stop and wait for you to type “continue”.

Workspace, and the code lane

A workspace is a git repo you already have on this machine, registered by name:

yothere workspace add site ~/code/acme-site
yothere workspace list
yothere workspace rm site

yothere never clones and never holds a git credential. It is a remote control for your box, so it can build exactly what you could build from your own terminal, and nothing more.

Bind a thread to a workspace and you get a repo-bound thread, the code lane:

yothere spawn --repo site "fix the layout shift on the pricing page"

Its turns run in their own git worktree, under ~/.yothere/worktrees/<workspace>/<thread>, on a branch named yothere/<thread-id>-<slug>. Two consequences worth knowing:

• Your working tree is never touched, and two code threads never collide. Three threads means three HEADs.
• The branch is the change, so the diff is clean by construction.

The worktree is isolation from other threads, not a sandbox. It does not contain what a turn reads, or what it writes elsewhere on the box. See the send-gate.

The thread commits. No approval of yours opens a push or a merge. git push and gh are on the never-grant list, so the approval path cannot mint a grant for them: there is no button that publishes. The agent leaves you a branch. You read it and publish it yourself.

Fleet

The fleet is all of your threads at once. yothere advances up to five agent turns in parallel by default, so the fleet is the unit you supervise, not the individual agent.

The default is a config value, not a hard spec. On the machine you pair it is yothere service --workers (env YOTHERE_LEASER_WORKERS); the local runner reads YOTHERE_MAX_CONCURRENCY.

Typed replies do not count against those five. Chat turns draw from their own pool on top of the work pool (two in flight on a paired machine, --chat-workers), so a question you type never queues behind the work. You can interrupt one thread while the other four keep going.

Brain

A brain is what actually does the work: it reads data, runs tools, drafts messages. Three backends ship today, and all run on your own machine, on your own login:

• Claude Code (claude -p per thread). The default. Needs your Claude subscription.
• The Codex CLI (codex exec). The same turn engine with a different backend, so a ChatGPT subscription is enough to run a thread. Auth is codex login into yothere’s own CODEX_HOME (YOTHERE_CODEX_HOME), not an API key.
• OpenClaw (openclaw agent --local). The open-source third brain, run through the same turn engine. It brings its own model provider (you set that key in OpenClaw, and yothere never stores it), and it runs contained: read-only or workspace tier, never full.

yothere never holds your model credentials and never bills you for inference. The backend seam (harness/base.py) is what keeps the turn engine harness-neutral, and the protocol yothere speaks to a brain is documented in Agent onboarding. Three backends is what runs today. That is the whole list.

Lane

The cockpit sorts the fleet into three lanes:

• Inbox. Only the threads that need a human.
• Working. What is in flight, with what each turn is doing right now.
• Done. A pile you review, not a queue you drive.

Most of the time the inbox is empty and the fleet is just working. That is the product functioning, not the product idle.

Card

A card is one thread in a lane, and its verbs match its ask. Exactly five kinds of ask exist:

An FYI lands in the inbox like the rest, sorted below the blocking asks, and it does not count against the inbox badge. Nothing else can reach you.

Runner

The runner is the headless advance engine. It runs a loop, one tick roughly every 30 seconds, and on each tick it:

1. Reaps finished worker subprocesses.
2. Sweeps stale threads (a running thread whose worker died) to stuck.
3. Checks the cost caps before spawning anything new.
4. Asks the attention router which threads to advance, bounded by max concurrency and a per-thread cooldown.
5. Spawns one worker subprocess per chosen thread.

Attention router

Other agent cockpits decide which agent runs next. yothere decides which thread wants the human’s eyes next.

It is deterministic and offline-first (no model call, no online learning), so it is unit-testable and never stalls on a network hop. It ranks the fleet by an additive score (a thread blocked on you outranks a finished one; urgency and staleness nudge the order) and recommends a single focus thread. A thread you pin gets a large bonus (+12), which lifts it over the ordinary fleet without overriding it: a thread marked urgent still scores higher.

The same ranking runs on the hosted control plane: it decides which of your threads to offer your machine next.

Voice

Voice is hosted. Click Connect in the cockpit and talk to your fleet in the browser. There is no phone number, no Twilio, and no API key of your own. The control plane mints a short-lived token per call.

On a call you can: hail a new task, hear what is waiting on you, answer a blocked thread out loud, approve a draft by saying “send it” (which records a real approval, the same one the Send button records), and pick a finished thread back up. You can mute the call, either with the mute button in the cockpit or by saying “mute me”, and nothing spoken while muted reaches the model.

The transcript streams into the cockpit live while the call runs. Because the media worker is ours, the transcript lives on the control plane only for the duration of the call and is deleted the moment it ends: the call content is not kept on our servers afterward (1.23.0 privacy). A local copy is written to ~/.yothere/logs/calls/ only when the voice session runs on your own paired machine. The audio itself is not recorded. See Privacy.

English is the default output language; neutral Latin American Spanish is a per-tenant setting in /settings.

Hosted voice includes 120 minutes a day (the allowance resets every day), so a forgotten call cannot run away.

The send-gate

A worker turn runs unattended, with bypassPermissions, in your work directory (YOTHERE_WORK_DIR, the turn’s cwd, not a sandbox boundary). The send-gate is what stops such a turn from firing a real outward action: a matched send is denied, and the worker writes a blocked status to ask you first. Your approval mints a single-use, thread-scoped grant that opens exactly that one send.

git push and gh can never be granted to a worker turn. They are on a never-grant list, so no approval of yours unlocks them for an agent. Publishing is yours: Ship it runs the push and the PR as you, outside any turn. There is no push. That is a rule in the gate, not a sandbox guarantee (see the trust page for the two paths that sit outside it).

Cost caps

The runner enforces spend limits so a runaway thread cannot quietly burn money. The defaults:

Hitting the per-thread cap is not a dead end. The thread comes back to the inbox as an answerable card (“This thread hit its budget cap. Continue, raise the cap, or stop?”), so you can raise the cap for that one thread without touching the fleet default. Discarding a draft never needs a worker turn, so a thread over its cap can still be discarded and closed.

The two spend caps are set with YOTHERE_DAILY_COST_CAP_USD and YOTHERE_PER_THREAD_CAP_USD.

Not built yet