@g3nomaly/g3n-mods

The g3n mods for Claude Code. A mod adds a pane, a status line, a slash command or a hook to Claude Code.

This package holds the mods themselves. You don't install it directly. The installer, @g3nomaly/mods, knows it as the built-in g3n-mods source and copies mods out of it into your project.

How to install

Run these from the root of your project:

bunx @g3nomaly/mods init                # creates .claude/mods.json and sets up VS Code
bunx @g3nomaly/mods add context-bar     # installs one mod
bunx @g3nomaly/mods add g3n-mods        # installs every mod in this package

Then open the project in VS Code and trust the workspace. New sessions load the mods, and /reload-plugins loads them into a session that is already open. Updating, removing and installing for every project with --user are covered in the @g3nomaly/mods README.

The mods

| Mod | What it does | Command | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | agent-adventure | An idle roguelike to watch while agents work. Each running agent fights as a hero: the main thread and every subagent, of every session, all in one party. The game runs in the mods viewer in VS Code, so a busy session never stalls it. With none running, the heroes rest in the tavern. A run is a dungeon of fights, two forks (a safe trail or a dangerous one with double XP and a relic), a camp and a boss. Heroes keep their level, skills and trophies between runs. A party wipe costs every hero 5 levels. Every 10 levels a hero picks one of two skills, up to three. Haiku names new heroes and makes the picks; the view shows what those calls cost, which uses none of your agents' context. Agents can name their own hero with the hero tool, which is cosmetic only. The game never changes what agents do | /agent-adventure | | agents-panel | The agents in .claude/agents with their model and a run button. A running agent shows a spinner, and a toast says when it starts and finishes | /agents-panel | | context-bar | One bar of context-window use split by source, with the total and where compaction starts | /context-bar | | custom-crab-agents | Adds each subagent to the agents panel as a crab drawn as Claude's mascot, walking while it works and blinking when done: its role (from its name or type) picks its hat and what it holds, such as a reviewer's deerstalker and magnifying glass, a tester's work helmet and wrench, a designer's top hat and brush. Shows model, effort, steps, context, tokens, cost and time. Click anywhere on a crab to open its whole conversation in a tab and message it there. Needs agents-panel, which installing it adds | /agents-panel | | delete-guard | Off by default: deletes run unasked. Turn it on with the switch in its pane, or /delete-guard on; it stays on in later sessions. While on, rm -rf and other permanent deletes wait on a card listing the files, their sizes and whether git can restore them, until you press Delete or Cancel. Cancel tells Claude which trash command to use instead. With nothing to draw the card on, the delete is refused | /delete-guard on \| off | | focus-mode | A timed focus block in which you're away: Claude's questions are refused, so it picks for itself and says what it assumed, and permission prompts are refused, so it works around the step and lists it for later. Countdown, progress bar and end button. Set the length with − and + in the pane, or pass the minutes; the length you pick is kept for later blocks | /focus-mode [minutes] \| end | | handoff | Writes a handoff with the handoff skill, clears the session, and attaches the handoff to your next prompt | /handoff-new [what the next session is for] | | hide-personal-data | Masks names, emails, phone numbers, IBANs and card numbers in replies. Hover a mask to read it | /hide-personal-data on \| off | | mini-game | Minesweeper, or whack-a-mole when you want zero thinking: hit the mole before it hides, three misses and the round ends, and it speeds up as you score. Both keep a high score. Switch games with the tabs in its pane | /mini-game [mines \| mole] | | tool-timeline | The last ten tool calls, one line each, with their durations, in a pane that keeps one height. Click a call to see it in full in the box under them. A denied call is struck through, next to the call that replaced it | /tool-timeline | | you-should-know | A compact card under a reply, one tagged line per point. QUESTION lines quote the questions the reply asks you, word for word. CHANGE, CONCLUSION and FACT lines come from one small Haiku call that reads your request beside the reply: what was added, removed or changed, the direct answer to what you asked, and costs or decisions only, never caveats. It runs only for replies of 800 characters or more | none |

Every mod with a pane shows it in the mods viewer. Only context-bar also opens it in the Claude Code chat when a session starts. Each pane mod has a showInClaudeCode option, Show in Claude Code in /config, that turns this on or off. A mod's command opens its pane in the chat whatever the option says, and for agents-panel, context-bar and tool-timeline running it again closes it there. A delete-guard card waiting on an answer also opens in the chat, and leaves once answered.

