README file from
GithubAI Session Atlas
Install from Obsidian Community Plugins · Русская версия
AI Session Atlas is an Obsidian plugin for macOS for people who work with Claude Code and Codex
every day. It indexes the session transcripts of both agents (~/.claude/projects and Codex's
~/.codex/sessions) into one searchable catalog, shows running sessions as live cards you can answer
from, counts tokens and cost, and runs Claude Code and Codex in terminal tabs inside Obsidian that
reopen the same session after a restart. Everything runs locally: the plugin starts a small Python
server on 127.0.0.1, and nothing is sent anywhere unless you turn on the optional AI features.

Features
-
Search. Full-text search over every Claude Code and Codex session: your prompts, the answers, shell commands and edited files. Filters by agent, project, category, topic and date. A session card shows the cost, edited files and an expandable Session feed with your prompts and the agent's replies, in the same format as Active. The latest 20 prompts load first; scroll up for earlier ones. As in Active, long messages use the feed's preview limits. The card has buttons to:
- Resume the session in an Obsidian terminal tab (
claude --resumeorcodex resume); - continue it in the other agent with Resume with…: a Claude Code session in Codex, a Codex session in Claude Code (see below);
- rename it (for Claude Code the name is also saved where
claude --resumeshows it); - delete it from the computer for good, after a confirmation that lists every file.
A copy made with Copy session (
claude --fork-sessionorcodex fork, also /branch or /fork in the agent) that keeps its source's name shows as "Name (2)", "(3)"…; its card links to the source ("Copy of …") and the source lists its copies ("Copies: …"). - Resume the session in an Obsidian terminal tab (
-
Active. Every running Claude Code session and every interactive Codex session as a card: what it is doing, what it said last, whether it waits for you. For sessions running in an AI Session Atlas terminal tab you can also:
- answer permission prompts and questions (for Codex: approvals, questions and choices, read from the tab's screen); a question with a preview per option shows the preview under the options, 👁 shows another option's, and a note can go with the answer; several Claude Code questions at once come as tabs, as in the terminal, and go together with "Send the answers";
- read and approve a Claude Code plan, or send it back with comments;
- type a reply (it can carry images), stop the agent, run slash commands.
A session that finished while you were away from its tab gets a dot before its title until you open the card or tab. "N new" marks the visible cards as seen. Detailed cards have four view modes. Conversation opens at the latest messages and loads earlier pages as you scroll up. Terminal lets you type into the running session in an Atlas tab and scroll through its output. Steps shows tools, commands and errors in order. Files shows which files the agent read or changed. Each card also shows the agent's task list or plan checklist. You can move a session from another terminal app into an Obsidian tab. The header shows each agent's 5-hour and weekly limits when known.
-
Statistics. Tokens, active time, cost at API prices and cache hit rate over a period, broken down by agent (Claude Code, Codex), model, category, topic, session, tool, skill and subagent, plus a weekly rhythm heatmap. Claude Code replies are priced at Anthropic API prices, Codex replies at OpenAI API prices. The cache tile also shows what rewriting the cache cost: replies that sent the context again after a pause or a context change. At 10% of the period's cost or more the tile is highlighted; ⓘ shows the causes and a panel lists the sessions that paid the most.
-
Updates at a glance. A short, visual “What’s new” summary once after an update. Reopen it from the command palette; automatic summaries can be turned off in settings.
-
Agent terminals. Ribbon buttons and commands open Claude Code or Codex in a terminal tab inside Obsidian. Each tab remembers the session it holds; after Obsidian restarts every agent tab brings its session back by itself, one at a time, without opening each tab. Closing a tab with a running agent asks for confirmation. A Claude Code session that runs in a background job of Claude Code (sent there with ← on an empty prompt or
/background, or opened withclaude attach) outlives its tab: the tab shows a server icon in the accent colour, and its close offers Close, keep running or Close and stop (claude stop, the conversation is kept). Such sessions without a tab are listed under Active → In the background, no tab: Bring back stops the background copy and continues the same conversation in an ordinary tab (the marked tab's menu offers it too), Stop ends it and keeps its history. While such a tab is open, its Active card shows the same server icon before the title, "· background" by the status, and Bring back too. A session that is replying asks first. Paths the agents print (~/…,/…,src/main.rs:12) are links: a click opens the file in its default app (a note of this vault in Obsidian, a folder in Finder), ⌘-click shows it in Finder, and the right-click menu can copy the path. -
Session groups. Agent tabs (and notes, including background tabs) go into named, coloured groups, as Chrome's tab groups: a chip before the group's tabs, a line of its colour under them, one click folds the group to its chip. Active shows each card's group and filters by it. See below.
-
Notifications. A notice when a session finishes its turn or waits for a decision, and a macOS notification when Obsidian is in the background. Notices stack, one per session; they hide after 10 s, 30 s or 1 min, or stay until you click or close them, and go by themselves once the session works again.
-
AI features, on by default and run only from a button, after a preview: topics and categories for sessions, a one-line summary of what was done, a session summary, and a session note for continuing the work in a new session. Hourly auto-classification is a separate switch, off by default.
-
File explorer clicks (off by default): left click opens a file in a new tab, middle click in the current one, and a file that is already open is focused instead of opened twice.
-
English and Russian interface.
Codex support
Search, Active, Statistics, terminal tabs, Copy session and deletion work for Codex sessions too. Checked with codex-cli 0.167.0. Differences from Claude Code:
- Sessions. The catalog reads Codex session files (rollouts) in
sessions/andarchived_sessions/of the Codex home. Codex's own thread titles are read from its state database (state_*.sqlite), opened read-only. Codex instructions, reasoning and tool output are not indexed.codex execruns count as automation, like Claude Code SDK runs. A subagent thread is part of the session that started it, as a Claude Code subagent is: Search finds its text there, Statistics count its replies and tokens there, and it is not listed by itself. A subagent thread whose parent session file is gone is listed on its own, as automation. - Rename saves the name in the catalog and asks Codex to rename the thread with its own command
(
thread/name/setthrough a short-livedcodex app-server, as/renamedoes), socodex resumeand Codex's own list show it too. Codex's session files are never written. If Codex cannot do it (not installed, too old), the name stays in the catalog and the page says why. - Copy session runs
codex fork <id>. Codex gives the copy its own id and keeps the source's history in the source's file, so Search finds the copy by its own turns. Codex names a thread by its first prompt, so a copy is numbered "Name (2)" only while Codex keeps the source's name on it. Subagent and review threads are not counted as copies. - Continue in a new session (a new session that starts from a session note) starts the source session's agent: a Codex session continues in Codex, with the same first prompt that names the session note file. Codex picks its own thread id when it starts, so each Codex launch writes its own session note file, and the catalog links the new thread to its source once a thread whose first prompt names that file is indexed.
- + Session in Active has an Agent choice (Claude Code or Codex; Claude Code by default, the last choice is remembered in this browser). Codex is offered only when it is turned on in Settings → AI Session Atlas → Agents.
- Terminal tabs follow the thread the tab's
codexhas open, also after/new,/resumeor/forkinside it, so after an Obsidian restart the tab comes back to the thread you were in. Codex keeps every thread it opened in the tab open: the newest one counts, then the one written last, so a thread switched back to with/resumecounts once you send it something. Codex gets no hook. - Folder in + Session is a text field: paste an absolute path, type
~/…, or the vault name and a path inside it, or pick a suggestion (folders your sessions ran in, then the real subfolders of what is typed; buttons for the vault root and home). Delete the tail to go up a level; ↑/↓ and Enter pick, Tab goes into the highlighted folder, Esc closes the list. A path that is not an existing folder is refused with the reason. - Active shows interactive
codexprocesses in a terminal, found withpsandlsof.codex execruns and the Codex app are not live cards; their sessions appear in Search. As on a Claude Code card, a Codex card shows the thread's active/goal, its running subagents (subagent session files of this thread written in the last 90 seconds), the commands it left running in the background (child processes ofcodexother than its MCP servers, matched by their exact command and arguments) and the messages waiting to be sent. A Codex started outside an Atlas tab runs its commands in its app-server daemon, so its card shows no background commands. The goal and messages queued throughcodex app-servercome from Codex'sgoals_1.sqliteandqueue_1.sqlite, opened read-only; messages queued in a terminal tab (Tab or Enter while Codex works) are read from the tab's screen. - Waiting for you. Codex writes no permission prompt into its files, so the plugin reads it from
the screen of its own terminal tab. For a Codex session in another terminal app, turn on
Settings → Agents → Codex: "waiting for you" outside tabs (off by default): it adds one hook to
Codex's
hooks.json, and the card shows the wait. Codex asks you to trust a new hook: open/hooksin Codex and allow it. Answer the prompt in that terminal, or move the session into a tab. Codex remembers that trust by the hook's place in the file, so turning the switch off removes the hook only while it is the last one; with your own hooks after it, it stays in place and does nothing. - Slash commands. "/" lists Codex's own commands, "$" the skills Codex itself offers, by its
names: the list Codex put into its newest session (nested skills such as
gstack/browse, its own.systemskills and plugin skills such asfigma:figma-useincluded); without one, the skills in$CODEX_HOME/skillsand~/.agents/skills./modelshows Codex's models from its own list (models_cache.json), then that model's reasoning efforts; Codex keeps the choice for this session only. The output of/statusand/mcpis shown on the card. - Statistics. A skill counts once a turn when you mention it with
$nameor when Codex reads itsSKILL.md(reading it in parts is one use; editing it is none), under the name Codex gives it. A subagent counts by its type (spawn_agent, "default" without one). A subagent started with its parent's context begins with a copy of the parent's turn; that copy counts only in the parent. - Limits. Codex's 5-hour and weekly limits come from Codex itself, as its
/statusshows them: while Codex cards are shown in Active, the server runscodex app-server, asks it once for the account's usage (account/rateLimits/read) and exits it, at most every 5 minutes. No thread is started and no model is called. When that fails (Codex not installed or not logged in), the numbers of Codex's last run are shown with their age ("3 h ago"); a window at 100% names its reset time. Claude Code limits need the Subscription limits switch. - Cost. Codex writes tokens but no cost. Statistics and live cards price Codex replies at OpenAI
API prices from a table built into the plugin; a model the table does not know shows no cost.
Prices can be fixed or added in
config.json(see Usage). - AI features work on Codex sessions too. They run through Claude Code when it is installed, and
through Codex (
codex exec) when only Codex is; Settings → AI features → Run through picks one. A request goes only to the agent its preview named: if the settings now point elsewhere, the page asks to open the preview again.
Resume with another agent
Resume with… on a Search card lists Claude Code and Codex. The session's own agent is the ordinary resume. The other agent gets a new session of its own, made from this conversation, and it opens in a terminal tab with that agent's ordinary resume. Checked with Claude Code 2.1.289 and codex-cli 0.167.0.
- What is copied: the conversation since its last context compaction, with the compaction summary: your prompts and the agent's replies word for word, and tool calls as short text lines (the command or the file, and the first 800 characters of the result). Thinking, reasoning and encrypted content are never copied.
- Title: the new session gets the source's title. If Codex cannot save it, Atlas shows a warning and lets you open the copy.
- Size: at most about 100,000 tokens, half of a 200,000-token context window. If the conversation is longer, the earliest messages are left out and the new session starts with a note saying so.
- The first message says that the conversation continues a Claude Code or Codex session, with its id and folder, and that the tool calls in it were made by the other agent.
- The source session is not changed. The new session has its own id and its own file:
~/.claude/projects/<folder>/<id>.jsonlfor Claude Code,~/.codex/sessions/YYYY/MM/DD/rollout-…jsonlfor Codex. A Codex session names the model provider set in~/.codex/config.toml(openaiif none). - In the catalog the new session is marked "from Claude Code" or "from Codex", and both cards link to each other. Its copied messages are not indexed or counted again: search and Statistics see them once, in the source session.
- An agent turned off in Settings → AI Session Atlas → Agents is shown disabled in the menu. Outside Obsidian (in a browser) the menu creates the session and shows the command to run.
Session groups
- Make a group: right-click a tab → Add to new group. The group editor opens: type a name, pick one of nine colours. Add to group puts another tab into an existing group; the tab moves next to the group's tabs. Remove from group takes it out. The same menu opens from the group label on an Active card (+ Group on a card without one).
- The chip: a click folds the group to its chip (with the number of tabs) or unfolds it; a right-click or Shift+F10 opens the editor: name, colour, a new Claude Code or Codex tab in the group, fold, Ungroup, Close group (asks once, then closes the group's tabs and ends their agents). A folded group never hides the tab in front: the nearest tab outside the group comes forward first.
- Dragging: a tab dropped onto a group's tab or its chip joins the group, even a group of one tab; a tab dropped onto a tab outside the group, or dragged away from it, leaves. Drag the chip to move the whole group, also between panes. Alt+Left/Right on the focused chip moves it by keyboard.
- Next/previous tab shortcuts skip collapsed groups. Going to a particular tab unfolds its group. Same-named groups remain separate in the Active filter; renaming keeps your selection.
- Groups are kept in the plugin's data and come back after Obsidian restarts. A group whose last tab closes is gone. Commands: Add tab to a new group, Remove tab from its group, Collapse or expand the tab's group (bindable to hotkeys).
Requirements
| macOS | 12 Monterey or newer |
| Obsidian | Desktop app, 1.8.7 or newer |
| Python | python3 3.8 or newer whose SQLite supports FTS5 with the trigram tokenizer. The system python3 comes with Xcode Command Line Tools |
| Agents | Claude Code installed and signed in. Codex is optional; checked with codex-cli 0.167.0 |
The plugin looks for python3 in this order: the path set in Settings → AI Session Atlas → Advanced → Custom
python3, /usr/bin/python3 (only when Command Line Tools are installed, so the plugin never runs
the stub that opens the installer), /opt/homebrew/bin/python3, /usr/local/bin/python3. If none
fits, a notice says so, and Settings → AI Session Atlas → Installation check shows every candidate it tried and an
Install Command Line Tools button (it runs xcode-select --install).
claude and codex are found on the PATH of your login shell. The plugin needs no Homebrew, Node,
tmux or other Obsidian plugins.
Installation
From the community plugin directory (listing): in Obsidian open Settings → Community plugins → Browse, search for AI Session Atlas, install and enable it.
Manually:
- Download
main.js,manifest.jsonandstyles.cssfrom the latest release. - Put them into
<vault>/.obsidian/plugins/session-atlas/. - In Obsidian, open Settings → Community plugins and enable AI Session Atlas.
On first start the plugin unpacks its server into
~/Library/Application Support/session-atlas/runtime/, starts it and builds the session index. With
many sessions the first index can take a few minutes.
Usage
-
Catalog. Click the library icon in the ribbon or run Open session catalog. The tab has three sections: Search, Active and Statistics.
-
Agent filter. Search, Active and Statistics each have an Agent list with Claude Code and Codex. Both are ticked by default, one always stays ticked, and the choice is remembered for each section.
-
Terminals. Click the Claude Code or Codex icon in the ribbon. A tab starts in the vault folder and runs your login shell. Sessions opened from the catalog start in their own working folder.
-
Commands:
Command ID Open session catalog open-catalogOpen Claude Code terminal open-claude-code-terminalOpen Codex terminal (when Codex is enabled) open-codex-terminalReload the plugin (tabs and sessions stay) reload-pluginCommand names follow the plugin language; the table shows the English ones.
-
Settings:
- Installation check: macOS,
python3, Claude Code, Codex, the server, the index (with a Rebuild button) and the subscription limits switch. - Language: English, Russian or as in Obsidian (the default). Topics, summaries and session notes are written in the same language.
- Agents: turn Claude Code and Codex on or off; until you do, each is on when the plugin finds it
at start-up, extra launch arguments for each (for example
--chrome), the Codex "waiting for you" hook (off by default), and the terminal font size. - Catalog: note folders, project roots, categories, note areas mapped to categories, sensitive areas
and projects, ticket prefixes. These live in
config.jsonin the data folder. - AI features: on/off, model and effort for each task, 1M-token window, which agent runs them (Auto, Claude Code, Codex) and the Codex model.
- Other: notices and how long they stay, macOS notifications, file explorer clicks.
- Advanced: custom
python3path and terminal shell.
- Installation check: macOS,
-
Codex prices.
openai_pricesinconfig.jsonfixes or adds the price of a Codex model, in US dollars per 1 million tokens:{"openai_prices": {"<model>": {"input": 2, "cached_input": 0.2, "output": 10}}}.cache_writeis optional;nullinstead of a price leaves the model unpriced. The change shows up in Statistics without a reindex. All costs are estimates at API prices, not what a subscription costs.
Agent Mail
Claude Code and Codex can write to each other by the title of an open Atlas terminal tab.
Nothing to set up. Every Claude Code or Codex session you start in an Atlas agent tab gets the Agent Mail MCP server bundled with Atlas, and its mail tools run without approval prompts. Atlas passes the server in the launch command, so your own ~/.claude.json and Codex config.toml stay untouched. Sessions started outside Atlas, for example in a regular terminal, do not get Agent Mail.
To use it, ask one agent: “Write to the session titled ‘Review the report’ and ask it to check the draft.” Sessions already open pick the server up after you resume them in a tab. Wake agents on new mail in Settings → AI Session Atlas → Agents is on by default; switching it off removes the server from newly started tabs.
Only one matching title is required to send. If several open sessions have that title, choose the recipient before sending. An open recipient tab is prompted once it is ready for input.
A letter sent from an Atlas tab carries a reply address for that tab. The recipient's answer goes back to that session and wakes it. Each letter in the inbox ends with the address to answer, and agents answer unless the letter ends with "(no reply needed)". An answer that needs no reply back ends with the same mark.
If a tab reports a usage limit, Agent Mail shows the reset time when available. If the limit appears after sending, check the recipient with mail_peers. The letter stays queued.
Atlas reads the Codex home folder from the login shell. If your Codex uses a different folder, set Codex home folder in the same settings section and reload Atlas. Use /hooks in Codex to trust the optional hook for approval notifications outside Atlas.
Disclosures
This section lists everything the plugin does outside Obsidian, as required by the Obsidian developer policies.
Network.
- The plugin starts a local HTTP server bound to
127.0.0.1on port 8787. The catalog tab is a page served by it; the plugin and the page talk only to this server. - The plugin and its server make no other network requests. There is no telemetry, no analytics, no update check, no ads and no account.
- The optional AI features run your own
claudeCLI, which sends data to Anthropic under your Claude Code account, or, when only Codex is installed or you pick it, your owncodexCLI, which sends data to OpenAI under your Codex login (see "AI features" below). - Claude Code and Codex running in terminal tabs connect to their providers as they always do. The plugin does not send anything to OpenAI itself.
- While Codex cards are shown in Active, the server may run your
codexascodex app-serverto read Codex's usage limits, at most every 5 minutes. Codex then asks OpenAI for your account's usage with its own login, as its/statusdoes. No model is called and nothing from your sessions is sent; the plugin never reads Codex's login. OpenAI prices come from a table inside the plugin, not from the network. - When you rename or delete a Codex session, the server runs your
codex(codex app-serverfor the name,codex deletefor deletion). Codex does that locally; no model is called.
Clipboard. The plugin reads clipboard text only when you choose Paste in a terminal's context menu, and sends it to that terminal as typed input. Copy actions write the selected terminal text or the requested catalog text to the clipboard. Pasting into a reply field can also attach images from the paste event. In Codex terminal tabs, image paste (keyboard or context menu) saves a private local file in the plugin uploads folder and pastes its path without submitting the prompt. The plugin does not poll the clipboard or keep a clipboard history. Pasted content can become part of the agent's transcript or an attached image, as with ordinary input.
Paths in terminal tabs. While the pointer is over a terminal line, the plugin checks whether the
paths printed on it exist on disk; for relative paths it finds the agent's working folder with ps
and lsof. Nothing is opened until you click: a click runs macOS open on that path, or opens a note
of this vault in Obsidian. Apps, scripts, installers and executable files are only shown in Finder,
never started.
Files outside the vault.
| Path | Access | Why |
|---|---|---|
~/.claude/projects/ |
read | Session transcripts: the catalog, Active and Statistics |
~/.claude/sessions/, ~/.claude/tasks/, ~/.claude/plans/ |
read | Running sessions, their task lists and plans |
~/.claude/commands/, ~/.claude/skills/, ~/.claude/plugins/, ~/.claude/settings.json |
read | The slash command list in Active |
~/.codex/sessions/, ~/.codex/archived_sessions/ |
read | Codex session files: the catalog, Active and Statistics, and the session a terminal tab should resume |
~/.codex/state_*.sqlite |
read only, opened in read-only mode | Codex's own thread titles |
~/.codex/goals_1.sqlite, ~/.codex/queue_1.sqlite |
read only, opened in read-only mode | A Codex card's /goal and queued messages in Active |
~/.codex/history.jsonl |
read | How many input history lines a Codex session has, shown before deletion |
~/.codex/skills/, ~/.agents/skills/, ~/.codex/models_cache.json |
read | The Codex command list and /model picker in Active |
~/.codex/config.toml |
read | The model provider a new Codex session names (Resume with… → Codex); its MCP servers, which Active does not count as background commands |
~/.codex/hooks.json |
write, only when you turn on Codex: "waiting for you" outside tabs | Adds the AI Session Atlas hook; a copy of an existing file is kept next to it (hooks.json.session-atlas.bak); turning it off removes only that hook, and only while it is the last one (otherwise it stays and does nothing) |
~/Library/Application Support/session-atlas/ |
read, write | The plugin's data folder: unpacked server, index, settings, logs (see "Privacy & data location") |
~/.local/state/obsidian-agent-terminals/ (or $XDG_STATE_HOME/obsidian-agent-terminals/) |
read, write | Which session each terminal tab holds, so the tab can resume it |
~/.claude/settings.json |
write, on first install when it has no status line, or when you turn on Subscription limits | Adds the AI Session Atlas status line (see below) |
A session's transcript in ~/.claude/projects/ |
append, only when you rename a session | Saves the new name where Claude Code reads it |
A new file in ~/.claude/projects/<folder>/ |
create, only when you use Resume with… → Claude Code | A new Claude Code session made from a Codex session |
A new file in ~/.codex/sessions/YYYY/MM/DD/ |
create, only when you use Resume with… → Codex | A new Codex session made from a Claude Code session |
A session's files in ~/.claude/ and its lines in ~/.claude/history.jsonl |
delete, only when you delete a session | See "Deleting a session" below |
A Codex session's files in ~/.codex/sessions/ and ~/.codex/archived_sessions/, its lines in ~/.codex/history.jsonl |
delete, only when you delete a Codex session | See "Deleting a session" below |
~/Library/Application Support/session-atlas/codex-waits/ |
write, by the Codex hook, only while it is on | One small file per Codex session: when it started waiting for an approval |
~/Library/Application Support/session-atlas/codex-hook-off |
write, by the plugin | The Codex hook is off but stays in hooks.json (your hooks follow it): while this file exists it does nothing |
~/Desktop, ~/Documents or a project folder |
write, only when you export a session note there | The exported session note file |
If CLAUDE_CONFIG_DIR is set in Obsidian's environment, every ~/.claude path above means that folder.
If CODEX_HOME is set, every ~/.codex path means that folder. The plugin never writes Codex's
databases or config.toml and never writes into an existing Codex session file. When you rename or
delete a Codex session, Codex's own commands change Codex's records (thread/name/set, codex delete);
codex app-server, run for the limits and the name, keeps its own logs and databases there as any
Codex run does. Codex records its trust of the hook in config.toml itself, when you allow it in
/hooks. The plugin creates a new session file only when you use Resume with… and deletes files
only when you delete a session.
Resume with… (Search card) creates a new session file of the other agent: in ~/.claude/projects/
for Claude Code or in ~/.codex/sessions/ for Codex. It happens only after a dialog that names the
folder; the file is created once and never overwritten, and the source session is only read. The new
file holds a copy of the conversation since its last context compaction (see "Resume with another
agent").
Delete the new session like any other if you no longer need it.
Processes.
python3 -m atlas.cli serve --port 8787from the data folder: the catalog server. It stops when the plugin unloads. While it runs, it starts short-livedpython3index passes, runspsto find running Claude Code and Codex sessions, and runslsofon interactivecodexprocesses to see which session file each one holds open (Codex writes no file per process).- Your login shell (
$SHELL -l -i), once per start, to readPATHand findclaudeandcodex. - Codex terminal tabs probe
codex --helpand use--no-daemonwhen supported. Each tab then keeps its own session process, so session switches and terminal controls can be verified. Existing CLI instances and your Codex settings are left alone. - Terminal tabs:
/bin/sh,catand/usr/bin/scriptprovide a pseudo-terminal, which runs your login shell, a tab script from the data folder, and thenclaudeorcodex. The tab passes Claude Code aSessionStart/UserPromptSubmithook through--settingsfor that launch only; your Claude Code settings files are not changed.psandsttyare used to find and resize tabs;psandlsoftell which Codex session a tab runs. sw_versandxcode-select -pfor the installation check;xcode-select --installonly when you press the install button.claude -porcodex exec, only when AI features are on (see below).codex app-server(one request: the new name) andcodex delete --force <id>, only when you rename or delete a Codex session.- With the Codex hook on, Codex runs
python3 …/atlas/codex_hook.pybefore it shows an approval prompt; the script writes the wait time to the data folder and prints nothing. - When you choose Move on an Active card, the plugin sends
SIGTERMto that Claude Code or Codex process in the other terminal app (it exits as on Ctrl+C) and resumes the session in an Obsidian tab (claude --resumeorcodex resume). It checks first that the process belongs to that session; for Codex, that the process holds this session's file open. A shared Codex app server is never stopped to move a single session.
AI features. On by default; nothing is sent until you press a button and confirm the preview. Turn them off in the settings. While they are off, the server refuses every request that would call a model.
- When on, they run your own
claudeCLI (claude -p) with your settings, hooks, MCP servers and tools disabled.ANTHROPIC_API_KEYis removed from the environment of these calls, so they use the account you signed in to Claude Code with and count against your subscription. The model issonnetunless you change it. Before a request larger than 200,000 characters, a small test request checks that the call works. - Through Codex (Run through: Auto picks Claude Code when it is installed, Codex otherwise):
your own
codex execwith--ephemeral(no saved session),--ignore-user-config(noconfig.toml: its MCP servers, hooks and profiles are skipped),--ignore-rules, hooks disabled, Codex's own tools off (no commands, file reads, web search, subagents, images or goals: a session's text cannot make the model reach anything), no skill list in the request, and a read-only sandbox in an empty folder. A Codex too old to know one of these switches refuses the call instead of running without it. It uses your Codex login and counts against your ChatGPT plan; the model is Codex's default unless you set Codex model. A custom provider goes incodex_exec_configinconfig.json(-c key=valuelines). The preview names the agent. - Session summary and session note: you see a preview of exactly what will be sent and confirm
it. A session note may send most of the session, as much as fits the model's context window. The full text of each
preview is saved in the data folder (
payloads/). - Topics and categories: a batch is sent after a preview of its size and samples. Each session is sent as a short fact card: title, working folder and branch, projects, tickets, a few prompts and edited file paths.
- Hourly automatic mode, if you turn it on, does the same for new and changed sessions without asking each time, up to 8 sessions an hour, through the agent it was turned on with. If the settings would later send them to another agent (Claude Code no longer found, another choice), it pauses and says why under the switch; turn it off and on to go on with the new agent.
- Sessions in areas or projects you mark as sensitive are never included in topic batches or the automatic mode.
- Claude Code saves these runs as its own transcripts under
~/.claude/projects/, in a folder the catalog skips.
Subscription limits. Claude Code reports 5-hour and weekly limits only to a status line script.
The Subscription limits switch adds a AI Session Atlas status line to ~/.claude/settings.json.
On first install it is turned on by itself when the file has no status line yet, and a notice says so.
Before its first edit the plugin saves a copy as settings.json.session-atlas.bak next to it. If you
already have a status line, or the file is not valid JSON, the switch is disabled and the file is
left alone. While enabled, the status line runs for every Claude Code session on the computer and
writes the limits to rate-limits.json in the data folder. It also shows the context window: used
tokens, the auto-compact point and the window size (e.g. context 227k · compact at ~467k · window 1M;
compact off when auto-compact is switched off). The point is estimated from Claude Code's settings
and environment, as the window minus its 33k buffer; the --autocompact launch flag and
CLAUDE_CODE_MAX_OUTPUT_TOKENS are not visible to the status line. Turning the switch off removes the
statusLine entry.
Deleting a session (Search card → Delete session) removes, after a confirmation that lists every
item: the transcript and the session folder in ~/.claude/projects/, its entries in
~/.claude/file-history/, ~/.claude/session-env/, ~/.claude/tasks/ and ~/.claude/todos/, its
lines in ~/.claude/history.jsonl (the input history), its session notes and its catalog data. For a
Codex session it first runs codex delete --force <id>, so Codex removes the thread from its own
records and session files itself, its subagent threads included; then it removes whatever is left of
its session files and its subagent threads' files in ~/.codex/sessions/ and
~/.codex/archived_sessions/, its lines in ~/.codex/history.jsonl, its session notes and its catalog
data. If Codex cannot delete it (not installed, too old), the files are
removed anyway and Codex may list the thread for a while, until it notices the file is gone. Files are
deleted, not moved to the Trash. A running session cannot be deleted.
Privacy & data location
Everything stays on your Mac. The data folder is ~/Library/Application Support/session-atlas/,
created with permissions that only your user can read. It contains:
| Item | Content |
|---|---|
runtime/ |
The server, the page and the tab scripts unpacked from main.js |
atlas.sqlite3 |
The search index of Claude Code and Codex sessions, topics, summaries and your edits |
config.json |
Catalog and AI settings, Codex prices |
context.md |
Notes about you for the topic classifier; edit it by hand |
csrf.token |
The token that protects the local server |
server.log |
Server log |
agent-args/ |
Extra launch arguments for Claude Code and Codex |
agent-mail-args/ |
Agent Mail launch flags that Atlas writes for the tab script |
uploads/ |
Images attached to replies; removed after 7 days |
handoffs/, payloads/, runner/ |
AI feature output, previews of sent text, the working folder of claude -p |
rate-limits.json |
Subscription limits, when the status line is enabled |
Plugin settings (language, agents, notifications) are stored by Obsidian in
<vault>/.obsidian/plugins/session-atlas/data.json.
Uninstall
- If you turned on Subscription limits, turn it off first: this removes the status line from
~/.claude/settings.json. Alternatively, restore~/.claude/settings.json.session-atlas.bak. - Disable and remove the plugin in Settings → Community plugins, or delete
<vault>/.obsidian/plugins/session-atlas/. The server stops when the plugin is disabled. - Delete the data folder:
~/Library/Application Support/session-atlas/. - Delete the terminal tab registry:
~/.local/state/obsidian-agent-terminals/. - Optionally delete
~/.claude/settings.json.session-atlas.bakand, if you used the AI features, the folder of their runs in~/.claude/projects/whose name ends withsession-atlas-runner.
If you turned on the Codex hook, turn it off first: this removes it from ~/.codex/hooks.json. If the
notice says it stayed (your own hooks follow it), delete its entry (the command with codex_hook.py)
by hand; Codex then asks you to trust the hooks after it again.
Alternatively, restore ~/.codex/hooks.json.session-atlas.bak (or delete hooks.json if the plugin
created it). Otherwise the plugin adds nothing to the Codex home.
Troubleshooting
| Symptom | Fix |
|---|---|
| Notice "Xcode Command Line Tools (python3) are needed" | Run xcode-select --install or press Install Command Line Tools in Settings → AI Session Atlas → Installation check. Then press Retry on the AI Session Atlas tab. If you use another Python, set its path in Settings → AI Session Atlas → Advanced → Custom python3. |
| "no python3 fits (...)" | The listed interpreters are older than 3.8 or their SQLite lacks FTS5 with the trigram tokenizer. Update Command Line Tools in Software Update or set a custom python3. |
| "the port is used by another program" | Another program listens on 127.0.0.1:8787. The port is fixed; stop that program and press Retry. A server left over from an older AI Session Atlas version is stopped and replaced automatically. |
| "the server did not start, see ..." | Read ~/Library/Application Support/session-atlas/server.log. Press Restart in Settings → AI Session Atlas → Installation check after fixing the cause. |
Claude Code shows as not found, or a tab cannot start claude |
Tabs run your login shell (-l -i). Make sure your shell profile puts claude on the PATH, or set another shell in Settings → AI Session Atlas → Advanced → Terminal shell. |
| Search shows old results | Press Rebuild next to "Session index" in Settings → AI Session Atlas → Installation check. |
Codex shows as not found, or a Codex tab cannot start codex |
Codex is optional. Make sure your shell profile puts codex on the PATH, as for claude, then turn Codex on in Settings → AI Session Atlas → Agents. |
| Codex sessions are missing from Search | The catalog reads $CODEX_HOME or ~/.codex. If you moved the Codex home with CODEX_HOME, Obsidian must have the variable in its environment too (for example launchctl setenv CODEX_HOME /path/to/codex-home, then restart Obsidian). Then press Rebuild. Check that Codex is ticked in the Agent filter. |
| A Codex tab starts a new session after a restart instead of the old one | The tab script looks for the session in ~/.codex/sessions/ only. With a moved Codex home, resume the session from Search. |
| A Codex card never shows that it waits for you | Codex permission prompts are read from the screen of the plugin's own tab. Move the session into a tab with Move. |
| A running Codex session is missing from Active | Only interactive terminal clients are shown. Plugin tabs use --no-daemon when available. For external clients using a shared server, only an explicit codex resume <id> can be matched; switching threads inside that external client cannot be tracked reliably. Restart that client with codex --no-daemon resume <id> for full tracking. The shared server is never stopped by Move. |
Development
Requirements: Node.js 20.19 or newer and python3 3.8 or newer.
npm ci # install build and lint tools
npm run build # main.js and styles.css in the repository root, next to manifest.json
npm run lint # ESLint with eslint-plugin-obsidianmd
npm test # Node tests, including the check that every page string has English and Russian
npm run e2e # browser tests
python3 -m pip install pytest
python3 -m pytest -q # Python tests
python3 tools/install_plugin.py --vault /path/to/test-vault --dev # build into a test vault
With --dev the installed plugin reloads itself on every build and runs apart from your working
setup: its own server on port 8788 and its own data folder
(~/Library/Application Support/session-atlas-dev). Open that test vault in a second Obsidian
window. Without --dev the build is only staged: a running Obsidian keeps the loaded version until
you run Reload the plugin or restart Obsidian. Release installs never reload themselves.
main.js embeds the Python server, the page and the zsh tab scripts; the plugin unpacks them at
runtime. The server uses only the Python standard library.
Project layout:
| Path | Content |
|---|---|
obsidian-plugin/src/ |
Plugin source (ES modules, bundled by esbuild) |
obsidian-plugin/styles.css |
Plugin styles |
obsidian-plugin/scripts/ |
zsh scripts for agent terminal tabs |
atlas/ |
Python server and indexer |
web/ |
The catalog page (index.html and web/js/) |
tests/ |
Python tests (pytest) |
tests/js/ |
Node tests |
tests/e2e/ |
Browser tests |
tools/ |
Development tools: vault installer, status line script, mutation testing, test fixtures |
esbuild.config.mjs, eslint.config.mjs |
Build and lint configuration |
manifest.json, versions.json |
Obsidian plugin manifest and version map |
main.js, styles.css |
Build output, not committed |
Contributing
See CONTRIBUTING.md. Report security issues as described in SECURITY.md. This project follows the Code of Conduct.
License
MIT. The release main.js and styles.css include xterm.js and its addons (MIT); see
THIRD-PARTY-NOTICES.md.