Getting Started

HelmIt installs as a native plugin on both platforms. There is no curl | bash, no vendored directory to copy into your repo, no template to fork. Two commands put the twelve HelmIt skills on your machine; a third: run once, inside a project: wires that project up.

This guide is the long version. It covers what the install commands actually do, why the qualified plugin@marketplace form is not optional, how you address HelmIt’s commands on each platform, the one Codex-specific step (the hook trust gate), and the first real loop from an empty repository to your first /ship.

Install

Claude Code

/plugin marketplace add helmit-dev/helmit
/plugin install helmit@helmit

Codex

codex plugin marketplace add helmit-dev/helmit
codex plugin add helmit@helmit

Same two steps, same names, different CLI surface. After the second command your client lists twelve skills under the helmit namespace: setup, spec, arch, env, chart, implement, validate, ship, next, yolo, heartbeat, uninstall.

What the two commands actually do

They are not “download” and “enable”. They do genuinely different things, and the distinction matters the first time something goes wrong:

Command	What it touches	What it installs
`… marketplace add helmit-dev/helmit`	your client’s list of known catalogs	nothing
`… install helmit@helmit` / `… plugin add helmit@helmit`	your client’s installed plugins	the HelmIt plugin

The first command registers a marketplace: a catalog that says “here is a plugin called helmit, and here is where its plugin root lives”. Registering a catalog downloads no skills, adds no commands, and changes nothing about how your agent behaves. If you stop after the first command, you have told your client where to look and nothing more.

The second command is the install. It resolves helmit inside the catalog named helmit, fetches the plugin root, and puts the skills and hooks in the client’s own plugin cache: outside any project of yours. HelmIt lives in the client’s cache, not in your repository; the only thing that ever lands in your repo is the .helmit/ kit that /helmit:setup writes, and the git hook it installs.

Why the qualified `plugin@marketplace` form is mandatory

Use helmit@helmit. Not helmit.

Every client ships with the official Anthropic marketplace already registered. The moment you add HelmIt’s catalog you have at least two catalogs in scope, and a bare plugin name no longer identifies one thing. Rather than guess: and silently install the wrong plugin: the client refuses and prints a hint telling you to qualify the name. The @ is the disambiguator: <plugin>@<marketplace>.

Read helmit@helmit as the plugin named helmit, from the catalog named helmit. The repetition is not a typo; the plugin and its catalog happen to share a name.

The same rule applies to removal: codex plugin remove helmit is refused for the identical reason, and codex plugin remove helmit@helmit works. If a plugin command errors with something about an ambiguous or unknown name, the fix is almost always the missing @marketplace suffix.

Ask your agent to install it

You can also describe the installation in plain language instead of typing the commands yourself. For example:

Claude Code: “Install the HelmIt plugin for me. Add the helmit-dev/helmit marketplace, install helmit@helmit, and confirm that the plugin is installed.”

Codex Desktop or CLI: “Install the HelmIt plugin for me. Register the helmit-dev/helmit marketplace, install helmit@helmit, and confirm the installed version.”

Review any actions the client asks you to authorize during installation.

Codex only: the hook trust gate

HelmIt ships hooks: the commit-gate reinforcement that inspects a git commit before it runs, and the token-metrics capture. Codex delivers plugin hooks untrusted and switched off by default. On first install it shows you the hooks and asks you to review them, because hooks can run outside the sandbox. You read them, press Trust, and toggle them on. It is a one-time step per install, and it is the correct default on Codex’s part: you should not accept executable hooks from a plugin you have not looked at.

Two things worth knowing about that gate:

Nothing about HelmIt’s guarantee depends on you granting trust. The official commit-gate guarantee is a git pre-commit hook that /helmit:setup installs into the project’s own .git/hooks/: harness-independent, and it runs whether or not any plugin hook is trusted. The plugin hook is reinforcement: it intercepts the commit earlier, before git ever starts, and gives the agent a clearer failure message. The floor is the guarantee. This is why the untrusted default is an inconvenience and not a hole.
On Claude Code there is no such step. The PreToolUse hook is declared by the plugin and travels with the install; you never edit settings.json by hand.

