coding-os

Coding OS — the cognitive operating system that gives AI agents memory, structure, and discipline. Teaches AI agents how to think (thinking_os) and how to code (workflow, hooks, skills, rules) — agent-agnostic so the same kernel serves Claude Code and OpenAI Codex without rewriting.

Website: https://coding-os.dev · Community: https://community.coding-os.dev

Prerequisites

Linux: replace brew install … with your distro's package manager (apt, dnf, pacman). Windows: WSL 2 + the same Linux steps.

Quickstart — panel first (one command)

If you would rather click than type, this is the whole install. It preflights prerequisites, installs the cos CLI, and boots the Hub:

curl -fsSL https://raw.githubusercontent.com/kouroshez/coding-os/main/install.sh | bash
# …or, from a checkout:  bash install.sh

Open the Hub at http://127.0.0.1:9188 and press New project. The Composer picks a preset (or your own stack mix), asks one sentence about the project, and scaffolds it — docs, board, knowledge graph, and agent setup included. There is no CLI step in between; everything below is the same flow with flags instead of clicks. (ADR-0007)

60-second quickstart (native uv)

# 1. Install the `cos` CLI globally
git clone https://github.com/kouroshez/coding-os.git
cd coding-os
uv tool install --editable .

# 2. Verify
cos --version                          # → coding-os, version X.Y.Z
cos doctor --bootstrap                 # preflight: python/bash/git/uv/sed prerequisites
cos doctor                             # full health sweep (must be all-green)

# 3. Spawn a new project, scaffolded with an agent + a stack
#    (--agent takes several: --agent claude,codex)
cos init --agent claude --template django --name my-shop --yes
cd my-shop                             # adapter installer ran for you and wrote
                                       # .claude/, .mcp.json, .coding-os/

# 4. Boot the multi-project Web Hub (graph + board + cognition + search)
cos hub start                          # → http://127.0.0.1:9188

Open http://127.0.0.1:9188 in your browser. You will see the knowledge graph of my-shop, the Scrumban board, the cognition trace timeline, and unified search across all retrieval layers.

For Codex, swap --agent claude for --agent codex (or pass both — --agent claude,codex) — everything else is identical. Each agent's installer is src/adapters/<agent>/install.sh; cos init runs it for you and re-runs it on cos update.

Choosing how much coding-os you install

The kernel ships as subsystem modules — docs, tasks (Scrumban), knowledge graph, agent memory, cognition, observability, hub extras, CI/CD — and you pick the set at create time. Prefer a small MCP surface, or don't want the web panel at all? Start lean:

cos init --agent claude --name my-app --profile lite --yes   # kernel only: discipline + safety
cos init --agent claude --name my-app --profile full --yes   # every subsystem
cos init --agent claude --name my-app --disable-module memory --yes

cos init --help lists the live profiles and module ids (both are read from src/core/subsystems.yaml, so the help never drifts). Omitting --profile applies the registry default — today standard, which leaves cognition and cicd off. The two flags are unioned: a profile can only remove more, so to re-enable something start from a wider profile. Everything stays adjustable later with cos module enable|disable or Hub Config → Modules, and the same chips appear in the Composer's Advanced section. Full model: meta-project.md § subsystem modules.

Run with Docker (Hub layer; native for projects)

Architecture split — adopted because each layer wants a different deploy shape:

The Hub container reads the host's projects via a read-only bind mount and the host's registry file, so every absolute path stays valid inside the container — no path translation.

Quickstart

docker compose up
# → http://127.0.0.1:9188

By default, docker-compose.yml bind-mounts $HOME read-only at the same path inside the container so cos registry scan ~ finds every .coding-os/ directory below it. Hub state (SQLite, traces) lives in the cos-state named volume and survives down / up.

Project auto-discovery, narrowing the mount for production, and manual docker run (no compose): docs/engineering/hub-architecture.md § Docker deployment.

MCP server wire-up (Claude / Codex)

cos init writes .mcp.json at the project root automatically. If you ever need to register the MCP server manually (e.g. another tool that reads MCP configs), this is the shape every adapter installs:

{
  "mcpServers": {
    "coding-os": { "command": "cos", "args": ["server-start"] }
  }
}

Verify the wire is live in your agent runtime:

• Claude Code: cos doctor shows mcp.coding-os = ok; the CLI exposes cos_* tools via ToolSearch("select:<tool>").
• Codex CLI: codex --mcp-list lists coding-os.

If the server isn't found, re-run bash src/adapters/<agent>/install.sh from the project root, then restart the agent.

What it is

coding-os is a three-layer composition (DNA → mRNA → phenotype):

src/core/  ──►  src/adapters/<agent>/  ──►  src/templates/<stack>/  ──►  consumer project
(DNA)         (mRNA)                       (phenotype)                 (organism)

Adding a new stack or a new agent is a pure YAML + Markdown change. No Python edits required.

What it does

