# Porting my homegrown GUI to a Claude Desktop mod
> Source:
> Published: 2026-10-22 00:00:00+00:00
# Porting my homegrown GUI to a Claude Desktop mod
**TL;DR:** I used to run Claude Code through [coide](https://github.com/vicmaster/coide), a GUI I built myself. When I switched to Claude Desktop’s Code tab, the feature I missed most was a boring one: a panel showing every skill and subagent I have, and where each one lives. Claude Desktop supports mods now, so I rebuilt that panel in a day as [skill-atlas](https://github.com/vicmaster/skill-atlas): a live pane, one `.tsx` file, installed with a symlink. This post is how a mod is put together, plus the four gotchas I hit.
For most of this year, my daily Claude Code driver was a GUI I built myself. coide was my first real Claude Code project: an Electron app wrapping the CLI, with the panels I wished the terminal had. Then Claude Desktop’s Code tab got good enough that maintaining my own wrapper stopped making sense, and I switched.
Mostly that was an upgrade. But there was one coide panel I kept reaching for and not finding: a sidebar that listed every skill and subagent available to the session, with descriptions, so I never had to remember whether `review-adoption` was a global skill or a project one, or fish for an agent’s name in the slash autocomplete.
Here’s the thing about retiring a homegrown tool: the code dies, but the features were never the point. They were a spec, written by months of daily use, for what the official tool would eventually need. So when Claude Desktop shipped support for mods (plugins that can draw panes inside the app), I didn’t mourn coide. I opened its repo and started porting.
The first port is `skill-atlas`, and it took a day. It’s open source and you can [install it with a symlink](https://github.com/vicmaster/skill-atlas). The rest of this post is how a mod is actually put together, and the four gotchas that cost me most of that day.
## What skill-atlas does
It’s a pane that lives next to the chat, with two views:
- **This session** shows everything the current session can use: project skills and agents from`/.claude/` , globals from`~/.claude/` , and skills shipped by installed plugins (read from`installed_plugins.json` ). Each entry carries the name and description parsed from its frontmatter, and globals and plugin skills get a scope badge. When two entries share a name, the project one wins, then the global one.
- **All projects** scans the folder your repos live in for`.claude/{skills,agents}` :`~/Projects` if you have one, otherwise the folder that holds the project the session is open in. It goes up to three levels deep, so grouping folders like`/` work, and it skips hidden and build folders like`node_modules` . Results are grouped by project, with the machine-wide set from`~/.claude` pinned on top. It’s a map of where every skill lives across your repos.
A filter input narrows both views as you type, and skills and agents get distinct icons so you can tell them apart at a glance. Clicking an entry expands it to show the full description and the path of the file behind it. The whole mod is read-only.
## Anatomy of a mod
A mod is a Claude Code plugin with a hooks module. skill-atlas is three files that matter:
- `.claude-plugin/plugin.json` , the manifest: name, version, and a`types` field pointing at your state contract (more on that below).
- `hooks/hooks.json` , a single line:`{ "modules": ["./register.tsx"] }` .
- `hooks/register.tsx` , the entire mod: scanners, state, a slash command, and the pane renderer.
The module exports a `register` function that subscribes to events. Three subscriptions cover the whole thing:
``` js
export const register: Register = on => {
on('session.start', async ($, e, next) => {
await $.command.register({
name: 'skill-atlas',
description: 'Show every skill and subagent (this session + all projects) in a pane',
})
void $.ui.open({ id: PANE, title: 'Skill atlas' })
void rescan($)
return next(e)
})
on('command.run', { command: 'skill-atlas' }, async $ => {
await $.ui.open({ id: PANE, title: 'Skill atlas' })
void rescan($)
return { text: 'Skill atlas pane opened.' }
})
on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
const { Box, Text, Button, Input } = $.ui.resolve(e)
// ...return JSX built from state
})
}
```
`$` is the engine interface, and it’s how the mod touches the world: `$.fs.list` and `$.fs.read` to scan skill folders, `$.state` for persistence, `$.ui` for the pane, `$.command.register` for the slash command. The `ui.render` handler is a pure function from state to JSX; every state change re-renders. If you’ve written React, the model is instantly familiar. If you’ve written an Electron app that does the same job, like I had, the striking part is how much infrastructure you don’t write: no window management, no IPC, no file watcher. The scanning logic I ported from coide landed almost unchanged; everything around it evaporated.
State goes through `$.state` with typed refs. A ref is a literal object:
``` js
const viewRef = { plugin: 'skill-atlas', key: 'view' } as const
const { value: view = 'session' } = await $.state.get(viewRef)
await $.state.set(viewRef, 'projects')
```
The ref’s keys and value types are checked against a contract you declare in `types/index.d.ts` (the file `plugin.json`’s `types` field points at), by augmenting the engine’s `PluginState` interface:
```
declare module 'claude-code' {
interface PluginState {
'skill-atlas': {
view: 'session' | 'projects'
filter: string
expanded: string[]
session: AtlasGroup[]
projects: ProjectGroup[]
scannedAt: number
}
}
}
```
A typo’d key or a wrongly-typed value is then a compile error. The bundled `plugin-authoring` example wraps the same calls in `atom`, `read`, and `update` helpers. Those are newer, so they need a recent CLI to validate (gotcha 2).
## Four gotchas the docs won’t tell you
### 1. `Button` is picky about its children
`Button` accepts strings and `Text` elements as children. Nothing else. Wrap a `Box` inside one to lay out a label with a description underneath, and the engine refuses to draw the pane at all (`