Add configuration files to git repositories without commits.https://repoverlay.tylerbutler.com/enhttps://repoverlay.tylerbutler.com/blog/introducing-profiles/https://repoverlay.tylerbutler.com/blog/introducing-profiles/Profiles combine overlays, agent instructions, and plugins into one named configuration. Apply a profile to any repository. Sat, 27 Jun 2026 00:00:00 GMT<p>repoverlay 0.17.0 introduces <strong>profiles</strong>, the biggest feature I have added since the project began. A profile combines overlays, agent instruction files, and plugins into one named configuration that you apply to a repository.</p> <div><h2 id="why-i-built-them">Why I built them</h2></div> <p>Overlays solve one problem well: they add configuration files to a repository without commits. But my own setup needed more than files. I wanted to say "give me everything I need to do Rust work with this agent" and have one command place the overlays, write the agent instructions, and install the skills and MCP servers I rely on.</p> <p>An overlay defines files to add. A profile defines a working environment. It refers to overlays and adds agent capabilities through instructions and plugins.</p> <div><h2 id="how-they-work">How they work</h2></div> <p>Define marketplaces and profiles in your repoverlay CCL configuration, beside <code dir="auto">sources</code>:</p> <div><figure><figcaption></figcaption><pre><code><div><div><span>marketplaces =</span></div></div><div><div><span><span> </span></span><span>=</span></div></div><div><div><span><span> </span></span><span>name = playground</span></div></div><div><div><span><span> </span></span><span>url = obra/claude-plugins</span></div></div><div><div> </div></div><div><div><span>profiles =</span></div></div><div><div><span><span> </span></span><span>rust-dev =</span></div></div><div><div><span><span> </span></span><span>description = Rust development profile</span></div></div><div><div><span><span> </span></span><span>overlays =</span></div></div><div><div><span><span> </span></span><span>= rust-base</span></div></div><div><div><span><span> </span></span><span>= rust-tools</span></div></div><div><div><span><span> </span></span><span>instructions =</span></div></div><div><div><span><span> </span></span><span>=</span></div></div><div><div><span><span> </span></span><span>content =</span></div></div><div><div><span><span> </span></span><span>Be concise in all responses.</span></div></div><div><div><span><span> </span></span><span>plugins =</span></div></div><div><div><span><span> </span></span><span>= playground/rust-dev</span></div></div></code></pre></figure></div> <p>Apply the profile to a specific harness, the application that runs the agent. To keep the profile in place until you remove it, use persistent mode:</p> <div><figure><figcaption><span></span></figcaption><pre><code><div><div><span>repoverlay</span><span> </span><span>profile</span><span> </span><span>apply</span><span> </span><span>rust-dev</span><span> </span><span>--harness</span><span> </span><span>copilot</span></div></div></code></pre></figure></div> <p>To apply it for one agent session with automatic cleanup, use ephemeral mode:</p> <div><figure><figcaption><span></span></figcaption><pre><code><div><div><span>repoverlay</span><span> </span><span>copilot</span><span> </span><span>--profile</span><span> </span><span>rust-dev</span></div></div></code></pre></figure></div> <p>Profiles use <strong>plugins</strong> in the Claude Code plugin format. A plugin supplies skills, agents, and MCP servers. When you apply a profile, repoverlay extracts managed plugins that it can cache. It puts each part in the path for the selected harness.</p> <p>Skills use <code dir="auto">.agents/skills/</code> for Copilot and <code dir="auto">.claude/skills/</code> for Claude. repoverlay merges MCP servers into <code dir="auto">.mcp.json</code>. Claude loads delegate plugins and plugins that repoverlay cannot cache through its own settings. Copilot skips these plugins with a warning.</p> <p>repoverlay applies profile capabilities to the target repository, not globally for the user or machine. It excludes new files from git when possible. Profiles can also update existing files through managed regions or JSON merges. repoverlay keeps cache and recovery snapshots outside the repository.</p> <div><h2 id="current-limitations">Current limitations</h2></div> <p>Profiles have these limits in 0.17.0:</p> <ul> <li>Profiles support GitHub Copilot and Claude Code. They do not support other harnesses yet.</li> <li>Only Claude supports <code dir="auto">delegate</code> install mode. This mode enables a plugin in the harness configuration. Copilot skips delegate plugins with a warning.</li> <li>A profile changes only the repository where you apply it. It does not install capabilities globally for the user or machine. Apply the profile to each repository where you need it.</li> <li><strong>One mode at a time per profile.</strong> A profile already applied persistently cannot also run as an ephemeral session. An active ephemeral profile cannot also be applied persistently. A lock file prevents concurrent ephemeral sessions. repoverlay recovers the lock automatically if a previous session was killed.</li> <li><strong>Interrupted cleanup needs a manual step.</strong> If an ephemeral session is interrupted and cleanup fails, repoverlay reports the error. It keeps enough state for you to finish with <code dir="auto">repoverlay profile remove</code>.</li> </ul> <div><h2 id="try-them">Try them</h2></div> <p>The <a href="https://repoverlay.tylerbutler.com/guides/profiles/">profiles guide</a> explains how to define, inspect, apply, and remove profiles. It covers marketplaces, managed and delegate plugins, and the capability paths for each harness. Read the guide, and tell me what you build.</p>releaseprofiles