1. Complexity Gate — classifies problems before acting (Cynefin: CLEAR / COMPLICATED / COMPLEX / CHAOTIC / CONFUSION).
2. Cognitive Cycle — CLASSIFY → ORIENT → PLAN → EXECUTE → VERIFY. The kernel rule (src/core/rules/thinking_os.md) is always active; the deep skill loads only when the gate returns COMPLICATED or COMPLEX.
3. Self-learning memory — SQLite-backed observations, metrics, and learned patterns across sessions (cos_search, cos_learn_*).
4. Hook enforcement — hooks gate writes, edits, prompts, sessions, and stops (exact count in src/core/hooks/registry.yaml). Adapter parity matrix in docs/engineering/.
5. Four-layer retrieval — agent memory (cos_search) · doc RAG (cos_doc_search) · task graph (cos_task_*) · knowledge graph (cos_graph_*).
6. Intent enforcement — when the user uses exhaustive vocabulary (FA + EN: همه / all / completely / until done), the Stop hook refuses premature "done" until an evidence bundle is recorded.
7. Upgrade path — cos update keeps every consumer project in sync with coding-os without touching user content.

Web Hub (http://127.0.0.1:9188)

A singleton FastAPI + Vite/React SPA that serves every registered project via /api/p/<slug>/*:

• Workspace — project overview, Scrumban board (kind × swimlane × epic, WIP enforcement), memory, cognition traces, unified search.
• Graph — Sigma.js canvas with deliberate view modes + smart export + dagre layout.
• Config — modules, git settings, hub settings, per-project chips.
• Marketplace — community skills/stacks (rolling out).
• Diagnostics — health, hooks log, token-burn audit.

cos hub start boots the hub. cos hub status reports health. Source: src/core/web/. UI: src/core/web/ui/ (npm run dev).

Architecture

coding-os/
├── src/                # All importable code (Python src-layout)
│   ├── cli/              # Factory entrypoint (`cos` command)
│   ├── core/             # Agent-agnostic brain (DNA)
│   │   ├── thinking_os/    # MCP server: memory, learning, metrics, cognition
│   │   ├── graph_os/       # Polyglot knowledge graph (SQLite backend)
│   │   ├── board_os/       # Scrumban task system
│   │   ├── web/            # Hub UI + FastAPI backbone
│   │   ├── hooks/          # Hook scripts (SSOT: registry.yaml)
│   │   ├── rules/          # Always-active rules + auto-generated artifacts
│   │   ├── skills/         # Universal skills
│   │   └── scripts/        # Kernel-internal regen tooling
│   ├── adapters/         # Per-agent translation (mRNA, adapter.yaml manifests)
│   │   ├── claude/         # Claude Code adapter
│   │   └── codex/          # OpenAI Codex CLI/Desktop adapter
│   ├── templates/        # Per-stack scaffolds (phenotype, stack.yaml-driven)
│   │   ├── _base/          # Generic base + fragments/
│   │   ├── django/         # Django + DRF + PostgreSQL
│   │   ├── nextjs/         # Next.js + React + TypeScript + Tailwind
│   │   ├── fastapi/        # FastAPI + Pydantic + SQLAlchemy
│   │   ├── go/             # Go stdlib + chi router
│   │   ├── go-fiber/       # Go + Fiber v3
│   │   ├── react-native/   # React Native + Expo
│   │   ├── python/         # Python library / CLI / MCP server
│   │   ├── meta/           # Meta-stack (for coding-os contributors)
│   │   └── …               # 27 stacks total — `cos list-stacks`
│   └── scripts/          # Maintenance + regen tooling
├── tests/              # cross-cutting tests
├── docs/               # Governance, engineering, playbooks, architecture
└── .coding-os/         # Per-project runtime state (gitignored)

Command index (highlights · 98 cos subcommands total)

Project lifecycle    init · adopt · setup · add-adapter · add-stack · update · materialize · eject
Diagnostics          doctor · health · list-stacks · list-adapters · hooks-dir · hooks-log
Hub                  hub start · hub status · hub stop
Board                board · task-create · task-start · task-move · task-done · daily · retro · wip
Cognition            cognition trace · trace-replay · trace-summary
Graph                29 graph-* subcommands (build · find · deps · analysis · review);
                     22 mirror a cos_graph_* MCP tool one-for-one, enforced by a parity test

Full catalogue with flows: docs/architecture/meta-project.md.

Slash commands (25 commands)

The cos CLI above is the factory. Inside an agent session you also get slash commands — packaged workflows invoked by typing /: 11 workflow commands (/board, /daily, /retro, /task, /classify, /compose, /memory-search, /verify, /review, /diagnose, /new-project) and 14 /role-* commands (the semantic roles of the cognition chain). They ship in .claude/commands/ (and .codex/commands/) and are version-controlled, so every teammate gets them on clone. Day-to-day usage: docs/workflow/workflow-guide.md.

MCP tools (cos_* family, all ok / fail envelope)

One MCP server (launched by .mcp.json → cos server-start) exposes every cos_* tool across ten families: health, memory (cos_search), learning, metrics, routing, docs (cos_doc_search), tasks (cos_task_*), graph (cos_graph_*, 22 tools), cognition (cos_compose_chain), and retrieval. Per-tool docs + envelope spec: docs/governance/mcp-tool-inventory.md.

The knowledge graph — why it changes the economics

Most "AI coding" tools answer structural questions ("who calls this?", "what breaks if I rename it?", "where does this data flow?") by reading files until the agent guesses an answer. That burns tokens, slows the loop, and produces hallucinations the moment a caller lives in a file the agent didn't open.

coding-os ships a precomputed knowledge graph as the third retrieval layer alongside memory and docs. Every commit refreshes 23 node kinds (functions, methods, classes, modules, routes, MCP tools, docs, headings, frontmatter, hooks, rules, skills, tasks, …) and 18 edge types (contains, calls, imports, inherits_from, handles_route, has_param_type, references_doc, is_decorated_by, links_to, …). The agent then asks the graph — cos_graph_references, cos_graph_impact, cos_graph_rename_plan — and gets a small, high-confidence JSON envelope back.

Benchmark — graph vs read-the-file (live repo · 33,548 nodes · 72,797 edges)

"What breaks if I change X?" answered two ways — read every caller file to be sure you caught them all (the safe manual path), vs one cos_graph_* envelope. Token counts are measured on this codebase (file bytes ÷ 4; tool tokens_estimated from the live envelope):

The exact numbers shift per machine and per tokenizer — the ratio (roughly 20–100× less context) is what holds. The leanest queries (cos_graph_references(limit=20)) answer in 140–600 tokens vs 2K–24K for even a single file Read. Every envelope carries total_count + truncated, so the agent knows when it has the whole answer — no silent truncation.

The savings compound: an agent asking 50 structural questions over a feature spends ~50–400 KB of context, not the multiple MB an exhaustive file sweep would cost — leaving the budget for actual reasoning.

Coverage, budgets, health — the anti-hallucination contract

Every coverage-sensitive tool reports its own incompleteness (total_count · result_truncated · walk_truncated — never silent), all 23 node kinds answer end-to-end in 0–23 ms, cos_graph_doctor sweeps stale nodes, and every Write/Edit re-indexes just the touched file. The full contract — budget knobs, per-kind latency, Hub view modes, and the probe-then-widen workflow — lives in graph_os-queries.md § Coverage, budgets, and benchmarks.

Deep dive: docs/engineering/graph_os-queries.md · docs/engineering/graph-hallucination-cures.md · docs/governance/mcp-tool-inventory.md.

Supported agents

Parity matrix + reasoning: docs/engineering/adapter-parity.md (the 2026-04-25 workflow audit is a historical snapshot predating Codex parity).

Configuration

.coding-os.yaml at every project root:

version: "1.0"
agents: [claude, codex]
templates: [django, nextjs]
state_dir: .coding-os
code_extensions: [py, ts, tsx]
verify:
  backend: "make lint-backend && make test-backend"
  frontend: "cd src/frontend && npm run lint && npm test"
protected_files:
  - "*/migrations/*.py"

Adding a new stack (zero Python changes)

Create src/templates/<id>/stack.yaml plus skills, rules, and scaffold docs — the CLI auto-discovers it (cos list-stacks), then make manifest-regen && make regen-rules refreshes the derived artifacts. The same pattern works for new adapters (src/adapters/<id>/adapter.yaml + install.sh). Step-by-step: docs/playbooks/template-authoring.md · docs/playbooks/adapter-authoring.md.

Project structure (for contributors)

make verify-hooks         # shellcheck + bash -n on every hook
make verify               # matrix-targeted tests for what changed
make test-mcp             # MCP self-test (cold start)
make docs-lint            # markdown structure + link integrity
cos health                # cross-project health summary
make manifest-regen       # refresh src/core/scaffold_manifest.json
make regen-rules          # refresh dimension-registry + skill-enforcement

CI runs the matrix on every PR. See .github/workflows/ci.yml.

Documentation

Troubleshooting

Still stuck? Run cos doctor --verbose and open a discussion with the output attached.

Support / Community

If coding-os saves you time, a star helps others find it. These links also live in the Hub footer (never inside the new-project Composer).

• ★ Star / follow on GitHub: https://github.com/kouroshez/coding-os
• Sponsor the project: https://github.com/sponsors/kouroshez · https://coding-os.dev/donate
• Questions / ideas: https://github.com/kouroshez/coding-os/discussions
• Community forum: https://community.coding-os.dev

License

Apache License 2.0 — see LICENSE. Copyright 2026 Kourosh Ebrahimzadeh and coding-os contributors.

Development began in April 2026; the full history is preserved in this repository. Release automation (release-please) starts at the 0.3.0 baseline (2026-05-20) — see CHANGELOG.md.