A multi-CLI workflow system that keeps going until tasks are implemented and verified.
- 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
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 |
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) |
| 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
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. Your gain: complex tasks are broken down and handled by the right specialist. |
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. |
- 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
- 8 helper scripts from helloagents/scripts
- 10 KB/plan templates from helloagents/templates
|
Without HelloAGENTS 
|
With HelloAGENTS 
|
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
uvorpip, installs the HelloAGENTS package, and launches an interactive menu for you to select target CLIs. Re-running performs an update.
Update:
helloagents update
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
uvcommand 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
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
helloagents # interactive menu
helloagents install codex # specify target directly
helloagents install --all # install to all detected CLIs
helloagents status
helloagents version
helloagents uninstall codex
helloagents uninstall --all
helloagents clean
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
# 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
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
# 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
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
# 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
- Install the package (script/pip/uv) and run
helloagentsto launch an interactive menu for selecting target CLIs (or specify directly withhelloagents install <target>). - In AI chat, every input is scored on five dimensions and routed to R0–R3.
- R2/R3 tasks enter the stage chain: EVALUATE → ANALYZE → DESIGN → DEVELOP. R1 fast flow handles single-point operations directly.
- RLM dispatches specialized sub-agents (e.g. explorer, designer, implementer) based on task complexity.
- EHRB scans each step for destructive operations; risky actions require explicit user confirmation.
- Three-layer memory (user / project KB / session) preserves context across sessions.
- Stage chain completes with verified output and optional knowledge base sync.
- AGENTS.md: router and workflow protocol
- pyproject.toml: package metadata (v2.2.5)
- 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/scripts: automation scripts
- helloagents/templates: KB and plan templates
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 commands |
| ~status / ~help | status and help |
-
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.
- 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
- 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
helloagentsinteractive 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
- 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
See CONTRIBUTING.md for contribution rules and PR checklist.
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
