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

Pilot cosmon in natural language

Goal: drive cosmon by saying what you want, for example, "nucleate a task to fix the flaky parser test, then tackle it and wait." This replaces typing cs commands by hand. You do this by pointing an agentic coding CLI at cosmon's own help surface, once, in a single line of config.

This is not a new cosmon feature or a plugin. cs is a plain command-line tool with a self-describing help surface. Any agent that can read cs help and run a shell command can already pilot cosmon. What is missing is a pointer telling it that cosmon is there: a CLAUDE.md/AGENTS.md section for every CLI, and (for Claude Code specifically) a skill that carries the same text without needing cs init first. See Claude Code: a skill, not just a pointer.

The idea in one picture

An agentic CLI (Claude Code, Codex, gemini-cli, opencode, aider, …) reads a context file in your repository when it starts. If that file says "to operate cosmon, run cs help", the agent discovers the whole command surface on its own, and your English turns into the right cs invocations.

you (English)  →  agentic CLI  →  reads `cs help`  →  runs `cs nucleate …`

The setup consists of installing cs, adding the pointer, and speaking.

Step 1: Install cs

curl -fsSL https://noogram.org/cosmon/install.sh | sh

This installs a single binary into ~/.local/bin (falling back to /usr/local/bin), verifying its checksum against the release SHA256SUMS. If that directory is not on your PATH, the installer says so and prints the line to add. Confirm:

cs --version
cs help          # the surface the agent will read

cs help is the load-bearing part. It prints every command grouped by theme (molecule lifecycle, fleet management, execution, …) with a one-line description each, and every subcommand takes --help. That is enough for an agent to work out the vocabulary without any further documentation.

man cs is an optional contributor extra. The published installer ships the cs binary and nothing else, so do not expect a man page on a fresh machine. Contributors who build from the repository get one via just install. Point your agent at cs help, which is always present.

Step 2: Add the pointer to your agent's context file

Each CLI reads its own file at startup, commonly AGENTS.md or CLAUDE.md at the repository root; check your tool's documentation for the exact name. Add a short section like this:

## Cosmon — Orchestration

Run `cs help` for the full command reference, `cs help guide` for the operator handbook,
and `man cs` for the manual page.

Source of truth: `.cosmon/state/` (JSON). Surfaces are projections — never edit directly.

The normal cycle for one unit of work:
```
cs nucleate task-work --var-file topic=<file>   # a long statement goes in a file, not a flag
cs tackle <id> --adapter claude                 # spawn a worker; omit --adapter for the project default
cs peek                                         # watch it work, or `cs wait <id>` to block
cs whisper <id> --file correction.md            # send a correction while the worker is still open
cs done <id>                                    # merge to the base branch + teardown (required)
```
Use `cs tackle`, not `cs run`, when you intend to read the result before merging: `cs run`
walks a whole DAG and calls `cs done` on completion itself, closing the review window.

Stopping early is not the end of a mission: the work stays on the branch and worktree recorded
at dispatch until you run `cs done <id>` (keep the partial work) or `cs collapse <id> --reason
"…"` (record abandonment). `cs complete`, `cs collapse`, and `cs status` print the exact
branch, recorded worktree (including overrides), and concrete `cs done` command. A collapse
preserves the branch for audit; it never licenses unaudited deletion.

Branch audit is concrete: inspect `git log --oneline <base>..<branch>` and `git diff
--stat <base>...<branch>`. Integrate completed work with `cs done <id>`; for abandoned
active work, put the reviewed disposition in `cs collapse <id> --reason "<verdict>"`.
Retain the branch unless deletion is separately reviewed. `cs status` shows live branches
as active work and collapsed or deliberately unmerged branches with their recorded disposition.

Finishing a mission means `cs status` reads clean afterward — no zombie session, no
un-harvested `Completed` molecule, and no unresolved molecule branch. Active work and retained
branches with a recorded audit disposition are visible, but are not residue. `cs status` says
`clean` or names every unresolved item.

