Atomemo Plugin Development

You are helping a developer build an Atomemo plugin. Atomemo plugins extend the platform with:

Tools: External API wrappers or local functions
Models: LLM definitions with capabilities, pricing, and parameter overrides
Credentials: Secure authentication definitions used by tools and models

Architecture Overview

Host (Atomemo App)
      ↕
  Plugin Hub          ← secure intermediary for lifecycle + message routing
      ↕
  Your Plugin         ← SDK + your business logic

Plugin Hub decouples the host and plugin and handles communication security
SDK (@choiceopen/atomemo-plugin-sdk-js) provides createPlugin, runtime context, file helpers, schemas, and type-safe plugin definitions
CLI (@choiceopen/atomemo-plugin-cli) scaffolds projects and manages auth plus debug setup

Read references/core-concepts.md first when the developer needs architectural context.

Main Component Types

Type	Purpose	Source directory
Tool	Invokes third-party services or local business logic	`src/tools/`
Model	Declares an LLM and its capabilities	`src/models/`
Credential	Collects and transforms authentication data	`src/credentials/`

A single plugin can contain multiple tools, models, and credentials.

Identify the Scenario

Scenario A — New project from scratch: Read:

references/quick-start.md
references/core-concepts.md
The relevant implementation guides below

Scenario B — Adding to an existing project: Read the relevant guide directly:

Adding a Tool → references/tool-plugin.md
Adding a Model → references/model-plugin.md
Adding Credentials → references/credential.md
Configuring Parameters → references/declarative-parameters.md, then load the specific sub-page(s) it points to for the task at hand
Understanding context.files → references/tool-plugin.md

Scenario C — Publishing: Read references/publishing.md.

Workflow

Step 1: Clarify intent

Determine:

Is this a new plugin or an existing plugin?
Does it need tools, models, credentials, or some combination?
Does it need file input/output (file_ref) handling?
Does it need advanced declarative parameters such as resource_locator or resource_mapper?
Is TypeScript acceptable? It is the recommended and best-supported path.

Step 2: Verify the Atomemo CLI

Before running atomemo commands, check whether the CLI is installed:

atomemo --version

If missing, install it:

npm install @choiceopen/atomemo-plugin-cli --global

If you need to compare against the latest published CLI:

atomemo --version
npm view @choiceopen/atomemo-plugin-cli version

Only upgrade after confirming with the user:

npm install @choiceopen/atomemo-plugin-cli@latest --global

Checking versions is safe to automate. Installing or upgrading is not.

Step 3: Set up the project (new projects only)

See references/quick-start.md. The normal sequence is:

atomemo auth login
atomemo plugin init
cd <plugin-name>
atomemo plugin refresh-key
bun install

Then in two separate terminals:

# Terminal 1 — watch mode (rebuilds on save, does NOT connect to Hub)
bun run dev

# Terminal 2 — connects to Plugin Hub
bun run ./dist

Step 4: Implement plugin components

Create definitions in the appropriate directories and register them in src/index.ts.

Typical project layout:

src/
  index.ts
  tools/
  models/
  credentials/
  i18n/

Registration pattern:

import { createPlugin } from "@choiceopen/atomemo-plugin-sdk-js"
import { myTool } from "./tools/my-tool"
import { myModel } from "./models/my-model"
import { myCredential } from "./credentials/my-credential"

const plugin = await createPlugin({ /* manifest fields */ })
plugin.addTool(myTool)
plugin.addModel(myModel)
plugin.addCredential(myCredential)
plugin.run()

For createPlugin(...) metadata, do not invent a brand-new manifest shape from memory. Open the existing src/index.ts first and preserve the scaffolded structure unless the developer explicitly wants to change plugin metadata. Keep the metadata used by createPlugin(...) aligned with package.json and README details; see references/core-concepts.md for entrypoint guidance and references/publishing.md for the metadata consistency requirement.

Step 5: Declarative parameters and file handling

Use declarative parameters for user input and configuration. Start with:

references/declarative-parameters.md — index only; read this to find the right sub-page, then load the specific sub-file(s) you need
references/declarative-parameters-overview-and-core-concepts.md — load this alongside the index for foundational knowledge
references/declarative-parameters-examples.md

Then load the focused page that matches the question:

Need allowed type values or plugin-type support → references/declarative-parameters-property-type-overview.md
Need common schema keys such as required, display, ui, depends_on, or decoder → references/declarative-parameters-property-base.md
Need the full definition of a scalar, object, array, or special property type → the matching basic/composite/special type page
Need UI component names or default rendering behavior → references/declarative-parameters-property-ui-reference.md and references/declarative-parameters-default-ui-behavior.md
Need dynamic visibility rules → references/declarative-parameters-display-condition.md
Need Tool-only remote selection or mapping flows → references/declarative-parameters-resource-locator.md and references/declarative-parameters-resource-mapper.md
Need examples to adapt quickly → references/declarative-parameters-examples.md

When a tool handles files, use context.files helpers instead of manually treating file references as plain JSON.

Step 6: Internationalization

All user-facing strings support i18n. Prefer the t() helper:

import { t } from "../i18n/i18n-node"

display_name: t("WEATHER_TOOL_DISPLAY_NAME"),
description: t("WEATHER_TOOL_DESCRIPTION"),

Step 7: Test locally

bun run build
bun run ./dist

bun run dev rebuilds in watch mode but does not connect to Plugin Hub — run it in a separate terminal from bun run ./dist, which creates the actual Hub connection.

Step 8: Publish (when ready)

See references/publishing.md. Key steps:

bun run release — validates, builds, syncs versions
Fork atomemo-official-plugins repo
Add plugin to plugins/<your-plugin-name>/
Open PR with title feat(plugin): add <your-plugin-name>

Reference Files

Load these on demand based on what the developer needs:

File	When to read
`references/quick-start.md`	New project setup
`references/core-concepts.md`	Architecture, plugin entrypoint, metadata consistency, lifecycle
`references/tool-plugin.md`	Building Tool plugins
`references/model-plugin.md`	Building Model plugins
`references/credential.md`	Defining credentials
`references/declarative-parameters.md`	Parameter routing guide + TOC; use it to choose the correct focused reference page
`references/declarative-parameters-examples.md`	Ready-to-copy parameter examples
`references/publishing.md`	Publishing to the marketplace

CLI Automation

You can automate most CLI steps except the browser-based login flow.

Safe commands to run automatically:

atomemo --version
npm view @choiceopen/atomemo-plugin-cli version
atomemo plugin init --no-interactive -n <plugin-name> -d "<description>" -l typescript
atomemo plugin refresh-key
bun install
bun run build
bun run ./dist

Commands that require user action:

atomemo auth login uses a device authorization flow. You cannot automate it. Guide the user through the browser verification step and wait for confirmation.

Common Mistakes to Avoid

Plugin names must match /^[a-z][a-z0-9_-]{2,62}[a-z0-9]$/
Never hardcode secrets
Model names should follow provider/model_name
Debug API keys expire; refresh with atomemo plugin refresh-key
Tools that handle files should use context.files
Every tool, model, and credential must be registered in src/index.ts

atomemo-plugin-development