# Cletus plugins

Build plugins for Cletus, the desktop AI assistant for engineering and
manufacturing teams, and publish them in the Eidonix plugin store.

## Status

- **Ready now:** the specification, the worker SDK (`sdk/pluginsdk`) and the
  `cletus-plugin` tool, which creates a plugin, checks it the way the store
  does and runs it under a test host. You can build and test a worker and
  its chat tools today.
- **Later releases:**
  - screens;
  - more host services (AI models, vision, speech, camera and microphone,
    saved connections, a secret store);
  - loading your development build into Cletus itself;
  - store submissions.

## What a plugin is

A plugin is a Go program (the **worker**) that adds chat tools Cletus's AI
can use, and services other plugins can call. Through the host it can:

- open and save files the user chooses;
- read and write the user's shared folders;
- start background Cletus runs over the user's files;
- connect to machines, databases and services the user sets up, or to
  servers it names.

## Start here

If you work with a coding agent (Claude Code, Codex or similar), point it at
this repository and tell it what you want to build. `AGENTS.md` holds the
rules it must follow, and it reads the rest from there.

If you work by hand, read in this order:

1. `docs/specification.md`: the package, `plugin.json`, permissions, the
   worker and services.
2. `docs/host-api.md`: every host method.
3. `docs/style-guide.md`: how Cletus plugins read and behave.
4. `docs/patterns.md`: how to build common kinds of plugin.
5. `docs/submission.md` and `docs/review-checklist.md`: how publishing will
   work.

## Tools

Needs Go 1.24 or later.

```sh
go install git.eidonix.com/eidonix/cletus-plugins/sdk/cmd/cletus-plugin@latest

cletus-plugin new acme.gauge-check                  # a working plugin from the template
cd gauge-check
cletus-plugin check                                 # the store's automated checks
cletus-plugin run tools                             # list the chat tools
cletus-plugin run invoke gauge_check_count_lines '{"path":"sample.txt"}'
```

`run` starts your worker under a test host that answers host calls the way
Cletus does, enforces your declared permissions, and prints every host call
your worker makes.

## Publishing

Plugins reach users only through the Eidonix plugin store, and Cletus
installs nothing else. You'll submit source code; Eidonix builds it, checks
it, reviews it and signs it. See `docs/submission.md`.

Questions, and requests for a publisher account: support@eidonix.com

## Licence

Apache License 2.0 (`LICENSE`). The names Cletus and Eidonix are not
licensed.