Ontology Atlas

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

[Ontology Atlas]

Understand your system as AI agents change its code.

A map of what your code does and why, kept as Markdown in your repository
and read by both you and your coding agent.

Download for macOS · Try it in the browser · Guide

[MIT license] [Latest release] [Listed on mcpservers.org] [On StackMap]

[The Ontology Atlas macOS app with the Online Store project selected: its domains named around it, everything unrelated receding, and the inspector showing the project record and its code-evidence state]

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. Initial analysis also excludes literal Markdown examples and marks truncated document evidence for review with a hash-bound original-source follow-up. Task matching and navigation use authored evidence; code examples, hidden comments and blockquotes cannot supply capability claims or work coordinates.

See it

Flat maps show domain labels with spaced outward capability branches and thin directed dependencies. Mark sizes and detail fade with the available row spacing as you zoom. Implementation elements form compact groups beside their capability, with readable names and membership stems. The overview limits crossing lines; inspecting an endpoint reveals its recorded connections and explicitly labelled bundle counts. Gentle local curves and screen-sized arrows keep direction legible. Individual relationship explanations and declaring documents remain available in relation review. A persistent bright outline distinguishes the selection, while amber exclamation marks mean evidence needs rechecking; the map key explains both marks and direction. Larger maps keep the same branch grammar with shorter previews and stable column groups. More/collapse controls disclose actual capabilities; focused areas keep that grammar and a labelled return to the full map. The Concepts panel separates searching, selecting and expanding the tree. Below 1280 px it temporarily folds beside an inspector and returns when that inspector closes; it can still be reopened explicitly. Project details keep dated source checks under Check record.

Empty folders and concepts without relationships reveal their start actions when returning to Map from another screen. Starter creation keeps a persistent retry action after a write failure, including partial creation. Retrying preserves existing files and writes the missing starter files; completion produces one success notification. Popup tours are retired. Folder opening guidance, contextual help and keyboard help remain. Returning from a concept's full reading view keeps that concept selected on the map. Returning through primary navigation restores the selected map concept and Concepts search for the same opened folder, in memory for this session. Ordinary unsent chat text survives screen changes in memory for the same opened folder; restoring it never sends a request.

Before a vault is connected, the installed app keeps Library, Planning, Agents and Briefing reachable and offers a folder chooser above the rail. A folder containing only wiki pages still opens in Library; its loaded-folder navigation remains based on its contents.

Library service setup is app-only: Atlas confirms folder and keychain saves before activation. A browser offers the app or Add files without collecting service tokens. Local setup does not verify service access. Library check history lists executed checks first; recorded sleep gaps are available through an explicit display control.

Planning reads a selected project's Markdown and bounded PNG/JPEG images in place in the macOS app. It keeps originals unchanged, refreshes the observed list, and offers an explicit return after opening source history or the ontology map. The app verifies the opened folder's identity after its descriptor is acquired; it cannot detect replacement before that point, other names or open descriptors sharing file bytes, or secrets inside documents. Browser and non-macOS desktop folder access, WebP and AVIF preview remain unavailable pending separate verification.

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

A project's source-path repair opens the affected concept and recorded relative path; stale or missing targets require remeasurement.

Project checks distinguish a document changed since its last meaning review from malformed input. They ask for review and explicit re-finalization; supported code paths and saved changes do not accept the meaning. Analysis filters capabilities by changed, missing or unchecked source evidence while keeping the selected claim open.

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. In the macOS app, documents and cited files can be dated in their respective bound Git repositories; missing access or history stays unknown, and a folder chosen for reading must match the existing connection. Analysis

Local-first

The installed app's Briefing prototype opens a chosen Git repository without requiring an ontology. Pull requests, commits and files have separate reading views. An explicit public GitHub read lists PRs updated in the selected local dates, including open and closed work; a moving, paginated list may be incomplete. Each PR original is attributed and remains inspectable. Commit-only summaries use a local model, while the separately labelled earlier combined briefing retains matched PR descriptions and earlier results. Private PR access and in-app ACP explanations are not yet available in the PR inventory. Failed reads retain the session's earlier results. Inspect individual commit messages and bounded, endpoint-based file comparisons inside Atlas. Author records and optional ontology grouping do not establish verified behavior changes. Change briefing

• 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 installpnpm devpnpm checks:changed -- --run

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

Pre-push checks the commit being pushed and runs affected lint, unit and Node tests in parallel with the relevant cheap checks. CI owns browser, full contract and dependency-graph verification. Test-only edits to CI tooling run their regressions without starting unrelated product suites; changes to the planner implementation still require exhaustive CI.

License

MIT. Third-party notices are in NOTICE.md, and the full license texts in public/third-party-licenses.txt. The pixel mascot and its sources are described in Brand.