What the agent does
The agent reads the plugin's shape and the API it compiles against before it touches a menu. In a plugin built from obsidianmd/obsidian-sample-plugin, src/main.ts holds a MyPlugin class whose onload loads settings, adds a dice ribbon icon that shows a Notice, a status bar item, three commands (open-modal-simple, replace-selected with an editorCallback that calls editor.replaceSelection('Sample editor command'), and open-modal-complex with a checkCallback gated on getActiveViewOfType(MarkdownView)), a SampleSettingTab, a global click listener through registerDomEvent and an interval through registerInterval; onunload is empty because every registration cleans itself up. src/settings.ts defines MyPluginSettings with one mySetting string and the tab. manifest.json is sample-plugin with minAppVersion 1.0.0 and isDesktopOnly: false, and versions.json maps 1.0.0 to 1.0.0, kept in step by version-bump.mjs when npm version runs.
The tooling decides how the new code has to look. package.json is type: module, builds with tsc -noEmit -skipLibCheck && node esbuild.config.mjs production, and lints with eslint .; its dev dependencies are esbuild 0.25.5, typescript ^5.8.3, eslint ^9.39.4 with eslint-plugin-obsidianmd ^0.4.0 and typescript-eslint ^8.59.1, jiti for the eslint.config.mts, and obsidian at latest, which resolves to 1.14.4 today. tsconfig.json is strict with noUncheckedIndexedAccess and noImplicitReturns, targeting ES2021 with the DOM lib. esbuild.config.mjs bundles src/main.ts into a CommonJS main.js with obsidian, electron and the CodeMirror packages external. eslint.config.mts applies obsidianmd.configs.recommended with the project service. .github/workflows/lint.yml runs npm ci, npm run build and npm run lint on Node 20, 22 and 24 for every push and pull request, and release.yml builds on a tag, attests main.js and drafts a release with main.js, manifest.json and styles.css. AGENTS.md asks for main.ts to stay about lifecycle, for feature code in its own modules, for this.register* on every listener, for sentence-case UI text and for an accurate minAppVersion when newer APIs are used.
In obsidian.d.ts, Workspace.on has four menu events: file-menu, since 0.9.12, with (menu, file, source, leaf?); files-menu, since 1.4.10, for a multi-selection in the file explorer; editor-menu, since 1.1.0, with (menu, editor, info); and url-menu, since 1.5.1. A Menu takes addItem and addSeparator, and a MenuItem takes setTitle, setIcon, setSection, setDisabled and onClick. The agent writes src/menus.ts with one exported registerContextMenus(plugin). On file-menu it adds Copy link to note for a TFile whose extension is md, which builds the link with app.fileManager.generateMarkdownLink(file, '') so the user's wiki-link or Markdown-link setting is respected, writes it with navigator.clipboard.writeText and confirms with a Notice; folders get nothing. On files-menu the same item copies one link per selected note joined by newlines. On editor-menu it adds Replace selected content, which calls the same function the replace-selected command already uses, moved into src/commands.ts so the command and the menu share it, and is setDisabled when editor.getSelection() is empty. Each handler is passed to plugin.registerEvent, so unloading the plugin removes it. main.ts gains one call to registerContextMenus(this) after addSettingTab.
Because files-menu exists only from 1.4.10, the agent raises minAppVersion in manifest.json to 1.4.10 and notes that versions.json gets the new mapping on the next npm version, as version-bump.mjs writes it. Then it runs npm ci, npm run build, which type-checks under the strict tsconfig.json and bundles main.js, and npm run lint, where the Obsidian plugin's rules check the UI strings and the way events are registered. There is no test runner in package.json and no Obsidian in the sandbox, so the proof is the clean build and lint plus the diff; the pull request names the manual check, copying main.js, manifest.json and styles.css into a vault's .obsidian/plugins/sample-plugin/ folder and right-clicking a note in the file explorer, a tab header and the editor.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add context menu items to this Obsidian plugin. Read package.json, manifest.json, versions.json, version-bump.mjs, tsconfig.json, esbuild.config.mjs, eslint.config.mts, AGENTS.md, src/main.ts, src/settings.ts and .github/workflows/lint.yml first, and read the Workspace.on overloads for file-menu, files-menu and editor-menu in node_modules/obsidian/obsidian.d.ts after npm ci. Write src/menus.ts exporting registerContextMenus(plugin): on file-menu add a Copy link to note item for Markdown files only that uses app.fileManager.generateMarkdownLink, writes to the clipboard and shows a Notice; on files-menu copy one link per selected note; on editor-menu add a Replace selected content item that shares its code with the existing replace-selected command, moved into src/commands.ts, and is disabled when nothing is selected. Register every handler with plugin.registerEvent and call registerContextMenus from onload. Raise minAppVersion in manifest.json to the version that introduced files-menu and explain the versions.json mapping in the pull request. Keep main.ts to lifecycle code, use sentence case for item titles, and do not touch styles.css or the settings tab. Run npm ci, npm run build and npm run lint, and open a pull request that lists the manual check in a vault.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds src/menus.ts and src/commands.ts, trims src/main.ts to the registration calls, and changes one line of manifest.json. Its description lists the three menus the items appear in, the setting that decides the link format, and the lint and build output from the sandbox.
The Node.js build workflow runs on the pull request on Node 20, 22 and 24: npm ci, npm run build and npm run lint, the same commands the agent ran, so a type error under noUncheckedIndexedAccess or a rule from eslint-plugin-obsidianmd shows there as well as in the run's record.
Before merging, a reviewer loads the built plugin in a vault and checks the three menus, decides whether raising minAppVersion to 1.4.10 is acceptable for the plugin's users or whether the files-menu handler should be dropped to keep 1.0.0, and checks that the source argument is not needed to limit the item to the file explorer, since the same item on a tab header is harmless.
Run it on every Obsidian plugin built from the sample
A team that maintains several plugins starts one run per repository from its own server: one POST /o/{org}/sessions each, with this prompt as input and that repository in resources. GET /o/{org}/github lists every repository the Rush GitHub App installation reaches, so a script can pick the ones with a manifest.json at the root. Each run reads its own main.ts, so a plugin that already has a src/commands/ directory gets its menu module beside it, and one whose minAppVersion is already past 1.4.10 gets no manifest change.
A plugin whose feature requests arrive as Linear issues runs the same prompt from an automation in the Project with a linear trigger on issues labelled menu. The trigger adds the issue after the prompt, so an issue that names the item it wants, or the menu it should appear in, reaches the agent with that wording, and the pull request links back to it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The Obsidian API is a typings file, and the facts that matter here, which event carries which arguments and since which app version, are in obsidian.d.ts rather than in the sample's source. The agent reads that file in its own sandbox after npm ci, compiles against it with the strict tsconfig.json, and runs the plugin's own lint rules, so the pull request arrives with the build that lint.yml would run already green.
Every command and its output stay with the run, from the d.ts lines the agent read to the esbuild output, so a reviewer who does not know the menu API can follow why files-menu moved minAppVersion. The same prompt runs across every plugin repository at once, each in its own sandbox with its own pull request.
Frequently asked questions
Why register the handlers with registerEvent?
Workspace.on returns an EventRef, and a handler added without registerEvent keeps running after the plugin is disabled, then runs twice after it is enabled again. registerEvent ties the reference to the plugin's lifetime, which is why onunload can stay empty, as it does in the sample.
Does raising minAppVersion matter?
It decides who can install the release. files-menu is marked since 1.4.10 in the typings, so a vault on an older app would load a plugin that subscribes to an event the app never fires; with minAppVersion at 1.4.10 the app refuses the update instead, and versions.json keeps the last version that still supports 1.0.0 for those users once npm version records the mapping.
Will the item appear on folders?
No. file-menu fires with a TAbstractFile, which is a TFile or a TFolder, and the handler checks instanceof TFile and extension === 'md' before adding anything. A right-click on a folder, an image or a PDF shows the app's own items only.
Can the menu item also be a command?
The editor item already is: it calls the same function as the replace-selected command, so a hotkey and the context menu do the same thing and a change to one cannot drift from the other. The copy-link item could be a command too, taking the active file from workspace.getActiveFile(), which the pull request mentions as a follow-up.
How is it tested without Obsidian in the sandbox?
By the compiler and the linter, which are what the repository runs in CI too: a wrong event signature or a missing await fails tsc under the strict config, and the Obsidian ESLint plugin checks the plugin-specific rules. The behaviour check is manual, in a vault, and the pull request says exactly what to click.
More Obsidian plugin jobs
The same job on other stacks
- Add a Context Menu Item to a Chrome Extension from a Linear Issue (Chrome Extension)
- Add a Context Menu to an Electron App (Electron)
More jobs like this: Hand off a long task
- Add Conversation Memory to a LangGraph Agent (LangGraph)