English | 简体中文

Cortex Harness

See it in 60 seconds: Done is a check result, not a claim — a public demo of one loop tick (tick -> propose -> check -> try-complete) where two of five items are refused because the evidence does not match. No model call, no server.

Cortex Harness is the open protocol and reference tooling for running CORTEX work as small Blocks. A Block has its own entrypoint, tests, and public contract. The CORTEX Kernel remains the authority for leases, replay, receipts, and completion decisions.

The public constitution is the CORTEX Six Laws, also called the CORTEX Collaboration Constitution. English is the source language for the engine and for these docs. Simplified Chinese counterparts are README.zh-CN.md and docs/zh-CN/.

This repository holds the Apache-2.0 license, the export allowlist, the cortexharness.org docs, and the directory reviewed Blocks land in.

Quickstart

Install Node.js 24 or newer. Cloning and testing does not need a CORTEX server or a DSH install.

git clone https://github.com/mobfish-ai/cortex-harness-open.git
cd cortex-harness-open
npm test

npm test runs the Node.js test runner, the export grep gate, and the CJK gate.

To send live commands, run a CORTEX task-pool server on loopback and install the adapter into a local DSH Web profile. Keep the token in the host environment:

export CORTEX_API_BASE_URL=http://127.0.0.1:8787
export CORTEX_API_TOKEN='token configured on your local task-pool server'
dsh plugin --profile web add "file:$PWD/packages/dsh-web-cortex-command"
dsh web

Then, in the chat input:

/cortex status
/cortex enqueue <task_id> <manifest> 1
/cortex enqueue <task_id> <manifest> 3
/cortex enqueue <task_id> <manifest> 5
/cortex recover

CORTEX_API_BASE_URL must use 127.0.0.1, localhost, or ::1. The default is http://127.0.0.1:8787. manifest is a relative path inside the manifest root configured on that server. The adapter can inspect, enqueue, and recover. Settlement and completion stay on the CORTEX side.

The registry name cortex-dsh-web-command is reserved for a later npm release. No registry release is published from this repository yet.

Architecture

Blocks

discovery-chain-index is the first Block. It builds an index of a discovery chain, the ordered record of what the harness found, so later blocks can read that index.

That block is still under review and is not exported into this repository. When the review finishes, it lands in blocks/ as blocks/discovery-chain-index, with the entry script scripts/discovery-chain-index.mjs. The candidate list, including the cortex-loop self-improvement engine, is in ROADMAP.md.

Reference adapter

packages/dsh-web-cortex-command is the host-side DSH Web bridge that is already in the tree. The browser sends a /cortex slash command and receives a short summary. The host process calls /v1/native-task-pool/{status,enqueue,recover} on the loopback API with CORTEX_API_TOKEN. Error text has the token replaced with [redacted] before it returns.

browser   slash command, no token     DSH host plugin (this repo)
host      Bearer token, loopback      CORTEX task-pool API
task pool                             CORTEX Kernel

The repository root package.json is the GitHub-installable bundle for that plugin. Its dsh.bundle.patch field points at packages/dsh-web-cortex-command/cordis.patch.yml.

The adapter is not an allowlisted class in ALLOWLIST.md. It remains as a pre-allowlist export.

Website

The docs site is VitePress under docs/. English pages are the source. docs/zh-CN/ is the Simplified Chinese display layer. The nav language menu switches locales. The canonical host is cortexharness.org. cortexharness.ai is reserved and has no site.

npm ci
npm run docs:build

The static output is docs/.vitepress/dist. Cloudflare Pages project cortexharness-org is named in wrangler.toml. CI builds the site on push to main. It does not deploy.

Public boundary

Exports follow ALLOWLIST.md. Credentials, vaults, customer records, store data, and local runtime state stay out. The grep gate enforces the hard bans. The CJK gate keeps Chinese, Japanese, and Korean characters inside the zh-CN docs and the fixture allowlist.

License

Apache License, Version 2.0. See LICENSE and NOTICE.

Contributing

CONTRIBUTING.md and SECURITY.md.