Atlas — Universal Project Map for Emacs

What is Atlas?

Atlas is a universal, extensible project map for Emacs. It inventories files, extracts symbols (functions, classes, variables, …), connects them with typed edges (import/require/provide/call/ref/…), and keeps everything in a deterministic store you can query, visualize, and export for LLM work.

• Clean core + thin ports: pure data modeling and transforms; effects live at the edges.
• Deterministic outputs: stable IDs and ordering for reproducible diffs and CI artifacts.
• Extensible enrichment: additional facts (entrypoints, roles, types, metrics) with provenance, confidence, and TTLs.
• LLM-first exports: a compact textual Atlas Prompt Map (APM v2) and an interoperable “LLM pack”.

Atlas works entirely locally and offline by default. Your code never leaves the machine unless you explicitly export it.

Highlights

• Files, symbols, edges, summaries, facts — normalized IR with stable IDs.
• Persistent store under .context/atlas/v1/ inside each project.
• In-memory indexes and lexical search with an inverted index.
• A simple context planner for building token-budgeted context groups.
• Minimal UI: progress modeline and an Entity Tree buffer (text-only, TTY-friendly).
• Exports: Graph (DOT/Mermaid), APM v2 (text), and an LLM pack (S-exp/JSON).

Status

• Emacs: 27.1+ (tested with recent Emacs; Emacs 29+ recommended for package-vc workflows).
• Providers: Built-in Elisp provider (L0–L2). Treesitter/LSP/external providers are specified and will incrementally land.

Why Atlas?

Large or multi-language repos need an always-fresh map you can search, traverse, and export — without running heavyweight IDEs or proprietary servers.

• Deterministic store: Repeatable builds and diffable artifacts.
• Extensible: Facts let you add value (entrypoints, types, roles) without breaking schemas.
• LLM-oriented: Export human-readable APM and compact “LLM packs” under token budgets.
• Emacs-first: Snappy, text-only UI that works everywhere (even over SSH).

Installation (use-package)

Below are two practical ways to load Atlas via use-package. Pick one.

Option A: Local checkout (recommended for development)

• Clone the repo and point :load-path at the lisp directory. Load autoloads only; enable UI if you like.

