Ontology Atlas

Một thư mục Markdown chứa ontology codebase đã được rà soát và một wiki có trích dẫn. 38 công cụ có kiểu dữ liệu, chỉ hoạt động cục bộ, mỗi lần ghi là một Git diff.

Tài liệu

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 map of this repository's own ontology with the Ontology Atlas project selected: its domains and capabilities laid out around it, a concept list on the left, and the project record with its code-evidence state on the right

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.

See it

Map, Neural view: the ontology drawn as a volume of lit clusters with one capability selected, and a panel naming what it depends on and what uses it
Map · Neural — the same concepts as a volume you can turn; select one to see what it depends on and what uses it.
Projects: one project's description, its domains as bars sized by the concepts they hold, and the capabilities inside the selected domain
Projects — what a project is for, how it divides into domains, and what each domain holds.
Library: wiki pages on the left with whether each still matches its source, a search box in the middle, and the sources to read first
Library — documents in, cited wiki pages out; find a passage, then check it in the source.
Planning: a project folder's Markdown files listed on the left, one document open on the right
Planning — read a project folder's Markdown in place, without copying it.
Changes: one day of merged work with its count, the hours it was merged, and the changes grouped by scope
Changes — what was merged in a period, counted and grouped, with the pull requests, commits and files behind it.
Git: the commit history on the left, and the concept one commit changed with its relations on the right
Git — each commit by the concepts it changed; an edited document shows up here before you commit it.
Harness: the files an agent reads, the rules that stop it before it acts and the checks that run afterwards, with one instruction file open
Harness — what an agent reads in your repository, what stops it before it acts, and what checks its work.
Automations: one scheduled document check with its cadence and last result, and the history of its runs
Automations — scheduled checks, and what each run found.

New in v2.0: Neural, a view of the map drawn as a volume you can turn, beside a 3D tree; Harness Setup, which lists what an agent reads, what stops it and what checks its work; a digest of merged work at the top of Changes; and the run history of every schedule in Automations. Analysis is no longer a separate destination. See the releases.

A few things worth knowing before you start:

  • The map shows declared relationships, not proof of runtime impact. It has five views: Flat, Hex, Domain structure, a 3D tree and Neural. Map
  • An empty folder offers its start actions, and a failed start can be retried without overwriting files. Popup tours are retired. First run
  • Library setup and checks need the app; a browser offers the app or adding files. Library
  • Planning is read-only and works in the macOS app on a folder you choose; it shows Markdown and PNG/JPEG images. Planning
  • Git's send-only action does not commit new file changes; it asks you to review a stale folder or branch again. Pull can change files across the repository. Git
  • Changes opens a Git repository you choose in the app, with or without an ontology. Reading public GitHub pull requests is a separate, explicit step and its list may be incomplete; private pull requests are not read. Change briefing
  • A project document edited since its last meaning review asks for review and explicit re-finalization; saving a change or matching a code path does not accept its meaning. MCP server
  • In the app's chat, each agent write waits for your permission. Codex starts read-only, and its locally configured permission profiles are not offered because their approval behaviour is not disclosed. Agents · Features
  • Before a folder is connected, the app keeps Library, Planning, Agents and Changes reachable. Features

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 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

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 covers choosing checks, CI internals and lane budgets.

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.

