Quickstart

This is the shortest path from a fresh install to a thread you spawned, advanced, and replied to. The first run uses a bundled demo brain, so you can see the whole loop (spawn, work, blocked, reply, done) without any API keys. Later steps point you at a real brain.

1. Install

Install the core package from PyPI (a virtualenv is recommended):

pip install yothere

Full install options, including the optional extras, are on the Install page.

2. First run

Run the demo first. It confirms the install end to end:

yothere init --demo

--demo starts a bundled Brain Protocol v1 brain on localhost, spawns one thread, and drives it through the real runner-to-worker-to-brain path in about 30 seconds, with zero API keys. You will watch it stream progress, go blocked to ask for your judgment (the attention router at work), get replied to the way you would, and finish done with a result summary on the board.

When you are ready to set up your real home, run init without the flag:

yothere init

That is idempotent and non-destructive. It creates the ~/.yothere layout, reports any brain it already detects (a remote YOTHERE_REMOTE_BRAIN_URL, a brains.yaml, or the claude CLI on your PATH), and wires the bundled demo brain if you have none. It never overwrites existing config.

3. Spawn a thread

Hail yothere with a task in plain language:

yothere spawn "scan our top 3 competitors and draft a one-pager"

Spawning is pure file I/O and safe to run in-session; it creates the thread but does not advance it (that is the runner’s job, step 4). Two flags are worth knowing:

• --focus pins the new thread as the focus thread, which the attention router never auto-interrupts.
• --mode auto|planning forces the scope. Without it, each task is classified automatically.

yothere spawn "ship the pricing page fix" --focus --mode auto

To advance the fleet, start the runner (it is operator-run, separate from spawning):

python -m yothere.runner loop

4. See the board

Build the standalone fleet board and open it in your browser:

yothere board --open

Prefer the terminal? Two text views cover the same ground:

yothere list      # a table of live threads and their state
yothere status    # a spoken-prose summary of the fleet

5. Reply

When a thread goes blocked, it needs your call. Answer it by id:

yothere reply <id> "yes, go ahead"

That flips the thread back to resumed, and the runner re-advances it. The reply text can also be piped over stdin:

echo "ship it" | yothere reply <id>

6. Next steps

• Onboarding: the full setup, from install to a real task advancing against your own brain.
• CLI reference: every command and flag, plus the module entry points.
• Configuration: environment seams and the brain registry.
• Agent onboarding: the machine-readable version of this path, for an agent setting itself up.

New to the ideas behind the loop? Read Core concepts first.