Telos README

telos

Telos is a local MCP server and command line for AI agents. It lets an agent read web pages and public APIs, triage a failed GitHub Actions run, check an HTML page for accessibility and size problems, and drive a browser or Windows app once you grant permission from your own terminal.

npx -y project-telos-mcp

Project Telos | gather | crucible | index | forum | telos | learn | emet | buildlang

It is plain Node.js 20+ with no npm dependencies. The npm package is project-telos-mcp. It serves 50 tools over stdio to any MCP host, such as Claude Code, Codex or the OpenAI Agents SDK.

What it does

• Reads the web and public APIs. telos reach and nine MCP tools read pages, feeds and sitemaps, and they follow robots.txt and Crawl-delay. They read Reddit through its official API with your own app, single X posts through X's oEmbed endpoint, and APIs such as Hacker News, GitHub, arXiv and Wikipedia. Each fetch is logged with its URL, time, status and a SHA-256 of the bytes. The crawler reads HTML as served and does not run page JavaScript, so pages behind a login or a bot check come back empty. See the reach guide.
• Controls a browser or Windows app after you grant it. The CLI drives Chrome through the DevTools Protocol and Windows apps through UI Automation. Each verb has a risk tier. Nothing runs until you issue a grant with telos grant issue, which needs an interactive terminal, so an agent's own shell cannot grant itself access. Consequential actions also ask for a confirmation each time. Password, OTP and card fields are always refused. App control is Windows only. The MCP tool for this lists the verbs and runs none of them. See the tier spec and the control contract.
• Logs every gated action. Gated actions and refusals append to a hash-chained log. After telos keys init the chain heads are signed with a local ed25519 key, and telos receipts verify <session.jsonl> finds edited, reordered, inserted or deleted entries.
• Triages CI. ci-triage --gh-run owner/repo#run_id reads a GitHub Actions run through the gh CLI and says whether it failed on a blocking step or only on warnings, such as a deprecated action runtime. It names the failing step type. It does not diagnose the test.
• Checks HTML pages. accessibility-doctor --html FILE runs 14 static checks, including language, viewport, skip link, landmarks, focus style, reduced motion and labels. performance-doctor --html FILE runs 14 byte-budget checks. Neither opens a browser.
• Writes packets you can verify later. proof.mjs writes a JSON packet for an agent action, a research claim, a colour measurement or a build invariant, with the inputs embedded. proof.mjs verify recomputes the hashes and values and prints MATCH, DRIFT (something changed) or UNVERIFIABLE (an input is missing). Packets are hash-checked and unsigned.

The repo also holds work in progress. The model foundry and learning forge are written contracts and call no model. The causal, embodied and quantum packets are small fixed demos. The creative engine is a set of deterministic image kernels behind demo/index.html. The presentation and operator doctors are tuned to the Project Telos repositories.

Try it

In an MCP host config, set "command": "npx" with "args": ["-y", "project-telos-mcp"]. A tools/list call against 0.9.0 returns 50 tools.

For the command line, install the package globally. That puts telos and telos-mcp on your PATH. Run telos from the install, not through npx, because the npm name telos belongs to an unrelated package.

npm install -g project-telos-mcp
telos reach doctor
# reach doctor  7/12 channels ready
# web         ready               free
# reddit      needs credentials   set REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET
# ...

telos reach fetch https://example.com
# {"result": {"url": "https://example.com/", "status": 200, "page": {"title": "Example Domain", ...}},
#  "receipt": {"fetches": [{"url": "https://example.com/robots.txt", "robots": "robots.txt 404: no restrictions", ...

telos ci-triage --gh-run owner/repo#run_id --summary
# blocking     1
# verdict      DRIFT

telos accessibility-doctor --html page.html --summary
# checks       14
# passed       10

Without a grant, a control verb is refused before it runs:

telos native-control browser navigate https://example.com
# "status": "REFUSED", "tier": "T3", "executed": false, "reason": "NO_GRANT"

To run the demos from source:

git clone https://github.com/HarperZ9/telos.git
cd telos
node demo/run.mjs
#   RUN A (normal render)  : CERTIFIED      recheck=true
#   RUN B (broken render)  : UNVERIFIABLE   recheck=true

From a checkout, npm start (the same as node demo/telos-mcp.mjs) runs the stdio MCP server.

demo/run.mjs renders a 4-D cube, recovers its vertex and edge counts from the image, and checks them against the known shape. The second render is too small to read, so it comes back UNVERIFIABLE.

The outputs above come from project-telos-mcp 0.9.0 installed from npm, run on Node 25 on Windows.

How it compares

• Playwright MCP and Chrome DevTools MCP cover far more browser verbs. Telos covers fewer, and adds Windows app control, a grant you issue from your own terminal, and a log of each action.
• Firecrawl and Jina Reader render JavaScript and run as hosted services. telos reach runs on your machine, reads HTML as served, and follows robots.txt.
• Lighthouse and axe-core load the page in a real browser and run far more rules. The Telos doctors are quick static checks on the HTML file.
• in-toto and Sigstore sign supply-chain attestations with managed keys and public logs. The Telos action log uses one local key, and its packets are hash-checked without a signature.

Running all five Project Telos servers

node demo/server-manifest.mjs prints host config (Codex TOML, Claude JSON, OpenAI Agents) that launches Telos beside gather, index, forum and crucible, for 78 tools in all plus 38 auxiliary compatibility tools. That setup expects all five repositories checked out side by side, with PROJECT_TELOS_PUBLIC set to their parent folder. The orientation commands:

node demo/catalog.mjs --summary          # 78 tools across the five servers
node demo/server-manifest.mjs --summary  # launch map with host config