Repository commands
CommandWhat it answers
node scripts/ci/run-playwright-ci.mjs --helpBrowser shard options, without discovering or running tests; unknown options fail before execution
pnpm agents:checkEach harness's instruction files are valid; Codex and Claude files need not match
pnpm brand:spritesRebuild Moru sprites, 74 animation exports, 16 poses and compass sizes from retained project sources; inspect assets/brand/moru/preview.html
pnpm brief:new -- --slug=<slug> --owns=<path,...>A delegation brief with the port, scratch, checks and merge lines filled in
pnpm build:staticReuse out/ only for matching build inputs; fail without a reuse stamp if inputs change during the build
pnpm bundle:plan · pnpm bundle:prunePlan merging several branches as one, then prune the branches main contains (/merge)
pnpm checks:changedWhich gates this change needs
pnpm conflicts:scanWhich open pull requests change the same files as this branch, and whether a trial merge conflicts
pnpm decisions:find <terms> · pnpm decisions:checkThe decision to cite or overturn, and whether this change owes one
pnpm design:tokens -- [--prefix=<name>]The current token ramps, resolved from app/styles
pnpm doc:new -- --type=<kind> --area=<area> --slug=<slug>A new living document from its template in docs/.templates/
pnpm docs:checkDocs gates, including pnpm docs:language, pnpm source:language, pnpm changelog:check, pnpm dev-checks:check, pnpm docs:meta
pnpm docs:meta · pnpm doc:history -- <path>Every living document's kind, status and area; one document's commits across moves
pnpm docs:moveMoves the documents in docs/.moved.json and rewrites references (-- --check only reports)
pnpm download:repo-factsRecords this repository's star and fork counts, with the day read, for the download page's open-source section
pnpm e2e:durations -- <timings dir>Rebalances the browser shards from downloaded playwright-timings-* reports
pnpm e2e:sleeps:checkRefuses a new fixed waitForTimeout without a // measurement window: note
pnpm gates:yield -- --runs=200Which CI checks ever failed, per run, from the lane reports CI uploads
pnpm gateway:capture -- --base-url=<static export>Re-shoots the app screens in public/gateway/, in Korean and English; --only=map,neural re-shoots this README's two map pictures
pnpm harness:tokens -- --since=<date>Where Claude Code tokens went per agent type, from local transcripts, and which runs broke the compaction window or turn caps (budget)
pnpm knipDead files, exports and types
pnpm licenses:check · pnpm notice:build · pnpm notice:checkShipped packages are on the license allow-list, and NOTICE.md is current (rules)
pnpm messages:build · pnpm messages:check · pnpm messages:adoptCompose messages/<locale>.json from one file per namespace, prove it current, and carry an old branch's edits
pnpm messages:coverage -- --locale <code>Checks one locale's strings against en: arguments, plurals, script, keep-terms and typography
pnpm perf:mcp:memory · pnpm perf:mcp:memory:checkWhether the MCP server releases memory across repeated calls; about a minute
pnpm pr:ci <n>Fire CI on a draft now
pnpm pr:land --plan <n...> · pnpm pr:land --conductDry-run a merge, or merge queued pull requests until the queue is empty
pnpm pr:land <n> · pnpm pr:queueQueue a pull request to merge (green ones merge together behind one CI run), and show the queue
pnpm review:facts -- --base=<ref>The mechanical facts a reviewer would otherwise count by hand: line growth, 800-line files, export and dependency changes, untouched sibling tests, security paths
pnpm seo:checkAfter pnpm build: every sitemap URL in out/ canonicalizes to itself, / and each locale root point at /{locale}/download/, and titles and descriptions are unique per locale
pnpm typecheckTypes across every file, with Next's generated route and page types
pnpm ui:audit -- --url=<base> --route=<path> [--setup=<module.mjs>]Prepare an interactive state with an optional local module, then measure rendered facts per width: horizontal overflow, occluded or unreachable controls, small touch targets, off-ramp type/radius/shadow values, low contrast, unequal repeated sets, scroll-end reserve
pnpm ui:look -- --route=<path> [--vault=fixture|sample|<dir>] [--widths=1440] [--audit]Builds and serves the static export on a free port (or uses --url), opens each route with a vault attached, and prints one screenshot path per route and width

Use --scope=<selector> to audit one visible modal or region. The selector must match exactly one visible element; the report includes its measured element count.

Moru

Moru is Atlas's pixel seal companion; the compass is the app identity. The repository includes 74 motions, 16 poses and their sources: 58 drawn motions and 16 scenes composed from them. Open the local motion studio to play, pause and inspect every frame.

Moru greeting Moru reading source Moru coding on a laptop Moru balancing a star Moru offering a heart Moru dancing Moru playing with a pup

Where Moru appears. At folder entry Moru greets you, holds out a small folder and waits; once a folder starts opening, play gives way to the waiting view. The download page has its own welcome. Reading a source, waiting for your permission and celebrating a finished check appear only when the app has observed that state, so Moru never shows progress nobody confirmed.

Petting. Press Moru for one short response. The first is gentle, the second reveals a playful one, and after that Moru works through everything it knows while avoiding the last two: 14 responses at folder entry, 18 on the download welcome. A small wordless bubble sometimes answers with a heart, a note or a sparkle, and a pup peeks out once in a long idle.

Staying out of the way. Moru moves only while airborne, and lands before it waits under your pointer. While work is pending it stays quiet and in place. Pause and resume live in Moru's menu (right-click or Shift+F10), with no playback button beside the character, and reduced motion answers with a still expression.

Moru's 16 poses
All 58 drawn motions

Waiting

Moru blinking while it waits Moru wiggling its tail Moru dozing Moru doing a little hop Moru tilting its head curiously Moru stretching Moru coming back from a rest

Greeting

Moru greeting Moru bowing softly Moru tipping a tiny hat Moru offering a flipper five Moru smiling shyly

At work

Moru opening a folder Moru peeking into a folder Moru reading source Moru searching Moru following a link Moru comparing two things Moru reviewing a proposal Moru waiting for a person Moru unsure Moru stopping Moru trying again Moru saving Moru refreshing Moru connecting Moru with a reply ready Moru finding nothing Moru coding on a laptop Moru celebrating observed completion

Feelings

Moru thinking Moru pondering Moru sending little hearts Moru giggling Moru frowning thoughtfully Moru with a tiny temper Moru blushing with a tiny temper Moru offering a heart

Play

Moru singing Moru dancing Moru chorus Moru dancing with its flippers Moru doing a somersault Moru playing with a fishing-line toy Moru and a fish Moru revealing a magic fish Moru playing peekaboo Moru chasing a bubble Moru balancing a star Moru sneezing sparkles Moru playing ball with a friend Moru cuddling three pups Moru playing with a pup

Scenes

Moru with an umbrella in the rain Moru watching snowflakes Moru in a little breeze Moru watching a floating ontology model Moru dancing with a floating ontology

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.