Skip to main content
Glama

coding-os

PyPI license python CI OpenSSF Scorecard cli

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. Modular by design: take only what you need — even just the knowledge graph (--profile lite --enable-module graph).

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

Coding OS — knowledge graph, Scrumban board, and an enforced engineering loop for AI coding agents

Free, and staying that way. Apache-2.0, no paid tier, no telemetry, no gated features — the kernel you run is the whole thing. Sponsorship buys maintenance time, not access.

Right-sized by construction

Loading a whole skill catalogue into every prompt is how agents run out of context before they run out of task. coding-os narrows it twice.

At cos init — a project installs only the stacks it declares. A WordPress project gets the wordpress skill and never sees go-patterns, rails or spring-boot. Alongside them sit the stack-agnostic ones — clean-code, testing-strategy, api-design, a11y, security-web — which apply to any codebase.

On every turn — what is on disk is not what is in context. A generated rules table maps file globs to skills, and the matching skill loads only when you are about to write a file it governs. Editing a React component loads nextjs-react; nothing else comes with it.

Three real installs, each from a cos init run, showing what the declared stacks actually add on top of the seven stack-agnostic rules everyone gets:

Preset

Always-on rules

The stack-specific ones

Stack skills on disk

wordpress-cms

8

wordpress-backend

wordpress

mern

9

nextjs-frontend, node-express-backend

nextjs-react, node-express

hexagonal-product

11

fastapi-backend, go-backend, go-fiber-backend, react-native-mobile

go-fiber, go-patterns, python-fastapi, react-native-mobile, react-native-patterns

In the WordPress install, zero files under .claude/ mention go-fiber, rails or spring-boot, and the polyglot install has zero mentioning WordPress anywhere. (Two governance contract docs do name other stacks — as examples of the naming convention, not as instructions.) That is the difference between a scoped install and a prompt directory that grows with every stack the tool has ever supported.

What that actually costs — measured, not asserted. A scaffold writes 395–461 files; 9 to 12 of them ever enter the prompt. Running the real cos init for all 21 shipped presets and summing only what is resident:

Project shape

Always-on tokens

Share of a 200k window

t3-style (Next.js) — the leanest

12,704

6.4%

wordpress-cms

12,738

6.4%

mern / pern (Express + Next.js)

13,158

6.6%

hexagonal-product (Go + Fiber + FastAPI + React Native)

13,972

7.0%

uv run python src/scripts/context_budget.py --all-presets

The spread across every profile is 12.7k–14.0k tokens, because 9,266 of those tokens are the stack-agnostic rules everyone gets and the per-stack overlays are only 199–1,171 each. Skills, slash commands, hooks and MCP tool schemas are not in that number — they load on demand.

Two things this figure is not: it is not free (7% of the window is 7% of the window), and it is not the 15,634 tokens (7.8%) this meta-repo itself carries — it pays for four kernel-only meta-* rules a consumer never receives (uv run python src/scripts/context_budget.py --project . reproduces it). The full accounting, the cache economics, and what is still unmeasured about instruction density are in context-budget.md.

Disable a module and its rules, tools and slash commands leave with it — see Modular by design.


Prerequisites

Tool

Min version

Why

macOS install

Python

3.10

CLI, MCP server, extractors

brew install python@3.12

uv

0.5

Fast Python installer + tool runner

curl -LsSf https://astral.sh/uv/install.sh | sh

Bash

4

Hook scripts use 4.x features (macOS ships 3.2)

brew install bash

Node.js

20

Only if rebuilding the Hub UI under src/core/web/ui/

brew install node@20

Docker

24

Only for the Docker quickstart below

brew install --cask docker

jq, perl

any

Optional — faster hook path. Both degrade to Python, so an image without them is fully enforced, just slower per tool call.

preinstalled on macOS

Linux: replace brew install … with your distro's package manager (apt, dnf, pacman). Windows: WSL 2 + the same Linux steps. cos doctor --bootstrap checks all of the above, including whether the hook layer has a JSON/stdin parser at all — without one every gate fails closed.

Related MCP server: SafeFlo

Install

Two paths to the same install — pick by preference, not capability. Both end with the cos CLI on your PATH and the Hub reachable at http://127.0.0.1:9188.

Path A — one command, then click

Preflights prerequisites, installs the 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

Then open the Hub 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. (ADR-0007)

Path B — native uv, scripted

# 1. Install the cos CLI globally, from PyPI
uv tool install coding-os              # upgrade later: uv tool upgrade coding-os

#    …or from a checkout, if you intend to work ON coding-os itself:
#    git clone https://github.com/kouroshez/coding-os.git && cd coding-os
#    uv tool install --editable .      # upgrade later: git pull (editable is live)

# 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 at once: --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.

The Hub is optional. The CLI-only loop is complete on its own: cd my-shop, open your agent (e.g. claude — MCP + hooks are already wired), then cos daily / cos task-create / cos task-start — cos init prints the exact first commands for your project. Every project ships its own guide at docs/workflow/workflow-guide.md. For an existing repo, use cos adopt instead of init.

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.

Modular by design — take only what you need

coding-os is not all-or-nothing. The kernel (session lifecycle + safety) is always on; everything else is a subsystem module you switch on or off: docs · tasks (Scrumban) · graph · memory · cognition · observability · hub-extras · cicd. Named profiles curate the set, so the agent's MCP tool surface stays as small as you want it.

Wanted just the knowledge graph? That is the entire install:

cos init --agent claude --name my-app --profile lite --enable-module graph --yes

lite is kernel-only; core adds docs, tasks, graph, memory and the Hub hooks; standard (the recommended default) adds observability; full is everything. What each one actually delivers, from four cos init runs:

Profile

Modules off

Always-on rules

Skills on disk

Hooks that self-skip

lite

8

7

44

51

core

3

8

46

21

standard

2

8

46

17

full

0

9

46

0

The gate is a derived allowlist (.coding-os/disabled-hook-scripts) that a disabled hook reads when it sources cos-env.sh — so a module you turned off costs nothing at runtime. The 14 safety-category hooks are never on that list, at any profile — secret-blocking, destructive-command and branch guards cannot be switched off by choosing a leaner install. Verify on your own project:

cos module list                       # what you ended up with
wc -l .coding-os/disabled-hook-scripts   # what stopped firing

Start lean and change your mind later — from the project root, cos module enable memory. --profile and --disable-module are unioned: they can only remove. --enable-module is the escape that keeps one on and pulls its dependencies with it — passing the same id to both flags is an error, not an override. cos init --help lists the live ids straight from src/core/subsystems.yaml, cos module list shows what you ended up with, and Hub Config → Modules — or the Composer's Advanced section at create time — flips any of it later. 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:

Layer

Runs where

Why

Hub (web panel: graph · board · cognition · search)

Docker (production-shaped)

Reproducible build · isolated runtime · same image dev → CI → prod

