GitHub - x-kej/claudius: adding whimsy to emotionless machines · GitHub
Skip to content You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert Branches Tags Open more actions menu Latest commit History 20 Commits 20 Commits Folders and files Name Name Last commit message Last commit date .claude-plugin .claude-plugin hooks hooks personas personas .gitignore .gitignore README.md README.md claudius.sh claudius.sh common.md common.md Repository files navigation Claudius Just because you have to use a coding agent at work doesn't mean you can't be silly about it.
Claudius is a Claude Code plugin that gives every session a randomly chosen persona: a noir detective, a Whitman-esque poet, a NASA flight controller, a caveman fresh out of the glacier, and about forty more. Install From GitHub: claude plugin marketplace add x-kej/claudius claude plugin install claudius@claudius Or from a local clone, which is better if you plan to edit personas, since a plugin from a local marketplace loads straight from your folder: git clone https://github.com/x-kej/claudius ~ /code/claudius claude plugin marketplace add ~ /code/claudius claude plugin install claudius@claudius You can also do this from inside a Claude Code session with the same commands as slash commands: /plugin marketplace add … , then /plugin install claudius@claudius .
Or use the /plugin menu. Either way, the persona takes effect from the next session you start. Both routes add the marketplace and the plugin to your user settings.json ( extraKnownMarketplaces and enabledPlugins ). If that file is generated by a dotfile manager such as chezmoi, add those two entries to its source too, or the next apply will remove them. Running the install commands first and then diffing the live file against your source is an easy way to get the exact JSON.
Upgrading from the hooks-only version Earlier versions were wired up as two hooks in ~/.claude/settings.json pointing at claudius.sh . Remove both of those hook entries when you install the plugin, before starting another session. If you don't, sessions get a persona from each. If you install from a local clone that still has the old weights.csv in it, your weights are copied into the plugin's data directory the first time it runs.
A GitHub install starts with fresh weights. How it works The plugin's SessionStart hook prints the persona as session context, and records it in a per-session state file in the plugin's data directory. Each session has its own record, so sessions running at the same time never affect each other. New session or /clear : draws a fresh persona. Resume ( claude --resume , --continue ) or compaction: re-sends the persona already recorded for that session, so the voice survives.
If the record is gone (older than 30 days, or the session predates this version), it draws a new one and tells Claude to drop any earlier persona. Every few prompts: a UserPromptSubmit hook adds a short reminder of the same recorded persona's voice. Each draw is logged to picks.log in the plugin's data directory, one line per draw: time, session id, start source, persona. Upgrading from the output-style version Earlier plugin versions delivered the persona as an output style, written to a single output-styles/persona.md that every session shared, so sessions could overwrite each other's personas.
If that file is still in your clone, delete it. Otherwise Claude Code keeps loading it as a forced output style alongside the hook's persona. Configuration Persona weights Picks are weighted to keep recent personas from repeating. The weights live in the plugin's data directory, ~/.claude/plugins/data/claudius-claudius/weights.csv , one row per persona: <name>,<preference>,<weight> . The weight is what's actually used to pick.
Higher means more likely. Each time a persona isn't picked, its weight grows by its preference. When it is picked, its weight resets to its preference. A preference of 1 , the default, gives an even rotation. Raise it for a persona you want more often, or lower it for a rare treat. Set a weight to 0 to take that persona out of the rotation. It stays at 0 until you change it. Reminder frequency The reminder fires every 4 prompts.
To change that, set CLAUDIUS_REMIND_EVERY in the env block of your Claude Code settings. Set it to 0 to turn reminders off and rely on the session-start persona alone. Writing personas Each persona is a Markdown file in personas/ . New files join the rotation automatically. The format: --- reminder : A one-line cue for the mid-session reminder. Name concrete material, like the address term, a few signature words, and the signature move. --- You ARE … (who the persona is, in a sentence or two) ** Address: ** how the persona speaks to the user. ** Frame: ** what the work becomes in the persona's world.
What reading files, running tests, editing, a bug, a pass, a failure, and a clean build are called. ** Moves: ** one to three sentence shapes or structural devices that make the voice recognizable at a glance. ** Lexicon: ** fifteen to twenty words and phrases in the register. ** Sample: ** > Two to four sentences of a routine technical moment in the voice, with real-looking paths and numbers. ** Emoji: ** a handful that fit.
The sample and the lexicon do most of the work. Claude imitates examples much more reliably than it follows descriptions of a tone. common.md holds the rules every persona shares, and it's appended to each one. Every new session draws a fresh persona, so the way to try a particular persona while tuning it is through the weights. Temporarily set every other persona's weight to 0 . Running without the plugin claudius.sh also works as a plain SessionStart hook in settings.json , without the plugin.
It behaves the same way, but keeps its state in .state/ in the repo. The reminder hook is claudius.sh --remind . About adding whimsy to emotionless machines Resources Readme Activity Stars 0 stars Watchers 0 watching Forks 0 forks Report repository Releases Packages Contributors Languages You can’t perform that action at this time.