1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223

<p align="center">
  <img src="packages/ui/public/favicon.svg" alt="panoplie" width="96" height="96">
</p>

<h1 align="center">panoplie</h1>

<p align="center">
  One place to manage the skills, rules, MCP servers, hooks and subagents of your coding agents,<br>
  across all your projects.
</p>

<p align="center">
  <img src="media/screenshots/project.png" alt="A project in panoplie: presets, items and their sync state" width="900">
</p>

---

## Why panoplie

Coding agents are configured through a growing pile of files: `SKILL.md` folders, rules, `.mcp.json`, `settings.json`, `AGENTS.md`, `config.toml`… Once you use them on more than a couple of projects, three problems show up:

- **Lost work.** A skill or a rule written in one project is not available in the next one, so it gets copied by hand, then the copies drift apart.
- **Global pollution.** Putting everything in `~/.claude` or `~/.codex` makes every item load in every session of every project. It costs context and triggers skills where they make no sense.
- **No overview.** Nothing tells you what exists, where it is used, and which copy is the right one.

panoplie fixes this with a **catalog** (a git repository holding your items) and a local UI that **writes the right files into each project**, for each agent, and keeps them in sync.

## How it works

```
                 ┌────────────── Catalog (git repo) ──────────────┐
                 │  skills/  rules/  mcp/  hooks/  agents/        │
                 │  presets/  nuxt-saas = nuxt + tailwind + …     │
                 └────────────────────────┬───────────────────────┘
                                          │  you pick presets and items per project
                    ┌─────────────────────┼─────────────────────┐
                    ▼                     ▼                     ▼
               acme-shop/            billing-api/             blog/
          .claude/skills/…        .agents/skills/…      .claude/skills/…
          .agents/skills/…        AGENTS.md (block)     .claude/rules/…
          .mcp.json               .codex/config.toml    panoplie.json
          panoplie.json             panoplie.json
```

- **The catalog is the source of truth.** It is a plain git repository, hosted wherever you like (or nowhere). Sync it across your machines or share it with your team.
- **Enabling an item writes real files into the project**, where each agent expects them. The project then works without panoplie, for you and for anyone who clones it. You commit those files with the project.
- **Nothing is written until you apply.** Every change goes through a review, and a file edited by hand is never overwritten without asking.
- **Global stays minimal.** Keep in `~` only what you really use everywhere, and move the rest to the projects that need it.

### Vocabulary

| Term | Meaning |
|---|---|
| **Item** | A skill, rule, MCP server, hook or subagent. |
| **Catalog** | Your library of items and presets, stored in a git repository. |
| **Preset** | A named bundle of items, for example *nuxt-saas* = Nuxt and Tailwind skills, TypeScript rules and the Nuxt docs MCP server. A preset can include other presets. |
| **Project** | A code folder you added to panoplie. |
| **Global** | Your user-level agent configuration (`~/.claude`, `~/.agents`, `~/.codex`). It loads in every project. |
| **Automatic / on demand** | Skill mode. *Automatic*: the agent sees the skill and uses it when it thinks it is relevant. *On demand*: the skill is installed but hidden from the agent until you call it yourself (`/name` in Claude Code, `$name` in Codex). Ideal for large families of niche skills you want at hand without paying for them in context. |

## A tour

### Projects: choose what each project uses

Pick presets, add or exclude single items, switch skills between automatic and on demand, and hide Global items you do not want in this project. Each item shows where it comes from (preset, catalog, local) and its state for every agent.

### Review before anything is written

panoplie computes a plan: files to add, update or remove, for each agent. You can undo any line before applying. When a file already exists or was edited by hand, you choose: **keep the project version**, **take the catalog version**, or **push the change back to the catalog**. You can compare both versions first.

<p align="center">
  <img src="media/screenshots/review.png" alt="Review changes before applying them, with conflict resolution" width="900">
</p>

### Clean up Global

panoplie lists everything loaded from your home folder and spots the items that are only used in some projects. **Move to projects** copies them to the catalog, enables them where they are needed, then removes them from Global. Nothing is removed from your home folder without an explicit action.

<p align="center">
  <img src="media/screenshots/global.png" alt="Global items loaded in every project, with tidy-up suggestions" width="900">
</p>

### Catalog: your library of items

Import what already exists on your machine (from Global or from any project), or write new items in the built-in editor: Markdown with preview for skills, rules and subagents, a form for MCP servers and hooks. Tag and search items, and see which projects use each one.

<p align="center">
  <img src="media/screenshots/catalog.png" alt="The catalog with a skill opened" width="900">
</p>

### Presets: bundles you enable in one click

<p align="center">
  <img src="media/screenshots/presets.png" alt="Presets with their items and usage" width="900">
</p>

### Marketplaces: import skills from others