Mods take settings, declared under userConfig in their .claude-plugin/plugin.json:

• agent-adventure, agents-panel, context-bar, delete-guard, focus-mode, mini-game and tool-timeline: showInClaudeCode, whether the pane opens in the Claude Code chat at session start (on for context-bar only).

• agent-adventure: model, the model that names heroes and picks skills and routes (haiku); off uses the game's own picks.

• focus-mode: minutes, the block length before you pick one (25).

• hide-personal-data: names, extra names to always mask, separated by commas.

• you-should-know: minChars, the shortest reply Haiku reads for changes, conclusions and facts (800); questions get a card at any length, and model, the model that picks the key point (haiku).

Requirements

• Bun, to run the installer
• Claude Code for VS Code (anthropic.claude-code) 2.1.296 or newer. The mods are typed against that release.

The mods also load in the terminal, but they are built for the VS Code extension.

Making your own mod

Each mod here is a plugin folder under mods/, and .claude-plugin/marketplace.json lists them:

mods/<name>/
├── .claude-plugin/plugin.json   # name, version, description
├── hooks/hooks.json             # { "modules": ["./register.tsx"] }
├── hooks/register.tsx           # exports `register`
├── types/index.d.ts
└── view/                        # optional: how the VS Code viewer draws it
    ├── panes.json               # { "panes": [{ "id", "title" }] }: the panes the viewer shows
    ├── view.ts                  # exports `mount(root, api)`
    └── view.css

Drawing a mod with HTML and CSS

On every surface but the VS Code viewer, a mod draws with the engine's elements (Box, Text, Button, Svg). In the viewer it can draw with its own HTML and CSS instead, as tool-timeline, agents-panel and custom-crab-agents do:

1. The hook hands over data. When the viewer draws the pane, the render hook returns a view box: a Box keyed g3n-view:<mod> holding the data as JSON in one Text, and a hidden Input keyed g3n-act:<mod> that receives the view's actions. The viewer's relay sets the prop g3nViewer: true on every pane the viewer draws. The Claude Code extension draws on the vscode surface too but never sets it, so check both: e.surface === 'vscode' and e.props.g3nViewer === true.
2. The view draws it. view/view.ts exports mount(root, api). root is a shadow root of the mod's own, so view.css applies only there and the editor's theme variables still reach it. mount returns { update(data) }, which gets the data each time the pane is drawn. Keep elements across updates, and animations and anything typed in the view keep going.
3. Actions go back to the hook. api.act(name, arg) arrives at the hidden Input's onSubmit as JSON of { name, arg }.

The installer bundles view/view.ts into view/view.js where the mod is installed, so the mod's source stays TypeScript. A view may import plain modules of its mod, such as hooks/sprite.ts, but not claude-code.

The folder name must match name in plugin.json. Mods are TypeScript only, and the installer refuses a mod that contains any .js, .mjs, .cjs or .jsx file. To share your own mods, put them in a git repository, npm package or local folder with the same layout and register it with bunx @g3nomaly/mods source add.

Development

Run bun install at the repository root first, then these from packages/g3n-mods:

bun run build       # rewrites .claude-plugin/marketplace.json from each mod's plugin.json
bun run typecheck
bun run test        # the tests in tests/, such as agent-adventure's game rules
bun run validate    # runs `claude plugin validate` on every mod
bun run types       # copies the mod API types into types/claude-code.d.ts
bun run sprites     # collects agent-adventure's sprite PNGs into hooks/spriteData.ts

agent-adventure keeps each sprite as its own PNG under mods/agent-adventure/sprites/: heroes, gear, items, enemies, effects, icons and scenery. Edit them in any pixel editor. An animation is one PNG with its frames side by side, named <name>_strip<frames>.png. Gear layers and item icons paint their material with four key colors, which take the item's material and tier at draw time: #ff00ff main, #a000a0 shade, #00ff00 accent and #ffa0ff highlight. Sprites are drawn at twice the resolution of the first version: a hero is 32x40. A hooks module loads TypeScript only, and the chat pane draws sprites as SVG, so bun run sprites checks the PNGs and collects their pixels into hooks/spriteData.ts. Run it after editing a sprite; the tests fail while it is out of date.

License

Elastic License 2.0. See LICENSE.