HelloAGENTS

A multi-CLI workflow system that keeps going until tasks are implemented and verified.

Table of Contents

• Why HelloAGENTS
• What Changed vs Legacy Repo
• Features
• Before and After (Snake Demo)
• Quick Start
• How It Works
• Repository Guide
• In-Chat Workflow Commands
• FAQ
• Troubleshooting
• Version History
• Contributing
• License

Why HelloAGENTS

Many assistants can analyze tasks but often stop before real delivery. HelloAGENTS adds strict routing, staged execution, and verification gates.

| Challenge | Without HelloAGENTS | With HelloAGENTS | |---|---|---| | Stops at planning | Ends with suggestions | Pushes to implementation and validation | | Output drift | Different structure every prompt | Unified routing and stage chain | | Risky operations | Easier to make destructive mistakes | EHRB risk detection and escalation | | Knowledge continuity | Context gets scattered | Built-in KB and session memory | | Reusability | Prompt-by-prompt effort | Commandized reusable workflow |

What Changed vs Legacy Repo

Compared with legacy multi-bundle releases, the v2.x line is now package-first with a fundamentally different architecture.

| Area | Legacy repo | Current repo | |---|---|---| | Distribution | Multiple bundle folders per CLI | One Python package + installer CLI | | Installation | Manual copy of config and skill folders | pip/uv install + helloagents interactive menu | | Routing | Three-layer (Context → Tools → Intent) | Five-dimension scoring (R0–R3) | | Workflow stages | 4 stages (Evaluate, Analyze, Design, Develop) | 4 stages + R1 fast flow, with sub-agent dispatch | | Agent system | None | RLM with 12 specialized roles and session isolation | | Memory | No persistence | Three-layer: L0 user, L1 project KB, L2 session | | Safety | Basic EHRB | Three-layer EHRB (keyword + semantic + tool output) | | Hooks | None | Auto-deploy lifecycle hooks (Claude Code 9 events + Codex CLI notify) | | CLI targets | 5 visible bundle targets | 6 targets: codex, claude, gemini, qwen, grok, opencode | | Commands | 12 | 15 workflow commands |

⚠️ Migration notice: Because repository structure and installation workflow changed in v2.x, legacy versions were moved to helloagents-archive: https://github.com/hellowind777/helloagents-archive

Features

RLM sub-agent orchestration

12 specialized roles (explorer, analyzer, designer, implementer, reviewer, tester, etc.) are dispatched automatically based on task complexity, with session isolation per CLI instance. Supports cross-CLI parallel scheduling and Agent Teams collaboration.

Your gain: complex tasks are broken down and handled by the right specialist, with parallel execution when possible.

Five-dimension routing (R0–R3)

Every input is scored on action need, target clarity, decision scope, impact range, and EHRB risk — then routed to R0 direct response, R1 fast flow, R2 simplified flow, or R3 standard flow.

Your gain: proportional effort — simple queries stay fast, complex tasks get full process.

Three-layer safety detection (EHRB)

Keyword scan, semantic analysis, and tool-output inspection catch destructive operations before execution. Interactive and delegated modes enforce user confirmation.

Your gain: safer defaults with zero-config protection.

Three-layer memory model

L0 user memory (global preferences), L1 project knowledge base (structured docs synced from code), and L2 session summaries (auto-persisted at stage transitions).

Your gain: context survives across sessions and projects.

Data points from this repo

• 6 CLI targets from helloagents/cli.py
• 15 workflow commands from helloagents/functions
• 12 RLM roles from helloagents/rlm/roles
• 4 stage definitions from helloagents/stages
• 5 core services from helloagents/services
• 4 rule modules from helloagents/rules
• 9 helper scripts from helloagents/scripts
• 2 hooks configs from helloagents/hooks
• 10 KB/plan templates from helloagents/templates

Before and After (Snake Demo)

Without HelloAGENTS

With HelloAGENTS

Quick Start

Method A: One-line install script (recommended)

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

The script auto-detects uv or pip, installs the HelloAGENTS package, and launches an interactive menu for you to select target CLIs. Re-running performs an update.

Update:

helloagents update

Method B: npx (Node.js >= 16)

npx helloagents

Installs the Python package and launches an interactive menu. You can also specify directly: npx helloagents install codex (or use npx -y to auto-download without prompting)

Requires Python >= 3.10. After first install, use the native helloagents command directly.

