Atlas Is Source Control for Coding Agents, and Its Best Idea Lives in a Gitignored Folder
A close read of agent-session checkpoints, patch-id reconciliation, and the one design decision that decides how much the whole thing is worth to you.
Atlas makes a promise in its README that most tools would bury: nothing here is locked in. Notes are markdown. Canvases are JSON. Sessions are JSONL. The editor is a file on disk. Close Atlas, open vim, keep working.
Then comes the exception, stated plainly in the same paragraph. The checkpoint record, the thing that links an agent session to the commit it produced, is SQLite, and it lives in the project's gitignored .atlas/ directory. The reason given is honest: it is queried, not read.
That exception is the product. Everything else Atlas does, other tools do too. The checkpoint is the new idea, and it is the only thing in the box that will not travel with your repository.
The problem it names, which is real
The framing in the README is the sharpest statement of this problem I have read: agents now write a large share of the code and keep none of the reasoning behind it. The prompt that produced a change, the tool calls it made, the approach it tried first and abandoned, all of it lives in a scrollback buffer until the buffer scrolls.
What survives is a commit message. Written by a model. Summarizing a diff.
Anyone who has run coding agents for more than a month knows the specific ache here. You open a file, find a function structured in a way that makes no sense, and you have exactly two options: git blame, which returns a model-authored one-liner, or archaeology through your own memory. The thing you want, the transcript where the agent explained that it tried the obvious approach first and the obvious approach deadlocked, is gone.
Atlas records it. Every agent session is written to .atlas/sessions.db locally: prompts, messages, tool calls, the files each touched, and the patches applied. When you commit, the commit is linked back to the session that produced it.
The engineering that makes it credible
Three implementation choices tell you this was built by someone who has thought about failure modes, and they are the reason I take the project seriously despite its alpha tag.
Commits are observed, not intercepted. Atlas does not wrap your git client or install a hook you have to remember. A commit made from a terminal, from another editor, or while Atlas is closed entirely still finds its session. This is the right call and it is the harder one. Interception gives you cleaner data and breaks the first time someone commits from a context you did not anticipate, which is a guarantee, not a risk.
Links survive history rewrites through patch-id reconciliation. Amend a commit and the link re-points. Rebase and it follows. Most provenance systems key on commit SHA, which means the first interactive rebase silently orphans the entire record. Atlas reconciles on patch-id instead, which is the identity that actually survives the operations people perform on history.
When a squash makes a link genuinely ambiguous, it orphans instead of guessing. This is the line that made me trust the rest. A provenance record that guesses is worse than no record, because a confident wrong answer about why code exists will be believed. Choosing to lose the link rather than fabricate one is a design value, and it is rarer than it should be.
There is a fourth choice worth naming for a different reason. Secrets are scrubbed before anything is persisted, not before upload. A local database of every prompt and tool call is itself a disclosure surface, and the README treats it that way. Backfilling existing Claude Code history via transcript import means the record can start before you installed the tool, which is the right default and also means a pile of old transcripts lands in that database at once.
The part that actually distinguishes it
The multi-agent story is stronger than the source-control story, and I suspect it is why the repo is moving.
Atlas runs Claude Code and Codex as external subprocesses over the Agent Client Protocol, and can spawn anything in the ACP registry: Cursor, OpenCode, Kilo Code and others, pulling each one's official binary automatically. Its own native agent runs in-process on a hard fork of the Codex engine. They all go through one send path.
Which means this is possible: a decision Claude Code made shows up in Codex's next prompt. Neither agent can read the other's history on its own. Atlas folds knowledge notes, your CLAUDE.md, your AGENTS.md, Claude Code's memory files and Codex's history into one index, embeds your message on-device, and matches against it every turn.
If you run more than one agent, you already know the cost this targets. Switching agents mid-task means re-explaining the task, and you pay it every time. The @ mention design is also better than the obvious version: @-ing a folder resolves to a pointer the agent reads on demand rather than pasting the contents, so one mention of a 5,000-line file does not occupy your context window for the rest of the session.
Back to the gitignored database
Here is my actual criticism, and it is not a small one.
The checkpoint record is the reason to use Atlas. It is also stored in SQLite, in .atlas/, which is gitignored. Work through what that means in a team.
Your colleague clones the repo. They get the code, the markdown notes in .atlas/knowledge/, your CLAUDE.md, all the portable artifacts. They do not get the checkpoints, because checkpoints are not in the repository. So the question "why does this function look like this" is answerable by exactly one person on the team: whoever ran the agent, on the machine they ran it on.
Which is roughly the situation before Atlas existed, except now the answer exists and is unreachable.
The README has an answer: sign in, create an organisation, sync across devices and teammates. That is a reasonable product decision and I am not going to pretend to be scandalized by it. But it means the local-first version of Atlas solves a single-developer problem, and the team version, the one where provenance does the most good, is the version that requires an account and sends your session history somewhere.
I want to be fair about the technical reasoning, because it is sound. A queryable index does not belong in git. Committing a binary SQLite file would produce merge conflicts on every pull and bloat the repository. Nobody should ship that.
But there is a middle path that does not appear to exist yet, and it is the thing I would want most: an exportable, mergeable checkpoint artifact. Append-only JSONL keyed by patch-id, committed alongside the code, with the SQLite database as a derived local index rebuilt from it. That would make provenance a property of the repository rather than a property of one laptop, and it would keep the no-lock-in promise whole. Sessions are already JSONL. The pieces are there.
Until something like that exists, be clear-eyed about what you are adopting: excellent single-developer provenance, with team provenance available as a hosted feature.
Put this into practice
The lowest-friction way in is not to change how you work at all.
Install it and keep your existing subscription. It is a .dmg for macOS or an .msi for Windows from the releases page. Atlas runs Claude Code and Codex as they are, over ACP, using the subscription you already pay for. The README is explicit that running your existing Claude Code through Atlas gets the session more context with no change to how you work. If you want the Claude Code agent specifically, install the claude CLI and put it on your PATH; the native agent needs no external CLI.
Run the transcript import first. It backfills existing Claude Code history, so your checkpoint record starts before today rather than from an empty database. Do this before you decide whether the tool is useful, because an empty provenance store is not a fair test of a provenance tool.
Then do the only evaluation that matters. Work normally for two weeks. Then find a commit from week one that you no longer remember, select its checkpoint, and chat with it. The README's pitch is that you do not have to read the raw transcript to get the context back, because the checkpoint answers from what actually happened in that session. Either that returns something you genuinely could not have reconstructed, or it does not. That is the whole product test, and nothing on the feature list substitutes for running it.
Decide the team question deliberately, not by drift. If you are evaluating this for more than yourself, work out now whether you are willing to sync sessions to an organisation. If you are not, plan on Atlas as personal tooling and do not build any team process that assumes checkpoints are shared.
Turn off the telemetry if you want it off. Anonymous usage analytics are on by default. The README says coarse metadata only, never code or prompts, and points at TELEMETRY.md for what is collected and how to disable it. It is disclosed clearly, which I appreciate, and it is still a default worth choosing rather than inheriting.
Honest limitations
The newest release is tagged alpha-0.3.3. Not a metaphor, an actual alpha. Worth noting how hard it is to pin even its date: the repository's releases page shows it published on September 19, while the releases atom feed reports September 22, which normally means the release was edited after publication. The project is Apache-2.0 with a real copyright line naming Adib Mohsin, and roughly 6,000 stars on a cache-busted shields read, which tells you about attention rather than maturity.
Platform support is macOS 13+ and Windows 10+ on x64. The README states Linux builds from the same Tauri codebase and is untested. If you develop on Linux, that is not a caveat, it is a blocker.
The ACP registry breadth is the feature I would trust least at this stage. Claude Code and Codex are described as the most-used, most-tested path, and the README carries an explicit note that QA on the long tail of registry agents is ongoing. Read "can spawn any agent in the ACP registry" as a capability that exists rather than a capability that is reliable.
Adding a second source-control layer to a repository you already ship from is a real commitment. You will feel the cost of .atlas/ in your project before you feel the benefit of the checkpoints, because provenance has a warm-up period by definition. Its value is proportional to how much history it has, and on day one it has none.
And the load-bearing caveat: every benefit above assumes the checkpoint record stays on the machine that created it, or that you sign in. There is no third option today.
What to do with this
The category Atlas is staking out is going to exist whether or not this particular implementation wins. Once agents write a majority of the code, the session that produced a change is the primary source and the commit message is a summary of a summary. Git has no slot for the primary source. Something will fill it.
What I would watch for, in Atlas or in whatever follows it, is one specific feature: an exportable checkpoint format that lives in the repository. The tool that ships mergeable, code-adjacent agent provenance is the one that makes this a team practice rather than a personal habit, and right now nobody has shipped it.
If you run one agent on one machine, install it this week and run the two-week test. If you run a team, watch the issue tracker for the word "export" before you build anything on it.
Sources: pacifio/atlas README, read from the raw file on main, 2026-09-22; Atlas documentation; Agent Client Protocol. License, star count and release tag verified this run against the repository's LICENSE file, cache-busted shields.io, and the releases feed.
Medium metadata
- Title: Atlas Is Source Control for Coding Agents, and Its Best Idea Lives in a Gitignored Folder
- Subtitle: A close read of agent-session checkpoints, patch-id reconciliation, and the one design decision that decides how much the whole thing is worth to you.
- Tags: AI Agents, Developer Tools, Git, Claude Code, Open Source
- Canonical: fervorai.dev