Browse skill sources and import what you want into your catalog. Three sources are built in ([Anthropic Skills](https://github.com/anthropics/skills), [Claude Code official plugins](https://github.com/anthropics/claude-plugins-official), [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills)), and you can add any git repository or Claude plugin marketplace.

<p align="center">
  <img src="media/screenshots/marketplaces.png" alt="Browsing a marketplace" width="900">
</p>

### Sync: the catalog is a git repository

Commit, pull and push from the UI, against any remote: GitHub, GitLab, Codeberg, rickub, a self-hosted server… Conflicts are resolved file by file. An optional automatic mode commits and syncs after each change. On a new machine, clone your catalog during setup, add your projects, and you are back.

## Supported agents and items

| | Claude Code | Codex |
|---|---|---|
| Skills | `.claude/skills/<name>/` | `.agents/skills/<name>/` |
| On-demand skills | `skillOverrides` in `.claude/settings.json` | `agents/openai.yaml` in the skill folder |
| Rules | `.claude/rules/<name>.md` (with optional `paths`) | Managed block in `AGENTS.md` |
| MCP servers | `.mcp.json` | `.codex/config.toml` |
| Hooks | `hooks` in `.claude/settings.json` | `.codex/hooks.json` |
| Subagents | `.claude/agents/<name>.md` | `.codex/agents/<name>.toml` |
| Hide a Global skill or MCP server | Yes | Not supported by Codex yet |

panoplie also writes two files at the root of each project, meant to be committed:

- **`panoplie.json`**: what the project uses (target agents, presets, added and excluded items, on-demand skills, hidden Global items).
- **`panoplie.lock`**: what panoplie installed, with content hashes, so it knows which files it owns and can detect manual edits.

Shared files (`.mcp.json`, `.claude/settings.json`, `.codex/config.toml`, `AGENTS.md`) are edited surgically: panoplie only touches the keys or the block it owns and leaves the rest as is.

panoplie also warns you about agent-specific pitfalls: a Codex project that is not trusted (Codex then ignores its `.codex/` folder), an `AGENTS.md` close to the 32 KiB Codex limit, or rules that Claude Code would load twice.

`CLAUDE.md` and `AGENTS.md` are shown read-only in each project, with their size. They are specific to each project and never go into the catalog.

## Install and run

> panoplie is in early development and not published on npm yet. Until the first release, run it from source (see below).

Requirements: **Node.js 22+**, **git**, and preferably **Microsoft Edge or Google Chrome** for the app window.

```sh
npx @panoplie/cli
```

panoplie starts a local server and opens the UI in an app window (Edge or Chrome in app mode, your default browser otherwise). Closing the window stops panoplie. Running the command again while panoplie is open brings the existing window back.

| Option | Effect |
|---|---|
| `--no-open` | Do not open a window, only print the URL. |
| `--port <n>` | Use this port instead of the default one (47821, or a free port if taken). |

The first launch walks you through the setup: create a new catalog or clone an existing one from git, check the detected agents, then add your projects (panoplie can scan your usual code folders for you).

### From source

```sh
git clone <repository-url> panoplie
cd panoplie
pnpm install
pnpm build   # builds the UI
pnpm start   # starts panoplie and opens the window
```

## Where your data lives

| What | Where |
|---|---|
| Catalog | `~/.panoplie/catalog` by default (a git repository, the location can be changed in Settings) |
| Machine settings (projects list, preferences, Global configuration) | `~/.panoplie/` |
| Project configuration | `panoplie.json` and `panoplie.lock` in each project |

Set `PANOPLIE_CONFIG_DIR` to use another folder than `~/.panoplie`, and `CODEX_HOME` if your Codex home is not `~/.codex`.

## Security and privacy

- **Local only.** The server listens on `127.0.0.1`, rejects other host names, and requires a random token generated at each launch, so other websites open in your browser cannot call it.
- **No secrets in the catalog.** MCP configurations store the *name* of environment variables, never their values. Credentials found in MCP arguments, URLs or environment when importing are redacted.
- **Limited writes.** panoplie writes only in the projects you added, in the catalog, and in your home folder when you explicitly apply a change to Global.
- **No telemetry.** panoplie only goes online to fetch the marketplace sources you browse and to sync your catalog with the git remote you configure.
- panoplie never executes the scripts contained in skills.

## FAQ

**Do my teammates need panoplie?**
No. The generated files are regular agent files committed in the project. panoplie only makes them easier to manage, and it makes catalog sharing easier for those who use it.

**What if I edit a generated file by hand?**
panoplie detects it (thanks to `panoplie.lock`) and asks what to do on the next apply: keep your version, take the catalog version, or push your change back to the catalog.

**Why are skills copied twice instead of symlinked?**
Claude Code reads `.claude/skills` and Codex reads `.agents/skills`. Symlinks are fragile on Windows and do not survive a clone, so panoplie writes plain copies and keeps them in sync.

**Does it work with other agents (Cursor, Copilot, Gemini CLI…)?**
Not yet. Claude Code and Codex are supported today; more agents are planned.

## Development

The repository is a TypeScript monorepo managed with pnpm:

| Package | Role |
|---|---|
| `packages/core` | Model, inventory scanners, catalog, resolution, rendering per agent, sync plan and apply. No UI dependency. |
| `packages/server` | Local HTTP API over `core`. |
| `packages/ui` | Nuxt single-page app served by the server. |
| `packages/cli` | The `panoplie` command: starts the server and opens the window. |

```sh
pnpm dev         # API on :4300 and the UI with hot reload on :3000
pnpm test        # Vitest
pnpm typecheck
```

Commits follow [Conventional Commits](https://www.conventionalcommits.org/).

## More from the author

- [Bloggrify](https://bloggrify.com): open source static blog generator built on Nuxt and Nuxt Content.
- [hakanai.io](https://hakanai.io): comments, analytics and newsletter for static blogs.
- [Writizzy](https://writizzy.com): blogging and newsletter platform.
- [Kula](https://kulamail.com): transactional and marketing email for developers and agents.

All projects are listed on [eventuallymaking.io](https://eventuallymaking.io/p/about-me).

## License

[MIT](LICENSE)