Plugin API Reference

Note

This is the API reference. For a tutorial on building your first plugin, start with Building Plugins.

Every Atlas plugin gets access to a global atlas object. This object is your entire interface to Atlas — it’s injected into your plugin’s sandbox when it loads. Calling a method that requires a permission your plugin didn’t request will throw an error.

atlas.vault

File and directory operations on the user’s vault.

atlas.vault.read(path)

Read the contents of a vault file.

Permission	read_vault
Parameters	path (string) — Path relative to vault root
Returns	Promise<string> — File contents

const content = await atlas.vault.read('daily/2026-02-27.md');

atlas.vault.write(path, content)

Create or overwrite a vault file.

Permission	write_vault
Parameters	path (string) — Path relative to vault root
	content (string) — File contents to write
Returns	Promise<void>

await atlas.vault.write('notes/my-note.md', '# Hello\nThis is a note.');

atlas.vault.list(path)

List files and directories at a vault path.

Permission	read_vault
Parameters	path (string) — Directory path relative to vault root. Use empty string '' for vault root.
Returns	Promise<Array<{name: string, isDirectory: boolean}>> — Array of file/directory objects

// List vault root
const items = await atlas.vault.list('');
// [
//   { name: 'daily', isDirectory: true },
//   { name: 'notes', isDirectory: true },
//   { name: 'readme.md', isDirectory: false }
// ]

// List daily notes folder
const dailyNotes = await atlas.vault.list('daily');
// [
//   { name: '2026-02-25.md', isDirectory: false },
//   { name: '2026-02-26.md', isDirectory: false },
//   { name: '2026-02-27.md', isDirectory: false }
// ]

atlas.vault.fileExists(path)

Check if a file exists in the vault.

Permission	read_vault
Parameters	path (string) — Path relative to vault root
Returns	Promise<boolean>

if (await atlas.vault.fileExists('notes/todo.md')) {
  const content = await atlas.vault.read('notes/todo.md');
}

atlas.vault.deleteFile(path)

Delete a file from the vault.

Permission	write_vault
Parameters	path (string) — Path relative to vault root
Returns	Promise<void>

await atlas.vault.deleteFile('notes/old-note.md');

atlas.vault.getFileMetadata(path)

Get metadata about a vault file.

Permission	read_vault
Parameters	path (string) — Path relative to vault root
Returns	Promise<{ size: number, created: string, modified: string, isDirectory: boolean }>

const meta = await atlas.vault.getFileMetadata('notes/todo.md');
console.log(meta.modified); // ISO timestamp
console.log(meta.size);     // bytes

atlas.vault.readBinary(path)

Read a binary file from the vault as a Base64-encoded string.

Permission	read_vault
Parameters	path (string) — Path relative to vault root
Returns	Promise<string> — Base64-encoded file contents

// Read an image file
const base64Image = await atlas.vault.readBinary('attachments/photo.jpg');

// Convert to data URL for display
const dataUrl = `data:image/jpeg;base64,${base64Image}`;

// Or decode to bytes in JavaScript
const binaryString = atob(base64Image);
const bytes = new Uint8Array(binaryString.length);
for (let i = 0; i < binaryString.length; i++) {
  bytes[i] = binaryString.charCodeAt(i);
}

Caution

All vault paths are relative to the vault root. Path traversal (..) is rejected — you cannot access files outside the vault.

---

atlas.ui

User interface components. All UI elements created by a plugin are automatically removed when the plugin is disabled.

atlas.ui.addToolbarButton(options)

Add a clickable button to the Atlas toolbar.

Permission	ui_components
Parameters	options (object) — see below
Returns	string — Button ID (for later removal)

Options:

Field	Type	Description
icon	string	Emoji or short text displayed on the button
tooltip	string	Hover text
onClick	function	Callback when clicked (can be async)

const buttonId = atlas.ui.addToolbarButton({
  icon: '🍅',
  tooltip: 'Start Pomodoro',
  onClick: () => startTimer()
});

atlas.ui.removeToolbarButton(buttonId)

Remove a toolbar button by its ID.

Permission	ui_components
Parameters	buttonId (string) — ID returned by addToolbarButton
Returns	void

atlas.ui.showNotification(message, type?)

Show a toast notification.

Permission	ui_components
Parameters	message (string) — Notification text
	type (string, optional) — 'info', 'success', 'warning', or 'error'. Default: 'info'
Returns	void

atlas.ui.showNotification('Work session complete!', 'success');
atlas.ui.showNotification('Something went wrong', 'error');

atlas.ui.showModal(options)

Show a modal dialog. Returns a Promise that resolves when the user clicks a button or dismisses the modal.

Permission	ui_components
Parameters	options (object) — see below
Returns	Promise<{ value: string, formData: object }>

Options:

