coding-os
This MCP server exposes the coding-os/thinking_os platform: project health, docs/memory retrieval, knowledge-graph analysis, task/Scrumban management, metrics/logs, and supervised agent workflow orchestration.
Check database health, schema, FTS/embeddings, graph staleness/doctor status, and retrieval quality.
Search documentation semantically or lexically with metadata filters; read doc headers and frontmatter-based header lists.
Explore the code knowledge graph: resolve symbols, inspect context/references/impact, find paths/cycles/dead code/test gaps, centrality/PageRank/communities, export subgraphs, plan renames, trace execution, and diff blast radius.
Search and manage agent memory and learned patterns; validate patterns, capture breakthrough narratives/trajectory snapshots, query failure patterns, cite retrievals, and regenerate digests.
Record/query metrics, trends, durable logs, observations, and live agent presence.
Manage Scrumban tasks end-to-end: create/edit/search/list/show/history/link, move/reposition/ready/reclaim/reconcile/pick/claim, board state, dependencies, daily/retro/WIP checks, and work logs.
Classify prompts/tasks, compose cognition chains, route models/skills, supervise/backtrack/discover/takeover, dispatch formula agents singly or in parallel, and record formula outputs.
Includes a Django project template and skill set, scaffolding a new project with agent setup and workflow.
Provides nextjs-react skills for Next.js development, loading relevant rules when editing React components in a Next.js project.
Provides an adapter for OpenAI Codex, enabling the same kernel with workflow, hooks, and skills in Codex CLI.
Loads React-specific skills and rules when working on React components, providing targeted coding guidance.
Provides Spring Boot skills for building Spring applications, with stack-specific patterns and best practices.
Includes a WordPress skill for WordPress-specific coding patterns, rules, and workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@coding-os create a new project for my Django app and set up the task board"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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. 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

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 |
| 8 |
|
|
| 9 |
|
|
| 11 |
|
|
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 |
| 12,704 | 6.4% |
| 12,738 | 6.4% |
| 13,158 | 6.6% |
| 13,972 | 7.0% |
uv run python src/scripts/context_budget.py --all-presetsThe 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 |
|
0.5 | Fast Python installer + tool runner |
| |
Bash | 4 | Hook scripts use 4.x features (macOS ships 3.2) |
|
Node.js | 20 | Only if rebuilding the Hub UI under |
|
Docker | 24 | Only for the Docker quickstart below |
|
| 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.shThen 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:9188Open 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 --yeslite 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 |
| 8 | 7 | 44 | 51 |
| 3 | 8 | 46 | 21 |
| 2 | 8 | 46 | 17 |
| 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 firingStart 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 | Host (native) | Agent runtimes (Claude Code / Codex CLI) live on the host filesystem · |
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:9188By 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 doctorshowsmcp.coding-os = ok; the CLI exposescos_*tools viaToolSearch("select:<tool>").Codex CLI:
codex --mcp-listlistscoding-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 |
| MCP server, hooks, rules, skills — agent-agnostic, stack-agnostic |
| Per-agent translation: |
| Per-stack overlays: 27 stacks, 11 CI-verified — |
| The |
Adding a new stack or a new agent is a pure YAML + Markdown change. No Python edits required.
What it does
Complexity Gate — classifies problems before acting (Cynefin: CLEAR / COMPLICATED / COMPLEX / CHAOTIC / CONFUSION).
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.Shared file memory — durable notes in
.agents/memory/, one fact per file under aMEMORY.mdindex, committed with the repo and read by Claude, Codex and any other agent.Hook enforcement — hooks gate writes, edits, prompts, sessions, and stops (exact count in
src/core/hooks/registry.yaml). Adapter parity matrix indocs/engineering/.Four-layer retrieval — agent memory (
.agents/memory/) · doc RAG (cos_doc_search) · task graph (cos_task_*) · knowledge graph (cos_graph_*).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.
Upgrade path —
cos updatekeeps every consumer project in sync withcoding-oswithout 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 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.

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.

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.

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.

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.

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.

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.

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 testFull 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 10Median 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 |
|
|
|
|
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:
"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.
A 3-hop blast radius is size-dependent, and on mid-size repos it can cost more than reading.
impactis +71–74% on django and this repo, +24% on requests, and −7% on fastapi. A wide transitive envelope is not free; reach fordepth=3when the codebase is large enough to make reading worse.Against bare
grepoutput 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 |
Codex CLI | Full for supported Codex events ✅ | Native agent skills | ✅ | Includes Bash, Read, |
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 showWith 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 codexEligibility 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-enforcementCI runs the matrix on every PR. See .github/workflows/ci.yml.
Documentation
Doc | What's in it |
Agent entry point — Core Loop, Critical Rules, Verification Matrix | |
Hexagonal design, DNA/mRNA/phenotype, propagation matrix | |
27 critical rules with rationale + repair steps | |
Per-tool spec + envelope contract | |
Domain routing, task protocol, memory contract | |
When to query the graph vs grep | |
Hub: FastAPI ↔ React SPA contract | |
Per-role adapter/model routing, capacity breaker, trigger modes | |
Hook authoring · adapter authoring · template authoring · MCP tool authoring | |
Claude SDK · Codex CLI integration | |
Setup, contribution loop, PR checklist | |
Vulnerability disclosure policy | |
Decision model, quality gates, becoming a maintainer | |
Honest constraints + the ratchets that shrink them | |
What 1.0 freezes + the deprecation ladder | |
Release notes |
Troubleshooting
Symptom | Cause | Fix |
|
|
|
| Adapter installer hasn't run for this project |
|
| Port 9188 busy (likely an old Hub still running) |
|
| macOS default bash 3.2 doesn't have associative arrays |
|
| Node.js missing or below 20 | Install Node ≥20 ( |
Docker build OOM on | Default Docker memory < 4 GB | Docker Desktop → Settings → Resources → bump memory to 4 GB+ |
| First-call schema not loaded (Claude defers MCP schemas) |
|
Codex hook is skipped | Project/hash trust is missing, the hooks feature is disabled, or the event/matcher is unsupported | Run |
Hub rejects the meta-repo checkout with | A stray | Update + restart Hub: |
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.
Available Tools
89 toolscos_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_regenerateAIdempotent
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_headerARead-onlyIdempotent
Return a single doc's header without reading the body.
Inputs: path (required). Returns: result
cos_doc_headers_byBRead-onlyIdempotent
Bulk header-only scan filtered by frontmatter.
Inputs: root, ssot, layer, limit, +2 more. Returns: result
cos_doc_searchARead-onlyIdempotent
Semantic + lexical search over project documentation chunks.
Stage-1 metadata pre-filter (since migration v22):
domain, layer, since_iso, and include_inactive narrow the
chunk universe BEFORE vector / FTS ranking. Vector search finds
meaning; metadata enforces reality (correct era, correct domain,
not superseded). Combine with source_types for cheap, indexed
pre-filtering.
Args:
query: Natural language search query (e.g. "commission rate calculation").
source_types: Optional comma-separated filter — restrict to specific
source types (e.g. "prd,architecture,adr"). Empty = all types.
limit: Maximum results (1-50, default 5).
mode: "auto" (default) | "semantic" | "lexical".
domain: Frontmatter domain: filter (BACKEND, FRONTEND, OPS,
DOCS, …). Empty = any. Indexed.
layer: Frontmatter layer: filter (adr, playbook, spec, policy,
reference, runbook, postmortem, task). Empty = any. Indexed.
since_iso: Lower bound on frontmatter updated: (YYYY-MM-DD).
Use when the agent asks about "recent" or "current" state and
a stale older doc would be the wrong answer. Empty = any age.
include_inactive: When False (default), hide chunks marked
is_active=0 because the source doc was deleted or superseded.
Set True for decision-history retrieval that must surface
superseded specs.
auto_context: When True (default), soft-default domain from the
active task's swimlane ($COS_AGENT_DIR/.swimlane). Explicit
domain argument always wins. Set False to disable.
Response meta carries filter_hints — heuristic suggestions
extracted from the query (date phrasing, domain keywords, layer
cues). Suggestions are NEVER auto-applied; the agent decides
whether to re-query with them. Mental model: Filter → Search →
Summarize. Vector finds meaning, metadata enforces correctness.
Returns: str: JSON envelope with results list and count. Each result carries source_path, source_type, heading_path, content, score, priority, mtime, chunk_index, retrieval_source.
Inputs: query (required), mode, layer, limit, +5 more. Returns: result
cos_failure_pattern_queryARead-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_centralityARead-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_communitiesDRead-onlyIdempotent
Louvain process clusters — response key is processes (not communities).
Inputs: top, min_size, max_members. Returns: result
cos_graph_contextARead-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_contractsBRead-onlyIdempotent
Enumerate every handler declared in the graph (HTTP / MCP / gRPC / events / WS).
Inputs: kinds, scope, include_test_sources. Returns: result
cos_graph_cyclesARead-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_codeARead-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_changesARead-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_diffARead-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_doctorARead-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_entrypointsCRead-onlyIdempotent
Top-N scored entry points (main / cli / http / cron / test) — TASK-081.
Inputs: top, kind, diversify, min_score. Returns: result
cos_graph_exportARead-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_impactARead-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_overviewARead-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_pathARead-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_queryARead-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_rankingARead-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_referencesARead-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_planARead-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_resolveARead-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_searchARead-onlyIdempotent
Find code symbols from a NATURAL-LANGUAGE description (semantic + lexical + centrality). For a KNOWN name / path / uid, use cos_graph_query instead.
Args: query: Natural-language or code-ish query (e.g. "validate jwt token"). top_k: Number of results to return (1–50).
Inputs: query (required), top_k. Returns: result
cos_graph_similarARead-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_filesARead-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_gapARead-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_traceARead-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_healthARead-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_extractAIdempotent
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_suggestARead-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_queryARead-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_queryARead-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_trendARead-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_recordDIdempotent
Record an observation explicitly.
Inputs: file_path (required), tool_name. Returns: result
cos_presence_queryARead-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_promoteAIdempotent
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_citeAIdempotent
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_checkARead-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_qualityARead-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_modelARead-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_skillARead-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_searchA
Search observations and learned patterns with 5-signal ranking.
Use during Orient step to find relevant past experience. Read-only over memory rows: retrieval telemetry only. Neither this tool nor cos_details moves confidence — only cos_learn_validate does.
Stage-1 metadata pre-filter:
min_confidencedrops decayed/low-trust patterns BEFORE ranking. Stale low-signal patterns can otherwise crowd out fresh hits. Default 0.3 skips decayed/unvalidated noise (fresh patterns start at 0.5, so they still pass); pass 0.0 to include everything.since_dayscaps row age. 0 = no cap (default) — age is opt-in so a valuable old decision is never silently hidden from default recall.
Args:
query: Search text (e.g. "backend rework", "django migration").
limit: Max results (1-20, default 5).
memory_type: Filter by type (pattern/workflow/error/decision/discovery). Optional.
min_confidence: Drop learned_patterns with confidence below this
value (0.0-1.0). Default 0.3 (skips decayed noise). 0.0 = no filter.
since_days: Drop rows older than now-since_days. 0 = no cap.
Common: 90 (one quarter) for "recent" queries.
Returns: str: JSON with results list [{id, title, confidence, impact_score, memory_type, source_table}].
Inputs: query (required), limit, since_days, memory_type, +1 more. 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_boardARead-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_filterARead-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_dailyCRead-onlyIdempotent
Produce the daily standup summary.
Inputs: since, agent_session. Returns: result
cos_task_dependenciesARead-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_dependentsARead-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_historyBRead-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_linkAIdempotent
Set a task's optional external_ref (e.g. github#42) — forge auto-detected; metadata only, never the id.
Inputs: ref (required), task_id (required). 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_pickBRead-onlyIdempotent
Return top candidate tasks to start next, ranked by priority.
Inputs: swimlane, priority_min, max_candidates. Returns: result
cos_task_readyAIdempotent
Add or remove the 'ready' label that gates icebox→in_progress.
Inputs: task_id (required), ready, agent_session. Returns: result
cos_task_reclaimCIdempotent
Reclaim zombie in_progress tasks (idle + owner session inactive) to icebox+ready.
Inputs: dry_run, idle_hours, agent_session. Returns: result
cos_task_reconcileARead-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_retroBRead-onlyIdempotent
Weekly retro metrics (cycle time, throughput, emergency count).
Inputs: since. Returns: result
cos_task_searchARead-onlyIdempotent
Semantic search over the task store with optional status/domain filters.
Use this when you need to find tasks related to a concept — even when exact keywords don't match. Falls back to LIKE on title + goal when embeddings are unavailable.
Args: query: Natural language query (e.g. "payment splitting multi vendor"). status: Optional status filter — one of open/wip/done/blocked. Empty = all. domain: Optional domain filter (BACKEND/FRONTEND/DOCS/INFRA/...). Empty = all. limit: Maximum results (1-100, default 10).
Returns: JSON with results and count. Each result: task_id, title, domain, status, file_path, goal_text, dependencies, score.
Inputs: query (required), limit, domain, status. Returns: result
cos_task_showARead-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_checkARead-onlyIdempotent
Lightweight check of current WIP counts vs. configured caps.
Inputs: no named parameters. Returns: result
cos_timelineARead-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_readARead-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
Scored across 89 tools
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.
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.
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.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Related MCP Servers
- AlicenseCqualityDmaintenanceMCP server for sharing source-backed engineering memory across AI coding clients like Cursor and VS Code.301MIT
- AlicenseNot gradedqualityCmaintenanceLocal MCP server for Claude Code providing persistent memory, task planning, and agent coordination with full transparency and no network calls.2MIT
- AlicenseNot gradedqualityAmaintenanceA 68-tool MCP server providing persistent memory, error tracking, decision logging, task orchestration, and multi-modal AI generation for coding agents like OpenCode and Claude Code.MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that exposes local agents as tools for Claude Code, enabling capabilities in quant, trading, news, reports, robotics, Notion, and FreeCAD.1-