a-ratz/atlas

> **Grow a knowledge vault by talking to your agents. Read it like a book.**
Atlas is a local web app over a folder of plain Markdown. You ask a question in
its chat; your agent (Claude Code, Codex or any other harness) researches it,
lands a capture, distills it into insights and links them into maps, while you
read along in the browser. Projects get one shared memory that every agent
loads, and Atlas keeps the page honest: every claim shows how far to trust it
and where it came from. The files are the truth, git is the history, and there
is no account. Atlas needs no database; search by meaning uses an optional
QMD index (recommended), which is built from the
files and can be rebuilt any time.
**▶ Try the live demo**: the demo vault in your browser, nothing
to install. No AI agent is connected there; the chat replays a recorded session, including one
distill you can start yourself.
**🎲 Follow a guided run**: one real session in thirteen steps, from an empty
vault through research, an idea and a spec to a project that builds a small browser roguelike.
Play the game it built.
**New since 0.6:**
- 💡 **Ideas:** write an idea down, or let your agent generate candidates from what the vault knows and keep the survivors. A spec works one out, and a project starts from the spec.
- 🔎 **Search by meaning:** QMD indexes the vault in five collections and stays fresh after every commit.
- 🗂️ **Cards that grow from research:** distilling writes a minimal card for each person and organization the insights rest on; **Expand cards** completes them.
- 📚 **Distilling checks the primary sources:** quotes, figures and attributions come from the paper or the docs, not from the research summary. It also files the few open questions that would change a claim.
Contents
- Quick start
- What you get: Home, the reader, talking to your agents, tours, the constellation, ideas, projects, people, small things
- How it works
- Your agent's side
- Demo vault
- How Atlas compares
- Status and roadmap
- This repository
---
Quick start
This installs one global skill, atlas, for every agent harness on the machine
(skills CLI).
Then say **"start atlas"** in Claude Code, Codex or any other harness. The first
time, the skill asks where Atlas should live (default ~/atlas), installs it
there and offers the demo vault. Open
**http://localhost:8765** and type what you are curious about, or / for
commands.
The engine needs uv, which brings Python and the
packages along; the agent installs it after asking if it is missing. Optional:
git for history and the feed, QMD for semantic
search, Tailscale for your phone.
Home with the demo vault: two agents listening, the week's metabolism, four things that need you, and a tour waiting.
---
What you get
Home
What happened while you were away, in one paragraph read from git, then the
agents on shift with their state and last answer.
- **Metabolism:** captures → insights → maps, and sketches → specs, with
seven-day sparklines of what arrived.
- **Needs you:** captures waiting to distill, proposed decisions, due revisits,
open questions, your own notes. Snooze a row until tomorrow, next week or next
month; it comes back early when what it counts changes.
- **What changed:** the git log with the agent behind each commit (Atlas-Agent
trailer); three or more commits in a row by the same hand fold into one row.
The reader
- **How far to trust it:** a meter over the note's status (speculative →
working → proven), whether it traces to a source, which map holds it, who
changed it last.
- **Provenance:** the chain from the source through the capture to this note.
- **Hover a link** to see where it goes; the map's previous and next note sit in
the header; a small graph shows the neighbourhood.
- **Your move:** buttons that fit the kind of note (an insight: find
connections, challenge it; a capture: distill it), plus keep, let go or leave a
note. Select any passage to ask your agent about it or challenge it.
Talking to your agents