Moodring

Moodring installs global developer “moods”: a standing base skill plus the author’s complete native skill set. It preserves native skill names and registers them through ~/.agents/skills, with matching Claude symlinks under ~/.claude/skills.

Install

Requires Node.js 20 or newer.

npx moodring install

Ensure $HOME/.local/bin is on PATH, then start a new Codex or Claude Code session. Invoke $moodring in Codex or /moodring in Claude Code.

Commands

moodring                 deterministically choose a mood
moodring <name>          activate a fuzzy-matched mood
moodring list            list the bundled catalog
moodring guide           show the current mood and native skills
moodring status          show the active stack and drift
moodring off             unload every active mood
moodring tips on|off     enable or disable session recording (off by default)
moodring tips            generate mood usage tips from the most recent session
moodring update          update Moodring and every bundled mood
moodring doctor          inspect state without repairing it

When another mood is active, the conversational skill asks whether to unload the current top mood or keep it and stack the new one. If stacked moods share a native skill name, the newest mood provides it; unloading that mood restores the older registration.

Human-facing output uses semantic terminal colors when stdout is interactive. Set NO_COLOR=1 to disable them or FORCE_COLOR=1 to preserve them through pipes and CI logs. JSON output is always uncolored.

moodring tips on installs a Claude Code SessionStart hook that records which mood each session ran under. moodring tips then analyzes the most recent session — via a tool-disabled Claude invocation or a read-only, ephemeral Codex invocation — and returns personalized tips for that session's mood. Transcript content is treated as untrusted data.

Moods and attribution

Moodring is a curator and installer. The original work belongs to its respective authors, and mood-specific commands link back to these sources.

| Mood | Author and source | License and Moodring changes | | --- | --- | --- | | Matt Pocock | mattpocock/skills | Native skills are MIT-licensed and preserved verbatim. Moodring adds the matt-pocock-mood router. | | poteto | Lauren Tan’s pstack | Native skills are MIT-licensed and preserved verbatim. Moodring adds the poteto-mood base. | | dmmulroy | David Mulroy’s skills | bro and coding-standards are preserved verbatim under the repository’s MIT license. Its upstream notice names Matt Pocock as copyright holder. | | Julien Barbier | jbarbier/CLAUDE.md | The repository has no redistribution license. Moodring does not copy it; jbarbier-mood is an independently written adaptation with explicit provenance. |

Every manifest pins an immutable source revision and records exact imports, license status, attribution, and commentary for synthesized work. Full upstream license notices ship beside the applicable mood.

Develop

npm test
npm run package

npm run package creates the architecture-neutral release/moodring.zip and release/SHA256SUMS consumed by the unified updater.

npm run sync:upstream fetches every pinned source declared in mood.json, replaces only its explicitly listed vendored paths, and prints the resulting Git diff. Synthesized or adapted skills are excluded from imports and documented by each manifest's adaptation.commentary.

Release

Update VERSION and package.json to the same unpublished version. Commit and push a clean main branch, authenticate with GitHub and npm, then run:

npm run release

The command tests and packages Moodring, creates and pushes the version tag, waits for the GitHub release, verifies its assets, and publishes the npm package. If publication stops after the tag or GitHub release, fix the reported problem and run the command again.

See MASTER_PLAN.md for the complete product contract.

See CONTRIBUTING.md to add or update a mood.