(use-package atlas
  :load-path "/path/to/atlas/lisp"
  :commands (atlas-open atlas-close
             atlas-index atlas-reindex-changed atlas-stats
             atlas-query-command
             atlas-entity-tree atlas-entities
             atlas-explore
             atlas-progress-mode
             atlas-watch-mode atlas-watch-add-root atlas-watch-remove-root atlas-watch-list-roots
             atlas-graph-export-command atlas-export-llm-command atlas-export-apm-v2-command atlas-export-llm-pack-command
             atlas-log-open atlas-log-clear)
  :init
  ;; Load autoload stubs; does not pull heavy modules until called.
  (require 'atlas-autoloads)
  ;; Optional: turn on modeline progress globally
  ;; (atlas-progress-mode 1)
  )

• Convenience setup (optional):
  • You can load atlas-setup.el to add the lisp path and autoloads in one go.
  • Then enable defaults with atlas-setup-enable.

(load "/path/to/atlas/lisp/atlas-setup.el")
;; Turn on progress UI and optionally start watching a root
;; (atlas-setup-enable)                      ; UI only
;; (atlas-setup-enable "/path/to/project/")  ; UI + watch this project

Option B: Emacs 29+ with package-vc (pull directly from Git)

• If your use-package supports :vc (Emacs 29+), you can source Atlas directly.

(use-package atlas
  :vc (:url "https://github.com/11111000000/atlas.git"
       :rev :newest
       :lisp-dir "lisp")
  :commands (atlas-index atlas-entity-tree atlas-progress-mode)
  :init
  (require 'atlas-autoloads))

• If your setup uses straight.el/quelpa/elpa mirrors, adapt accordingly by pointing to the lisp/ dir and requiring atlas-autoloads.

Quickstart

Index your current project

• Open a project (Atlas will detect root via project.el/VC/.context):
  • M-x atlas-index
  • This builds the store under <root>/.context/atlas/v1/ and in-memory indexes.

Explore entities

• Open the Entity Tree (text-only UI):
  • M-x atlas-entity-tree
  • Keys (inside the tree buffer):
    • g: refresh
    • RET/o: open item
    • v: peek (side window preview)
    • d: toggle inline docstring
    • TAB: fold/unfold at heading
    • n/j and p/k: next/previous heading
    • s: search view
    • E: edges view
    • P: plan view
    • i: toggle follow-mode (auto-peek as you move)
    • a: actions menu (uses transient if available)

Run a quick search

• M-x atlas-query-command — enter a query, get top-k matches.

Export a graph

• M-x atlas-graph-export-command — choose selector (file path, symbol id, or feature:NAME), depth, and output DOT/Mermaid.

Export for LLMs

• APM v2 (text): M-x atlas-export-apm-v2-command
• LLM pack (S-exp): M-x atlas-export-llm-pack-command
• LLM pack (JSON): M-x atlas-export-llm-command

See progress in the modeline

• M-x atlas-progress-mode — shows “Atlas: f=X s=Y e=Z” while indexing.

Watch for changes (auto re-index changed files)

• M-x atlas-watch-mode (global) — watches the current directory.
• Or add/remove roots:
  • M-x atlas-watch-add-root
  • M-x atlas-watch-remove-root
  • M-x atlas-watch-list-roots

Concepts

Core IR

• File: inventory item.
• Symbol: top-level program entity (function, class, var, …) with a stable :id.
• Edge: typed relation between entities (require/provide/import/export/call/ref/…).
• Summary: text snippet bound to a file or symbol (optional).
• Fact: enrichment assertion with provenance and confidence (optional).

Stable IDs

• Format: LANG:REL#NAME@BEG-END/KIND
• Deterministic within a file as long as source spans don’t change.

Store layout (on disk)

• <root>/.context/atlas/v1/
• files.sexp, symbols.sexp, edges.sexp, summaries.sexp (optional), facts.sexp (optional), meta.sexp
• Compression: .sexp or .sexp.gz (transparent via jka-compr).

In-memory model and search

• Hash indexes for files/symbols/edges, plus an inverted index for lexical search.
• Tokenization:
  • Default: ASCII [a-z0-9_]+ (lowercased).
  • Optional: Unicode-aware (NFKC + :word:+) with optional CamelCase splitting.

Events and UI

• Topics: :atlas-index-start, :atlas-index-progress, :atlas-index-done, :atlas-index-error.
• UI throttles to avoid churn; handlers are exception-safe.

Security and privacy

• Offline by default; no code leaves your machine unless you export it yourself.
• Store and logs remain local to the project.

Usage patterns

Typical workflow

• Index once (full), then run changed-only re-indexes automatically via watch mode or manually on demand.
• Search and jump by name/sig/file tokens; plan a context with 1-hop expansion.
• Export a compact prompt map or a machine-friendly LLM pack for downstream tools.

Commands you’ll likely use daily

• atlas-index — full or changed-only depending on TTL and change detection.
• atlas-entity-tree — quick, text-only navigator of features/files/symbols.
• atlas-query-command — quick lexical search for symbols.
• atlas-progress-mode — light modeline indicator for long runs.

Exports you can rely on

• Graph (DOT/Mermaid): share a small subgraph in docs/PRs.
• APM v2 (text): compact, human-readable lines optimized for LLM prompts.
• LLM pack (S-exp/JSON): interoperable bundle for external tooling.

Configuration

Indexing and store

• atlas-index-ttl — seconds before a run is considered stale (default: 600).
• atlas-exclude-dirs — directory regexps to skip (e.g., node_modules, build, vendor, .context).
• atlas-max-file-size — deep-parse cap; large files degrade gracefully.
• atlas-hash-content — compute content hashes for small files to improve change detection.
• atlas-store-compressed — write .sexp.gz to shrink the store.
• atlas-segment-threshold — future-facing segmentation hint (kept in meta opts).

Tokenization

• atlas-unicode-tokens — enable Unicode-aware tokenization (NFKC + :word:+).
• atlas-tokenize-camelcase — add CamelCase sub-tokens (keeps original token too).

Planner

• atlas-plan-default-budget — default token budget.
• atlas-plan-model — plan “brief” vs “rich” (extensible).

Elisp provider knobs

• atlas-elisp-use-elisp-refs — optional call/ref enrichment (not enabled by default).
• atlas-elisp-refs-max-size — size cap for elisp-refs.

UI and watch

• atlas-ui-progress-throttle — mode-line update throttle (seconds).
• atlas-entity-tree-* — view defaults, icons, docstring limits, graph depth, search k.
• atlas-watch-file-regexp — which files to watch (default “\.el\’”).

Provider model

Built-in today

• Elisp provider: L0 inventory, L1 symbols (defun/defmacro/defvar/defcustom/defconst), L2 require/provide edges; adds Commentary as file summaries.

Extending beyond Elisp

• Treesitter providers (generic) and LSP/CLI providers (advanced) are specified:
  • Precise imports/exports/types; limited call/ref graphs under caps.
  • Deterministic batches with sorted edges and stable symbol ordering.
  • Clear :source for provenance (treesit|lsp|cli|heuristic).

Exports

Graph (DOT/Mermaid)

• Input: selector (file REL | symbol-id | feature:NAME | list), depth, optional edge-type filter.
• Output: stable node/edge ordering; labels escaped.
• Commands:
  • atlas-graph-export-command (interactive)
  • atlas-graph (programmatic API)

APM v2 (text)

• Sections: Project header, Modules overview, API surface, Edges, Entrypoints, Enrichment facts, Notes/TODOs.
• Deterministic lines suitable for prompts and diffs.
• Command:
  • atlas-export-apm-v2-command

LLM pack (S-exp/JSON)

• Brief bundle: query, top hits, files/spans, small graph, estimated tokens, rationale.
• Commands:
  • atlas-export-llm-pack-command (S-exp)
  • atlas-export-llm-command (JSON)

Tips and recipes

Keep it fast

• Exclude vendor/build dirs; enable atlas-hash-content for small files.
• Use watch mode to continuously pick up changes; debounce and TTL keep churn low.

Build a context quickly

• M-x atlas-entity-tree → P (plan view) → enter a query → get budgeted spans with 1-hop deps via require→provide.

Share a dependency slice

• atlas-graph-export-command → choose a feature file and depth=1 → attach DOT/Mermaid to PRs or docs.

Troubleshooting

“No providers registered”

• The Elisp provider registers automatically when needed. If you see this once (e.g., minimal setups), explicitly require it:
  • (require ‘atlas-source-elisp)

“Nothing changed”

• Atlas tracks mtime/size (and hash if enabled). If a run reports up-to-date but you expect changes, check:
  • Project root detection (M-x atlas-open to verify)
  • Exclude patterns (atlas-exclude-dirs)
  • File size caps (atlas-max-file-size)

“Entity Tree is empty or stale”

• Press g to refresh; enable auto-refresh on index events (default).
• Ensure you indexed first: M-x atlas-index.

Development

Local dev loop

• Add lisp/ to load-path and require atlas-autoloads (or load atlas-setup.el).
• Enable atlas-log for visibility (defaults to enabled).
• Inspect logs: M-x atlas-log-open.

Contributing

• Start with the v1 SPEC under spec/v1/ for schemas, storage, providers, enrichment, and exports.
• Keep outputs deterministic and schema types stable.
• Prefer additive changes (new optional fields/predicates); document migrations if needed.

References

SPEC (v1)

• IR: spec/v1/10-ir/*
• Storage: spec/v1/20-storage/*
• Model: spec/v1/30-model/*
• Providers: spec/v1/40-providers/*
• Enrichment: spec/v1/50-enrichment/*
• Exports: spec/v1/60-exports/*
• Conformance: spec/v1/90-conformance/*

Example fixtures

• Minimal and multi-language fixtures in spec/v1/examples/* illustrate store contents, edges, facts, and APM text.

License

• See the LICENSE file in the repository.

FAQ

Does Atlas send my code anywhere?

• No. Atlas is offline by default. Only you can export artifacts, and they remain local unless you share them.

Can I use it over SSH/TTY?

• Yes. The UI is text-only and works in TTY. No icon fonts are required (optional if available).

Will there be non-Elisp providers?

• Yes. Treesitter, LSP, and external CLI providers are defined by the SPEC and will land incrementally. Consumers must tolerate unknown edge types and virtual prefixes by design.

How stable is the format?

• v1 requires type stability for existing keys; additions are optional. Non-additive changes would bump the schema with documented migrations.