Acknowledgment: Thanks to @setsuna1106 for generously transferring the npm helloagents package ownership.

Method C: UV (isolated environment)

Step 0 — Install UV first (skip if already installed):

# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

After installing UV, restart your terminal to make the uv command available.

Install and select targets (one command):

uv tool install --from git+https://github.com/hellowind777/helloagents helloagents && helloagents

Installs the package and launches an interactive menu for you to select target CLIs. You can also specify directly: helloagents install codex

Update:

helloagents update

Method D: pip (Python >= 3.10)

Install and select targets (one command):

pip install git+https://github.com/hellowind777/helloagents.git && helloagents

Installs the package and launches an interactive menu for you to select target CLIs. You can also specify directly: helloagents install codex

Update:

pip install --upgrade git+https://github.com/hellowind777/helloagents.git

Install HelloAgents for different CLI targets

helloagents                  # interactive menu

helloagents install codex    # specify target directly

helloagents install --all    # install to all detected CLIs

Verify

helloagents status

helloagents version

Uninstall

helloagents uninstall codex

helloagents uninstall --all

Clean caches

helloagents clean

Codex CLI example

First install:

# One-line script (recommended, auto-launches interactive menu after install)
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

# npx (or use npx -y to auto-download without prompting)
npx helloagents install codex

# UV
uv tool install --from git+https://github.com/hellowind777/helloagents helloagents && helloagents install codex

# pip
pip install git+https://github.com/hellowind777/helloagents.git && helloagents install codex

Update later (auto-syncs installed targets):

helloagents update

Claude Code example

First install:

# One-line script (recommended, auto-launches interactive menu after install)
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

# npx (or use npx -y to auto-download without prompting)
npx helloagents install claude

# UV
uv tool install --from git+https://github.com/hellowind777/helloagents helloagents && helloagents install claude

# pip
pip install git+https://github.com/hellowind777/helloagents.git && helloagents install claude

Update later (auto-syncs installed targets):

helloagents update

Beta branch

To install from the beta branch, append @beta to the repository URL:

# One-line script (auto-launches interactive menu after install)
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/beta/install.sh | HELLOAGENTS_BRANCH=beta bash

# Windows PowerShell
$env:HELLOAGENTS_BRANCH="beta"; irm https://raw.githubusercontent.com/hellowind777/helloagents/beta/install.ps1 | iex

# npx (or use npx -y to auto-download without prompting)
npx helloagents@beta

# UV
uv tool install --from git+https://github.com/hellowind777/helloagents@beta helloagents && helloagents

# pip
pip install git+https://github.com/hellowind777/helloagents.git@beta && helloagents

How It Works

1. Install the package (script/pip/uv) and run helloagents to launch an interactive menu for selecting target CLIs (or specify directly with helloagents install <target>). Hooks and SKILL.md are auto-deployed during installation.
2. In AI chat, every input is scored on five dimensions and routed to R0–R3.
3. R2/R3 tasks enter the stage chain: EVALUATE → ANALYZE → DESIGN → DEVELOP. R1 fast flow handles single-point operations directly.
4. RLM dispatches specialized sub-agents (e.g. explorer, designer, implementer) based on task complexity. Supports parallel scheduling and Agent Teams for complex tasks.
5. EHRB scans each step for destructive operations; risky actions require explicit user confirmation. Hooks provide additional pre-tool safety checks when available.
6. Three-layer memory (user / project KB / session) preserves context across sessions.
7. Stage chain completes with verified output and optional knowledge base sync.

Repository Guide

• AGENTS.md: router and workflow protocol
• SKILL.md: skill discovery metadata for CLI targets
• pyproject.toml: package metadata (v2.2.8)
• helloagents/cli.py: installer entry
• helloagents/functions: workflow commands
• helloagents/stages: analyze, design, develop
• helloagents/services: knowledge, package, memory and support services
• helloagents/rules: state, cache, tools, scaling
• helloagents/rlm: role library and orchestration helpers
• helloagents/hooks: Claude Code and Codex CLI hooks configs
• helloagents/scripts: automation scripts
• helloagents/templates: KB and plan templates

In-Chat Workflow Commands

These commands run inside AI chat, not your system shell.

