Configuration files

Tile configuration

tile.json

The tile.json file is the configuration file for a tile. It includes important metadata that helps Tessl identify, version and describe tiles.

Here's an example tile.json:

{
  "name": "tessl/npm-shadcn",
  "version": "3.6.0",
  "docs": "docs/index.md",
  "describes": "pkg:npm/[email protected]",
  "summary": "CLI and programmatic API for adding UI components from registries. Supports multi-registry, dependency resolution, code transformation, and MCP integration for AI assistants.",
  "private": false
}

The tile.json also includes any information about agent steering. Tiles can include agent steering as a complement to the main content of the tile, or they can be steering-only.

For example, here's what the tile.json for a private, steering-only tile might look like:

  {
    "name": "myorg/code-style",
    "version": "0.0.1",
    "summary": "TypeScript code style guidelines for MyOrg",
    "private": true,
    "steering": {
      "naming": {
        "rules": "steering/naming.md"
      },
      "exceptions": {
        "exceptions": "steering/exceptions.md"
      }
    }
  }

And here's a tile that includes steering as a complement:

  {
    "name": "myorg/queue-connector",
    "version": "1.2.0",
    "summary": "Message queue SDK and its best practices for MyOrg",
    "docs": "docs/index.md",
    "steering": {
      "dead-letter-handling": {
        "rules": "steering/dead-letter-handling.md"
      },
      "dev-mode": {
        "rules": "steering/dev-mode.md"
      }
    }
  }

tile.json supports a number of straightforwardly-named fields:

name (string, required): Name for the tile in workspace/tile-name format

version (string, required): Semantic version of the tile

summary (string, required): Brief description of the tile

docs (string, optional*): Path to tile documentation entrypoint (e.g. "docs/index.md")

describes (string, optional*): Package URL of the external package this tile documents.

steering (object, optional*): An object mapping steering "rule" names to their markdown files. Used to provide subjective guidance and instructions to agents, rather than technical documentation.

*A note on tile.json validation:

1. If describes is set, docs is required

2. Either docs or steering must be present in tile.json. As demonstrated above, you can also include both.

Project configuration

tessl.json

The tessl.json file is the manifest for your project's tile dependencies. It specifies which tiles are installed and their versions:

{
  "name": "my-project",
  "dependencies": {
    "workspace/tile-name": {
      "version": "1.0.0"
    }
  }
}

This file is created automatically when you run tessl init or tessl install. Tessl manages the dependencies in this file as you install or uninstall tiles.

.tessl directory

The .tessl directory contains Tessl's configuration and cached data:

.tessl/
|-- .gitignore                  # Ignores tiles/ and RULES.md
|-- tiles/                      # Downloaded tiles (not committed to git)
|   `-- workspace/
|       `-- tile-name/
|           |-- tile.json
|           `-- docs/
`-- RULES.md                    # Generated steering for agents (not committed to git)

The .tessl/.gitignore file is automatically created to exclude the tiles/ directory and RULES.md from version control, as these are generated files that can be reinstalled from tessl.json.

Agent steering files

Tessl creates and updates steering files for AI coding agents to help them understand your project context and installed tiles. The location and format of these files varies by agent:

• Cursor:

  • .cursor/rules/tessl__*.mdc - Tile-specific steering rules (auto-generated, not committed to git)

  • .cursor/rules/tessl_context.mdc - Instructions for gathering context from Tessl MCP

• Claude Code:

  • CLAUDE.md - Context file with instructions for gathering context from Tessl MCP

  • .tessl/RULES.md - Consolidated steering from all installed tiles

  • AGENTS.md - If this file exists, Tessl adds a reference to .tessl/RULES.md

These files are created when you run tessl init --agent <agent-name> or when Tessl auto-detects an agent in your project.

MCP configuration files

When configuring AI agents, Tessl adds MCP (Model Context Protocol) server configuration to connect the agent to Tessl's MCP server. The location varies by agent:

• Cursor: .cursor/mcp.json

• Claude Code: .mcp.json in the project root

These files configure the agent to run tessl mcp start as an MCP server, enabling the agent to access Tessl's tools and context.

AGENTS.md

The AGENTS.md file provides project context to AI coding agents. This file is similar to CLAUDE.md and other agent context files used by various AI coding assistants.

Note: Tessl does not create or manage AGENTS.md directly. However, if AGENTS.md exists in your project, Tessl will automatically add a reference to .tessl/RULES.md when you configure an agent with tessl init. This allows your agent to access tile-specific guidance and context.

If you're using AGENTS.md in your project:

• Add your own project context, coding conventions, and patterns

• Tessl will append a section linking to .tessl/RULES.md (marked with <!-- tessl-managed -->)

• The content is used by AI agents during code generation

User preferences

Tessl stores user preferences globally to customize your experience. You can view and modify these preferences using the tessl config commands.

Available preferences

• shareUsageData - Whether to share telemetry and usage data with Tessl (defaults to true)

• agents - Which agents to configure on tessl init (default to auto-detect when empty); see supported agents in tessl init --help .

Managing preferences

View all current preferences:

tessl config get

View a specific preference:

tessl config get shareUsageData

Set a preference:

tessl config set shareUsageData false

Opting out of telemetry

To opt out of sharing telemetry and usage data:

tessl config set shareUsageData false

For more information about data collection, see Sharing Usage Data.