noogram/cosmon

cosmon

Noogram is an open, federated system for running long AI-agent missions inside your own perimeter — every step kept as plain files you own. Its kernel, cosmon, is a stateless CLI that gives each agent an identity, a lifecycle, and crash-recovery.

noogram.org — home · docs.noogram.org — documentation

Cosmon is the open-source kernel distributed with Noogram. Its command-line tool, cs, runs multi-step work across several agents and models while keeping the operational state and history in files on disk. You can also adopt cosmon on its own to run several agents on one codebase.

What it looks like

cs peek is the observation portal — a full-screen view of the fleet where j/k moves between workers, p drops into a worker's live terminal, and b/l/e/s show its briefing, log, events, and result. Its non-interactive sibling, cs ensemble, prints the same state as plain text:

Ensemble: 4 workers, 6 molecules (1 pending, 0 queued, 3 running)

  NAME                     ROLE             LIVE     INPUT   OUTPUT      COST   MOLECULE
  ────────────────────────────────────────────────────────────────────────────────────
  intro-writer-a3f2        implementation   idle      2.3M      30K    $10.55   task-...a3f2
  codec-section-8d2d       implementation   idle     29.2M     170K    $63.41   task-...8d2d
  citations-review-25a2    implementation   idle      7.6M      44K    $18.83   task-...25a2
  promotion-gate-e39f      implementation   unknown      -        -         -   task-...e39f
                                                     ─────────────────────────
                                        fleet total   39.1M     244K    $92.79

  Molecules: 1 pending, 0 queued, 3 running, 2 completed

once an assets path is agreed; the capture above is real cs ensemble output, trimmed to an illustrative four-worker fleet. --

Crash recovery, concretely. A worker dies, or you reboot the machine mid-run. Its state is already on disk, so cs tackle puts a fresh worker back on the same molecule and it resumes from the last recorded step — nothing re-run from scratch, no lost thread. That is the one behaviour to keep in mind while reading the rest.

Cosmon is one command-line tool, cs. Each command runs, writes to files on disk, and exits. The local workflow has no database server or scheduler to operate. (cs init does create a local .cosmon/registry.sqlite: it is a gitignored, derived index rebuilt from the JSON files on demand — a cache, not the source of truth for molecule state and history, which stay in .cosmon/ JSON and git.) That lets a small team — three to ten agents — add it to an existing repository without standing up new infrastructure. By default cs drives a local model over an OpenAI-compatible endpoint such as Ollama; it can also hand a task to Claude Code, Codex, Aider, hosted APIs (Anthropic, OpenAI, Google Gemini, Mistral AI, Qwen, DeepSeek, GLM, or Kimi), or local models through llama.cpp or Ollama. It is written in Rust and installs as a single binary.

Contents

• Why cosmon
• Install
• Prerequisites
• First contact: cs demo
• The lifecycle verbs
• How it works

• Local, remote, and federation
• A real session
• CLI reference
• Vocabulary
• Project structure
• Contributing

• License

Why cosmon

• Runs inside your perimeter. With the local workflow, the agents operate on

your corpus and write their documents and full execution trace to a disk you control. A configured hosted model can receive context: network egress is advisory-only on macOS unless you set COSMONEGRESSREQUIRENETNS=1 (enforced via a network namespace, Linux only), and the filesystem is never confined. Cosmon does not sandbox what an adapter can read or send.

• Every claim points to its source — and you can refuse it. Outputs retain