Installation

Requirements#

Claude Code and/or Codex, python3 3.9 or newer, and git. macOS and Linux are supported; Windows isn't yet.

Quick install#

The script clones the repository and runs a dry run. It then prints the install command to run.

curl -fsSL https://raw.githubusercontent.com/umararshad4/honey-stack/main/install.sh | bash

Or do it by hand:

git clone https://github.com/umararshad4/honey-stack.git && cd honey-stack
bin/honey install --dry-run && bin/honey install

Plugin only#

If you only want the plugin, without the CLI on your PATH:

claude plugin marketplace add umararshad4/honey-stack && claude plugin install honey@honey-stack
codex plugin marketplace add umararshad4/honey-stack && codex plugin add honey@honey-stack

Pin a version with marketplace add … --ref v0.2.0. In this mode honey isn't on PATH, so run it as python3 <plugin dir>/bin/honey doctor (the same goes for uninstall).

After installing#

1. Claude Code: run /reload-plugins.
2. Codex: open /hooks and trust the honey entries.
3. Check everything with honey doctor.

Global activation#

honey install adds a small managed block to ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md, preserving your personal instructions. At the first user turn it loads honey bootstrap --agent claude (or codex). This read-only fallback provides the workflow and the indicator when startup context is missing; it never fakes hook events. Uninstall removes the block and keeps any later personal edits.

Verify hook delivery#

The 🍯 HONEY prefix shows that rules were injected. To check whether a session actually receives hooks:

honey doctor --agent codex --session <session-id> --json   # or --agent claude

Installation, enablement, recent delivery and payload coverage are reported separately. For Codex, hook_trust reads the native hook registry: review_required means the plugin needs review in /hooks, and unknown means the registry couldn't be checked.