Talking to HelmIt

Claude Code and Codex Desktop: the `/helmit:` prefix

Every HelmIt command is namespaced by its plugin: /helmit:setup, /helmit:spec, /helmit:chart, /helmit:implement, /helmit:validate, /helmit:ship, /helmit:next. The prefix is not cosmetic. Short names like spec and next collide with native and third-party commands on both platforms, and the namespace is how the platform resolves the collision. Type /helmit: and the command list filters down to HelmIt’s steps.

Get in the habit of typing the prefix. A bare /next may resolve to something else entirely depending on what else you have installed.

Codex CLI: the `$` selector

Codex CLI has no /helmit:<cmd> slash-command syntax. The same skills: literally the same SKILL.md files, one shared core: are invoked through the $ selector: type $, filter, pick the skill. They also appear in the /skills list, and they are picked up implicitly when your request matches a skill’s description. Codex applies the plugin namespace on both of its surfaces, so what you see is helmit:<skill>.

On Codex Desktop, you can also invoke a HelmIt skill with the $ selector or /skills. Wherever this documentation writes /helmit:spec, read it on Codex CLI as the skill named spec, invoked through the selector. The contract is identical; only the way you point at it differs.

`/next`: the only command you have to remember

You do not need the table of twelve skills in your head. Every HelmIt command ends by telling you where you now are and what the single next step is, and offers to run it: conduction is distributed across the flow. /helmit:next is the safety net for when there is no recent command to follow: a new session, a different machine, a week away from the project, an interrupted phase you cannot reconstruct from memory.

/next reads the project’s position out of .helmit/STATE.md and routes deterministically from it. It does not guess, it does not re-derive intent from the conversation, and it advances exactly one step before stopping. If you remember one thing from this page, remember /helmit:next.

Set up the project, then resume your work

Open the repository you want to work in. If the project is not yet configured with HelmIt, run setup once:

/helmit:setup

In later sessions, open that project and ask for the next step:

/helmit:next

These commands work in Claude Code and Codex Desktop. In Codex CLI, select helmit:setup or helmit:next with $ or /skills. next reads the project’s state and points you to the next action, even after an interruption.

First run

First session From an empty project to the phase loop

Setup establishes the project contract; next keeps the route clear as the project crosses its human and deterministic gates.

/helmit:setup Onboard the project Add HelmIt files and commit checks to the repository.
/helmit:next Get one clear next action See the next step based on the project's state.
/helmit:spec Set the product direction Describe the project's goal and main requirements.
/helmit:arch Define how to check the project Record the technologies and commands used to check the code.
/helmit:next Enter the phase loop Follow the route to define, build, and complete one phase at a time.

Human gate Deterministic proof

Run /helmit:setup once to configure the project. Then use /helmit:next whenever you return. It points to the next step, from defining the product to shipping a phase. The configured checks protect commits and phase completion.

1. Onboard the project: `/helmit:setup`

Open your project (or an empty directory) and run:

/helmit:setup

It asks as little as it can get away with: the language for talking to you, the language for your artifacts, and one confirmation of the project type it detected. Everything else is detected deterministically or deferred to the command that owns it. Then it:

scaffolds .helmit/: KEEL.md, SPEC.md, ROADMAP.md, REQUIREMENTS.md, INBOX.md, STATE.md, config.json, phases/;
injects a marker-delimited HelmIt section into CLAUDE.md (Claude Code) or AGENTS.md (Codex), touching nothing outside its own markers;
installs the git pre-commit floor into .git/hooks/.

/setup runs once per project. If .helmit/ already exists it stops and tells you to run /helmit:next instead: it will not overwrite a kit that is holding your project’s state. A git repository is required (it offers git init if there isn’t one), because the workflow anchors its tracking to commits.

The freshly installed pre-commit hook is a no-op at this point: it reads the gate commands from .helmit/config.json, and those are still empty. /helmit:arch fills them, and from that moment the gate has teeth.

2. Then just run `/helmit:next`

From here on, one command:

/helmit:next