| Command | Purpose | |---|---| | ~auto | full autonomous workflow | | ~plan | planning and package generation | | ~exec | execute existing package | | ~init | initialize knowledge base | | ~upgradekb | upgrade knowledge structure | | ~clean / ~cleanplan | cleanup workflow artifacts | | ~test / ~review / ~validatekb | quality checks | | ~commit | generate commit message from context | | ~rollback | rollback workflow state | | ~rlm | role orchestration (spawn / agents / resume / team) | | ~status / ~help | status and help |

FAQ

• Q: Is this a Python CLI tool or prompt package? A: Both. CLI manages installation; workflow behavior comes from AGENTS.md and helloagents docs.

• Q: Which target should I install? A: Use the CLI you run: codex, claude, gemini, qwen, grok, or opencode.

• Q: What if a rules file already exists? A: Non-HelloAGENTS files are backed up before replacement.

• Q: What is RLM? A: Role Language Model — a sub-agent orchestration system with 12 specialized roles dispatched based on task complexity.

• Q: Where does project knowledge go? A: In the project-local .helloagents/ directory, auto-synced when code changes.

• Q: Does memory persist across sessions? A: Yes. L0 user memory is global, L1 project KB is per-project, L2 session summaries are auto-saved at stage transitions.

• Q: What are Hooks? A: Lifecycle hooks auto-deployed during installation. Claude Code gets 9 event hooks (safety checks, progress snapshots, KB sync, etc.); Codex CLI gets a notify hook for update checks. All optional — features degrade gracefully without hooks.

• Q: What is Agent Teams? A: An experimental Claude Code multi-agent collaboration mode. Multiple Claude Code instances work as teammates with shared task lists and mailbox communication, mapped to RLM roles. Falls back to standard Task sub-agents when unavailable.

Troubleshooting

• command not found: ensure install path is in PATH
• package version unknown: install package first for metadata
• target not detected: launch target CLI once to create config directory
• custom rules overwritten: restore from timestamped backup in CLI config dir
• images not rendering: keep relative paths and commit readme_images files

Version History

v2.2.8 (current)

• AGENTS.md: Codex CLI attention optimization for more stable HelloAGENTS execution

v2.2.7

• G12 Hooks integration spec: 9 Claude Code lifecycle hooks + Codex CLI notify hook
• Auto-deploy Hooks: auto-deploy and clean up Hooks config during install/uninstall
• Codex CLI native sub-agent: G10 adds spawn_agent protocol with cross-CLI parallel scheduling
• Agent Teams protocol: G10 adds Claude Code multi-role collaboration protocol
• SKILL integration: auto-deploy SKILL.md to skills discovery directory for all CLI targets
• RLM command expansion: add ~rlm agents/resume/team subcommands with parallel multi-role dispatch
• Stage parallel optimization: parallel rules for analyze/develop stages, serial annotation for design
• Memory v2 bridge: add Codex Memory v2 bridge protocol
• Script modularization: extract config_helpers.py module

v2.2.5

• RLM sub-agent system: 12 specialized roles with automatic dispatch and session isolation
• Five-dimension routing (R0–R3): replaces legacy three-layer routing
• Four-stage workflow + R1 fast flow: stage chain (Evaluate → Analyze → Design → Develop) with R1 fast flow for single-point operations
• Three-layer memory: L0 user preferences, L1 project knowledge base, L2 session summaries
• Three-layer EHRB: keyword + semantic + tool-output safety detection
• Package-first installer: pip/uv install with helloagents interactive menu
• 15 workflow commands: added ~rlm, ~validatekb, ~status
• 6 CLI targets: added OpenCode support
• Interactive installation menu: multi-select target CLIs with one command
• Auto locale detection: CLI messages switch between Chinese and English based on system locale
• Windows encoding fix: UTF-8 safe subprocess handling on all platforms
• Knowledge base service: structured project docs auto-synced from code changes
• Attention service: live status tracking and progress snapshots

v2.0.1 (legacy multi-bundle baseline)

• Multi-bundle distribution with manual copy-based installation
• Three-layer routing (Context → Tools → Intent)
• 4 workflow stages, 12 commands, 5 CLI targets
• No sub-agent system, no persistent memory

Contributing

See CONTRIBUTING.md for contribution rules and PR checklist.

License

This project is dual-licensed: Code under Apache-2.0, Documentation under CC BY 4.0. See LICENSE.md.

If this project helps your workflow, a star is always appreciated.

Thanks to codexzh.com / ccodezh.com for supporting this project