Field	Type	Description
title	string	Modal title
content	string	HTML content rendered inside the modal body
buttons	array	Array of button objects

Button objects:

Field	Type	Description
label	string	Button text
value	string	Value returned when this button is clicked
type	string	'primary' or 'secondary'

Return value:

• value — The value of the button that was clicked, or 'dismiss' if the modal was closed without clicking a button
• formData — An object containing values from <input> elements in the modal content, keyed by their id attribute

const result = await atlas.ui.showModal({
  title: 'Enter Task',
  content: `
    <div style="padding: 0.5rem;">
      <label>Task name:</label>
      <input type="text" id="task-name" placeholder="What are you working on?" />
    </div>
  `,
  buttons: [
    { label: 'Cancel', value: 'cancel', type: 'secondary' },
    { label: 'Start', value: 'start', type: 'primary' }
  ]
});

if (result.value === 'start') {
  const taskName = result.formData['task-name'];
  // ...
}

atlas.ui.addStatusBarItem(options)

Add a text element to the bottom status bar.

Permission	ui_components
Parameters	options (object) — { text: string, tooltip?: string }
Returns	string — Item ID (for updates and removal)

const itemId = atlas.ui.addStatusBarItem({
  text: '🍅 Ready',
  tooltip: 'Pomodoro Timer'
});

atlas.ui.updateStatusBarItem(itemId, options)

Update the text and/or tooltip of an existing status bar item.

Permission	ui_components
Parameters	itemId (string) — ID returned by addStatusBarItem
	options (object) — { text?: string, tooltip?: string }
Returns	void

atlas.ui.updateStatusBarItem(itemId, {
  text: '🍅 24:30',
  tooltip: 'Working: Write documentation'
});

atlas.ui.removeStatusBarItem(itemId)

Remove a status bar item by its ID.

Permission	ui_components
Parameters	itemId (string) — ID returned by addStatusBarItem
Returns	void

---

atlas.tools

Execute Atlas agent tools programmatically. These are the same tools the AI agent uses.

atlas.tools.search(query)

Search the vault using RAG (hybrid vector + text search).

Permission	execute_tools
Parameters	query (string) — Search query
Returns	Promise<array> — Search results

const results = await atlas.tools.search('meeting notes from last week');

atlas.tools.createNote(path, content)

Create a new note in the vault.

Permission	execute_tools
Parameters	path (string) — Note path relative to vault root
	content (string) — Note content (markdown)
Returns	Promise<void>

await atlas.tools.createNote('notes/pomodoro-log.md', '# Pomodoro Log\n');

atlas.tools.getDailyNote(date?)

Get or create the daily note for a given date.

Permission	execute_tools
Parameters	date (string, optional) — Date in YYYY-MM-DD format. Defaults to today.
Returns	Promise<string> — Path to the daily note

const path = await atlas.tools.getDailyNote();
// 'daily/2026-02-27.md'

atlas.tools.addTask(task, options?)

Add a task to a note (defaults to today’s daily note).

Permission	execute_tools
Parameters	task (string) — Task text
	options (object, optional) — see below
Returns	Promise<void>

Options:

Field	Type	Description
date	string	Date in YYYY-MM-DD format (defaults to today)
filePath	string	Specific file to add the task to
section	string	Section heading to add the task under

// Add to today's daily note
await atlas.tools.addTask('Completed pomodoro: Write documentation');

// Add to a specific file under a section
await atlas.tools.addTask('Review PR #42', {
  filePath: 'projects/atlas.md',
  section: 'Tasks'
});

atlas.tools.toggleTask(taskText, options?)

Toggle a task’s completion status.

Permission	execute_tools
Parameters	taskText (string) — Text of the task to toggle
	options (object, optional) — see below
Returns	Promise<void>

Options:

Field	Type	Description
filePath	string	File containing the task
date	string	Date of the daily note containing the task
complete	boolean	Force complete (true) or incomplete (false) instead of toggling

await atlas.tools.toggleTask('Review PR #42', { complete: true });

atlas.tools.searchContent(query, limit?)

Full-text search across vault content.

Permission	execute_tools
Parameters	query (string) — Search query
	limit (number, optional) — Max results to return
Returns	Promise<array> — Matching results

const results = await atlas.tools.searchContent('pomodoro', 10);

---

atlas.config

Plugin-specific settings and global Atlas configuration.

atlas.config.getPluginSettings()

Get your plugin’s saved settings.

Permission	None
Returns	Promise<object> — Your plugin’s settings object (empty {} if none saved)

const settings = await atlas.config.getPluginSettings();
const workDuration = settings.workMinutes || 25;

atlas.config.setPluginSettings(settings)

Save your plugin’s settings. These persist across app restarts.

Permission	None
Parameters	settings (object) — Key-value pairs to save
Returns	Promise<void>

