repoverlay 0.17.1 is available.Release notes

Quick start

Start with one instruction file for your agent. Apply it, examine the result, then remove it. This example works offline after installation. It needs no overlay sources or plugins.

Install

Choose the package manager you already use:

Homebrew
Cargo

For macOS or Linux with Homebrew installed:

brew install tylerbutler/tap/repoverlay

Build from source with Rust 1.91 or later:

cargo install repoverlay

On Windows without Rust, use the PowerShell installer. See Installation for prebuilt binaries and other methods.

Confirm the binary is on your PATH:

repoverlay --version

Try it

Use the rust-dev profile from the homepage for this example. A profile is a reusable setup for an agent. An overlay is a set of files. Use the second tab if you only need files, not agent instructions.

Profiles (recommended)
File overlays

This example uses Claude Code. For GitHub Copilot, replace claude with copilot in both the apply and remove commands. Copilot uses AGENTS.md instead of CLAUDE.md for instructions.

Define the profile once

Create ~/.config/repoverlay/config.ccl, including its parent directory if needed. If you already have a profiles section, add rust-dev under it instead of replacing your configuration.
```
profiles =
  rust-dev =
    description = My first agent profile
    instructions =
      =
        content =
          Be concise in all responses.
```
This profile has one instruction and no external dependencies. Keep it in your global configuration to reuse it in other repositories.
Apply it in a git repository

In your terminal, go to the repository where you want these instructions. Then run:
Terminal window
```
repoverlay profile apply rust-dev --harness claude
```
repoverlay adds the instruction to a managed section in CLAUDE.md. It excludes a new file through .git/info/exclude. If the file is already tracked, git still shows its changes. Review them before you commit.
Inspect the result
Terminal window
```
repoverlay profile status
```
Look for rust-dev and the claude harness. Open CLAUDE.md to see Be concise in all responses. in the managed section.
Terminal window
```
git diff
```
A newly excluded file will not appear in this diff. An existing tracked instruction file will show the added section.
Remove the example
Terminal window
```
repoverlay profile remove rust-dev --harness claude
```
repoverlay removes the managed instruction. Your profile definition stays in the global configuration so you can apply it again. Run repoverlay profile status to confirm it is no longer applied.

An overlay adds a set of files directly to a repository. It does not need a profile or a harness.

Open a git repository

In your terminal, go to the repository where you want the files. Check its state:
Terminal window
```
repoverlay status
```
Browse and apply an overlay

This step needs a network connection:
Terminal window
```
repoverlay browse tylerbutler
```
Select an overlay from the list. Review the files before you apply it. repoverlay can save the source for future use.
Inspect the result
Terminal window
```
repoverlay status
```
The output lists the applied overlay's name, source, and managed files.
Remove the overlay

Use the name from the status output in place of my-overlay:
Terminal window
```
repoverlay remove my-overlay
```

If something goes wrong

What you see	What to do
`repoverlay` is not found	Restart your terminal and check that the install directory is on your PATH. See Installation.
The profile cannot be found	Check that `rust-dev` is under `profiles` in `~/.config/repoverlay/config.ccl`. Run `repoverlay profile list` to see configured names.
The directory is not a git repository	Go to an existing git checkout before you apply the profile.
Changes appear in `git diff`	An instruction file was already tracked. Review the managed section, or remove the profile with the same name and harness.

Next steps

Add skills, agents, and MCP servers with plugins when you need a larger setup. To manage plain configuration files, learn about creating and sharing overlays.