Consumer projects (each project's .coding-os/, MCP server, skills, adapters)

Host (native)

Agent runtimes (Claude Code / Codex CLI) live on the host filesystem · cos init factory writes alongside your source · IDE/editor needs direct paths

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)

Layer

What it owns

src/core/

MCP server, hooks, rules, skills — agent-agnostic, stack-agnostic

src/adapters/

Per-agent translation: .claude/, .codex/ rendering

src/templates/

Per-stack overlays: 27 stacks, 11 CI-verified — cos list-stacks marks each verified or experimental

src/cli/

The cos factory CLI that composes the three layers

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. Shared file memory — durable notes in .agents/memory/, one fact per file under a MEMORY.md index, committed with the repo and read by Claude, Codex and any other agent.

  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 (.agents/memory/) · doc RAG (cos_doc_search) · task graph (cos_task_*) · knowledge graph (cos_graph_*).

  6. Intent enforcement — when the user uses exhaustive vocabulary ("all" / "every" / "completely" / "until done", matched in English and one additional language), 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.

The Web Hub (http://127.0.0.1:9188)

One FastAPI + Vite/React singleton serves every registered project through /api/p/<slug>/* — cos hub start boots it, cos hub status reports health. It is genuinely optional: the CLI loop is complete without it. What it adds is one surface where the board, the knowledge graph, agent memory, live agent presence and the hook stream are the same state the agent reads, not a dashboard rendered beside it.

Hub home listing four registered projects and the agents live in each

Hub home is the entry point: register an existing .coding-os/ folder, scan a directory for them, or scaffold a new project from a preset. Each project card carries the agents attached to it right now — the model each is running, the complexity gate it recorded, and the role it holds in the current chain.

Overview — what the agent is doing, in one screen

Agents live, spend against budget, WIP against cap, and the hook stream as it fires. block-dangerous-commands 15s ago is not a log line scraped after the fact — it is the same enforcement record the gate wrote when it ran.

Workspace Overview with live agent, cost, WIP counters and the recent hook stream

The board — Scrumban with enforced WIP

Seven columns; the three that gate flow carry a cap — in progress, testing, emergency. 1 / 1 WIP is not decoration: cos task-move refuses to overfill a capped column, so the board cannot drift from what is actually being worked on. Columns holding nothing collapse to a labelled rail and hand their width to the columns holding work — then expand back into full drop zones the moment you start dragging a card.

Scrumban board with three empty columns collapsed to rails and WIP counters on the rest

Group by swimlane instead of flat, and open any card for its outcome contract, its lifecycle chips, and every commit that touched it with the real diff inline. The task is the pointer; the code is the evidence.

Chat — the agent, with the project already loaded

A session started here inherits the project's MCP server, hooks, rules and board. Pick the model, the reasoning effort, and which semantic role should answer; the quick actions under the composer are the openings that actually pay off — resume where we left off, map the subsystems, review my current changes.

Chat landing with model, effort and role pickers above six quick actions

Search — one query, three retrieval layers

Docs, tasks and the graph answer the same query in parallel, each in its own section with its own count. A layer still in flight shows …, never a zero — an unanswered layer and an empty one are different facts, and a summary that conflates them is worse than one that waits.

Unified search returning 24 results for one query across docs, tasks and the graph

The graph — ask the codebase structurally

Sigma.js over the extracted code + doc graph. The left spine is containment, the tabs switch between the blended overview, pure containment, dependencies and detected communities, and the budget control decides how much of the graph to draw. The badge is honest about coverage: it names the sample and the whole-graph total, so a capped view can never read as a complete one. This is the surface behind cos_graph_* — the reason an agent answers "who calls this?" without grepping the tree.

Knowledge graph canvas showing 800 of 78,128 nodes with view-mode tabs and a depth budget

Diagnostics — every hook that fired, and why

The log tail is structured, not a text blob: filter by level floor, scope glob, message substring or a relative window, and follow it live. Alongside it sit the doctor probes, observability charts, and per-session cognition traces.

Diagnostics Logs tab with level, scope, substring and window filters over a structured event table

Modules — turn subsystems off and the tools go with them

The kernel is always on. Everything else is a switch, and disabling one gates its MCP tools and self-skips its hooks. Owns is the blast radius of that switch. Depends on is enforced, not advisory — tasks needs docs, so docs cannot be disabled first, and the button that would break it is disabled with the reason attached rather than failing after the click.

Config Modules tab showing subsystem toggles, owned artifacts and dependency direction

Also in the Hub: per-project Git and supervision settings, and a Marketplace for community skills and stacks (rolling out). Source: src/core/web/; UI: src/core/web/ui/ (make ui-dev for HMR).

Architecture

coding-os/
├── src/                # All importable code (Python src-layout)
│   ├── cli/              # Factory entrypoint (`cos` command)
│   ├── core/             # Agent-agnostic brain (DNA)
│   │   ├── thinking_os/    # MCP server: metrics, routing, docs, 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 (11 CI-verified) — `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 · 99 cos subcommands total)

Project lifecycle    init · adopt · setup · add-adapter · add-stack · update · materialize · eject
Modules              module list · module enable · module disable   (per-project surface control)
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
Supervision          supervision show · enable · disable · set   (per-role adapter/model/effort)
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 /: 10 workflow commands (/board, /daily, /retro, /task, /classify, /compose, /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 seven families: health, metrics, routing, docs (cos_doc_search), tasks (cos_task_*), graph (cos_graph_*), and cognition (cos_compose_chain). 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 envelope vs a competent agent, on public repos

The number to beat is not "read every matching file" — no sensible agent does that. It is what a good agent actually does: grep, then open a bounded window around the matches in the few highest-hit files. That is the default baseline, and every figure below is measured against it on public checkouts you can reproduce.

uv run --extra graph_os python src/core/graph_os/bench/third_party.py \
    --repo https://github.com/django/django --ref 5.2 --queries 10

Median savings over the highest-degree symbols per repo — --queries 10 on the public checkouts, 8 on this one (min in brackets — the honest worst case):

Repo

.py files

references

impact (3 hops)

rename_plan

psf/requests @ v2.32.5

36

77.7% (41.9)

24.2% (−53.8)

74.8% (43.7)

fastapi/fastapi @ 0.116.1

1,129

79.5% (−3.4)

−6.8% (−85.6)

82.4% (11.0)

django/django @ 5.2

2,818

76.8% (50.3)

70.8% (18.5)

77.1% (51.1)

this repo

3,317

79.7% (65.9)

74.0% (64.7)

79.7% (65.7)

Every number below is a token cost. The harness measures what each approach spends, not whether its answer is better; it emits no accuracy metric and has not been run against a code-retrieval benchmark. Read the tables as a cost result and nothing more (limits).

Read it as three findings, including the one that does not flatter us:

  1. "Who calls this?" and "what does a rename touch?" are a consistent ~75–82% cheaper, across repos spanning two orders of magnitude in size. This is the robust win and the reason the graph-first rule exists.

  2. A 3-hop blast radius is size-dependent, and on mid-size repos it can cost more than reading. impact is +71–74% on django and this repo, +24% on requests, and −7% on fastapi. A wide transitive envelope is not free; reach for depth=3 when the codebase is large enough to make reading worse.

  3. Against bare grep output alone on a small repo, the graph loses badly (−169% on requests). If match lines answer the question, they are the right tool. The graph earns its keep when you need the complete set.

That completeness is the part a token count cannot show. Every envelope carries total_count and its own truncation flags, so the agent knows whether it has the whole answer — grep never tells you what it missed. The harness enforces the same discipline on itself: an envelope whose traversal was capped is reported as incomplete and never scored as a saving. (The previous version of this table did exactly that — it published "508 impacted, 98.3% saved" from a walk_truncated envelope whose real count, at a sufficient budget, is 1,494.)

Method, the other two baselines, and the limits — including that highest-degree probe selection favours the graph — are in third-party-token-bench.md.

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

Agent

Hook coverage

Skills

MCP server

Notes

Claude Code

Full for its native events ✅

Native skills

✅

No native SessionEnd.

Codex CLI

Full for supported Codex events ✅

Native agent skills

✅

Includes Bash, Read, apply_patch, MCP, prompt, compact, subagent, permission, Stop, and SessionEnd hooks.

Codex Desktop

Same project hook/config contract as Codex CLI ✅

Native agent skills

✅

Project hooks require trust/review; Hub observability is native, while Hub interactive chat is still Claude-only.

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

Agent supervision — pick the model per role (opt-in)

Off by default. Turn it on and every role — the 11 in the canonical chain plus the distiller, onboarder and repairer specialists — can run on its own adapter, model, and reasoning effort: a cheap model reviewing, an expensive one architecting. It works with a single adapter too, since routing across one provider's own model tiers is the common case rather than a fallback.

cos supervision enable
cos supervision set --orchestrator-model claude-sonnet-5-5   # project default
cos supervision set --role reviewer  --role-model claude-haiku-5-5 --role-effort low
cos supervision set --role architect --role-model claude-opus-5-5  --role-effort xhigh
cos supervision show

With more than one adapter installed, a role can cross runtimes entirely — review on Codex while architecture stays on Claude:

cos supervision set --role reviewer --role-adapter codex

Eligibility is probed, not declared: an adapter is offered for a role when its dispatcher resolves at load time, so an adapter whose CLI or SDK is missing is never silently routed to. Model catalogs come from adapter.yaml, and an adapter that publishes none (Codex takes a freeform -m) accepts the model you type. A new runtime is therefore configurable the day it is installed.

When a provider reports a rate limit, only the model pool that hit it goes into a persistent cooldown — providers meter each pool separately, so an exhausted Opus pool must not stop a reviewer running on Haiku. Recovery is one half-open probe, not a retry storm against a limit that cannot succeed.

Same policy from the Hub (Config → Settings), the CLI, or MCP — no Hub required. Disabled means disabled: no probe, no state write, no tokens.

Full contract: docs/engineering/agent-supervision.md · operator guide: docs/playbooks/agent-supervision-setup.md

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

Doc

What's in it

AGENTS.md

Agent entry point — Core Loop, Critical Rules, Verification Matrix

docs/architecture/meta-project.md

Hexagonal design, DNA/mRNA/phenotype, propagation matrix

docs/governance/critical-rules.md

27 critical rules with rationale + repair steps

docs/governance/mcp-tool-inventory.md

Per-tool spec + envelope contract

docs/governance/agent-workflow.md

Domain routing, task protocol, memory contract

docs/engineering/graph_os-queries.md

When to query the graph vs grep

docs/engineering/hub-architecture.md

Hub: FastAPI ↔ React SPA contract

docs/engineering/agent-supervision.md

Per-role adapter/model routing, capacity breaker, trigger modes

docs/playbooks/

Hook authoring · adapter authoring · template authoring · MCP tool authoring

docs/adapters/

Claude SDK · Codex CLI integration

CONTRIBUTING.md

Setup, contribution loop, PR checklist

SECURITY.md

Vulnerability disclosure policy

GOVERNANCE.md

Decision model, quality gates, becoming a maintainer

KNOWN_LIMITATIONS.md

Honest constraints + the ratchets that shrink them

docs/governance/stability-contract.md

What 1.0 freezes + the deprecation ladder

CHANGELOG.md

Release notes

Troubleshooting

Symptom

Cause

Fix

cos: command not found after uv tool install

~/.local/bin (or uv's tool dir) not on PATH

uv tool update-shell then open a new shell

cos doctor reports mcp.coding-os = absent

Adapter installer hasn't run for this project

bash src/adapters/<agent>/install.sh from project root, then restart the agent runtime

cos hub start fails with Address already in use :9188

Port 9188 busy (likely an old Hub still running)

lsof -ti:9188 | xargs kill then re-run; or cos hub start --port 9999

make verify complains bash: declare -A …

macOS default bash 3.2 doesn't have associative arrays

brew install bash (Makefile picks up /opt/homebrew/bin/bash automatically)

cos init fails on npm ci step

Node.js missing or below 20

Install Node ≥20 (brew install node@20); only required if your template touches src/core/web/ui/

Docker build OOM on npm ci

Default Docker memory < 4 GB

Docker Desktop → Settings → Resources → bump memory to 4 GB+

ToolSearch returns InputValidationError for a cos_* tool

First-call schema not loaded (Claude defers MCP schemas)

ToolSearch("select:cos_<name>") first, then call the tool

Codex hook is skipped

Project/hash trust is missing, the hooks feature is disabled, or the event/matcher is unsupported

Run /hooks, confirm [features] hooks = true, then inspect cos hooks-list --agent codex

Hub rejects the meta-repo checkout with sits inside … already a coding-os project

A stray .coding-os/ exists higher up (e.g. ~/.coding-os/ from a test run) — fixed 2026-05-23: only registered ancestors block

Update + restart Hub: git pull && cos hub stop && cos hub start. If still blocking, the ancestor is genuinely registered: cos registry remove <ancestor-path>

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).

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.

Available Tools

89 tools
cos_ambiguity_checkA

Run the 7-criteria Anti-Ambiguity gate over the session EvidenceBundle. Returns violations (formula, criterion, detail). Empty list = gate passes. Fires once at PLAN→EXECUTE; CLEAR 1 tasks skip this check.

Inputs: persona_id (required), session_id (required), task_marker (required). Returns: result

cos_analyze_taskA

Extract TaskSignals (domain, action, novelty, urgency, scope, external_dependency, is_takeover, breaking_change, ...) from a prompt + optional memory/graph context. Replaces persona keyword matching. Under 500ms; cached per task_marker.

Inputs: prompt (required), complexity, dimensions, session_id, +2 more. Returns: result

cos_backtrack_logB

Record a backtrack event. Returns {count, advisory, suggested_action, root_cause_summary}. advisory fires at ≥3/≥5 backtracks. suggested_action gives a concrete next step when root_cause is supplied. root_cause_summary shows per-cause counts for this session.

Inputs: reason (required), session_id (required), to_formula (required), from_formula (required), +6 more. Returns: result

cos_classify_promptA

Heuristic Cynefin + dimensions classifier. Reads a user prompt and returns {complexity, dimensions, reasoning, signals}. Optionally writes the gate marker so enforce-task-start.sh passes. Replaces the manual write-state.sh .thinking_os-gate step. Sub-second; deterministic; no LLM call.

Inputs: prompt (required), record, agent_dir. Returns: result

cos_compose_chainA

Compose an ordered formula-role chain from TaskSignals. Strategy: situation override > preset match > per-role scoring composer > hard fallback. Returns ComposedChain with provenance (preset_id, preset_version, effective_threshold, activations).

Inputs: signals_json (required), session_id, situation_id, preset_min_score. Returns: result

cos_detailsA

Get full details of a pattern, observation, or task outcome.

Args: pattern_id: Row ID (or task_id string for task_outcomes). source: Table name — observations, learned_patterns, or task_outcomes.

Returns: str: JSON with full record.

Inputs: pattern_id (required), source. Returns: result

cos_digest_regenerateA
Idempotent

Refresh .coding-os/digest.md from current memory state.

The digest is a ≤ 2.4 KB rolling snapshot of the agent's identity: active beliefs, fading patterns, recent breakthroughs, preferences. Session-startup reads this file to give the agent a coherent memory anchor before any retrieval fires.

Args: project_root: Override project root. Empty (default) uses cwd.

Returns: {path, size_chars, truncated, status} envelope.

Inputs: project_root. Returns: result

cos_discoveryB

Capture a mid-work discovery. decision=backtrack_now triggers an immediate backtrack recommendation. decision=record_for_later stores the discovery for session summary review.

Inputs: kind (required), summary (required), decision (required), persona_id (required), +3 more. Returns: result

cos_dispatch_formulaA

Return the rendered agent prompt and input slice for a formula-agent. The main agent uses this to construct the subagent dispatch. Does NOT spawn the subagent — returns prompt text only.

Inputs: formula_id (required), persona_id (required), session_id (required), task_marker (required), +1 more. Returns: result

cos_dispatch_formula_runA

EXPLICIT, OPT-IN sub-agent spawn for one role. Costs ~5k tokens per call (system prompt + input slice + completion) and rebuilds context inside the sub-agent. PREFER lazy-loading: read src/core/thinking_os/agents/.md inline and produce the output schema yourself — same accuracy, far fewer tokens, no context rebuild penalty. Use this tool only when (a) the role's work is long-running and would dominate the main loop, or (b) you explicitly want a separate session for parallelism. If no SDK is available, returns status='skipped' and the main agent should execute the role's procedure inline.

Inputs: formula_id (required), persona_id (required), session_id (required), task_marker (required), +6 more. Returns: result

cos_dispatch_parallel_runA

Spawn multiple formula-agents concurrently via asyncio.gather. Use when the supervisor returns action='dispatch_parallel' (e.g. security_auditor layers). Each output is persisted to the bundle. Returns list of DispatchResults in input order.

Inputs: persona_id (required), session_id (required), formula_ids (required), task_marker (required), +6 more. Returns: result

cos_doc_headerA
Read-onlyIdempotent

Return a single doc's header without reading the body.

Inputs: path (required). Returns: result

cos_doc_headers_byB
Read-onlyIdempotent

Bulk header-only scan filtered by frontmatter.

Inputs: root, ssot, layer, limit, +2 more. Returns: result

cos_failure_pattern_queryA
Read-onlyIdempotent

Aggregate structured failure anatomy from backtrack_events.

Returns which root_cause categories recur most frequently, with examples. Use before planning to avoid known failure modes. Requires migration v25 (structured backtrack anatomy columns).

root_cause filter values: wrong_model | scope_too_large | missing_context | tool_failure | spec_ambiguity | env_mismatch | other

Args: root_cause: Optional filter to a specific root cause category. domain: Reserved for future per-domain filtering. limit: Max pattern groups to return (1-50, default 10).

Returns: JSON with {patterns: [{root_cause, count, examples}], total_structured, total_backtrack}.

Inputs: limit, domain, root_cause. Returns: result

cos_graph_centralityA
Read-onlyIdempotent

Hub detection — surface high-degree (or high-betweenness) nodes.

Use to identify chokepoints / refactor priorities / nodes that demand extra review.

Args: metric: "degree" (cheap, default) or "betweenness" (expensive). top: Max nodes returned (default 20). kind: Optional kind filter (e.g. "function", "class"). Empty = all.

Returns: JSON envelope with nodes ranked by centrality score.

Inputs: top, kind, metric. Returns: result

cos_graph_communitiesD
Read-onlyIdempotent

Louvain process clusters — response key is processes (not communities).

Inputs: top, min_size, max_members. Returns: result

cos_graph_contextA
Read-onlyIdempotent

Return callers + callees + siblings + referenced docs around a symbol.

Args: uid_or_name: Node uid or fuzzy label. Uid scheme: code:file:<path> | code:function:<path>::<name> | code:class:<path>::<name> | code:module:<dotted> | doc:file:<path> | doc:heading:<path>#<slug>:<level> | folder:<path>. Raw repo paths (core/foo.py) are auto-resolved to code:file: / doc:file: / folder:; if all variants miss, a fuzzy label match is tried. Run cos_graph_query first to discover candidates. direction: "in" | "out" | "both". depth: BFS depth (default 1). include_content: When True, each returned node gains a content field with source text read from file_path:start_line..end_line (capped at 2000 chars, with truncated: bool). Silently skipped when the file is missing or the node has no file_path. (B21) include_evidence: JOIN evidence rows (costs ~2× tokens). include_spine: S3 — pulls the CONTAINS-ancestor chain (file → folder → …) so the UI can render breadcrumbs.

Inputs: uid_or_name (required), depth, direction, include_spine, +2 more. Returns: result

cos_graph_contractsB
Read-onlyIdempotent

Enumerate every handler declared in the graph (HTTP / MCP / gRPC / events / WS).

Inputs: kinds, scope, include_test_sources. Returns: result

cos_graph_cyclesA
Read-onlyIdempotent

Detect circular dependencies as strongly-connected components.

Args: scope: "imports" (module-level circular deps, the design smell) or "calls" (function cycles incl. legitimate mutual recursion). top: Max cycles returned (default 20). min_size: Minimum SCC size to report (default 2).

Returns: JSON envelope with cycles (each {size, members}) + total_count.

Inputs: top, scope, min_size. Returns: result

cos_graph_dead_codeA
Read-onlyIdempotent

List in-repo symbols with zero non-test inbound references (dead-code candidates).

Surfaces functions / methods / classes that nothing (outside tests) calls, constructs, subclasses, or type-references — the inverse of centrality. Candidates only: dynamic-dispatch / CLI-registered / externally-called symbols may appear; verify with cos_graph_references before deleting.

Args: kind: Optional filter — function | method | class. Empty = all three. top: Max candidates returned (default 50, max 500). include_tests: Count test-sourced edges + include test files (default False).

Returns: JSON envelope with dead (list) + total_count.

Inputs: top, kind, include_tests. Returns: result

cos_graph_detect_changesA
Read-onlyIdempotent

Map changed files to affected symbols + downstream tasks + risk level.

Args: files: Comma-separated file paths (empty → echo empty envelope). scope: Label only; "working" | "staged" | "HEAD~1..HEAD". analyze_downstream: Walk transitive blast radius.

Inputs: files, scope, analyze_downstream. Returns: result

cos_graph_diffA
Read-onlyIdempotent

Graph blast-radius of a git revision range (base..head).

Resolves changed files via git diff --name-only base..head, then maps them to affected symbols + downstream consumers + risk (PR/review view).

Args: base: Base git revision (default HEAD~1). head: Head git revision (default HEAD). analyze_downstream: Walk transitive consumers (default True).

Returns: JSON envelope with range, files, symbols, downstream_consumers, risk_level.

Inputs: base, head, analyze_downstream. Returns: result

cos_graph_doctorA
Read-onlyIdempotent

Graph health snapshot — orphans, dangling edges, duplicates, backend status.

Call when graph queries return nothing or meta.backend_fallback=true.

Args: fix: If True, attempt safe repairs (delete dangling edges). Default False — use the report-only mode to see what would change first.

Returns: JSON envelope with healthy boolean, issues list, stats dict.

Inputs: fix. Returns: result

cos_graph_entrypointsC
Read-onlyIdempotent

Top-N scored entry points (main / cli / http / cron / test) — TASK-081.

Inputs: top, kind, diversify, min_score. Returns: result

cos_graph_exportA
Read-onlyIdempotent

Export a subgraph as json | mermaid | dot.

Args: format: Output format (json / mermaid / dot). root_uid: Optional seed; empty walks the edge table. edge_types: Comma-separated edge filter (empty = all). max_nodes: Hard cap on node count. include_spine: S3 — also include the CONTAINS ancestor chain. mode: TASK-141 view-mode blend when no root is pinned — auto (semantic + contains, default), containment, dependencies, or processes. exclude_kinds: Comma-separated noise kinds to drop. Sentinel __default__ (default) applies the built-in noise list; empty string disables filtering.

Inputs: mode, format, root_uid, max_nodes, +3 more. Returns: result

cos_graph_impactA
Read-onlyIdempotent

Group affected nodes by risk tier (will_break / should_review / context).

Args: uid: Fully-qualified node uid. Scheme: code:file:<path> | code:function:<path>::<name> | code:class:<path>::<name> | code:module:<dotted> | doc:file:<path> | folder:<path>. Raw repo paths (core/foo.py) are auto-resolved to code:file: / doc:file: / folder:. If unsure, run cos_graph_query first to discover the right uid. direction: "downstream" (callers — break if uid changes) | "upstream" (deps uid calls/imports) | "both". depth: BFS hop limit (default 3). confidence_min: Drop edges below this score (default 0.3, matching the function + HTTP route). visit_limit: BFS node-visit cap (1..50000, default 500). Raise when meta.walk_truncated is true.

Inputs: uid (required), depth, direction, visit_limit, +1 more. Returns: result

cos_graph_overviewA
Read-onlyIdempotent

Aggregate files into module nodes with weighted cross-module edges (architecture map).

One whole-repo shape in a single call: directories become nodes weighted by member count, and cross-module imports/calls/inheritance aggregate into weighted edges. Same-module edges are dropped, and tests, build output and worktrees are excluded so the map is the architecture rather than a mirror of it.

Args: max_modules: Heaviest modules kept (default 40, max 100). min_edge_weight: Prune edges lighter than this (default 1).

Returns: JSON envelope with , and module_count.

Inputs: max_modules, min_edge_weight. Returns: result

cos_graph_pathA
Read-onlyIdempotent

Shortest path between two nodes (either direction).

Args: source_uid: Origin uid (auto-resolves raw paths; see cos_graph_impact for the scheme). target_uid: Destination uid (same rules as source_uid). max_hops: BFS depth limit (default 5).

Inputs: source_uid (required), target_uid (required), max_hops. Returns: result

cos_graph_queryA
Read-onlyIdempotent

Look up a symbol by a KNOWN short term, path, or uid (lexical + graph expansion). For a natural-language DESCRIPTION of code whose name you don't know, use cos_graph_search instead.

TIP: prefer SHORT terms ("sdk_dispatcher", "ClaudeSDKDispatcher.dispatch") or a literal path / uid. Long natural-language queries return weaker matches because the index is built from labels + docstrings, not free text.

UID scheme (also accepted as q): code:file: · code:function::: · code:class::: code:method:::. · code:module: doc:file: · doc:heading:#: · folder:

When the query looks like a path or uid and the lexical pass returns nothing, the tool falls back to a direct uid lookup so the agent gets a single-item hit instead of empty results.

Args: q: Short term, path, or uid (non-empty). NL queries work but degrade. kinds: Comma-separated filter of node kinds (e.g. "function,class,method"). Empty = all. limit: Max results (default 10). max_hops: Walk expansion depth (default 2). confidence_min: Edge confidence floor (default 0.3). include_spine: S3 — attach the CONTAINS-ancestor chain to each result for breadcrumbs.

Returns: JSON envelope with results array. See docs/engineering/graph_os-queries.md.

Inputs: q (required), kinds, limit, max_hops, +2 more. Returns: result

cos_graph_rankingA
Read-onlyIdempotent

PageRank — node importance, optionally personalised by query.

Use for: knowledge condensation (top-N canonical concepts), query-personalised search ranking, documentation sourcing.

Args: query: Optional personalisation query ("auth", "graph backend"). Empty = global PageRank. top: Max nodes returned (default 20). kind: Optional kind filter. Empty = all. damping: PageRank damping factor (default 0.85). iterations: Power-iteration count (default 30).

Returns: JSON envelope with nodes ranked by PageRank score.

Inputs: top, kind, query, damping, +1 more. Returns: result

cos_graph_referencesA
Read-onlyIdempotent

List inbound edges — "who references this?".

Args: uid: Fully-qualified node uid. Scheme: code:file:<path> | code:function:<path>::<name> | code:class:<path>::<name> | code:module:<dotted> | doc:file:<path> | folder:<path>. Raw repo paths are auto-resolved. kinds: Comma-separated edge types. Empty string (default) picks edge types automatically per node-kind — class nodes get constructs+has_param_type+is_decorated_by+inherits_from, function/method get calls+accesses_field+imports, files get imports+links_to+references_doc+contains. R4-02. limit: Max edges returned (default 100).

Inputs: uid (required), kinds, limit. Returns: result

cos_graph_rename_planA
Read-onlyIdempotent

Plan a rename — call-sites, docs, tests, strings, risk.

Args: uid: Symbol to rename. Scheme: code:function:<path>::<name> | code:class:<path>::<name> | code:module:<dotted>. Raw paths are auto-resolved when applicable. new_name: Replacement symbol name. check_strings: Also scan string literals for the old name.

Inputs: uid (required), new_name (required), check_strings. Returns: result

cos_graph_resolveA
Read-onlyIdempotent

Resolve a natural-language label, path, or partial uid to canonical uids.

Use this BEFORE other cos_graph_* tools when you don't know the exact uid. Tries: direct uid → path/qualname → FTS5 full-text → LIKE fallback.

UID scheme: code:file: · code:function::: · code:class::: code:method:::. · code:module: doc:file: · doc:heading:#: · folder:

Args: q: Natural language ("the dispatcher function"), label ("ClaudeSDKDispatcher"), path ("adapters/claude/sdk_dispatcher.py"), or qualname ("Class.method"). kinds: Comma-separated kind filter (e.g. "function,method,class"). Empty = all. top: Max results (default 10).

Returns: JSON envelope with results (ranked list of {uid, kind, label, …}) and strategy (which resolution path matched).

Inputs: q (required), top, kinds. Returns: result

cos_graph_similarA
Read-onlyIdempotent

Return the top-K nodes most similar to uid (difflib baseline).

Args: uid: Fully-qualified node uid (see cos_graph_impact for scheme). Raw repo paths are auto-resolved to code:file: / doc:file: / folder:. top_k: Number of similar nodes to return. confidence_min: Minimum similarity score (0.0–1.0).

Inputs: uid (required), top_k, confidence_min. Returns: result

cos_graph_stale_filesA
Read-onlyIdempotent

List indexed files with a git commit newer than the index pass that read them.

Truncation carries a flag because the harness knows it truncated. Staleness carries none: the graph is complete against its own model while the model is behind the tree, so the envelope looks clean either way. Ask this before acting on a confidently complete answer.

Args: top: Max paths returned (default 100, max 5000).

Returns: JSON envelope with stale (list), stale_count, indexed_files and index_age_seconds. Fails with unavailable when git history cannot be read — an empty list would read as "nothing is stale".

Inputs: top. Returns: result

cos_graph_test_gapA
Read-onlyIdempotent

List prod function/method/class with zero inbound edge from any test (untested symbols).

Candidates only: indirect exercise (CLI / fixtures / dynamic dispatch) may not appear as a graph edge. Shell excluded (no call-graph).

Args: kind: Optional filter — function | method | class. Empty = all three. top: Max returned (default 50, max 500).

Returns: JSON envelope with untested (list) + total_count.

Inputs: top, kind. Returns: result

cos_graph_traceA
Read-onlyIdempotent

Forward execution walk from entry_uid until terminals.

Args: entry_uid: Function/method uid to start from, e.g. code:function:core/foo.py::bar. Raw paths or names are auto-resolved (file → code:file: then entry-point heuristic). Run cos_graph_query first if unsure. terminals: Comma-separated edge labels that stop the walk. max_steps: Hard cap on emitted steps.

Inputs: entry_uid (required), max_steps, terminals, include_external. Returns: result

cos_healthA
Read-onlyIdempotent

Return database health stats: row counts per table, schema version, DB size, FTS5 availability, embeddings status.

Use this tool to verify the thinking_os database is operational and to get a quick summary of stored data volume.

Returns: str: JSON object with keys: tables (row counts), schema_version, fts5_available, db_size_bytes, rag (embeddings + doc_chunks status).

Inputs: no named parameters. Returns: result

cos_learn_extractA
Idempotent

Scan task outcomes to discover recurring patterns.

Detects domain_rework, skill_correlation, and complexity_mismatch patterns. Inserts new patterns into learned_patterns with calculated confidence.

Args: min_occurrences: Minimum occurrences to consider a pattern (default 3).

Returns: str: JSON with extracted patterns list and analysis stats.

Inputs: min_occurrences. Returns: result

cos_learn_narrativeA

Record what was learned from a difficult task (breakthrough narrative).

Call this after a rework→success breakthrough to capture:

  • What approaches failed and why

  • What finally worked

  • The reusable key insight

Creates a high-impact learned pattern for future suggestions.

Args: task_id: Task identifier (e.g. "TASK-100"). what_failed: Approaches that didn't work. what_worked: The solution that resolved the issue. key_insight: Reusable lesson learned (required).

Returns: str: JSON with status, history_id, pattern_id.

Inputs: task_id (required), key_insight, what_failed, what_worked. Returns: result

cos_learn_suggestA
Read-onlyIdempotent

Return relevant patterns for the current task context.

Includes spaced repetition: fading patterns (0.2-0.4 confidence) that were once validated get priority for re-validation.

Args: domain: Task domain (e.g. "BACKEND"). Optional. complexity: Cynefin classification. Optional. task_type: Type of task (e.g. "feat"). Optional. limit: Max suggestions (1-20, default 5).

Returns: str: JSON with suggestions list [{id, pattern, confidence, reason}].

Inputs: limit, domain, task_type, complexity. Returns: result

cos_learn_validateA

Record whether a suggested pattern was helpful.

Updates confidence using brain-inspired formulas:

  • Helpful: LTP with diminishing returns + temporal proximity bonus

  • Not helpful: LTD proportional penalty

Args: pattern_id: ID in learned_patterns table. was_helpful: Whether the pattern was useful (default True).

Returns: str: JSON with old/new confidence and validation status.

Inputs: pattern_id (required), was_helpful. Returns: result

cos_log_queryA
Read-onlyIdempotent

Query the durable log_events store (WARN+), most-recent first — the agent's "what is broken now".

Inputs: level, limit, scope, since, +4 more. Returns: result

cos_metric_queryA
Read-onlyIdempotent

Query agent metrics with optional filters.

Args: domain: Filter by domain (e.g. "BACKEND"). Optional. model: Filter by model (e.g. "sonnet"). Optional. outcome: Filter by outcome (e.g. "rework"). Optional. agent_type: Filter by agent type. Optional. date_from: Start date (ISO format, e.g. "2026-03-01"). Optional. date_to: End date (ISO format, e.g. "2026-03-25"). Optional. limit: Max rows (1-100, default 20).

Returns: str: JSON with total count and matching rows.

Inputs: limit, model, domain, date_to, +3 more. Returns: result

cos_metric_recordA

Record a single agent performance metric after task completion.

Args: agent_type: Type of agent (e.g. "general", "planner", "code-reviewer"). outcome: Result — one of: success, rework, partial, blocked. task_id: Task identifier (e.g. "TASK-143"). Optional. model: Model used (e.g. "sonnet", "opus"). Optional. duration_ms: Duration in milliseconds. Optional. domain: Task domain (e.g. "BACKEND", "FRONTEND", "INFRA"). Optional. complexity: Cynefin classification (e.g. "CLEAR", "COMPLICATED"). Optional.

Returns: str: JSON with inserted row id and status.

Inputs: outcome (required), agent_type (required), model, domain, +3 more. Returns: result

cos_metric_trendA
Read-onlyIdempotent

Get aggregated trend data for agent metrics.

Args: metric: One of: success_rate, rework_rate, count. window_days: Lookback window in days (1-365, default 30). group_by: Grouping dimension: domain, model, agent_type, complexity.

Returns: str: JSON with trends array containing period, counts, and rate.

Inputs: metric, group_by, window_days. Returns: result

cos_observation_recordD
Idempotent

Record an observation explicitly.

Inputs: file_path (required), tool_name. Returns: result

cos_presence_queryA
Read-onlyIdempotent

Return per-agent presence state and live-session inventory.

Reads .coding-os/<agent>/sessions/*.json (the same files agent-presence.sh writes) and applies the SSOT rules in board_os.presence. When agent is empty, every adapter registered in adapters//adapter.yaml is reported.

Used by cos daily, CI gates, and the live-agents board UI to verify zombie sessions are gone after deploy.

Inputs: agent. Returns: result

cos_promoteA
Idempotent

Promote a validated pattern to a rule or feedback memory file.

Requires confidence >= 0.3. Creates file content but does NOT write to disk (caller writes the returned content to the appropriate location).

Args: pattern_id: ID in learned_patterns table. target: Output type — "feedback" or "rule".

Returns: str: JSON with status, filename, and file content to write.

Inputs: pattern_id (required), target. Returns: result

cos_retrieval_citeA
Idempotent

Mark retrieval rows as actively cited by the agent.

Call this after using one or more chunks/patterns/tasks in a meaningful way (read them carefully, applied them). Cited retrievals get ~4× the weight when priority-learning runs, so the signal is only useful if it reflects actual use — do NOT cite passive retrievals.

Args: retrieval_ids: Comma-separated list of retrieval ids (int), returned as retrieval_ids in prior cos_search / cos_doc_search / cos_task_search responses. e.g. "12,17,24".

Returns: JSON with {updated, unknown} — updated count + list of ids that did not exist.

Inputs: retrieval_ids (required). Returns: result

cos_retrieval_enrichment_checkA
Read-onlyIdempotent

Recommend whether to enable contextual retrieval enrichment.

The underlying LLM enrichment path is intentionally a stub — this tool exists so the decision is metric-driven and auditable before anyone pays the Haiku bill.

Args: lookback_days: Window of retrieval quality data (default 14).

Returns: {recommend: bool, reason, cost_warning?, summary}.

Inputs: lookback_days. Returns: result

cos_retrieval_learnA

Adjust document_chunks.priority based on recent retrieval outcomes.

Walks retrievals with a known outcome in the lookback window and:

  • chunk cited in a success task → priority += 0.02

  • chunk cited in a rework/blocked task → priority −= 0.01

  • passive retrievals ±0.005 (weaker signal)

Clamped to [0.1, 0.9]. Intended to run nightly via cron or after a batch of task-done events.

Args: lookback_days: How many days of retrievals to consider (default 7). dry_run: When True, compute changes without writing.

Returns: {adjusted, gained, lost, changes[], status} envelope.

Inputs: dry_run, lookback_days. Returns: result

cos_retrieval_qualityA
Read-onlyIdempotent

Report mean retrieval precision over the lookback window.

Precision is derived from (was_cited, outcome) pairs on the retrievals table, so it's honest: a retrieval that was cited and led to success counts as 1.0; a cited retrieval that led to rework counts as 0.0. Used to decide whether contextual enrichment is worth the LLM cost.

Args: lookback_days: Window in days (default 14). layer: Optional layer filter ("memory"|"docs"|"tasks").

Returns: {mean_precision, samples, below_gate, gate, layer, status}.

Inputs: layer, lookback_days. Returns: result

cos_role_infoA

Return metadata for a formula-role (researcher..refactorer): prompt_prefix, tools_budget, intensity_steps, backtrack_triggers, criteria_required. Useful for the main agent before dispatch.

Inputs: role_id (required). Returns: result

cos_route_modelA
Read-onlyIdempotent

Recommend optimal model based on historical outcome data.

Cold start (<10 outcomes): returns static default from performance.md. Warm: queries success rates per model for the given complexity+domain.

Args: complexity: Cynefin classification (CLEAR/COMPLICATED/COMPLEX/CHAOTIC). dimensions: Number of problem dimensions (default 1). domain: Task domain (e.g. "BACKEND"). Optional.

Returns: str: JSON with recommended_model, confidence, reason, fallback_model.

Inputs: complexity (required), domain, dimensions. Returns: result

cos_route_skillA
Read-onlyIdempotent

Recommend skills based on historical outcome data.

Cold start: returns static defaults from skill-enforcement.md. Warm: augments with historically successful skills.

Args: domain: Task domain (e.g. "BACKEND", "FRONTEND"). task_type: Type of task (e.g. "feat", "fix"). Optional. complexity: Cynefin classification. Optional.

Returns: str: JSON with skills list [{name, confidence, reason}].

Inputs: domain (required), task_type, complexity. Returns: result

cos_situation_detectB

Classify a set of signals into a situational dispatch chain id (incident-response, onboarding, scope-change, external-integration, design-review, existing-project-takeover) or null if none match. The matched situation overrides persona primary_formulas.

Inputs: signals. Returns: result

cos_superviseA

Return the next action the main agent should take: dispatch a formula-agent, backtrack, or signal done. Call repeatedly after recording each formula output via cos_supervise_record_output. Never spawns agents itself — only tells the main agent what to dispatch.

Inputs: persona_id (required), session_id (required), task_marker (required), phase, +5 more. Returns: result

cos_supervise_record_outputA

Append a formula-agent's output to the session EvidenceBundle and record the dispatch in formula_dispatches. Call after each formula-agent returns. status: ok|fail|timeout.

Inputs: formula_id (required), persona_id (required), session_id (required), output_json (required), +3 more. Returns: result

cos_supervision_configB

Show, enable, disable, or partially configure the current project's adapter-neutral supervision policy without requiring Hub.

Inputs: mode, role, action, clear_role, +12 more. Returns: result

cos_takeoverA

Bootstrap an existing-project-takeover session: sets the situation to existing-project-takeover, picks legacy-maintainer persona, and returns the first dispatch action (Analyst in reverse mode). Use when inheriting a legacy repo with no docs.

Inputs: session_id (required), task_marker (required), repo_description. Returns: result

cos_task_boardA
Read-onlyIdempotent

Return the board state grouped by (swimlane, status) with WIP info. Complete/archive columns are keyset-paginated (pass cursor + status_filter to load more).

Inputs: epic, kind, limit, cursor, +4 more. Returns: result

cos_task_by_filterA
Read-onlyIdempotent

List tasks matching an optional status and/or domain filter.

No semantic query — pure structured filter. Use when you need "all open backend tasks" or "all blocked tasks" without a specific concept.

Args: status: Filter by status (open/wip/done/blocked). Empty = all. domain: Filter by domain (BACKEND/FRONTEND/DOCS/...). Empty = all. limit: Maximum results (1-100, default 20).

Returns: JSON with results list (sorted by task_id ASC) and count.

Inputs: limit, domain, status. Returns: result

cos_task_claim_nextC

Atomically select+claim the top runnable task for this session (or claimed=null).

Inputs: swimlane, priority_min, agent_session. Returns: result

cos_task_createA

Create a new Scrumban task file + sync to DB.

Prefer this over hand-writing YAML. Validates swimlane against scrumban-config.yaml and kind against the 8-value enum. Pass ready=True to mark the task pullable in one shot; for bug-kind tasks pass acceptance= (G/W/T lines) and repro= so the create satisfies its own DoR in one call.

Inputs: kind (required), title (required), swimlane (required), epic, +11 more. Returns: result

cos_task_dailyC
Read-onlyIdempotent

Produce the daily standup summary.

Inputs: since, agent_session. Returns: result

cos_task_dependenciesA
Read-onlyIdempotent

Return the tasks that task_id directly depends on.

Use before starting a task to verify prerequisites are done. Returns only direct (first-level) dependencies — use repeated calls for transitive traversal.

Args: task_id: Task identifier (e.g. "TASK-199").

Returns: JSON with task_id, dependencies list, and count.

Inputs: task_id (required). Returns: result

cos_task_dependentsA
Read-onlyIdempotent

Return the tasks that declare task_id as a dependency.

Use for impact analysis: "If I change TASK-195, what downstream tasks need to be re-verified?" Returns only direct dependents — non-transitive.

Args: task_id: Task identifier (e.g. "TASK-195").

Returns: JSON with task_id, dependents list, and count.

Inputs: task_id (required). Returns: result

cos_task_editA

Edit a task's frontmatter fields and/or body; each change is recorded to the actor-attributed edit history.

Inputs: task_id (required), body, epic, title, +7 more. Returns: result

cos_task_historyB
Read-onlyIdempotent

Full actor-attributed task history — creation, status transitions, field edits, and git commits.

Inputs: task_id (required), limit, include_commits. Returns: result

cos_task_moveC

Transition a task through the Scrumban state machine.

Inputs: to (required), task_id (required), reason, bypass_wip, +1 more. Returns: result

cos_task_pickB
Read-onlyIdempotent

Return top candidate tasks to start next, ranked by priority.

Inputs: swimlane, priority_min, max_candidates. Returns: result

cos_task_readyA
Idempotent

Add or remove the 'ready' label that gates icebox→in_progress.

Inputs: task_id (required), ready, agent_session. Returns: result

cos_task_reclaimC
Idempotent

Reclaim zombie in_progress tasks (idle + owner session inactive) to icebox+ready.

Inputs: dry_run, idle_hours, agent_session. Returns: result

cos_task_reconcileA
Read-onlyIdempotent

Triage stranded in_progress/testing tasks with completion evidence + a review recommendation (read-only).

Inputs: include_active. Returns: result

cos_task_repositionB

Update Scrumban status and/or swimlane (MD frontmatter + sync).

Inputs: task_id (required), to, reason, swimlane, +2 more. Returns: result

cos_task_retroB
Read-onlyIdempotent

Weekly retro metrics (cycle time, throughput, emergency count).

Inputs: since. Returns: result

cos_task_showA
Read-onlyIdempotent

Show a single task's frontmatter fields and full markdown body — in-session alternative to raw ls/grep/Read on docs/tasks.

Inputs: task_id (required), include_body. Returns: result

cos_task_wip_checkA
Read-onlyIdempotent

Lightweight check of current WIP counts vs. configured caps.

Inputs: no named parameters. Returns: result

cos_timelineA
Read-onlyIdempotent

Get recent task outcomes and observations timeline.

Args: days: Lookback window (1-365, default 30). domain: Filter by domain (e.g. "BACKEND"). Optional. limit: Max entries (1-50, default 20).

Returns: str: JSON with timeline entries [{id, title, date, outcome, type}].

Inputs: days, limit, domain. Returns: result

cos_traceabilityA

Read-only audit: verify that tasks have doc anchors and that recent formula dispatches have matching evidence in the bundle. Idempotent and non-blocking. scope: task|project.

Inputs: persona_id (required), session_id (required), task_marker (required), scope. Returns: result

cos_trajectory_readA
Read-onlyIdempotent

Return the most recent project trajectory snapshot(s).

Use at session start to understand WHERE the project is heading before looking at the task board. Returns phase, current focus, architectural decisions made, anti-patterns discovered, and open questions.

Args: limit: Number of recent snapshots to return (1-20, default 1).

Returns: JSON with {snapshots: [...], count: int}.

Inputs: limit. Returns: result

cos_trajectory_snapshotA

Persist a project trajectory snapshot for the current session.

Records WHERE the project is heading (phase, focus, architectural decisions, anti-patterns discovered, open questions) so future sessions have strategic context beyond task history. Each call creates a new row linked to the previous snapshot via supersedes_id.

Args: session_id: Current session identifier. phase: Current development phase (e.g. "v2 hardening"). current_focus: What the team is focused on right now. architectural_decisions: JSON array of {decision, rationale} objects. anti_patterns_discovered: JSON array of {pattern, context} objects. open_questions: JSON array of {question, priority} objects or plain strings. next_logical_step: Single-sentence description of what comes next. confidence: Confidence in this trajectory assessment (0.0-1.0).

Returns: JSON with {status, id, supersedes_id}.

Inputs: session_id (required), phase, confidence, current_focus, +4 more. Returns: result

cos_work_log_appendB

Append one Work Log line to a task. Critical for Codex sessions.

Inputs: summary (required), task_id (required), source, agent_session. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 89 tools

    Disambiguation2/5

    Several tool clusters have overlapping purposes: cos_graph_query vs cos_graph_search vs cos_graph_resolve, cos_search vs cos_doc_search vs cos_task_search, cos_task_pick vs cos_task_claim_next, and cos_supervise vs cos_dispatch_formula. Descriptions attempt to differentiate boundaries, but with 89 tools an agent must read carefully to avoid misselection.

    Naming Consistency4/5

    All tools consistently use the cos_ prefix and snake_case, which makes the set predictable at the casing level. However, the underlying convention mixes verb_noun (cos_task_create) with noun phrases (cos_graph_contracts, cos_task_by_filter, cos_health), so it is not a perfectly uniform pattern.

    Tool Count1/5

    89 tools is far beyond the recommended 3-15 range and represents an extreme mismatch for a single server. The surface is fragmented across graph analysis, task management, memory, retrieval, metrics, and supervision, making discovery and selection costly.

    Completeness4/5

    The server covers task lifecycle, graph exploration, memory learning, retrieval quality, metrics, and supervision with extensive operations. Minor gaps exist, such as explicit documentation authoring or task deletion, but core workflows for the stated coding-OS domain are largely complete.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that exposes local agents as tools for Claude Code, enabling capabilities in quant, trading, news, reports, robotics, Notion, and FreeCAD.
      1
      -