Overlay config files into git repositories without committing them.https://repoverlay.tylerbutler.com/enhttps://repoverlay.tylerbutler.com/blog/introducing-profiles/https://repoverlay.tylerbutler.com/blog/introducing-profiles/Profiles compose overlays with AI harness capabilities (instructions and plugins) into one loadable unit you can apply to any repo. Sat, 27 Jun 2026 00:00:00 GMT<p>repoverlay 0.17.0 ships <strong>profiles</strong>, the biggest feature I've added since the project began. A profile bundles overlays with AI harness capabilities (instruction files and plugins) into a single named unit you apply to a repo.</p> <div><h2 id="why-i-built-them">Why I built them</h2></div> <p>Overlays solve one problem well: they drop config files into a repo without committing them. But my own setup outgrew plain 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>A profile captures that intent. An overlay describes files to place. A profile describes a working environment: a recipe that references overlays as ingredients and layers harness capabilities on top.</p> <div><h2 id="how-they-work">How they work</h2></div> <p>You define marketplaces and profiles in your repoverlay CCL config, alongside <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>Then you apply it to a specific agent harness. Apply it persistently:</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>Or apply it only for the lifetime of an agent session, with automatic cleanup:</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 carry capabilities through <strong>plugins</strong>, the same Claude-style plugin format the Claude Code ecosystem uses. A plugin ships skills, agents, and MCP servers. When you apply a profile, repoverlay decomposes managed/cacheable plugins and places their parts using each harness's own paths: skills land under <code dir="auto">.agents/skills/</code> for Copilot and <code dir="auto">.claude/skills/</code> for Claude, and MCP servers merge into <code dir="auto">.mcp.json</code>. Delegate or non-cacheable plugins are Claude-delegated and Copilot-skipped with a warning.</p> <p>Profile capabilities are applied to the target repo, not installed globally for the user or machine. New repo-local files are git-excluded when possible, but profiles can also update existing repo files through managed regions or JSON merges, and repoverlay keeps cache and recovery snapshots outside the repo.</p> <div><h2 id="current-limitations">Current limitations</h2></div> <p>Profiles are new. These limits stand today:</p> <ul> <li><strong>Two harnesses.</strong> Profiles target GitHub Copilot and Claude Code. No other agent is supported yet.</li> <li><strong>Delegate install is Claude-only.</strong> The <code dir="auto">delegate</code> install mode, which records a plugin in the harness's own enablement config, currently means something only for Claude. Copilot skips delegate plugins with a warning.</li> <li><strong>Repo scope only.</strong> A profile touches just the repo you apply it to. There is no user- or machine-global profile install, so capabilities you want everywhere need a profile applied per repo.</li> <li><strong>One mode at a time per profile.</strong> A profile already applied persistently cannot also run as an ephemeral session, and vice versa. A lock file guards against concurrent ephemeral sessions and recovers 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 and leaves enough state behind 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> covers defining, inspecting, applying, and removing profiles in full, including marketplaces, managed versus delegate plugins, and how each harness maps capabilities. Give it a read, and tell me what you build.</p>releaseprofiles