ontology-atlas

English | 한국어 | 日本語 | 简体中文

Why

Coding agents now change code faster than a team can keep a picture of it in their heads. Atlas keeps that picture beside the code: what each part is for, which files implement it, what depends on what, and what nobody knows yet. Your agent reads it before a task and proposes updates after; you keep, correct or reject each change as a Markdown diff.

• Your agent starts with context. Claude Code, Codex, Cursor and Antigravity read the concepts, code paths, dependencies and open questions a task touches, over MCP.
• You own the record. One Markdown file per concept in an atlas/ folder, versioned and reviewed in Git like the code.
• You decide what is true. Agent proposals stay proposals until you accept them.
• It says what it does not know. A line on the map is a declared relationship, not proof of runtime impact; missing evidence shows as unknown, never as safe. Compact task handoffs preserve whole uncertainty statements or report omissions with the document reads needed to inspect them. Task matching and navigation use authored evidence; code examples, hidden comments and blockquotes cannot supply capability claims or work coordinates.

See it

Quick start

1. Install the app from the download page, or open the browser version.
2. Open a folder. Atlas reads its Markdown in place, or starts an atlas/ folder in your repository, and shows the path before it writes anything.
3. Connect your agent. In Agents › MCP, press Connect for your tool, restart the agent, and ask about your next task.

macOS (Apple Silicon) is signed and notarized and carries the MCP server inside the app. Windows x64 is an unsigned beta. On Linux, use the browser version or run the CLI and MCP server from a source checkout. Releases list each version's files and checksums.

How it works

your-repo/
├── src/
└── atlas/                 ← cloned, branched and reviewed with the code
    ├── project.md
    ├── domains/  capabilities/  elements/
    ├── sources/           documents kept exactly as they arrived
    └── wiki/              pages written from those sources, every fact cited

A Markdown file whose frontmatter has kind: is one concept. Its uid never changes, its slug is its current address, and its path names the code it describes. The map, documents, Library, Insights and Git screens all read these files.

Your agent reaches the folder two ways:

• MCP: the agent starts the Atlas MCP server, which reads and writes the folder on disk, even with the app closed. Connect an agent · MCP reference
• ACP: Claude Agent and Codex also run in the app's own chat; each write waits until you allow it. Agents

Analysis compares recorded dependencies between responsibilities, then opens the exact concepts and declaring document beside the selected claim. Implementation records, unchecked source and missing explanations stay distinct. Analysis

Local-first

• No backend, account or telemetry. The folder stays plain Markdown on your disk.
• Model calls with your API key or a local model are opt-in, and each records its destination in .ontology-atlas/llm-audit.jsonl.
• A connected coding agent may send your prompt and what it reads to its own provider; Atlas's log does not cover those transfers.

Trust · Security

Status

Atlas is early. Our benchmark has not yet shown better answers with Atlas, and Atlas was slower (the correction). Construction trials, their failures and limits are in the construction measurements.

Documentation

What is Atlas? · First five minutes · What becomes a node? · Relations · Specification · Features · CLI · Architecture

Contributing

Read CONTRIBUTING.md; external pull requests come from forks. AGENTS.md is the contract for people and agents alike.

pnpm install
pnpm dev
pnpm checks:changed -- --run

pnpm pr:land <number> merges a reviewed pull request and keeps its original commits. Development checks is the full gate reference.