atlas

name	atlas
description	macOS-only AppleScript control for the ChatGPT Atlas desktop app. Use only when the user explicitly asks to control Atlas tabs/bookmarks/history on macOS and the "ChatGPT Atlas" app is installed; do not trigger for general browser tasks or non-macOS environments.

Atlas Control (macOS)

Use the bundled CLI to control Atlas and inspect local browser data.

Quick Start

Set a stable path to the CLI:

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export ATLAS_CLI="$CODEX_HOME/skills/atlas/scripts/atlas_cli.py"

Then run:

uv run --python 3.12 python "$ATLAS_CLI" app-name
uv run --python 3.12 python "$ATLAS_CLI" tabs --json

The CLI requires the Atlas app bundle in /Applications or ~/Applications:

• ChatGPT Atlas

If AppleScript fails with a permissions error, grant Automation permission: System Settings → Privacy & Security → Automation → allow your terminal to control ChatGPT Atlas.

Tabs Workflow

1. List tabs to get window_id and tab_index:

uv run --python 3.12 python "$ATLAS_CLI" tabs

2. Focus a tab using the window_id and tab_index from the listing:

uv run --python 3.12 python "$ATLAS_CLI" focus-tab <window_id> <tab_index>

3. Open a new tab:

uv run --python 3.12 python "$ATLAS_CLI" open-tab "https://chatgpt.com/"

Optional maintenance commands:

uv run --python 3.12 python "$ATLAS_CLI" reload-tab <window_id> <tab_index>
uv run --python 3.12 python "$ATLAS_CLI" close-tab <window_id> <tab_index>

Bookmarks and History

Atlas stores Chromium-style profile data under ~/Library/Application Support/com.openai.atlas/browser-data/host/.

List bookmarks:

uv run --python 3.12 python "$ATLAS_CLI" bookmarks --limit 100

Search bookmarks:

uv run --python 3.12 python "$ATLAS_CLI" bookmarks --search "docs"

Search history:

uv run --python 3.12 python "$ATLAS_CLI" history --search "openai docs" --limit 50

History for today (local time):

uv run --python 3.12 python "$ATLAS_CLI" history --today --limit 200 --json

The history command copies the SQLite database to a temp location to avoid lock conflicts.

If history looks stale or empty, check both Atlas data roots and use the one with the most recent History file:

• ~/Library/Application Support/com.openai.atlas/browser-data/host/
• ~/Library/Application Support/com.openai.atlas.beta/browser-data/host/

References

Read references/atlas-data.md in the skill folder (for example, $CODEX_HOME/skills/atlas/references/atlas-data.md) when adjusting data paths or timestamps.