Expected catalog summary:

Project Telos MCP Catalog
tools    78 total, 78 available
transport stdio, streamable-http
gather    5 tools ...
index     5 tools ...
forum     5 tools ...
crucible  13 tools ...
telos     50 tools ...

Health and state:

node demo/status.mjs --summary
node demo/doctor.mjs --summary
node demo/room.mjs --json

Each command prints JSON with a MATCH, DRIFT or UNVERIFIABLE status. The package's telos and telos-mcp commands route to the same scripts.

See it work

The animated explainer steps through the cube demo, a proof packet verified from its own contents, and four edits that each come back DRIFT with the failing check named. Its source is docs/explainer/index.html.

A passing check can still be wrong is a 2 min 24 s narrated, captioned film about the same loop. The film page has the transcript and sources.

Proof packets

Write the demo agent-action packet, then verify it from the packet alone:

node demo/proof.mjs agent-action --demo --json > packet.json
node demo/proof.mjs verify packet.json

Output from a fresh clone:

verdict       MATCH
witness       unavailable / UNVERIFIABLE

Edit the packet and verify again, and the changed fields are named:

$ node demo/proof.mjs verify edited.json
packet_hash_mismatch (DRIFT)
artifact_digest_mismatch (DRIFT) outputs[0].digest
embedded_verdict_not_derived (DRIFT)

The witness line is a second check by emet. Telos looks for it in a sibling ../emet checkout or at TELOS_EMET_CLI. With emet present the line reads witnessed / MATCH. The witness can lower a verdict and never raises one.

The packet holds source refs, context refs, route, admission decision, side effects and output digests. The verifier recomputes the digests from the embedded inputs, so editing any of those fields gives DRIFT, and a missing input gives UNVERIFIABLE with its path. The verdict is computed from the checks, so a MATCH written into the packet has no effect. The other packet types work the same way: research recomputes source digests, visual recomputes colour and luminance from embedded sRGB samples, and build checks a conserved quantity against a fixture that must break it. Details are in docs/PROOF-LANES.md.

Command surface

node demo/catalog.mjs is the authoritative map. Highlights by area:

Most accept --summary for a compact terminal (TUI) view and --json for IDE, app, and automation hosts.

The doctors in full: node demo/ci-doctor.mjs, node demo/presentation-doctor.mjs, node demo/accessibility-doctor.mjs, node demo/performance-doctor.mjs, node demo/compatibility-doctor.mjs, and node demo/operator-doctor.mjs, plus node demo/ci-triage.mjs and node demo/mcp-freshness.mjs. Live CI intake works read-only: node demo/ci-triage.mjs --gh-run owner/repo#run_id --summary.

Documentation

• docs/INTRODUCTION.md: what Telos is and your first ten minutes.
• docs/HOW-IT-WORKS.md: the verifier loop, step by step, including where it stops.
• docs/ARCHITECTURE.md and docs/PROJECT-CONNECTION-MAP.md: system shape and how the five flagships connect.
• docs/PROOF-LANES.md: the proof packet types and what each one recomputes.
• docs/CURRENT-STATE.md: current state of each surface.
• USAGE.md: install, run, MCP, and verify commands.

Peer repos: gather (research intake), index (workspace maps and context), forum (agent routing with a causal ledger), crucible (claim verification), emet (independent second check). Telos can launch gather, index, forum and crucible beside itself from one manifest; each also stands alone.

Status

project-telos-mcp 0.9.0 is the current release, on npm and as GitHub release artifacts that include native Windows ZIP and MCPB client packages. See the client package guide. npm test runs every test file in demo/, and CI runs it on each change. Interfaces may still move between minor versions. The research packets are fixed demos: they do not do causal discovery, robot safety or hardware error correction.

Upgrading from 0.2.0

0.3.0 writes native-control ledger hash version 2. Upgrade readers before writers, because 0.2.0 readers reject the new format. New readers still accept old receipts. Browser evidence packets are not redacted: URLs, titles, selectors, artifact references and summaries stay in them, so keep them private. See release notes.

The roadmap is docs/PROJECT-TELOS-LARGE-SCALE-ROADMAP-2026-07-02.md. The documentation index is docs/DOCUMENTATION-CONSOLIDATION-REGISTRY-2026-07-02.md, with machine-readable data under docs/registry/.

Reading a record

Most commands print a JSON record. Here is one from the artwork checker, field by field. Run it with python tools/check_repo_art.py --json:

License

Text: CC BY 4.0. Code: FSL-1.1-MIT.

The whitepapers and research notes in docs/research/ are licensed CC BY 4.0. Share and adapt them with credit to Zain Dana Harper; the terms are in LICENSE-TEXT.

The code and the software documentation are FSL-1.1-MIT (fair source). The code is open to read and run, free for nearly any use except building a competing product, and each release converts to the MIT license after two years. Copyright is held by the author. See LICENSE.

Version 0.9.0 and earlier releases were published under FSL-1.1-ALv2 and keep that license, so each of them still converts to Apache 2.0. FSL-1.1-MIT applies from the next release.

For developers

Zero dependencies, so there is nothing to install. Run the MCP contract tests and smoke checks before opening a PR:

npm run test:mcp
node demo/catalog.mjs --summary
node demo/server-manifest.mjs --summary
node demo/room.mjs --json

CI (.github/workflows/ci.yml) runs npm test on Node 24. Run one test file with node demo/<name>.test.mjs. node demo/operator-doctor.mjs --summary checks that the README, package metadata and examples match the code.

Built by Zain Dana Harper in Seattle. More tools: Project Telos, Flywheel and its getting started guide, and the workspace canon.