Atomemo Plugin Development

You are helping a developer build an Atomemo plugin. Atomemo is Choiceform's workflow automation platform. Plugins extend it with new Tools (external API calls, functions) and Models (LLM definitions).

Architecture Overview

Host (Atomemo App)
      ↕  (secure, decoupled)
  Plugin Hub              ← intermediary, handles security + comms
      ↕
  Your Plugin             ← SDK + your business logic

• Plugin Hub: Prevents direct host↔plugin contact; protects both sides
• SDK (

  @choiceopen/atomemo-plugin-sdk-js

  ): Handles communication, types, i18n, lifecycle
• CLI (

  @choiceopen/atomemo-plugin-cli

  ): Project scaffolding, dev server, build, publish

Two Plugin Types

src/tools/

src/models/

A single plugin can contain multiple Tools AND multiple Models.

Identify the Scenario

Scenario A — New project from scratch: Read

references/quick-start.md

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

Scenario C — Publishing: Read

references/publishing.md

Workflow

Step 1: Clarify intent

Ask (or infer from context):

1. New project or adding to an existing one?
2. Tool plugin, Model plugin, or both?
3. Does it need credentials (API keys, tokens)?
4. Target language? (TypeScript strongly recommended)

Step 2: Verify the Atomemo CLI

Before running any

atomemo

Check if installed:

atomemo --version

If the command is not found, install it first:

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

Check if up to date:

# Get the currently installed version
atomemo --version

# Get the latest published version
npm view @choiceopen/atomemo-plugin-cli version

If the versions differ, upgrade before proceeding:

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

Both of these checks are safe to run automatically. Confirm the upgrade with the user before running it — it modifies their global environment.

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

See

references/quick-start.md

atomemo auth login
atomemo plugin init        # interactive: name, description, language
cd <plugin-name>
atomemo plugin refresh-key
bun install
bun run build
bun run ./dist             # connects to Plugin Hub

Step 4: Implement plugin components

For each component:

1. Create the definition file in the appropriate directory
2. Implement the required interface (

   satisfies ToolDefinition

   /

   ModelDefinition

   /

   CredentialDefinition

   )
3. Register in

   src/index.ts

Project file layout:

src/
  index.ts           ← entry point; register everything here
  tools/             ← one file per tool
  models/            ← one file per model
  credentials/       ← one file per credential type
  i18n/              ← translations (auto-generated by SDK)

Registration pattern (index.ts):

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: Internationalization

All user-facing strings support i18n. Always use the

t()

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

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

Only fall back to inline

I18nText

{ en_US: "...", zh_Hans: "..." }

t()

Step 6: Test locally

bun run build        # build the plugin
bun run ./dist       # connect to Plugin Hub

bun run dev

bun run ./dist

Successful connection shows:

status: ok, response: { success: true }

Step 7: 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/tool-plugin.md

references/model-plugin.md

references/credential.md

references/declarative-parameters.md

references/declarative-parameters-examples.md

references/publishing.md

CLI Automation

When helping a developer set up a new project, you can execute CLI commands on their behalf using the Bash tool — except for

atomemo auth login

What you can run automatically:

# CLI environment check — always run these before any atomemo command:
atomemo --version                                  # check if installed; install if missing
npm view @choiceopen/atomemo-plugin-cli version    # check latest version

# Install or upgrade (confirm with user before running — modifies global environment):
npm install @choiceopen/atomemo-plugin-cli --global
npm install @choiceopen/atomemo-plugin-cli@latest --global

# Non-interactive project init — provide all flags to skip prompts:
atomemo plugin init --no-interactive -n <plugin-name> -d "<description>" -l typescript

# These are always non-interactive:
atomemo plugin refresh-key
bun install
bun run build
bun run ./dist    # connects to Plugin Hub; bun run dev only rebuilds, does not connect

What requires user action:

atomemo auth login

Always confirm with the user before running CLI commands that create files or modify their environment.

Common Mistakes to Avoid

• Plugin naming: Must match

  /^[a-z][a-z0-9_-]{2,62}[a-z0-9]$/

  — lowercase only, 4–64 chars, starts with a letter, ends with a letter or digit, no consecutive special chars
• Hardcoded secrets: Never hardcode API keys; always use the Credentials system
• Model naming: Must follow

  provider/model_name

  format (4–64 chars, alphanumeric/underscore/hyphen/slash only)
• Dev key expiry: Debug API key expires after 24 hours; run

  atomemo plugin refresh-key

  to renew
• Missing registration: Every tool/model/credential must be registered in

  src/index.ts