Settings and System Integration

Settings panes

AtomLens keeps settings grouped into focused panes:

• Workspace: includes Open a browser when launching AtomLens and lets you choose either Local Molecule Files or Managed Repository as the startup browser.
• Managed Repository: includes Sync chemical files over iCloud. Turning it off keeps the Managed Repository available and stores its content locally on that Mac or iPad.
• Text Size: controls one Help-browser scale plus practical UI text-size choices used across AtomLens surfaces.
• Permissions: includes the helper for granting smoother sandbox access to the home folder.
• MCP Server: configures local stdio and HTTP access for automation clients.
• Shortcuts and About provide reference information without leaving the app.

Export diagnostics

On Mac and iPad, open Settings > About > Export Diagnostics…, choose a destination, then share the saved JSON report when requesting help. Include the approximate incident time, app build, and what you were doing.

The report contains recent memory and activity measurements, app/device details, and available Apple MetricKit reports. Local history has a fixed size limit and up to seven days of retention. Molecule contents and document paths are excluded; nothing is sent automatically. A forced termination may leave no final event.

On OS 27, available Apple reports also describe activity such as PDF scanning, indexing, structural search, 3D viewing and document automation. iPad reports can include memory-limit terminations; 3D metrics can include frame performance. Reported activity provides context for investigation, and does not by itself establish the cause of a crash or resource use.

On Mac, Workspace also offers Start 3D visualization with auto-rotation. On iPad, control rotation directly in the canvas HUD. Both platforms offer separate interface and Help text-size controls under Text Size.

Permissions

In sandboxed macOS environments, AtomLens may need file access grants for smoother reopen, search, Quick Look, and Finder-label update behavior.

• If a file does not reopen from Search or Open Recent, open it once through the file picker and grant access if macOS asks.
• If Finder labels do not update from Local Molecule Files, grant access to the relevant location and try the label action again.
• The optional Grant Access... helper exists to reduce repeated friction for frequently used locations.

Finder and Spotlight

AtomLens integrates with macOS system surfaces so that chemistry files remain useful outside the main app window.

• Quick Look: chemistry previews are available in Finder, Local Molecule Files, and Managed Repository.
• Spotlight: AtomLens writes searchable chemistry metadata for local file lookup.
• Finder labels: Local Molecule Files and Managed Repository read native label and tag metadata, filter by it, and can write selected label changes back to files.

Useful Terminal examples

mdfind 'de_losko_atomlens_is_molecule == 1'
mdfind 'de_losko_atomlens_is_reaction == 1'
mdfind 'de_losko_atomlens_inchi_key == "HVQAJTFOCKOKIN-UHFFFAOYSA-N"'

MCP service

AtomLens includes a bundled MCP helper and a local MCP Server settings pane for external clients such as Codex. In a standard macOS installation, the helper lives at /Applications/AtomLens.app/Contents/Helpers/atomlens-mcp.

• For stdio MCP clients, launch atomlens-mcp directly.
• For HTTP JSON-RPC clients, open Settings, select MCP Server, choose the port, keep or create the required bearer token, then start the server.
• Use Create to generate a bearer token, and enable Launch at login when the HTTP server should stay available after signing in even if AtomLens is not open.
• The Settings-managed local HTTP endpoint binds to 127.0.0.1 and defaults to http://127.0.0.1:8080/mcp. Do not expose the helper outside a trusted loopback connection.
• HTTP requests must include the configured bearer token. The helper rejects request bodies larger than 1 MiB before reading them.
• The launch-at-login helper reads the app-written MCP configuration from Application Support and exits without listening if that configuration is missing a bearer token.
• The Codex connector toggle edits ~/.codex/config.toml. AtomLens may ask for Home folder access before installing it.
• The current MCP surface covers repository search, add, batch get, exact identifier lookup, export, delete, color labels, favorites, and recent-use metadata.

Codex configuration

[mcp_servers.atomlens]
command = "/Applications/AtomLens.app/Contents/Helpers/atomlens-mcp"
enabled = true

After saving the Codex config, restart Codex so it reloads the MCP server list.

Troubleshooting

• Apply & Render is disabled: the current input is empty or AtomLens cannot detect a supported structure format yet.
• Local Molecule Files shows no files: Spotlight may still be indexing, or AtomLens has not found supported chemistry filenames yet.
• Finder-label filters hide everything: active Finder-label filters are combined, so a result must match every selected label.
• Extract stops early: the source probably contains only one valid record, while Extract requires multiple records.
• Map controls are disabled in reaction mode: the current reaction does not include atom-map numbers.
• Need reaction artwork: use File > Share > Share as SVG, PNG, or PDF for visual whole-reaction output. Use RXN, RDF, Reaction SMILES, RInChI, or CML when you need chemistry file export.

Privacy and licenses

AtomLens is local-first desktop software.

• Parsing, viewing, browsing, exporting, and extraction happen locally on your Mac.
• PDF text extraction, AI-assisted chemical-name and drawing recognition, AI-assisted name generation, deterministic structure validation, and structure thumbnails happen locally. Selected PDFs and extracted text are not uploaded.
• No account or login is required for normal use.
• Spotlight and Quick Look maintain local macOS indexes and preview caches.
• Export and extraction output is written only to destinations you choose explicitly.

OPSINSwift source and license notice (bundled)

Document chemistry model notices: model and provenance notice, ChemDataExtractor2 MIT license, SciBERT Apache License 2.0, the DECIMER Image Segmentation source, model, and attribution notice, and the offline IUPAC name model data and provenance notice.

The basic AI icon used in the scan workflow diagram comes from the European Commission AI icon set. The Commission states that the icons are freely usable without attribution; AtomLens nevertheless records the source here for transparency.

3D color palette licensing and attribution details: 3D Color Palettes and Licensing

© 2026 Dr. Sascha Losko - Obscure Essentials. All rights reserved.