Using tiles directly from your repo

Use tiles directly from your repository for codebase-specific context

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

When to check tiles into your repo vs using the registry

Check tiles into your repo when:

• You want a simple distribution method - tiles 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 tiles up to date independently from code changes

How it works

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

Setup

1. Create the tile in your repository

cd my-repo
tessl tile new --name myworkspace/my-tile --path ./tiles/my-tile

This creates the tile structure:

my-repo/
├── tiles/my-tile/
│   ├── tile.json
│   ├── docs/                  # This repo's architecture
│   │   └── index.md
│   └── rules/                 # This repo's conventions
│       └── standards.md
└── tessl.json

2. Install it locally

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

tessl install file:./tiles/my-tile

This updates your tessl.json:

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

3. Commit both to version control

git add tiles/my-tile/ tessl.json
git commit -m "Add repository-specific context tile"

Team workflow

When team members clone the repository:

git clone <repo>
cd <repo>
tessl install

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

Updating the tile

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

1. Edit tile content (docs, 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 - Tile 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 tiles:

my-monorepo/
├── frontend/
│   ├── tiles/my-tile/           # Frontend patterns
│   │   ├── tile.json
│   │   ├── docs/              # React patterns
│   │   └── rules/             # UI standards
│   └── tessl.json             # References frontend tile
├── backend/
│   ├── tiles/my-tile/           # Backend patterns
│   │   ├── tile.json
│   │   ├── docs/              # API patterns
│   │   └── rules/             # Backend standards
│   └── tessl.json             # References backend tile
└── shared/
    └── tiles/my-tile/           # Cross-cutting concerns
        └── docs/              # Service communication

Each workspace's tessl.json references its local tile and any shared tiles:

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

Related

• Developing tiles locally - Create and test tiles with local development workflow before checking them into your repo

• Configuration files - Complete tile.json reference