HelloAGENTS: a workflow layer that makes an AI coding CLI finish the job

The specific failure mode this project targets

The README states the problem in a single paragraph, and it is unusually concrete for this category of tool. AI coding CLIs can move fast, but they can also stop at advice, skip checks, lose project context, shift responsibility when tasks get hard, or report completion before the work is really done. HelloAGENTS describes itself as a workflow layer on top of Claude Code, Gemini CLI, Grok Build, Cursor and Codex CLI, and its stated job is to anchor the agent as a capable executor, block responsibility shifting patterns, help it choose the right path, use task specific quality skills, keep a project knowledge base, and verify work before delivery. The README frames it as a v3 full rewrite based on Node.js, Markdown rules, skills and small runtime scripts, and it notes that the older Python line now lives in a separate helloagents-archive repository for anyone still looking for v2.x. The primary language is JavaScript, and the package is published on npm as helloagents.

Fourteen skills that load only when the stage needs them

The core mechanism is a set of fourteen built-in skills, and the loading strategy matters more than the list. The README says they are loaded only when the current stage needs them, so simple tasks stay light while complex work gets stricter checks. The list is organised by domain. UI work has hello-ui for planning, design contracts, implementation mapping and visual validation, and the README adds that all UI work first follows a shared UI quality baseline, with hello-ui going deeper in host global mode, in initialized projects or in explicit UI workflows. Then there is hello-api for design, validation, error format and compatibility, hello-security for auth, secrets, permissions and injection risks, hello-test for TDD, coverage, edge cases and test structure, and qa-review, the unified quality review that covers verification commands, blocking fixes, delivery evidence and closeout. The rest cover errors, performance, data, architecture, debugging, subagent delegation, written deliverables and reusable lessons, plus a helloagents skill that handles command routing and state coordination. When visual evidence is required, the README says it is recorded in the current session artifacts/visual.json.

Chat commands that read one skill at a time

Interaction happens inside the AI CLI chat with a tilde prefix, and the README is explicit that the command skill is read directly while unrelated skills are not loaded unless the workflow needs them. The command set maps to stages of work. ~ask is interactive clarification that pins down goals, direction, scope and constraints and explicitly does not write files, while ~auto chooses the main path and keeps going until delivery or a real blocker. ~plan produces requirements, solution design, task breakdown and a plan package, and ~build implements from the current request or from an existing plan. There is ~prd for a product requirements document built through guided dimension by dimension exploration, and ~loop as the long running entry point, which in Codex prefers the sequence /goal, then ~auto, then ~qa. The remaining commands cover initialisation and knowledge sync, writing tests, running the unified quality loop, generating a conventional commit message, archiving finished plans and cleaning temporary files, and showing the current settings. Several aliases exist for muscle memory: ~do maps to ~build, ~design to ~plan, ~review to ~qa, and ~idea to ~ask, which is marked deprecated.

Keeping project knowledge on disk instead of in chat history

One row of the README's comparison table states the problem plainly: without the layer, context is scattered and plans live in chat history; with it, project knowledge and plan files stay on disk. HelloAGENTS creates and maintains a project knowledge base under .helloagents/, and the README says the point is that future turns understand the repository without re-discovering it. That is the concrete difference between a memory feature inside one session and a written record that a later session, or a colleague, can read. The workflow layer also touches the CLI configuration files themselves, which is where the risk sits, and the README describes the mitigation as install, update, cleanup and doctor flows that check managed files, listed as safer config writes in the table. The delivery side is described as completion that uses state, evidence and verification rather than natural language saying done.

The install and update flow is a Node CLI with managed hosts

The package exposes its own binary and its lifecycle is driven by scripts in package.json, which is the clearest picture of how it touches your machine.

  "bin": {
    "helloagents": "cli.mjs",
    "helloagents-js": "cli.mjs",
    "helloagents-js.cmd": "cli.mjs",
    "helloagents-turn-state": "scripts/turn-state-cli.mjs"
  },
  "scripts": {
    "postinstall": "node cli.mjs postinstall",
    "deploy": "node cli.mjs install",
    "deploy:global": "node cli.mjs install --all --global",
    "sync-hosts": "node cli.mjs update",
    "cleanup-hosts": "node cli.mjs cleanup",
    "switch-branch": "node cli.mjs switch-branch"
  },

Where the licence question is not settled by the metadata

This is the one detail an adopter has to resolve by reading rather than by trusting a badge. The package.json declares the licence as Apache-2.0 and the README carries a licence badge reading Apache-2.0, but the repository listing classifies the licence as other, a custom licence that GitHub cannot classify, pointing at the LICENSE file. That combination is a flag, not a formality. If your organisation has a licence allowlist, the badge and the file are two different sources of truth and you need the file. It is also worth noting the versioning picture, which is layered. The README and the package.json both say version 3.1.9, while the recent release tags are v4.0.6-beta.1 from 2026-09-06, v4.0.5-beta.1 from 2026-08-14 and v4.0.4-beta.18 from 2026-07-29. So the published tags are ahead of the version string in the repository you are reading, which tells you the branch you clone is not the same as the newest published artefact. The last push was on 2026-09-06.

When a workflow layer is the wrong answer

The honest cases where this kind of tool does not help. If you already drive your CLI with a well written project level instruction file and a disciplined prompt, much of what the skills provide is duplicative, and you would be paying in context tokens and in a second configuration format for rules you already wrote once. If your work is a single small edit, the whole idea of stages, plans and closeout is overhead, and the README itself concedes that simple tasks stay light only because the skills load on demand. If you are on a platform the project does not support, there is nothing to install, since the host integration is per vendor directory. And the project is explicit about the fact that it shifts responsibility onto the agent rather than improving the model: nothing here makes a small model write better code, it makes a capable model behave consistently. The alternative approach worth naming is the plain one: keep your conventions in a single instruction file, keep your plans in the repository, and keep your verification in your test suite. That gives you the same three outcomes with no extra tooling, at the cost of the automation and the enforcement that a layer like this provides.

Editorial conclusion

Adopt HelloAGENTS if you drive an AI coding CLI daily and find it stopping at suggestions, losing project context between sessions or reporting completion without evidence, since those are the three failures it is built to address. Do not adopt it if you want a model or a tool, because it replaces neither, and expect it to write files into your project under .helloagents/ as well as into the CLI configuration directories. Before you install, read the LICENSE.md file yourself, because the package metadata declares Apache-2.0 while the repository is classified under a custom licence, and check which of the five supported CLIs you actually use before running the install flow.

Frequently asked questions

Official sources

1. hellowind777/helloagents on GitHub
2. Issues
3. README
4. Releases