It reads STATE.md, tells you where you are, and offers the next step. Say yes, do the step, run it again. The sequence it walks you through, once per project and then once per phase:

Position after the last step	What `/next` offers	The gate
`setup-done`	`/helmit:spec` (product)	only a material product decision pauses
`spec-app-approved`	`/helmit:arch`	observed facts are recorded; only a new material tradeoff pauses
`arch-approved`	`/helmit:env`	deterministic tool check
`env-ready`	`/helmit:spec` (delivery, next phase)	only a material delivery decision pauses
`spec-feature-approved:<p>`	`/helmit:implement`	implementation prepares or adapts the executable plan
`chart-approved:<p>`	`/helmit:implement`	quick floor on every logical commit; focused proof on task completion
`implemented:<p>`	`/helmit:ship`	coverage, acceptance, final proof, and closure in one milestone
`validated:<p>`	`/helmit:ship`	optional diagnostic already passed; reuse its exact proof
`shipped:<p>`	`/helmit:spec` for the next phase	:

The product-level steps (spec at product level, arch, env) form one preparation flow and normally continue while the next act is already authorized. Each capability can still be invoked directly. After the first /ship, /next loops you back to a delivery /spec for the next phase, and you are in the phase cycle proper.

3. What happens the first time you commit

Once /helmit:arch has recorded your real proof commands, every logical commit crosses the staged quick floor. A candidate that completes a task also runs its focused verify:; complete test/build/lint proof belongs to real integration-risk and ship boundaries. The Git floor reads .helmit/config.json and is enforced by the hook, not requested of the model. --no-verify and equivalent bypasses are off the table by design. If a required check is red, the commit does not happen, the flow tells you what failed, and it routes you to the fix.

This is the part that people notice first and appreciate later. A phase cannot accumulate on top of broken code, which is exactly what makes the higher autonomy modes safe to use.

4. Your first `/ship`

/helmit:ship closes a phase: it runs the full suite one last time, marks the phase shipped in ROADMAP.md, reports the phase’s token totals, and: only if you have configured it or ask for it: prepares a pull request. Pushing and opening the PR are remote actions and are shown to you for confirmation first.

It never merges. Not to main, not to an integration branch, not in full-auto mode, not if you ask it to “just finish everything”. Merging is your act, always.

When /ship returns, /next points at the feature /spec for the following phase. That is the loop.

When you know the outcome you want but not the capability name, see which command should I use?.

Update HelmIt

Update the plugin in the client you use. Your project files stay in place.

Claude Code: run both commands, then start a new session:

/plugin marketplace update helmit
/plugin update helmit@helmit

Codex Desktop: open /plugins, find HelmIt, and choose Update. If that option is unavailable, reinstall the plugin. Then start a new task.

Codex CLI: refresh the marketplace and reinstall the plugin in your terminal. Then start a new session:

codex plugin marketplace upgrade helmit
codex plugin remove helmit@helmit
codex plugin add helmit@helmit

Prefer to ask your agent? Use one of these examples:

Claude Code: “Update HelmIt in this Claude Code installation. Refresh the helmit marketplace, update the helmit@helmit plugin, confirm the installed version, and tell me when I need to start a new session.”

Codex Desktop or CLI: “Update HelmIt in this Codex installation. Refresh the helmit marketplace, reinstall the helmit@helmit plugin through the terminal, confirm the installed version, and tell me when I need to start a new task or session.”

After updating, open each project and run helmit:env to check whether its instructions and commit protection also need updating. In Codex CLI, select that skill with $ or /skills.

After the first phase

The per-command contracts: preconditions, inputs, process, guardrails: are in the reference section. Those pages are generated from the same SKILL.md files the agent executes, so what you read is what runs.
Existing codebase rather than an empty directory? The workflow is identical; what changes is how the project’s harness gets described: you decide it in greenfield, the agent detects it from the real code in brownfield and you confirm item by item.
Something out of scope surfaced mid-task: a bug, a friction point, a better idea? It goes to .helmit/INBOX.md in one line and the current task continues untouched. /next offers triage at phase boundaries.