Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Ten minutes to cosmon

This is the shortest path from an empty terminal to one piece of work that an AI agent did, finished, and merged into your main. Every block below is meant to be copied and run in order.

If you want the same journey with the why behind each verb, take the tutorials instead. This page is the short route; the tutorials provide the explanation.

0. What you need

Two things beyond cs itself either way, because a cosmon worker is a real terminal session doing real git work:

git --version         # each worker runs on its own branch, in its own worktree
tmux -V               # each worker lives in a tmux session

Then it forks on what runs the worker:

You have Claude Code. One line of config completes setup. There is no backend to stand up:

claude --version       # confirm it is on PATH

Dispatch with cs tackle <id> --adapter claude below, or set default = "claude" under [adapters] in .cosmon/config.toml so you can drop the flag. No Ollama, no model to pull, nothing to serve.

You want a local model instead. A model backend has to actually be running and serving something before you dispatch:

ollama serve          # a model backend on localhost:11434 (the default adapter)
ollama pull qwen3:8b  # …serving a model. `serve` alone serves nothing

ollama serve with nothing pulled is the first sharp edge people hit: the daemon answers, so everything looks healthy, and the dispatch dies seconds after it starts. Cosmon now checks before spawning and refuses with a named repair. Pulling the model first avoids that detour.

Pull qwen3:8b specifically, which is also cosmon's built-in default. The local loop needs a model that emits structured tool_calls on /v1/chat/completions; qwen3:8b was measured to do that. A model that merely looks more capable is often the wrong choice. For example, qwen2.5-coder:7b, for instance, pastes its tool call into the message text as raw JSON, which lands in your output verbatim instead of creating a file. vLLM and llama-server work the same way, at their own endpoint; both, other models, and how to switch, are in docs/guides/local-model-selection.md (the OpenAI-compatible servers guide).

Missing git or tmux? Neither is installed by cosmon, and on a machine with no package manager yet, there is a prerequisite before installation. See Set up cosmon, which spells out how to get git, tmux and Ollama from nothing on macOS and Linux.

1. Install cs

curl -fsSL https://noogram.org/cosmon/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"   # skip if the installer did not ask for it
cs --version

~/.local/bin is not on the default PATH on a fresh account; without the export line cs --version exits 127. Put it in your shell profile too.

Homebrew and from-source routes, what that script does line by line, and why man cs is not installed are on Install cosmon.

2. Initialise a project

From the root of any repository you want cosmon to track:

cd ~/path/to/your/project
cs init

That creates .cosmon/, the directory holding all of cosmon's project state: your units of work, their event logs, and the canonical recipes. Later commands walk up to find it, the way git finds .git/. Running it twice is safe.

cs init also writes three files outside .cosmon/: a .gitleaks.toml at the repository root and two per-user files in your home directory. They are listed, with what removes them, in Set up cosmon → what cs init writes.

3. Create a unit of work

cs nucleate task-work --var topic="Add a --version flag to the CLI"

A formula (task-work) is the recipe: a small TOML file of ordered steps. A molecule is one run of that recipe: cosmon's unit of tracked work, with a state, a current step, and a durable trace on disk.

Nucleate creates the molecule. Nothing executes yet. The command prints an id:

Nucleated molecule task-20260711-a1b2 from formula task-work
  Steps: 2

Yours will differ; substitute it everywhere below.

4. Put it in motion

cs tackle task-20260711-a1b2

If you picked "You have Claude Code" in step 0, add --adapter claude (or skip the flag if you already set default = "claude" in .cosmon/config.toml).

Tackle creates a git worktree and branch for this molecule, opens a tmux session, and launches your agent inside it with the briefing injected. It returns immediately. The worker runs in the background while your shell stays free.

5. Watch it work

cs peek

cs peek is the fleet portal: workers on the left, the selection followed on the right. Press p to drop into the live pane of the selected worker, q to come back up. Never use tmux attach; it breaks the agent's rendering.

To block until the work is finished instead of watching it:

cs wait task-20260711-a1b2

6. Close the loop

cs done task-20260711-a1b2

Done merges the worker's branch into main, kills the tmux session, and removes the worktree. It is the only verb that merges: a worker can finish its own steps, but it cannot merge itself. That call stays yours.

Confirm:

cs status

The molecule shows as completed and no worker is running. That empty ensemble is the correct resting state.

The whole cycle, in one picture

cs nucleate   →   cs tackle   →   cs wait   →   cs done
  create          start a         block until    merge the
  the work        worker on it    it finishes    result, clean up

Everything the worker did is still on disk under .cosmon/, long after the tmux pane is gone. That on-disk trace is the point: a worker dying never loses your work.

Where to go next