API Reference

The AMC Plugin SDK exposes 13 APIs to plugins. Some are available on both the frontend (via the AgentMC bridge) and the backend (via the PluginContext); others are backend-only or frontend-only.

API Summary

API	Description	Availability	Permission
Storage	Key-value storage	Both	storage
Database	Collection-based CRUD	Both	storage
Sessions	Spawn and manage Claude sessions	Both	sessions
AI	Generate text with AI models	Both	ai
Filesystem	Read and write files	Backend only	storage
HTTP	Fetch external URLs	Backend only	network
Cron	Schedule recurring tasks	Backend only	cron
CLI Endpoints	Register REST endpoints	Backend only	cli
Sidebar	Badge count and item list	Both	None
Toast	In-app and OS notifications	Both	notifications (for notify)
Settings	Read plugin settings	Both	None
Events	Pub/sub messaging	Backend only	None
Logging	Structured log output	Backend only	None

Access Patterns

Backend -- the PluginContext object is passed to your plugin's activate() function:

// src/backend/index.ts
import type { PluginContext } from '@agent-mc/plugin-sdk'

export function activate(ctx: PluginContext) {
  ctx.storage.set('initialized', true)
  ctx.log.info('Plugin activated')
}

Frontend -- the global AgentMC bridge is available in your UI code:

// src/ui/plugin.ts
const value = await AgentMC.storage.get('initialized')
AgentMC.toast.show({ type: 'info', message: 'Hello from the UI' })

Bridge-Only APIs

The following APIs are available only on the frontend through the AgentMC bridge. They do not have backend equivalents and do not require permissions.

Theme

Read and react to AMC's current theme.

// Get the current theme
const theme = AgentMC.theme.get()
// theme: { mode: 'dark' | 'light', visualTheme: string }

// Listen for theme changes
const unsubscribe = AgentMC.theme.onChange((theme) => {
  document.body.className = theme.mode
})

Method	Returns	Description
get()	{ mode: string; visualTheme: string }	Current theme state
onChange(callback)	() => void	Subscribe to theme changes. Returns an unsubscribe function

Export

Save files, generate PDFs, and interact with the user's filesystem through system dialogs.

// Save a text file (shows Save As dialog)
await AgentMC.export.saveFile({
  filename: 'report.md',
  content: markdownContent,
  type: 'text/markdown',
})

// Generate and save a PDF
await AgentMC.export.savePDF({
  filename: 'report.pdf',
  markdown: markdownContent,
  metadata: { title: 'Weekly Report' },
})

// Let the user pick a folder
const folder = await AgentMC.export.pickFolder({
  title: 'Choose output directory',
})

// Write multiple files to a directory
await AgentMC.export.writeFiles({
  directory: folder,
  files: [
    { name: 'index.ts', content: tsCode },
    { name: 'styles.css', content: cssCode },
  ],
})

// Verify files exist
await AgentMC.export.verifyFiles({
  directory: folder,
  files: ['index.ts', 'styles.css'],
})

// Open a folder in the system file manager
await AgentMC.export.openFolder({ path: folder })

Method	Description
saveFile(opts)	Show a Save As dialog and write a file
savePDF(opts)	Render Markdown to PDF and save
pickFolder(opts?)	Show a folder picker dialog, returns the selected path
writeFiles(opts)	Write multiple files to a directory
verifyFiles(opts)	Check that files exist in a directory
openFolder(opts)	Open a folder in the OS file manager

Project

Query and create AMC projects.

// List all projects
const projects = await AgentMC.project.listAll()

// Find a project by folder path
const project = await AgentMC.project.findByFolder('/path/to/repo')

// Create a new project
const newProject = await AgentMC.project.create({
  name: 'My App',
  folderPath: '/path/to/my-app',
})

// Open AMC's Add Project dialog with a folder pre-selected
await AgentMC.project.openAddDialog({
  preselectedFolder: '/path/to/repo',
})

Method	Description
listAll()	List all projects in AMC
findByFolder(folderPath)	Find a project by its folder path
create(opts)	Create a new project
openAddDialog(opts)	Open the native Add Project dialog

Assets

Read files bundled with your plugin (from the assets/ directory in your plugin package).

// Read a bundled file
const template = await AgentMC.assets.readFile('templates/default.md')

// List files in a directory
const files = await AgentMC.assets.listFiles('templates')

Method	Returns	Description
readFile(path)	Promise<string>	Read a bundled asset file as text
listFiles(path)	Promise<string[]>	List files in a bundled asset directory