Search...Search plugins and themes...
⌘K
Sign in
  • Get started
  • Download
  • Pricing
  • Enterprise
  • Account
  • Obsidian
  • Overview
  • Sync
  • Publish
  • Canvas
  • Mobile
  • Web Clipper
  • CLI
  • Learn
  • Help
  • Developers
  • Changelog
  • About
  • Roadmap
  • Blog
  • Resources
  • System status
  • License overview
  • Terms of service
  • Privacy policy
  • Security
  • Community
  • Plugins
  • Themes
  • Discord
  • Forum / 中文论坛
  • Merch store
  • Brand guidelines
Follow us
DiscordTwitterBlueskyThreadsMastodonYouTubeGitHub
© 2026 Obsidian

AI Session Atlas

Oleg TestovOleg Testov387 downloads

Search, watch and resume Claude Code and Codex sessions: full-text search, live session cards, usage stats, and agent terminal tabs that come back after a restart.

Add to Obsidian
  • Overview
  • Scorecard
  • Updates36

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.

AI Session Atlas: live agent cards, search, statistics, rhythm and limits (demo data)

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 --resume or codex 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 --resume shows it);
    • delete it from the computer for good, after a confirmation that lists every file.

    A copy made with Copy session (claude --fork-session or codex 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: …").

  • 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 with claude 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/ and archived_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 exec runs 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/set through a short-lived codex app-server, as /rename does), so codex resume and 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 codex has open, also after /new, /resume or /fork inside 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 /resume counts 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 codex processes in a terminal, found with ps and lsof. codex exec runs 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 of codex other 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 through codex app-server come from Codex's goals_1.sqlite and queue_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 /hooks in 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 .system skills and plugin skills such as figma:figma-use included); without one, the skills in $CODEX_HOME/skills and ~/.agents/skills. /model shows 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 /status and /mcp is shown on the card.
  • Statistics. A skill counts once a turn when you mention it with $name or when Codex reads its SKILL.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 /status shows them: while Codex cards are shown in Active, the server runs codex 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>.jsonl for Claude Code, ~/.codex/sessions/YYYY/MM/DD/rollout-…jsonl for Codex. A Codex session names the model provider set in ~/.codex/config.toml (openai if 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:

  1. Download main.js, manifest.json and styles.css from the latest release.
  2. Put them into <vault>/.obsidian/plugins/session-atlas/.
  3. 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-catalog
    Open Claude Code terminal open-claude-code-terminal
    Open Codex terminal (when Codex is enabled) open-codex-terminal
    Reload the plugin (tabs and sessions stay) reload-plugin

    Command 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.json in 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 python3 path and terminal shell.
  • Codex prices. openai_prices in config.json fixes 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_write is optional; null instead 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.

  1. In Settings → AI Session Atlas → Agents, enable Wake agents on new mail.
  2. Under Connect Agent Mail, copy each setup command and run it in a regular terminal. These commands use the MCP server bundled with Atlas and the same local mail folder. If you already use a compatible Agent Mail server, keep it and make sure both clients use that folder.
  3. Resume the agent sessions so they load the MCP. Then ask one agent to “Write to the session titled ‘Review the report’ and ask it to check the draft.”

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. Each agent's tool approval settings still apply.

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.

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.1 on 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 claude CLI, which sends data to Anthropic under your Claude Code account, or, when only Codex is installed or you pick it, your own codex CLI, 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 codex as codex app-server to 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 /status does. 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-server for the name, codex delete for 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 8787 from the data folder: the catalog server. It stops when the plugin unloads. While it runs, it starts short-lived python3 index passes, runs ps to find running Claude Code and Codex sessions, and runs lsof on interactive codex processes 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 read PATH and find claude and codex.
  • Codex terminal tabs probe codex --help and use --no-daemon when 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, cat and /usr/bin/script provide a pseudo-terminal, which runs your login shell, a tab script from the data folder, and then claude or codex. The tab passes Claude Code a SessionStart/UserPromptSubmit hook through --settings for that launch only; your Claude Code settings files are not changed. ps and stty are used to find and resize tabs; ps and lsof tell which Codex session a tab runs.
  • sw_vers and xcode-select -p for the installation check; xcode-select --install only when you press the install button.
  • claude -p or codex exec, only when AI features are on (see below).
  • codex app-server (one request: the new name) and codex delete --force <id>, only when you rename or delete a Codex session.
  • With the Codex hook on, Codex runs python3 …/atlas/codex_hook.py before 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 SIGTERM to 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 --resume or codex 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 claude CLI (claude -p) with your settings, hooks, MCP servers and tools disabled. ANTHROPIC_API_KEY is 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 is sonnet unless 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 exec with --ephemeral (no saved session), --ignore-user-config (no config.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 in codex_exec_config in config.json (-c key=value lines). 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
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

  1. 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.
  2. Disable and remove the plugin in Settings → Community plugins, or delete <vault>/.obsidian/plugins/session-atlas/. The server stops when the plugin is disabled.
  3. Delete the data folder: ~/Library/Application Support/session-atlas/.
  4. Delete the terminal tab registry: ~/.local/state/obsidian-agent-terminals/.
  5. Optionally delete ~/.claude/settings.json.session-atlas.bak and, if you used the AI features, the folder of their runs in ~/.claude/projects/ whose name ends with session-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.

HealthExcellent
ReviewSatisfactory
About
Search Claude Code and Codex session transcripts by text, project, domain, topic and date. See running sessions as live cards, reply to agents and answer their questions. Resume sessions in persistent Obsidian terminal tabs, or continue a copy with the other agent. View token, cost and activity statistics for either agent or both. Restore tabs after a restart. Data stays local unless you enable optional AI features.
AISearchFiles
Details
Current version
2.12.0
Last updated
21 hours ago
Created
2 months ago
Updates
36 releases
Downloads
387
Compatible with
Obsidian 1.8.7+
Platforms
Desktop only
License
MIT
Report bugRequest featureReport plugin
Author
Oleg TestovOleg Testovolegtestov
GitHubolegtestov
  1. Community
  2. Plugins
  3. AI
  4. AI Session Atlas

Related plugins

Claudian

Embeds Claude Code/Codex and other local Agents as AI collaborators in your vault.

Smart Connections

Find related notes and excerpts while writing. Your AI link building copilot displays relevant content in graph + list view. A local embedding model powers semantic search. Zero setup. No API key.

ChatGPT MD

A seamless integration of ChatGPT, OpenRouter.ai and local LLMs via Ollama into your notes.

Omnisearch

Intelligent search for your notes, PDFs, and OCR for images.

Gemini Scribe

Allows you to interact with Gemini and use your notes as context.

Smart Second Brain

Chat with an agent that knows your notes, search by meaning, and see your vault grouped into topics. Runs on Ollama, OpenAI, Anthropic, and more.

Local LLM Helper

Use a local LLM server to augment your notes

Claude Code IDE

Connect your vault to Claude Code and share editor context with the CLI.

Notebook Navigator

A better file browser and calendar inspired by Apple Notes, Bear, Evernote and Day One.

Quick Switcher++

Enhanced Quick Switcher, search open panels, and symbols.