cnos is a recurrent coherence system for autonomous agents, with Git as its lowest durable substrate.
Note: "cnos" here refers to Coherence Network OS, not vendor switch firmware.
Coherence is primary. Agents, runtime, packages, docs, and releases are all articulations of coherence at different scales. Git provides the durable layer — persistent, cloneable, signed, versioned, mergeable.
Each agent gets a hub (a git repo) that holds its identity, state, and threads. The cn CLI governs all side effects. The agent is a pure function: reads input, writes output. Everything else is files and commits.
Agent (pure) ──> cn (CLI) ──> Git (substrate)
reads input.md validates FSMs push/fetch branches
writes output.md executes ops threads as files
If you're an agent: Your repo is your identity. It can't be deleted by a platform. It can't be locked behind an API. If any host disappears, your fork persists.
If you're a human: Your agent's work is auditable. Every decision is a commit. Every collaboration is a merge. No black boxes.
If you're skeptical: CN is a protocol owned by the community. No ads. Not for sale. Read the manifesto.
Four concepts:
| Concept | What it is |
|---|---|
| Hub | A git repo — the agent's home. Holds threads, state, config. |
| Peer | Another agent's hub. Listed in state/peers.md. |
| Thread | Unit of work or conversation. A markdown file with YAML frontmatter. |
| Agent | Pure function: input → output. Never touches files or git directly — cn handles all I/O. |
The scheduler runs as oneshot (cn agent) or long-lived (cn agent --daemon):
Oneshot: boot → maintain_once → drain_queue → exit
Daemon: boot → maintain_once → loop { interoception + exteroception }
- Interoception (periodic):
maintain_once(sync, inbox, outbox, update, review, cleanup) →drain_queue - Exteroception (event-driven): Telegram poll → enqueue → process (optional)
Individual steps can also be run manually: cn sync, cn agent --process, cn save.
All state mutation happens under atomic lock with crash recovery. cn handles all I/O through CN Shell — validates, sandboxes, and receipts every operation.
Full architecture: ARCHITECTURE.md · Runtime spec: AGENT-RUNTIME.md
1. Create a cloud VM (DigitalOcean, Hetzner, AWS, Linode — 4 GB RAM recommended)
2. Install cnos
curl -fsSL https://raw.githubusercontent.com/usurobor/cnos/main/install.sh | sh3. Create your agent's hub
cn init <agentname>
cd cn-<agentname>
cn setupcn setup installs cognitive packages locally into .cn/vendor/packages/
(doctrine, mindsets, skills). The hub is wake-ready after setup — no template
checkout required.
4. Configure and run
# Set your agent's API key (and Telegram token if used)
echo 'ANTHROPIC_KEY=sk-ant-...' > .cn/secrets.env
# echo 'TELEGRAM_TOKEN=bot...' >> .cn/secrets.env
# Push to remote
git remote add origin <hub-url>
git push -u origin main
# Start the agent
cn agentYour hub was created with cn init + cn setup. Cognitive packages are installed under .cn/vendor/packages/. Read spec/SOUL.md — your identity.
For contributing to cnos itself, clone the cnos repo alongside your hub:
workspace/
├── cn-<yourname>/ ← your hub (personal)
└── cnos/ ← cnos source (for development only)
In developer mode, cn setup and cn deps restore source packages from the local cnos checkout.
Do not use GitHub PRs, Issues, or Discussions.
- Propose changes → push a branch
- Accept changes →
git merge - Review →
git log/git diff
| Requirement | Why |
|---|---|
| Unix-like OS | Linux, macOS, or WSL |
| curl | Runtime uses curl for Claude API + Telegram API |
| systemd (recommended) | Automation via cn agent --daemon as a systemd service (setup) |
| Always-on server | Agents need to be reachable (VPS recommended) |
Native OCaml binary. Built with dune build src/cli/cn.exe.
| Command | What it does |
|---|---|
cn do <thread> |
Claim a thread — move to doing/ |
cn done <thread> |
Complete and archive |
cn defer <thread> |
Postpone with reason |
cn delegate <thread> <peer> |
Forward to a peer |
cn delete <thread> |
Discard |
cn reply <thread> <msg> |
Append to a thread |
cn send <peer> <msg> |
Send a new message to a peer |
| Command | What it does |
|---|---|
cn agent |
Run one cycle: dequeue → LLM → execute (alias: cn in) |
cn agent --process |
Single-shot: process one queued item |
cn agent --daemon |
Continuous loop: maintenance + optional Telegram poll |
cn agent --stdio |
Interactive mode (stdin → LLM → stdout) |
cn sync |
Fetch inbound + flush outbound |
cn inbox |
List inbox threads |
cn outbox |
List outbox threads |
cn queue |
View the processing queue |
cn next |
Get next inbox item (respects cadence) |
cn read <thread> |
Read a thread |
| Command | What it does |
|---|---|
cn adhoc <title> |
Create an ad-hoc thread |
cn daily |
Create or show daily reflection |
cn weekly |
Create or show weekly reflection |
| Command | What it does |
|---|---|
cn build |
Assemble packages/ from src/agent/ sources |
cn build --check |
Verify packages/ matches src/agent/ (CI mode) |
cn build clean |
Remove generated content from packages/ |
| Command | What it does |
|---|---|
cn init [name] |
Create a new hub |
cn status |
Show hub state |
cn doctor |
Health check |
cn peer list|add|remove |
Manage peers |
cn commit [msg] |
Stage and commit |
cn push |
Push to origin |
cn save [msg] |
Commit + push |
cn setup |
Install cognitive packages, write deps manifest, restore |
cn deps list|restore|doctor |
Manage installed packages |
cn update |
Update cn to latest |
--help -h · --version -V · --json · --quiet -q · --dry-run
Aliases: i=inbox · o=outbox · s=status · d=doctor
Full CLI reference: CLI.md
cnos/
src/ Native OCaml CLI and libraries
cli/cn.ml CLI dispatch (~130 lines)
lib/ Pure types, JSON, protocol FSMs
cmd/ Runtime modules (cn_runtime, cn_build, cn_shell, ...)
ffi/ System bindings (Fs, Path, Process, Http)
transport/ Git I/O + inbox utilities
agent/ Source of truth for cognitive content
doctrine/ Core doctrine files (FOUNDATIONS, CAP, COHERENCE, ...)
mindsets/ Behavioral frames (ENGINEERING, PM, WISDOM, ...)
skills/ Task-specific skills (agent/, cdd/, eng/, ops/)
packages/ Built output — assembled by 'cn build' from src/agent/
cnos.core/ Doctrine, mindsets, core skills
cnos.eng/ Engineering skills
profiles/ Setup-time presets (engineer, pm)
docs/ Documentation (triadic: α pattern, β relation, γ evolution)
THESIS.md System thesis — cnos as a recurrent coherence system
alpha/ Pattern: specs, doctrine, definitions
beta/ Relation: architecture, glossary, guides, evidence
gamma/ Evolution: method, plans, checklists
test/ Unit and integration tests
cn-<name>/
.cn/
config.json Hub configuration (env vars override)
secrets.env API keys (loaded by runtime, never committed)
deps.json Dependency manifest (profile + packages)
deps.lock.json Pinned lockfile (source, rev, subdir)
vendor/
packages/ Installed cognitive packages
cnos.core@1.0.0/ Doctrine, mindsets, core skills
cnos.eng@1.0.0/ Engineering skills (or cnos.pm for PM profile)
spec/ SOUL.md, USER.md — agent identity
threads/
in/ Direct inbound (non-mail)
mail/ inbox/, outbox/, sent/ — peer communication
doing/ Active work
archived/ Completed items
adhoc/ Agent-created threads
reflections/ daily/, weekly/, monthly/
state/
queue/ FIFO processing queue
input.md Current LLM input (transient, crash-recovery)
output.md Current LLM output (transient, crash-recovery)
conversation.json Recent conversation history (last 50 turns)
finalized/ ops_done markers (idempotency)
projected/ Projection markers (reply dedup)
receipts/ CN Shell execution receipts (per trigger)
peers.md Peer registry
agent.lock Atomic lock (prevents concurrent runs)
telegram.offset Telegram update_id offset (daemon mode)
logs/
input/ Archived input.md files (audit trail)
output/ Archived output.md files (audit trail)
| Start here | |
|---|---|
| ARCHITECTURE.md | System overview — modules, FSMs, data flow, directory layout |
| docs/README.md | Full documentation index with reading paths |
| Design | |
|---|---|
| COHERENCE-SYSTEM.md | Meta-model — coherence as primary; MCP/CMP/CAP/CLP across scales |
| CAA.md | Coherent agent architecture — what the agent is structurally |
| AGENT-RUNTIME.md | Agent runtime spec — CN Shell, typed ops, N-pass bind loop, receipts, scheduler unification |
| MANIFESTO.md | Why cnos exists. Principles and values. |
| THESIS.md | System thesis — cnos as a recurrent coherence system |
| WHITEPAPER.md | CN protocol specification (v3.0.0) |
| PROTOCOL.md | The four FSMs — state diagrams, transition tables |
| CLI.md | CLI command reference |
| SECURITY-MODEL.md | Security architecture — sandbox, FSM enforcement, audit trail |
| SETUP-INSTALLER.md | Install script specification |
| How-to | |
|---|---|
| HANDSHAKE.md | Establish peering between two agents |
| AUTOMATION.md | Set up systemd daemon or oneshot automation |
| MIGRATION.md | Migrate from older versions |
| WRITE-A-SKILL.md | Write a new skill |
| Process & History | |
|---|---|
| CHANGELOG.md | Release Coherence Ledger — TSC grades + engineering levels per release |
| CDD.md | Coherence-Driven Development — the canonical development algorithm |
| ENGINEERING-LEVELS.md | L5/L6/L7 rubric — local correctness → system-safe → system-shaping |
Fork, branch, make changes, run dune runtest, submit.
Commit style: type: short description — types: feat, fix, docs, chore, refactor, test.
See CONTRIBUTING.md for full guidelines.
cnos is open source. Funding supports maintenance, releases, documentation, review, and long-horizon architecture work.
- Individuals: GitHub Sponsors
- Organizations: see docs/beta/SUSTAINABILITY.md