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

Main Component Types

src/tools/

src/models/

src/credentials/

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

Identify the Scenario

Scenario A — New project from scratch: Read:

1. references/quick-start.md

2. references/core-concepts.md

3. 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

• Understanding

  context.files

  →

  references/tool-plugin.md

Scenario C — Publishing: Read

references/publishing.md

Workflow

Step 1: Clarify intent

Determine:

1. Is this a new plugin or an existing plugin?
2. Does it need tools, models, credentials, or some combination?
3. Does it need file input/output (

   file_ref

   ) handling?
4. Does it need advanced declarative parameters such as

   resource_locator

   or

   resource_mapper

   ?
5. Is TypeScript acceptable? It is the recommended and best-supported path.

Step 2: Verify the Atomemo CLI

Before running

atomemo

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

atomemo auth login
atomemo plugin init
cd <plugin-name>
atomemo plugin refresh-key
bun install
bun run dev
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()

Step 5: Declarative parameters and file handling

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

• references/declarative-parameters.md

• references/declarative-parameters-examples.md

When a tool handles files, use

context.files

Step 6: Internationalization

All user-facing strings support i18n. Prefer the

t()

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

bun run ./dist

Step 8: Publish (when ready)

See

references/publishing.md

1. bun run release

   — validates, builds, syncs versions
2. Fork

   atomemo-official-plugins

   repo
3. Add plugin to

   plugins/<your-plugin-name>/

4. Open PR with title

   feat(plugin): add <your-plugin-name>

Reference Files

Load these on demand based on what the developer needs:

references/quick-start.md

references/core-concepts.md

references/tool-plugin.md

references/model-plugin.md

references/credential.md

references/declarative-parameters.md

references/declarative-parameters-examples.md

references/publishing.md

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

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