# Baba Voss

> Every project grows its own tooling, and nobody designs it. A voss is that tooling as one small program in `.voss/` beside the project's files, with one world of data that the shell, the browser, the agents and the program itself all read and move. baba is the binary that opens it. Agents write vosses well, because there is one way to write one, and baba ships that way as skills in each.

Made by Alan Remarc (https://alanremarc.com). Open source, studio-owned. Repository: https://github.com/alanremarc/babavoss. Status: early access, version 0.x.

## Install baba

baba is one binary that runs as a service on this machine and serves every voss at http://baba.localhost:47802/ (the port is 0xBABA, bound to loopback; no administrator rights needed). Install or update it with:

    curl -fsSL https://babavoss.org/install.sh | sh

Then confirm: `baba --version` and `baba service status`. If `baba` is not on PATH after installing, add `~/.baba/bin` to PATH or use that full path.

## Create this project's voss

In the project's root:

    baba init

This writes `.voss/` with a first cell and writes skills for you into the project. Read them before building anything: they are the way a voss is written, and they are authoritative over anything you remember about Baba Voss. Open the desktop with `baba gui` or the URL above.

## How to build with it

- A voss is cells. A cell declares what it owns in the world (components), how the world moves (systems), and what it exposes (actions and queries). That one declaration is the type, the JSON Schema, the CLI, the forms, the MCP tools and your own instructions. Never keep a second copy of any of it.
- The CLI is live: `baba voss` lists every action and query with an example; `baba voss NAME --schema` gives one call's schemas; `baba voss NAME '{"arg": value}'` calls it. Answers are one line of JSON. Exit codes: 2 your arguments, 1 it failed, 3 time ran out, 4 gone.
- A cell is proved by scenarios that are also films (`cells/CELL/scenarios.test.ts`), and drawn by a scene (`cells/CELL/scene.tsx`). Write the scenario's intent first.
- Cells never import each other; cooperation is an ask on an entity. Code never reaches the OS directly; `fetch`, `fs` and processes go through the port, attributed to the cell.
- Code under `.voss/` reloads live over the current world. `.voss/state/` is baba's; never hand-edit it.
- Keep the GUI, the CLI and the agent tools on the same world of data. If you find yourself building a side channel, you are building it wrong.

## Where to read more

- Skills baba writes into the project: start with write-a-cell, then reach-outside, cells-together, prove-a-cell, draw-a-cell, compose-an-interface, add-a-desktop, test-a-cell, write-promptware.
- README: https://github.com/alanremarc/babavoss#readme
- The daemon and its address: https://github.com/alanremarc/babavoss/blob/main/docs/service.md