🏭 Matterbridge AI Plugin Factory

⛔ This project is no longer maintained

The plugin factory has been shut down and this repository is now archived.

We decided to stop the factory in favour of the external integrations built directly into Gladys Assistant, which give a better and more sustainable experience than AI-generated Matterbridge plugins.

What this means:

The factory is no longer running: new issues are not processed, and existing requests will not be generated, fixed or published.

Plugins that were already generated remain available in the repository branches and releases, as-is and unsupported.

The code and documentation below are kept for reference / historical purposes only.

👉 If you want to connect a device or service to Gladys, use the built-in external integrations in Gladys instead.

🌟 Overview (archived)

This factory automates the creation of Matterbridge plugins that bring Matter compatibility to non-Matter smart home devices. Users submit plugin requests via GitHub Issues, and an AI agent (powered by Claude) analyzes existing integrations and generates working plugins.

How It Works

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  User creates   │────▶│  VPS polls or    │────▶│  Claude Code    │
│  GitHub Issue   │     │  receives        │     │  generates      │
│  with template  │     │  webhook         │     │  plugin code    │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                                          │
                                                          ▼
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  User tests &   │◀────│  Artifact ready  │◀────│  Build & pack   │
│  provides       │     │  comment posted  │     │  plugin         │
│  feedback       │     └──────────────────┘     └─────────────────┘
└─────────────────┘
         │
         ▼
┌─────────────────┐
│  AI revises if  │
│  needed         │
└─────────────────┘

🚀 Quick Start

⛔ Not applicable anymore — the factory is stopped, plugin requests are no longer accepted or processed. The steps below are kept for reference.

For Users (Requesting a Plugin)

Go to Issues → New Issue → 🔌 Plugin Request
Fill out the template with:
- Device/service name
- Links to existing integrations (Home Assistant, Node-RED, etc.) - REQUIRED
- Device capabilities you want
- API documentation links
Submit and wait for the AI to process your request
Download the generated plugin artifact and test it
Provide feedback in the issue

For Repository Owners (Setup)

Clone to your Ubuntu VPS
Run the setup script:
```
./scripts/setup-vps.sh
```
Configure .env with your GitHub token
Authenticate Claude Code CLI with your Pro plan:
```
claude login
```
Start the service (webhook) or enable cron (polling)

📋 Requirements for Plugin Requests

✅ What Makes a Good Request

Existing integrations provided - Links to Home Assistant, Node-RED, OpenHAB, or npm packages
Clear API documentation - Official docs or well-documented community resources
Specific capabilities - List exactly what features you need
Standard protocols - HTTP/REST, WebSocket, MQTT, etc.

❌ What Won't Work

Proprietary/undocumented protocols
Devices requiring physical hardware modifications
Services without existing open-source integrations
Requests without reference implementations

🏷️ Label System

Label	Description
`plugin-request`	Initial request tag
`pending-review`	Waiting for AI processing
`in-progress`	AI is generating the plugin
`ready-for-testing`	Plugin artifact available
`needs-revision`	User reported issues
`needs-info`	Missing required information
`completed`	Successfully tested
`error`	Processing failed

📁 Repository Structure

matterbridge-ai-plugin-factory/
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── plugin-request.yml    # Issue template
│   │   └── config.yml            # Template config
│   └── labels.yml                # Label definitions
├── prompts/
│   ├── AGENT_SYSTEM_PROMPT.md    # AI system instructions
│   └── ISSUE_PROCESSING_PROMPT.md # Issue parsing prompt
├── scripts/
│   ├── setup-labels.sh           # Label setup script
│   └── setup-vps.sh              # VPS setup script
├── src/
│   ├── index.js                  # Main entry point
│   ├── process-issue.js          # Issue processing
│   └── webhook-server.js         # Webhook handler
├── plugins/                      # Generated plugins (gitignored)
├── package.json
├── .env.example
└── README.md

⚙️ Configuration

Environment Variables

Variable	Description	Required
`GITHUB_TOKEN`	GitHub PAT with repo access	Yes
`GITHUB_REPO_OWNER`	Repository owner	Yes
`GITHUB_REPO_NAME`	Repository name	Yes
`PLUGINS_OUTPUT_DIR`	Directory for generated plugins	No
`ARTIFACTS_DIR`	Directory for build artifacts	No
`CLAUDE_MODEL`	Claude model to use (e.g. `claude-opus-4-7`)	No
`WEBHOOK_SECRET`	GitHub webhook secret	For webhook mode
`WEBHOOK_PORT`	Webhook server port	For webhook mode
`TELEGRAM_BOT_TOKEN`	Telegram bot token (from @BotFather)	For notifications
`TELEGRAM_CHAT_ID`	Telegram chat ID to send messages to	For notifications

Claude Code CLI Authentication

Authenticate with your Claude Pro plan:

claude login

🔄 Workflow Details

1. Plugin Request Processing

When an issue with plugin-request + pending-review labels is created:

Validates required fields (existing integrations, capabilities)
Posts acknowledgment comment
Runs Claude Code CLI with system prompt
Builds and packages the plugin
Uploads artifact and posts download link

2. Feedback Handling

When users comment on ready-for-testing issues:

Positive feedback → Labels as completed
Negative feedback → Labels as needs-revision, triggers revision workflow

3. Publishing

Maintainers can comment /publish on completed issues to:

Create a PR with the plugin code
Add to the plugins collection

🛠️ Development

Local Testing

# Install dependencies
npm install

# Run webhook server
FACTORY_MODE=webhook node src/index.js

CLI Reference

The main entry point for manual operations is src/process-issue.js:

node src/process-issue.js [issue-number] [flags]

Commands / Flags

Flag	Description
(none)	Process all pending issues (no issue number) or fully generate the given issue
`--fix`	Read latest feedback comment on the issue, regenerate fix, rebuild and re-publish
`--resume`	Resume an interrupted Claude Code session for the issue (continue where left off)
`--publish-only`	Skip AI generation; rebuild & publish the existing local plugin for the issue
`--model <name>`	Override the Claude model (also supports `--model=<name>` and `CLAUDE_MODEL` env)

Examples

# Process all new issues
node src/process-issue.js

# Fully generate plugin for issue #5
node src/process-issue.js 5

# Fix plugin for issue #5 based on latest feedback comment
node src/process-issue.js 5 --fix

# Resume interrupted Claude Code session for issue #5
node src/process-issue.js 5 --resume

# Rebuild & re-publish existing plugin for issue #5 (no AI)
node src/process-issue.js 5 --publish-only

# Use a specific Claude model
node src/process-issue.js 5 --model claude-opus-4-7
node src/process-issue.js 5 --fix --model=claude-opus-4-7
CLAUDE_MODEL=claude-opus-4-7 node src/process-issue.js 5

Hourly CRON (Batch — recommended for large queues)

src/process-batch.js is the smart orchestrator for processing many plugin requests within Claude's 5-hour usage window. Run it hourly via cron; each invocation:

Processes as many issues as possible (fixes first, then new generations)
Stops cleanly when the time budget is nearly exhausted
Detects Claude credit/quota exhaustion and pauses the factory (issues are re-queued, not left stuck in in-progress)
Resumes automatically when the pause expires or on the next cron tick

node src/process-batch.js
node src/process-batch.js --model claude-opus-4-7
node src/process-batch.js --dry-run    # show next job without running
node src/process-batch.js --status     # show pause state
node src/process-batch.js --clear-pause

Tune via environment variables (see .env.example):

Variable	Default	Purpose
`FACTORY_MAX_RUNTIME_MS`	4.5h	Max batch duration
`FACTORY_MIN_JOB_MS`	45min	Min time left to start another plugin
`FACTORY_MAX_PLUGINS`	6	Max plugins per run
`FACTORY_PAUSE_DURATION_MS`	5h	Pause after credits exhausted

Example crontab (see also scripts/crontab.example):

# Matterbridge AI Plugin Factory — batch schedule
# Log files: /home/matterbridge/logs/<job>-YYYY-MM-DD.log

0 * * * * cd /opt/matterbridge-factory && /usr/bin/node src/process-batch.js --model claude-opus-4-8 >> /home/matterbridge/logs/process-batch-$(date +\%Y-\%m-\%d).log 2>&1

This single job replaces separate process-next-issue.js (daily generation) and process-next-fix.js (hourly fixes) cron entries.

Daily CRON (Process One Issue Per Day)

src/process-next-issue.js fetches the oldest open issue with labels plugin-request + pending-review and generates a single plugin, then exits. Perfect for a daily cron:

node src/process-next-issue.js
node src/process-next-issue.js --model claude-opus-4-7

Example crontab (runs every day at 6:00 AM):

0 6 * * * cd /opt/matterbridge-factory && /usr/bin/node src/process-next-issue.js >> /var/log/matterbridge-factory.log 2>&1

Daily CRON (Process One Fix Per Day)

src/process-next-fix.js finds the oldest issue labeled ready-for-testing whose latest comment is from a human (i.e. the user left feedback after the last bot reply) and runs --fix on it, then exits.

node src/process-next-fix.js
node src/process-next-fix.js --model claude-opus-4-7

Example crontab (runs every day at 7:00 AM, one hour after new-issue generation):

0 7 * * * cd /opt/matterbridge-factory && /usr/bin/node src/process-next-fix.js >> /var/log/matterbridge-factory.log 2>&1

Publishing Model

Source code (plugins/issue-N/<plugin-name>/ without dist/, node_modules/, *.tgz) is committed to a branch plugin/issue-N-<plugin-name>, making it reviewable and mergeable.
Build artifact (.tgz) is uploaded to a GitHub Release tagged plugin-issue-N. Re-running --fix or --publish-only replaces the existing asset.

Adding New Device Types

Update prompts/AGENT_SYSTEM_PROMPT.md with:

New Matter device type mappings
Cluster configurations
Example implementations

📚 Resources

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

📄 License

MIT License - see LICENSE for details.

⚠️ Disclaimer

This is an experimental AI-powered tool. Generated plugins:

May require manual adjustments
Should be thoroughly tested before production use
Are provided as-is without warranty

The AI adapts existing open-source integrations - always respect original licenses.

Name		Name	Last commit message	Last commit date
.github		.github
prompts		prompts
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.template.json		tsconfig.template.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation