Skip to main content

Plugins

A plugin is a Python package that adds to Codee without changing it. It can:

  • ship skills. Codee links them into .claude/skills, keeps them out of Git, and shows them read-only on the Skills page.
  • add skill triggers. A new trigger shows up in the Skill type picker with its own fields, and the executor ticks it every 60 seconds, or at the trigger's own POLL_SECONDS.
  • ask for settings. They are filled in on the plugin's card on the Plugins page.

The Plugins page​

Plugins in the sidebar lists every installed plugin with its package and version, the triggers and skills it adds, and its settings. Each one has an on/off switch:

  • Off removes its skills from .claude/skills straight away, and the executor stops ticking its triggers from its next tick on. No restart is needed. Its settings are kept, and so are your skills that use its triggers; they just don't run while it is off.
  • On brings both back.

The switch is stored as disabled_plugins in .codee/settings.json. A plugin that failed to load is listed at the top of the page with the reason.

Installing one​

Codee finds plugins through the codee.plugins entry point, so installing one is uv add in your Codee project, then restarting codee-start:

uv add codee-acme

A plugin that lives in a folder of your project is added the same way, as a path dependency in the project's pyproject.toml:

[project]
dependencies = ["codee-agent", "codee-acme"]

[tool.uv.sources]
codee-acme = { path = "plugins/acme", editable = true }

Writing one​

# plugins/acme/pyproject.toml
[project]
name = "codee-acme"
version = "0.1.0"

[project.entry-points."codee.plugins"]
acme = "codee_acme.plugin:AcmePlugin"
# plugins/acme/src/codee_acme/plugin.py
from pathlib import Path

from codee_plugin_abstract.plugin import (
AbstractCodeePlugin, AbstractSkillTrigger, PluginField)


class WebhookTrigger(AbstractSkillTrigger):
TYPE = "webhook" # x-codee-trigger: webhook
SKILL_FIELDS = [ # shown in the skill editor
PluginField("x-acme-path", "Webhook path", placeholder="/deploy"),
]

def tick(self, skills, run_skill, settings):
for skill in skills:
if called(settings["base_url"], skill.fields["x-acme-path"]):
run_skill(skill, skill.body) # records the run on the Runs page


class AcmePlugin(AbstractCodeePlugin):
NAME = "acme"
DISPLAY_NAME = "Acme"
SETTINGS_FIELDS = [ # shown on the Plugins page
PluginField("base_url", "Acme URL"),
PluginField("api_token", "Acme API token", secret=True),
]

def skills_dir(self):
return Path(__file__).parent / "skills" # <slug>/SKILL.md inside

def triggers(self):
return [WebhookTrigger()]

More a plugin can declare​

MemberOnWhat it does
DESCRIPTIONtriggerMarkdown shown above the skill body when the trigger is picked, in a panel the reader can collapse: what the skill receives, which placeholders it can use.
PluginField(..., multiline=True)fieldA text area instead of a one-line input; saved to frontmatter as a YAML block.
PluginField(..., searchable=True) + search_field(), describe_field_values()field, pluginA picker instead of an input: the user searches (search_field returns FieldOption(value, label)) and picks any number, shown as chips by label. Stored one per line as <value> # <label>; the trigger gets only the values. describe_field_values names values stored without a label.
PluginField(..., choices=((value, label), ...), default=..., visible_when=(key, value))fieldA select of fixed choices; a value to start from; a field shown only while another field of the same form holds a given value (a mode's options, a provider's credentials).
POLL_SECONDStriggerHow often tick is called; 60 by default, never below 10.
data_dirpluginA folder of the plugin's own (.codee/plugins/<NAME>), set by Codee, for tokens and polling state.
SUPPORTS_SIGN_IN + sign_in_url(), complete_sign_in(), signed_in_as(), sign_out()pluginSign in to a service as a user (OAuth). Codee puts Sign in on the plugin's card, serves the callback at /api/oauth/plugins/<NAME>/callback, and checks the state it sent; the plugin exchanges the code and keeps the tokens in data_dir. Raise SignInError to show a message.

Built-in plugins​

Two plugins ship inside codee-agent, so there is nothing to install. They are still plugins: each has its card on the Plugins page, its settings and its on/off switch.

  • Microsoft Teams (teams, in src/codee_teams): the Teams trigger.
  • Files (files, in src/codee_files): serves a folder of this host at /p/files/<path> on the admin UI, a folder URL as its index.html. The folder is .codee/plugins/files unless its card names another. Off until you turn it on, because being on shows the folder to everyone who can open the admin UI.

If an older separately installed copy (codee-teams) is still in your project, the built-in one is used and the copy is ignored; uv remove codee-teams when convenient.

Plugins kept in this repository​

Plugins that live in the Codee repository sit under plugins/<name>/, each its own package. The repository is a uv workspace, so uv sync --all-packages installs them next to Codee for development, and pytest runs their tests with Codee's. None of them is part of codee-agent: each is released and installed on its own.

Rules:

  • A skill field's key is the frontmatter key its value is written under. Prefix it with your plugin's name (x-acme-…) so it can't clash with another plugin.
  • A trigger TYPE can't reuse issue, cron, email, aws-sqs, or another plugin's. A clash, or a plugin that fails to import, is reported on the Plugins page and skipped.
  • tick runs on the executor's plugin scheduler, a thread shared by every plugin trigger, so keep it short and start long work (an agent run) in a thread of its own; it is only called while Codee isn't paused and at least one skill uses the trigger.
  • run_skill raises if the agent run failed or was killed (after recording it), so you can decide whether the event that fired it is used up.
  • A plugin skill whose name matches a skill of your project is not installed: the project's skill wins.

Conflicting issue triggers​

Two issue-triggered skills conflict when they trigger on the same work item type in a common status, whether they come from a plugin or from your project. The Skills page marks both skills and shows the number of conflicting skills next to Skills in the sidebar. Until the conflict is resolved, Codee runs neither of them for that status.