Oleg Testov387 downloadsSearch, 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.
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.

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:
claude --resume or codex resume);claude --resume shows it);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:
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.
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/ 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.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.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.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.~/…, 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.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.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.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.$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./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.config.json (see Usage).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… 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.
~/.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).| 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.
From the community plugin directory (listing): in Obsidian open Settings → Community plugins → Browse, search for AI Session Atlas, install and enable it.
Manually:
main.js, manifest.json and styles.css from the
latest release.<vault>/.obsidian/plugins/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.
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:
python3, Claude Code, Codex, the server, the index (with a
Rebuild button) and the subscription limits switch.--chrome), the Codex "waiting for you" hook (off by default), and the terminal font size.config.json in the data folder.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.
Claude Code and Codex can write to each other by the title of an open Atlas terminal tab.
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.
This section lists everything the plugin does outside Obsidian, as required by the Obsidian developer policies.
Network.
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.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).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.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).$SHELL -l -i), once per start, to read PATH and find claude and codex.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./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.python3 …/atlas/codex_hook.py before it shows an approval
prompt; the script writes the wait time to the data folder and prints nothing.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.
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.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.payloads/).~/.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.
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.
~/.claude/settings.json. Alternatively, restore ~/.claude/settings.json.session-atlas.bak.<vault>/.obsidian/plugins/session-atlas/. The server stops when the plugin is disabled.~/Library/Application Support/session-atlas/.~/.local/state/obsidian-agent-terminals/.~/.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.
| 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. |
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 |
See CONTRIBUTING.md. Report security issues as described in SECURITY.md. This project follows the Code of Conduct.
MIT. The release main.js and styles.css include xterm.js and its addons (MIT); see
THIRD-PARTY-NOTICES.md.