Who does what — you decide the mission and protected inputs (`cs nucleate --protect`) and
accept or drop each result; the pilot drives the cycle above; workers do the work. Full
breakdown: https://docs.noogram.org/explanation/pilot-and-workers.html

That is the whole transport (cs init --upgrade writes and maintains it for you, inside marker comments it can update without touching anything else you add to the file). It carries no secrets and pins no versions: it names the tool, states that it is on PATH, points at cs help for everything else, and spells out the one loop that is easy to get wrong from cs help alone. A long statement belongs in a file bound with --var-file instead of being typed into --var; a worker keeps running after wait returns, so a correction goes through cs whisper --file before cs done; and cs tackle (not cs run) is the verb that leaves the review window open.

Keep it minimal on purpose. A long transcription of cosmon's commands into your context file is a second copy of the reference that will rot; the block above delegates to the copy that ships with the binary. The same source text also ships as a Claude Code skill. See Which CLIs work below.

Step 3: Speak

With the pointer in place, you talk to your coding CLI normally:

"Nucleate a task to fix the flaky parser test, then tackle it with Claude and wait for it."

and it resolves that into the cycle:

cs nucleate task-work --var topic="fix the flaky parser test"
cs tackle task-20260716-1a2b --adapter claude
cs wait   task-20260716-1a2b

A statement that runs to more than a sentence belongs in a file instead, so it survives verbatim (front matter, quotes, accents, multiple pages) rather than being squeezed through shell quoting:

cs nucleate task-work --var-file topic=enonce.md

Reread, correct, accept is the loop measured against a real worker: cs wait returns as soon as the worker reaches completed, but its tmux pane, worktree, and branch all survive that state, so you can still act on it. Reread with cs peek or git diff main...feat/<id>; if something is off, send a correction with cs whisper <id> --file correction.md. The fix lands as a new commit on the same branch. Only cs done <id> merges it, so use cs tackle, never cs run, whenever you intend to read a result before it merges. cs run walks a whole DAG and calls cs done on completion itself, which closes the review window before you get to look.

Other phrasings map the same way. "What's running right now?" becomes cs status or cs ensemble, "show me what that worker is doing" becomes cs peek.

If the agent guesses a flag that does not exist, that is the signal your pointer is being skipped. Make sure the context file is at the repository root and that your CLI actually loads it.

Which CLIs work

Any coding agent that can read a context file and run shell commands. That includes Claude Code, Codex, gemini-cli, opencode, and aider, among others. Cosmon does not integrate with them individually and does not detect which one you are using. It exposes cs help, and they read it. Support is therefore a property of the CLI (does it read a context file? can it run a shell command?), not something cosmon maintains per tool.

This is a different axis from --adapter. Here an agentic CLI drives cosmon from the outside, translating your English into cs commands. The adapter is the reverse: cosmon spawning a model underneath to do the work of a molecule. You can use either alone, or both.

Claude Code: a skill, not just a pointer

Claude Code users have a second option that needs no cs init in the target repository first: the same Orchestration text above also ships as a Claude Code skill, tools/cosmon-skill/SKILL.md in this repository. One source text, two renderings: the ## Cosmon — Orchestration block cs init --upgrade writes into CLAUDE.md/AGENTS.md, and this skill file. Both are generated from the same constant (cosmon_filestore::project_upgrade::generate_cosmon_skill_md), so a test fails if the two ever say something different.

Install it once, at the user level, and it loads on demand in every repository, including one that has never run cs init. From a clone of the cosmon repository:

cd tools/cosmon-skill && ./install.sh

That copies SKILL.md into ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/cosmon/ (idempotent and safe to re-run after an update). When CLAUDE_CONFIG_DIR is set, the installer uses that directory so the skill is available to the matching account. Pass ./install.sh --link to install a symlink that follows the repository as it changes. To scope it to a single project instead, copy or symlink SKILL.md into that project's .claude/skills/cosmon/ directory. Either way, the skill costs nothing when unused. Claude Code only loads it when you ask it to pilot cosmon, and it carries the same content as the CLAUDE.md/AGENTS.md pointer, so a repository with cs init already run and a repository without it read the same instructions.