haechi — Workflow plugin for Claude Code and Codex

Haechi is a Claude Code and Codex plugin for AI coding agent workflows. Reproduce bugs, build features, review code, and verify changes with your repository's own commands.

Install the plugin, configure your repository once, and describe a task. Haechi gives the agent task playbooks, repository settings and verification tools, with guidance to report what was checked before calling the work done.

Early release: workflow guidance continues to evolve. See the 0.1.0 release notes for compatibility and verification scope.

Quick start · Usage examples · Commands · Settings · Contributing · Skills · Agents

Quick start

You need Git, Node.js 24 LTS (24.22.2 or newer), and a Claude Code or Codex installation with plugin support. Keep your Node.js LTS line on its latest security patch. The repository pins its development version in .nvmrc; with nvm, run nvm install and nvm use from the repository root.

1. Install for your agent

Claude Code

claude plugin marketplace add jisuzzzz/haechi
claude plugin install haechi@haechi

Codex

codex plugin marketplace add jisuzzzz/haechi
codex plugin add haechi@haechi

For Codex, open a new terminal, run codex, and trust the haechi hooks in /hooks.

2. Set up your repository

Open your repository in your agent and run:

/haechi:setup

Setup detects the verification commands and test locations, confirms the forbidden commands and sensitive-data rule, and proves that the commands run. It saves shared settings in .haechi.json and asks for personal preferences once per machine.

Run setup once per repository, then again when its execution settings change. Git settings are resolved when a Git operation needs them.

3. Reproduce and fix a bug

/haechi:bug The due date shows the next day for users in UTC-5. Reproduce it and fix the conversion.

For this bug, the agent collects a reproduction, finds the cause, adds a failing test, fixes the code and checks that the test passes. Its report shows what changed and what was verified.

You can also describe a task in natural language and let the agent choose useful skills. Prefixing the prompt with a command explicitly requests that method; it does not make the method an exclusive workflow.

What haechi adds

• Checks that fit your repository. Hooks supply your configured verification commands, forbidden commands and task guidance, including recovery after compaction. Later requests remind the agent to assess the relevant guidance and required evidence.
• Reproduce, repair and verify. Bug fixes need evidence of the failure before the repair and the result afterward. Features need checks against their acceptance criteria; code reviews report findings without editing code. The common work contract defines these obligations across task methods.
• UI previews before implementation. The preview skill guides the agent to build and check an interactive proposal, then carry the selected design and interaction criteria into implementation.
• Work you can resume. For work that spans sessions, depends on another task or produces a shared result, work-graph guides the agent to record the goal, progress, decisions, verification results and next action, with links to native sessions.
• Delegation when it helps. The main session gives a bounded task to a repository-required agent or the plugin's generic worker, with the required guidance, context, file ownership and expected evidence. Independent reviews use separate executions, and the main session checks the results. See delegate for the packet procedure and host limits.
• Results with verification evidence. The agent checks each requested outcome against actual results on the final change and reports gaps. Exit 0 alone is insufficient; missing proof is implemented · unverified.

Settled requirements can stay in the conversation. The spec skill helps consolidate requirements and acceptance criteria; its description guides selection. It does not require a saved document or a new approval. Completed changes get local commits; push, PR/MR creation and merge require authorization, which your request can already provide.

Usage examples

Review code with Claude Code or Codex

/haechi:review Review this branch against main. Report defects with evidence; do not edit files.

The review reports concrete defects, open questions and verification gaps within the requested scope. The request above keeps the repository files unchanged.

Preview a UI before implementation

/haechi:preview Show two options for the table row actions menu. Let me open the menu, select an action and see the result using sample data. Keep this to a prototype.

For a disposable prototype, the agent builds an interactive HTML preview outside the repository, serves it on localhost, and checks the relevant states and interactions in a browser before sharing the URL. It reports any unavailable checks. When implementation is requested, the selected design and interaction criteria become the reference for the product change.

Resume work across sessions

For a task already recorded by work-graph, start a later session in the same repository and describe the work to continue:

Continue the recorded table row actions menu task. Check its goal, decisions, verification results and next action before making changes.

For eligible work, work-graph guidance calls for recording the task before substantial work and updating it when the remaining plan or completion judgment changes. It retains applicable user constraints and durable results so a later session can find what remains. Short standalone questions need no new task.

Records live in the repository's Git common directory. Linked worktrees share them; separate clones and remote machines do not synchronize them automatically. Hooks remind the agent to maintain these records; recording still depends on the agent following the guidance. See work-graph for storage, session access and handoff details.