await atlas.config.setPluginSettings({
  workMinutes: 25,
  breakMinutes: 5,
  longBreakMinutes: 15,
  notificationsEnabled: true
});

atlas.config.get(key)

Read a global Atlas configuration value.

Permission	config
Parameters	key (string) — Configuration key
Returns	Promise<any> — Configuration value

const leanMode = await atlas.config.get('lean_context_mode');

atlas.config.set(key, value)

Write a global Atlas configuration value.

Permission	config
Parameters	key (string) — Configuration key
	value (any) — Value to set
Returns	Promise<void>

Caution

Modifying global configuration affects the entire Atlas app, not just your plugin. Only use atlas.config.get/set if your plugin genuinely needs to read or change app-wide settings. For plugin-specific settings, use getPluginSettings() / setPluginSettings() instead — no permission required.

---

atlas.data

Per-plugin persistent file storage. Each plugin gets its own data/ directory inside its plugin folder. No permission required.

atlas.data.read(filename)

Read a file from your plugin’s data directory.

Permission	None
Parameters	filename (string) — Filename (no paths, no ..)
Returns	Promise<string> — File contents

const history = await atlas.data.read('pomodoro-history.json');
const data = JSON.parse(history);

atlas.data.write(filename, content)

Write a file to your plugin’s data directory. Creates the data/ directory automatically if it doesn’t exist.

Permission	None
Parameters	filename (string) — Filename (no paths, no ..)
	content (string) — File contents
Returns	Promise<void>

const history = { sessions: [], totalPomodoros: 42 };
await atlas.data.write('pomodoro-history.json', JSON.stringify(history, null, 2));

Tip

Use atlas.data.* for plugin state that should survive across app restarts — session history, cached data, user preferences that don’t belong in settings. Filenames are validated: no path separators (/, \) or traversal (..) allowed.

---

atlas.plugin

Plugin identity, logging, and command registration. No permission required.

atlas.plugin.id

Type	string
Description	Your plugin’s ID from the manifest

atlas.plugin.name

Type	string
Description	Your plugin’s display name from the manifest

atlas.plugin.version

Type	string
Description	Your plugin’s version from the manifest

atlas.plugin.log(…args)

Log a message to the browser console, prefixed with [Plugin: {id}].

Permission	None
Parameters	...args — Any values to log (same as console.log)

atlas.plugin.log('Timer started for task:', taskName);
// Console output: [Plugin: pomodoro] Timer started for task: Write docs

atlas.plugin.registerCommand(command)

Register a command with an optional keyboard shortcut.

Permission	None
Parameters	command (object) — see below
Returns	string — Full command ID ("pluginId:commandId")

Command object:

Field	Type	Required	Description
id	string	Yes	Unique command ID within your plugin
name	string	No	Display name
description	string	No	What the command does
hotkey	string	No	Keyboard shortcut (e.g. 'Ctrl+Shift+P')
callback	function	Yes	Function to call when triggered (can be async)

Hotkey format: Modifier keys (Ctrl, Shift, Alt, Meta) joined with +, followed by a key. Case-insensitive. Examples: 'Ctrl+Shift+P', 'Alt+T', 'Ctrl+E'.

const cmdId = atlas.plugin.registerCommand({
  id: 'toggle',
  name: 'Toggle Pomodoro Timer',
  hotkey: 'Ctrl+Shift+P',
  callback: toggleTimer
});

atlas.plugin.unregisterCommand(commandId)

Remove a previously registered command.

Permission	None
Parameters	commandId (string) — Full ID returned by registerCommand

Note

Commands and their keyboard shortcuts are automatically unregistered when your plugin is disabled. You only need unregisterCommand if you want to remove a command while the plugin is still active.

---

atlas.manifest

Read-only access to your plugin’s manifest data. No permission required.

atlas.manifest.id

Type	string
Description	Plugin ID

atlas.manifest.name

Type	string
Description	Plugin display name

atlas.manifest.version

Type	string
Description	Plugin version

---

Permission Enforcement

If your plugin calls an API method without the required permission, Atlas throws an error:

Error: Plugin "my-plugin" does not have permission "read_vault"

This error is thrown immediately — the operation is not attempted. Make sure your plugin.json includes all permissions your plugin needs.

Lifecycle Hook Reference

Hook	When Called	Use For
onLoad()	Plugin first loaded	Initialize state, add UI elements, register commands
onEnable()	After onLoad, or when user re-enables	Start background work, connect to services
onDisable()	User disables plugin	Stop timers/intervals, save state
onUnload()	App shutdown or plugin removal	Final cleanup

Auto-cleanup on disable: Atlas removes all toolbar buttons, status bar items, registered commands, keyboard shortcuts, and plugin tab UI that your plugin created. You don’t need to manually remove these.

You must clean up: setInterval / setTimeout timers, event listeners you added outside the atlas API, any ongoing async operations.