Using plugins directly from your repo

Use plugins directly from your repository for codebase-specific context

Instead of publishing plugins to the Tessl Registry, you can also check them directly into your repository. This is a simpler way to distribute plugins together with your code.

When to check plugins into your repo vs using the registry

Check plugins into your repo when:

• You want a simple distribution method - plugins travel automatically with your code
• Context is tightly coupled to this specific codebase
• You don't need version management across multiple projects

Use the Tessl Registry when:

• You need centralized management and updates
• You want evaluation and review workflows
• You need automated distribution across multiple repositories
• You want to keep plugins up to date independently from code changes

How it works

Repository-specific plugins are committed to your codebase and referenced in tessl.json with a file: source. Team members automatically get the plugin when they clone the repo and run tessl install.

Setup

1. Create the plugin in your repository

cd my-repo
tessl plugin new --name myworkspace/my-plugin --path ./plugins/my-plugin

This creates the plugin structure for skills or rules:

my-repo/
├── plugins/my-plugin/
│   ├── .tessl-plugin/plugin.json
│   └── skills
│       └── my-plugin/
│          └── SKILL.md
│   └── rules/                 # This repo's conventions
│       └── standards.md
└── tessl.json

2. Install it locally

Add the plugin to your project by referencing it in tessl.json with a file: source:

tessl install file:./plugins/my-plugin

This updates your tessl.json:

{
  "name": "my-project",
  "dependencies": {
    "myworkspace/my-plugin": {
      "version": "1.0.0",
      "source": "file:./plugins/my-plugin"
    }
  }
}

3. Commit both to version control

git add plugins/my-plugin/ tessl.json
git commit -m "Add repository-specific context plugin"

Team workflow

When team members clone the repository:

git clone <repo>
cd <repo>
tessl install

The plugin installs automatically from the file: source in tessl.json. Everyone gets the same codebase-specific context.

Updating the plugin

Changes to the plugin go through your normal code review process:

1. Edit plugin content (rules, skills)
2. Commit changes: git commit -m "Update architecture docs"
3. Create pull request
4. Team reviews context changes like code changes
5. Merge to main

Team members get updates when they pull and run tessl install.

Benefits

• Versioned with code - plugin evolves alongside the codebase
• Automatic distribution - Team gets context when they clone
• Code review - Changes to patterns/architecture reviewed via PR
• Private - Context stays internal, no publishing needed
• Self-documenting - Codebase carries its own context

Example: Monorepo workspaces

In monorepos, create workspace-specific plugins:

my-monorepo/
├── frontend/
│   ├── plugins/my-plugin/           # Frontend patterns
│   │   ├── .tessl-plugin/plugin.json
│   │   ├── skills/            # Frontend Testing methodology
│   │   └── rules/             # UI standards
│   └── tessl.json             # References frontend plugin
├── backend/
│   ├── plugins/my-plugin/           # Backend patterns
│   │   ├── .tessl-plugin/plugin.json
│   │   ├── skills/            # Database migration process
│   │   └── rules/             # Backend standards
│   └── tessl.json             # References backend plugin
└── shared/
    └── plugins/my-plugin/           # Cross-cutting concerns
        └── skills/            # Unified Code Review

Each workspace's tessl.json references its local plugin and any shared plugins:

{
  "dependencies": {
    "myworkspace/frontend-context": {
      "source": "file:./plugins/my-plugin"
    },
    "myworkspace/shared-context": {
      "source": "file:../shared/plugins/my-plugin"
    }
  }
}

Related

• Developing plugins locally - Create and test plugins with local development workflow before checking them into your repo
• Configuration files - Complete plugin.json reference