Commands

Choose a useful method or describe the task naturally. Existing commands remain compatible; none exempts product changes from the common work contract. Each command links to its instructions.

Focused skills handle particular work:

• delegate exposes a compact step input form and assembles complete worker guidance into task files, returning only a coordinator receipt. Direct delivery depends on the host; it does not enforce permissions or prove behavior.
• spec helps establish requirements and acceptance criteria; preview builds and checks UI proposals; sweep coordinates independent units of work.
• impact-map, sibling-path-map, mutation-check and review-diff support verification and review.
• eval records workflow failures and compares proposed improvements in fresh contexts before changing active guidance. It runs when relevant to an evaluation task and adds no background memory or global rules. Seed observations are in evals/failures.md.
• answer shapes choices, problem explanations and concrete scenarios while preserving evidence and useful explanations. work-graph keeps minimal shared task state and native session links.
• Clear writing supplies shared expression guidance for chat and lasting prose; document composes cross-team documents from shared Parts and six templates; request uses that system to write and update requests in one file.
• commit makes a local commit; mr opens a GitHub PR or GitLab MR; ci-watch watches and fixes GitLab CI through merge and cleanup. GitHub CI watching is not available yet.

Browse all skills in skills/ and the single generic worker in agents/. See worker migration and validation for upgrade steps, host requirements and measurement limits.

For a document without an earlier request, start from the current observation:

/haechi:document Draft a backend request for a support queue: the Open tab shows 12 tickets but no rows. If the development screen is accessible, capture it and mark the count and empty list. Keep the suspected backend cause unconfirmed.

The document skill reuses browser helpers or temporary Playwright scripts for captures. screenshot-annotate.mjs in the installed plugin preserves the original PNG and creates a separate PNG with numbered borders; GIF is optional when motion matters. Agent-facing Parts and templates use English, while work documents follow the recipient's language. The capture guide covers coordinates, attachments and missing access. See the validation scope and unresolved quality claims before treating the templates as a writing standard.

Settings

Setup preserves explicit settings and unknown existing keys. A saved command is not proof that it works; setup runs the smallest relevant check and reports anything left unverified.

Git host, base/protected branches, naming rules and PR/MR formats are optional settings. The Git skills resolve them when needed from explicit settings, repository instructions and remote information, and ask about an unresolved target at that operation.

For Python repositories, see the backend verification guide for source-to-test mapping and test database prerequisites.

Source and contributing

Edit the root source folders. The installed plugins in dist/ are generated from them.

Use the Node.js version in CI when building the distributions. After editing source:

npm ci
npm run build
npm run check

tools/*.mts and hooks/rules.mts are TypeScript sources. Keep relative tool imports ending in .mjs; TypeScript resolves them to .mts during development. The build removes types and emits the existing .mjs paths into both distributions. Plugin users need no TypeScript compiler.

npm run typecheck checks the sources with strict TypeScript settings. Both npm run build and npm run check run it first. npm run check also checks whether the distributions match the source. Tests import the generated JavaScript, so rebuild before testing source changes. Run affected tests individually with node --test test/<name>.test.mjs, then commit the source and regenerated dist/ files together. For a README-only change, run npm run check and check the links.

Open a pull request for your changes. The design notes explain the architecture; the verification scope decision records earlier verification changes and limits.

Session context

Starting a prompt with /haechi:feature <task> (or bug, refactor, perf, review, test-hardening) remembers that selection within the session and working directory. Follow-up prompts and resumed or compacted sessions receive a reminder. Supporting skills such as /haechi:preview and /haechi:spec leave the selection intact and can also be used on their own. Product UI implementation uses the selected design reference and inherits the common work contract's tests, rendered comparison and component reuse review. The stored command is a user preference, not an exclusive workflow or proof of completed work.

A new primary command replaces the selection. Use /haechi:context clear when a task is finished, cancelled or replaced; natural-language task changes are not classified automatically. A new session has no selection.

This records user intent, not skill execution, progress or permission to edit. Persistence requires the host to deliver the literal command in UserPromptSubmit.prompt, together with session_id and cwd. Hosts that consume slash commands before this event cannot persist the selection through this mechanism. Local hook payload tests do not establish live host compatibility.

License

MIT. See LICENSE and NOTICE for attribution.

Evaluation tools

Use the shared Harbor runner to compare constructed React/FastAPI tasks and locally prepared SWE-bench tasks. Historical findings and limitations are recorded separately from the reusable tools; raw logs, snapshots and generated task payloads stay in local archives.