HelloAGENTS

Let AI go beyond analysis — keep pushing until implementation and verification are done.

Important

Looking for the old version of HelloAGENTS? The legacy codebase has been moved to a separate archive repository: helloagents-archive

Before and After

Without HelloAGENTS

With HelloAGENTS

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

Core Features

RLM Sub-Agent Orchestration

3 specialized roles (reviewer / writer / brainstormer) plus host CLI native sub-agents (explore / code / brainstorm) are dispatched automatically based on task complexity. Tasks are scheduled via DAG dependency analysis with topological sort and layer-by-layer parallel dispatch. 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.

Structured Workflow (Evaluate → Design → Develop)

Every input is scored on five dimensions and routed to R0 direct response, R1 fast flow, R2 simplified flow, or R3 standard flow. R2/R3 enter the full stage chain with explicit entry conditions, deliverables, and verification gates. Supports interactive and fully delegated modes.

Your gain: proportional effort — simple queries stay fast, complex tasks get full process with verification at every step.

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.

Two-Layer Memory Model

L0 user memory (global preferences) and L1 project knowledge base (structured docs synced from code).

Your gain: context survives across sessions and projects.

Extensibility & Customization

Voice notifications (5 event sounds), custom command extension (.helloagents/commands/*.md), user-defined tool orchestration (sub-agents, skills, MCP servers, plugins), and flexible configuration options. All features work across 6 CLI targets with graceful degradation.

Your gain: tailor the workflow to your team's needs without forking the codebase.

Multi-CLI Support

One rule set works across Claude Code, Codex CLI, OpenCode, Gemini CLI, Qwen CLI, and Grok CLI (Experimental/Community). Automatic feature detection and graceful degradation ensure consistent experience regardless of CLI capabilities.

Your gain: switch between CLIs without relearning workflows or reconfiguring rules.

Sub-Agent Native Mapping

CLI	Native Sub-Agent Mechanism	RLM Mapping
Claude Code	Agent tool (explore / code / shell)	Direct mapping, supports Agent Teams
Codex CLI	spawn_agent / Collab (multi-thread)	spawn_agent parallel scheduling, CSV batch orchestration
OpenCode	Task tool (build / plan / general / explore)	Direct sub-agent mapping
Gemini CLI	Built-in tool calls	Fallback to sequential execution
Qwen CLI	Built-in tool calls	Fallback to sequential execution
Grok CLI (Experimental)	Built-in tool calls	Fallback to sequential execution

Additionally, HelloAGENTS provides: five-dimension routing scoring (action need, target clarity, decision scope, impact range, EHRB risk) to automatically determine processing depth for each input; 6 CLI targets (Claude Code / Codex CLI / OpenCode / Gemini CLI / Qwen CLI / Grok CLI) with one rule set across all; Hooks integration (Claude Code 11 lifecycle hooks + Codex CLI notify hook + Gemini/Grok CLI hooks) with automatic graceful degradation when unavailable.

CLI Compatibility Quick Reference

CLI	Recommended Version	Key Features	Configuration Notes
Claude Code	Latest	Agent Teams, 11 lifecycle hooks, auto-memory	Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` for teams mode
Codex CLI	0.110+	spawn_agent, CSV batch, collaboration_modes	Enable sub-agents, CSV orchestration, set `project_doc_max_bytes >= 131072`
OpenCode	Latest	Task tool, custom agents, MCP	Supports primary agents (build/plan) + subagents (general/explore)
Gemini CLI	Latest	Built-in tool calls	Sequential execution fallback
Qwen CLI	Latest	Built-in tool calls	Sequential execution fallback
Grok CLI (Experimental)	Latest	Built-in tool calls	Community wrapper, hooks not fully verified

📋 Detailed CLI-specific notes (click to expand)

Codex CLI Configuration:

Enable sub-agents and CSV orchestration features
Set project_doc_max_bytes = 131072 in config.toml
Configure developer_instructions for routing protocol priority
Enable collaboration_modes for TUI interactive selection (v0.110+)
Configure nickname_candidates for agent role identification
Configure CSV batch processing if using parallel workflows

Claude Code Setup:

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable for Agent Teams
11 lifecycle hooks auto-configured during installation (SessionStart, UserPromptSubmit, SubagentStart/Stop, PostToolUse, Stop, TeammateIdle, PreCompact, PreToolUse, SessionEnd, PostToolUseFailure)
Auto-memory feature enabled by default

Other CLIs:

OpenCode supports Task tool with primary agents (build/plan) and subagents (general/explore)
Gemini/Qwen/Grok use sequential execution fallback
All features work with graceful degradation
Hooks may not be available on all platforms

Quick Start

💡 Choose your installation method:

First-time users → Method A (one-line script, recommended)

Node.js developers → Method B (npx)

Python developers → Method D (pip)

Need isolated environment → Method C (UV)

⚠️ Prerequisite: All AI CLIs (Codex CLI / Claude Code, etc.) should be upgraded to the latest version with relevant feature flags enabled (e.g., sub-agents, CSV orchestration) to access all HelloAGENTS capabilities. VSCode extensions for these CLIs update more slowly — some newer features may require waiting for the extension to catch up. See CLI-specific compatibility notes below.

⚠️ Windows PowerShell 5.1 does not support &&. Run commands on each side of && separately, or upgrade to PowerShell 7+.

Method A: One-line install script (recommended)

macOS / Linux:

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

Windows PowerShell:

irm https://github.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: re-run the install command above.

Uninstall: uv tool uninstall helloagents or pip uninstall helloagents (depends on what the script detected)

Switch branch:

# macOS / Linux
curl -fsSL https://github.com/hellowind777/helloagents/beta/install.sh | HELLOAGENTS_BRANCH=beta bash

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

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

npx helloagents

Installs the Python package via pip 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.

Update: npx helloagents@latest

Uninstall: pip uninstall helloagents

Switch branch: npx helloagents@beta

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: uv tool install --from git+https://github.com/hellowind777/helloagents helloagents --force

Uninstall: uv tool uninstall helloagents

Switch branch: uv tool install --from git+https://github.com/hellowind777/helloagents@beta helloagents --force

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

Uninstall: pip uninstall helloagents

Switch branch: pip install --upgrade git+https://github.com/hellowind777/helloagents.git@beta

HelloAGENTS commands (after installation)

⚠️ These commands depend on the installed package. If a remote update causes issues, use the native install/update/uninstall commands from your installation method above.

helloagents                  # interactive menu
helloagents install codex    # specify target directly
helloagents install --all    # install to all detected CLIs
helloagents status           # check installation status
helloagents version          # check version
helloagents update           # update + auto-sync all targets
helloagents update beta      # switch branch + auto-sync
helloagents uninstall codex  # uninstall from a CLI target
helloagents uninstall --all  # uninstall from all targets
helloagents clean            # clean caches

Codex CLI example

First install:

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

# Windows PowerShell
irm https://github.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

⚠️ Codex CLI config.toml compatibility notes: The following settings may affect HelloAGENTS:

[features] child_agents_md = true — experimental, injects extra instructions that may conflict with HelloAGENTS

project_doc_max_bytes too low — default 32KB, AGENTS.md will be truncated (auto-set to 131072 during install)

agent_max_depth = 1 — limits sub-agent nesting depth, recommend keeping default or ≥2

agent_max_threads too low — default 6, lower values limit parallel sub-agent scheduling (CSV batch mode recommends ≥16)

[features] multi_agent = true — must be enabled for sub-agent orchestration to work

[features] sqlite = true — must be enabled for CSV batch orchestration (spawn_agents_on_csv)

Collab sub-agent scheduling requires Codex CLI feature gate to be enabled

💡 Best practices:

Codex 0.110+ recommended for full feature set (collaboration_modes, nickname_candidates)

HelloAGENTS is optimized for Codex CLI — supports high and below reasoning effort levels. xhigh reasoning is not supported and may cause instruction-following issues

Use the terminal/CLI version of Codex for the best experience. The VSCode extension updates lag behind the CLI — newer features (e.g., CSV batch orchestration, Collab multi-agent) may require waiting for the extension to catch up

Claude Code example

First install:

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

# Windows PowerShell
irm https://github.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

💡 Claude Code sub-agent orchestration tips:

Sub-agents (Agent tool) work out of the box, no extra configuration needed

Agent Teams collaboration mode requires environment variable: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Parallel sub-agent count is managed automatically by the model, no user-side limit config needed

Configuration

Customize workflow behavior via config.json after installation. Only include keys you want to override — missing keys use defaults.

Storage locations (highest priority first):

Project-level: {project_root}/.helloagents/config.json — current project only
Global: ~/.helloagents/config.json — all projects
Built-in defaults

Available keys:

Key	Type	Default	Description
`OUTPUT_LANGUAGE`	string	`zh-CN`	Language for AI output and KB files
`KB_CREATE_MODE`	int	`2`	KB creation: `0`=OFF, `1`=on-demand (prompt ~init), `2`=auto on code changes, `3`=always auto
`BILINGUAL_COMMIT`	int	`1`	Commit language: `0`=OUTPUT_LANGUAGE only, `1`=OUTPUT_LANGUAGE + English
`EVAL_MODE`	int	`1`	Clarification mode: `1`=progressive (1 question/round, max 5), `2`=one-shot (all at once, max 3)
`UPDATE_CHECK`	int	`72`	Update check cache TTL in hours: `0`=OFF
`CSV_BATCH_MAX`	int	`16`	CSV batch max concurrency: `0`=OFF, cap 64 (Codex CLI only)

Example:

{
  "KB_CREATE_MODE": 0,
  "EVAL_MODE": 2
}

File missing or unparseable is silently skipped with defaults applied. Unknown keys produce a warning and are ignored.

Common Configuration Scenarios

📝 English-only projects

{
  "OUTPUT_LANGUAGE": "en-US",
  "BILINGUAL_COMMIT": 0
}

All AI outputs, KB files, and commit messages will be in English only.

🚫 Disable automatic KB creation

{
  "KB_CREATE_MODE": 0
}

Knowledge base won't be created automatically. Use ~init command when needed.

⚡ High-concurrency batch processing (Codex CLI)

{
  "CSV_BATCH_MAX": 32
}

Increase parallel CSV batch processing from 16 to 32 (max 64). Requires Codex CLI with CSV orchestration enabled.

🔕 Disable update checks

{
  "UPDATE_CHECK": 0
}

Skip version update checks entirely (not recommended for production use).

💬 One-shot clarification mode

{
  "EVAL_MODE": 2
}

Ask all clarification questions at once (max 3) instead of progressive mode (1 question per round, max 5).

How It Works

In short: HelloAGENTS automatically selects processing depth based on task complexity — simple questions get fast responses, complex tasks go through the full evaluate→design→develop flow, with safety checks and memory retention throughout.

Detailed flow:

Install & Deploy — Run helloagents to select target CLI, auto-deploys config files and hooks
Smart Routing — Every input is auto-scored; simple queries get direct answers, complex tasks enter structured workflow
Stage Progression — Complex tasks advance through "Evaluate → Design → Develop" stages, each with clear deliverables
Auto Orchestration — System dispatches sub-agents and specialized roles based on complexity, parallelizes when possible
Safety Guard — Each step scans for destructive operations, risky actions require user confirmation
Memory Retention — User preferences, project knowledge, session context persist across sessions
Verified Completion — Stage chain completes with verified output, auto-syncs knowledge base

In-Chat Workflow Commands

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

Common Commands:

Command	Purpose
~auto	full autonomous workflow
~plan	planning and package generation
~exec	execute existing package
~init	initialize knowledge base
~commit	generate commit message from context
~status / ~help	status and help

Quality Checks:

Command	Purpose
~test	run project tests
~review	code review
~validatekb	validate knowledge base

Advanced Features:

Command	Purpose
~upgradekb	upgrade knowledge structure
~clean / ~cleanplan	cleanup workflow artifacts
~rollback	rollback workflow state
~rlm	role orchestration (spawn / agents / resume / team)

Usage Guide

Three Workflow Modes

Mode	Description	When to use
`~auto`	Full autonomous flow from requirement to verified implementation (Evaluate → Design → Develop → Verify)	Clear requirement, want end-to-end delivery
`~plan`	Planning only, generates a proposal package then stops — no code written	Want to review the plan before committing
`~exec`	Skip evaluation and design, execute an existing plan package directly	After `~plan` review, ready to implement

Typical pattern: ~plan first → review → ~exec to implement. Or just ~auto for one-shot delivery.

Interactive vs Delegated Mode

When ~auto or ~plan presents its confirmation, you choose:

Interactive (default): pauses at key decision points (plan selection, failure handling)
Delegated (fully automatic): auto-advances all stages, auto-selects recommended options, only pauses on EHRB risk
Plan-only delegated: fully automatic but stops after design, never enters development

Without ~ commands, plain-text input is automatically routed to R0–R3 based on complexity.

Requirement Evaluation

Before R2/R3 tasks enter execution, the system scores requirements on four dimensions (scope 0–3, deliverable spec 0–3, implementation conditions 0–2, acceptance criteria 0–2, total 10). Score ≥ 8 proceeds to confirmation; < 8 triggers clarifying questions:

EVAL_MODE=1 (default, progressive): asks 1 lowest-scoring dimension per round, up to 5 rounds
EVAL_MODE=2 (one-shot): asks all low-scoring dimensions at once, up to 3 rounds

Context inferred from the existing codebase counts toward the score automatically. Say "skip evaluation / just do it" to bypass the questioning phase.

Parallel Design Proposals

In the R3 standard path, the design stage dispatches 3–6 sub-agents to independently generate competing implementation proposals. The main agent evaluates all proposals across four dimensions: user value, solution soundness, risk (including EHRB), and implementation cost. Weights are dynamically adjusted based on project characteristics (e.g., performance-critical systems weight soundness higher; MVPs weight cost higher).

Interactive mode: user selects a proposal or requests re-generation (max 1 retry)
Delegated mode: recommended proposal is auto-selected
R2 simplified path skips multi-proposal comparison and goes directly to planning

Auto Dependency Management

During development, the system auto-detects the project's package manager via lockfiles (yarn.lock → yarn, uv.lock → uv, Gemfile.lock → bundler, etc.) and handles dependencies:

Declared but missing dependencies: auto-installed
New dependencies required by tasks: auto-added with declaration file updated
Ambiguous dependencies: user is asked before installing

Quality Verification (Ralph Loop & Break-loop)

Ralph Loop (Claude Code, via SubagentStop Hook): after a sub-agent completes code changes, the project's verification command runs automatically. On failure, the sub-agent is blocked from exiting and must fix the issue (max 1 retry loop). Verification command priority: .helloagents/verify.yaml → package.json scripts → auto-detected.

Break-loop (deep root cause analysis): triggered when a task fails repeatedly (after Ralph Loop + at least 1 manual fix attempt), performing five-dimension root cause analysis:

Root cause classification (logic error / type mismatch / missing dependency / environment / design flaw)
Why previous fixes didn't work
Prevention mechanism suggestions
Systemic scan — same issue in other modules?
Lessons learned recorded in the acceptance report

Custom Command Extension

Create .helloagents/commands/ in your project and drop in Markdown files — the filename becomes the command name:

.helloagents/commands/deploy.md  →  ~deploy
.helloagents/commands/release.md →  ~release

File content defines the execution rules. The system applies a lightweight gate (requirement understanding + EHRB check).

Smart Commit (~commit)

~commit does more than generate a message:

Analyzes git diff to auto-generate Conventional Commits formatted messages
Pre-commit quality checks (code-doc consistency, test coverage, verification commands)
Auto-excludes sensitive files (.env, *.pem, *.key, etc.) — never runs git add .
Shows file list before staging, supports exclusion
Options: local commit only / commit + push / commit + push + create PR
Bilingual commit messages when BILINGUAL_COMMIT=1

Manual Sub-Agent Invocation

Beyond automatic dispatch, you can manually invoke specific roles:

~rlm spawn reviewer "review src/api/ for security issues"
~rlm spawn writer "generate API reference docs"
~rlm spawn reviewer,writer "analyze and document the auth module"  # parallel

Available roles: reviewer (code review), writer (documentation), brainstormer (multi-proposal comparison).

Multi-Terminal Collaboration

Multiple terminals (across different CLIs) can share a task list:

# Terminal A
hellotasks=my-project codex

# Terminal B
hellotasks=my-project claude

Commands once enabled:

~rlm tasks                  # view shared task list
~rlm tasks available        # see unclaimed tasks
~rlm tasks claim <id>       # claim a task
~rlm tasks complete <id>    # mark done
~rlm tasks add "task title" # add a new task

Tasks are stored in {KB_ROOT}/tasks/ with file locking to prevent concurrent conflicts.

KB Auto-Sync & CHANGELOG

The knowledge base syncs automatically at these points:

After every development stage, main agent syncs module docs to reflect actual code
After every R1/R2/R3 task completion, CHANGELOG is auto-appended
On session end (Claude Code Stop Hook), KB sync flag set asynchronously

CHANGELOG uses semantic versioning (X.Y.Z). Version source priority: user-specified → project file (package.json, pyproject.toml, etc., supporting 15+ languages/frameworks) → git tag → last CHANGELOG entry → 0.1.0. R1 fast-path changes are recorded under a "Quick Modifications" category with file:line range.

KB_CREATE_MODE controls automatic behavior: 0=off, 1=prompt on demand, 2=auto on code changes (default), 3=always auto.

Worktree Isolation

When multiple sub-agents need to modify different regions of the same file simultaneously (Claude Code only), the system automatically uses Task(isolation="worktree") to create an independent git worktree for each sub-agent, preventing Edit tool conflicts. The main agent merges all worktree changes in the consolidation phase. Only activated when sub-agents have overlapping file writes; read-only tasks don't use it.

CSV Batch Orchestration (Codex CLI)

When ≥6 structurally identical tasks exist in the same execution layer, the system auto-converts tasks.md into a task CSV and dispatches via spawn_agents_on_csv. Each worker receives its row data + instruction template, executes independently, and reports results.

Progress tracked in real-time via agent_job_progress events (pending/running/completed/failed/ETA)
State persisted in SQLite for crash recovery
Partial failures still export results with failure summary
Heterogeneous tasks automatically fall back to spawn_agent sequential dispatch
Configure concurrency via CSV_BATCH_MAX (default 16, max 64, set to 0 to disable)

Update Check

On the first response of each session, the system silently checks for new versions. Results are cached at ~/.helloagents/.update_cache, valid for the duration set by UPDATE_CHECK (default 72 hours, set to 0 to disable). When a new version is available, ⬆️ New version {version} available appears in the response footer. Any errors during the check are silently skipped and never interrupt normal usage.

Repository Guide

AGENTS.md: router and workflow protocol
SKILL.md: skill discovery metadata for CLI targets
pyproject.toml: package metadata (v2.3.7)
helloagents/cli.py: CLI entry point
helloagents/_common.py: shared constants and utilities
helloagents/core/: CLI management modules (install, uninstall, update, status, dispatcher, hooks settings)
helloagents/functions: command definitions (15)
helloagents/stages: design, develop
helloagents/services: knowledge, package, memory and support services
helloagents/rules: state, cache, tools, scaling, sub-agent protocols
helloagents/rlm: role library and orchestration helpers
helloagents/hooks: Claude Code, Codex CLI, Gemini CLI, and Grok CLI hooks configs
helloagents/scripts: automation scripts (sound notify, progress snapshot, safety guard, etc.)
helloagents/agents: sub-agent definitions (3 RLM roles)
helloagents/user/commands: custom command templates
helloagents/assets: sound resources (5 event sounds)
helloagents/templates: KB and plan templates

FAQ

Q: Is this a Python CLI tool or prompt package?

A: Both. The CLI manages installation and updates, while the workflow behavior comes from AGENTS.md and documentation files. Think of it as a delivery system + intelligent workflow protocol.

Q: Which target should I install?

A: Choose the CLI you're actively using: codex (Codex CLI), claude (Claude Code), gemini (Gemini CLI), qwen (Qwen CLI), grok (Grok CLI), or opencode (OpenCode). You can install to multiple targets with helloagents install --all. See CLI Compatibility Quick Reference for details.

Q: What if a rules file already exists?

A: HelloAGENTS automatically backs up non-HelloAGENTS files before replacement. Backups are timestamped and stored in your CLI's config directory. You can restore them anytime if needed.

Q: What is RLM?

A: Role Language Model — HelloAGENTS's sub-agent orchestration system. It includes 3 specialized roles (reviewer, writer, brainstormer) plus native CLI sub-agents. Tasks are scheduled via DAG dependency analysis with parallel execution when possible. Learn more in Usage Guide.

Q: Where does project knowledge go?

A: In the project-local .helloagents/ directory. The knowledge base auto-syncs when code changes (controlled by KB_CREATE_MODE config). It includes module docs, CHANGELOG, session summaries, and custom commands. See KB Auto-Sync & CHANGELOG.

Q: Does memory persist across sessions?

A: Yes, through two layers: L0 user memory (global preferences in ~/.helloagents/) and L1 project KB (per-project in .helloagents/). Context survives even if you close and reopen your CLI.

Q: What are Hooks?

A: Lifecycle hooks auto-deployed during installation. Claude Code gets 11 event hooks (safety checks, dangerous command guard, progress snapshots, KB sync, sound notifications, tool failure recovery, etc.); Codex CLI gets a notify hook for update and sound notifications; Gemini CLI and Grok CLI get hooks for context injection, progress snapshots, and sound notifications. All optional — features degrade gracefully when hooks aren't available. No manual configuration needed.

Q: What is Agent Teams?

A: An experimental Claude Code feature where multiple Claude Code instances collaborate as teammates with shared task lists and mailbox communication. Enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. When unavailable, HelloAGENTS falls back to standard Task sub-agents. See Multi-Terminal Collaboration.

Troubleshooting

Command not found

Problem: helloagents: command not found after installation

Diagnosis: Install path not in system PATH

Solution:

UV: Restart terminal after UV installation
pip: Check pip show helloagents for install location, add to PATH
Verify with which helloagents (Unix) or where helloagents (Windows)

Verification: Run helloagents version

Package version unknown

Problem: Version shows as "unknown"

Diagnosis: Package metadata not available

Solution: Install the package first: pip install git+https://github.com/hellowind777/helloagents.git or use UV/npx methods

Verification: Run helloagents version — should show current version number

Target not detected

Problem: CLI target not found during installation

Diagnosis: Config directory doesn't exist yet

Solution: Launch the target CLI at least once to create its config directory, then retry helloagents install <target>

Verification: Check config paths:

Codex CLI: ~/.codex/
Claude Code: ~/.claude/
Others: see CLI documentation

Custom rules overwritten

Problem: Custom rules replaced by HelloAGENTS

Diagnosis: Installation replaces existing files

Solution: Restore from timestamped backup in CLI config directory (e.g., ~/.codex/rules/AGENTS.md.backup.20260304_132146)

Verification: Check backup files in config directory

Images not rendering

Problem: README images don't display

Diagnosis: Missing image files or incorrect paths

Solution:

Keep relative paths in README (e.g., ./readme_images/)
Ensure readme_images/ folder is committed to repository
Verify image files exist locally

Verification: Check ls readme_images/ shows all referenced images

CCswitch replaces HelloAGENTS config

Problem: After switching CCswitch profiles, HelloAGENTS stops working (workflow commands unrecognized, hooks not firing, rules missing)

Diagnosis: CCswitch replaces the entire CLI config directory (e.g., ~/.claude/) when switching profiles, overwriting HelloAGENTS's hooks, permissions, and rule files

Solution: After switching CCswitch profiles, run one of these commands to restore HelloAGENTS:

helloagents install claude    # reinstall to specific CLI target
helloagents update            # update + auto-sync all installed targets

Prevention: Since v2.3.5, automatic configuration integrity check on session start — if HelloAGENTS config is missing or corrupted, a warning is displayed with recovery instructions

Verification: Run helloagents status to confirm all targets show as installed

CCswitch configuration conflict

Problem: HelloAGENTS config reappears after uninstall when switching CCswitch profiles

Diagnosis: CCswitch saved HelloAGENTS settings before uninstall

Solution: After uninstalling HelloAGENTS, manually clean up HelloAGENTS-related settings (hooks, permissions, rules) from all saved CCswitch profiles

Verification: Check CCswitch profile directories for HelloAGENTS remnants

Version History

v2.3.7 (current)

Bug Fixes:

Fixed non-coding tasks incorrectly creating knowledge base when KB_CREATE_MODE=2 (added programming task check in design.md Phase1 step 1)
Fixed R2 standard flow redirecting to archive instead of DEVELOP after proposal selection (constrained overview type to ~exec entry only)
Fixed non-coding tasks incorrectly creating plan packages (added programming task precondition to package.md create() interface)

Improvements:

Optimized implementation plan state recovery after context compression
Optimized overall design flow

v2.3.6

New Features:

Sub-agent orchestration overhaul: added brainstormer sub-agent for independent parallel proposal ideation during DESIGN multi-proposal comparison
Sub-agent blocking mechanism: auto-block and fallback to main agent on sub-agent failure or timeout

Improvements:

Tool/Shell constraint optimization: allow fallback to Shell when built-in tools fail (fixes Codex CLI Windows apply_patch repeated failures)
Shell encoding constraint refinement: explicit UTF-8 no-BOM requirement, separate read/write encoding handling for PowerShell
Added batch file write rule (merge ≥3 files into a single temp script to avoid sandbox per-command blocking)
Removed session memory features that couldn't be fully implemented in CLI (session_summary template, SessionEnd memory sync), streamlined service layer
Sub-agent consolidation: removed 3 redundant sub-agents (kb-keeper, pkg-keeper, synthesizer), functionality returned to main agent and RLM roles
Sub-agent voice notification skip, task stability fixes
Unified user config directory structure (user/memory/, user/commands/, user/sounds/)
Uninstall script enhancements
Visual verification gap and UI quality fixes

v2.3.5

New Features:

Voice notification system with 5 event sounds (complete, idle, confirm, error, warning) across Windows/macOS/Linux, with smart two-layer routing (stop_reason + G3 format icon detection)
Claude Code hooks expanded from 9 to 11 lifecycle event types: added dangerous command guard (PreToolUse), session end cleanup (SessionEnd), and tool failure recovery suggestions (PostToolUseFailure)
Hooks support expanded to Gemini CLI and Grok CLI (SessionStart, BeforeAgent/AfterAgent, PreCompress, PreToolUse, PostToolUse)
Codex CLI 0.110 features: collaboration_modes for TUI interactive selection, nickname_candidates for agent role identification
Configuration integrity check on session start (auto-detect config corruption or replacement by CCswitch etc.)
Context compression pre-save with automatic progress snapshot (pre_compact.py, progress_snapshot.py — actual implementations replacing placeholder hooks)
User-defined tool registration and orchestration — intelligent invocation of custom sub-agents, skills, MCP servers, and plugins
Custom command extension support via .helloagents/commands/*.md

Improvements:

Comprehensive audit fixes (21 issues: 6 HIGH + 9 MEDIUM + 6 LOW)
- Code quality: extracted 5 shared utility functions, eliminated circular dependencies
- Cross-platform: unified platform detection, consistent encoding handling
- Security: configuration backup before overwrite, placeholder validation
- Documentation: configuration rationale, compatibility verification notes
Core architecture: new dispatcher module, Codex roles definition, Claude rules management, hooks settings manager
Install/update script refactoring with persistent configuration
Voice notification accuracy and false positive reduction (Codex client filtering, Windows sync playback)
Sub-agent nickname optimization across CLIs
Codex CLI interactive menu, persistent memory, and context compression optimization
R2 simplified flow and evaluation module re-integration
Context compression state persistence optimization
Tool/Shell usage optimization
CCswitch compatibility notes for configuration cleanup after uninstall
SKILL discovery entry optimization

v2.3.4

Split 3 oversized files (>450 lines) into 6 independent modules
Consolidated 9 CLI management scripts into core/ subpackage
Extracted shared constants and utilities into dedicated module, eliminating circular dependencies
Removed redundant backward-compatible re-exports
Elevated Codex CLI routing protocol priority to prevent system prompt override

v2.3.0

Comprehensive cross-audit fix: unified role output format, normalized path references, code-doc consistency alignment
Quality verification loop (Ralph Loop): auto-verify after sub-agent completion, block and feedback on failure
Auto context injection for sub-agents and rule reinforcement for main agent
Deep 5-dimension root cause analysis on repeated failures (break-loop)
Auto-inject project technical guidelines before sub-agent development
Pre-commit quality checks (code-doc consistency, test coverage, verification commands)
Worktree isolation for parallel editing
Custom command extension (.helloagents/commands/)
Auto-append Git author info to CHANGELOG entries

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.

Next Steps

Getting Started:

Install HelloAGENTS using your preferred method: Quick Start
Try ~auto with a simple task to see the full workflow in action
Explore ~plan + ~exec for more control over the process

Learn More:

Read Usage Guide for detailed workflow patterns
Check Configuration to customize behavior
Review In-Chat Workflow Commands reference

Community & Support:

Star the repo if HelloAGENTS helps your workflow
Report issues or request features on GitHub Issues
Contribute improvements: see CONTRIBUTING.md

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 250 Commits
.github/workflows		.github/workflows
bin		bin
helloagents		helloagents
readme_images		readme_images
scripts		scripts
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
README_CN.md		README_CN.md
SKILL.md		SKILL.md
install.ps1		install.ps1
install.sh		install.sh
package.json		package.json
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

HelloAGENTS

Table of Contents

Before and After

Core Features

Sub-Agent Native Mapping

CLI Compatibility Quick Reference

Quick Start

Method A: One-line install script (recommended)

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

Method C: UV (isolated environment)

Method D: pip (Python >= 3.10)

HelloAGENTS commands (after installation)

Codex CLI example

Claude Code example

Configuration

Common Configuration Scenarios

How It Works

In-Chat Workflow Commands

Usage Guide

Three Workflow Modes

Interactive vs Delegated Mode

Requirement Evaluation

Parallel Design Proposals

Auto Dependency Management

Quality Verification (Ralph Loop & Break-loop)

Custom Command Extension

Smart Commit (~commit)

Manual Sub-Agent Invocation

Multi-Terminal Collaboration

KB Auto-Sync & CHANGELOG

Worktree Isolation

CSV Batch Orchestration (Codex CLI)

Update Check

Repository Guide

FAQ

Troubleshooting

Command not found

Package version unknown

Target not detected

Custom rules overwritten

Images not rendering

CCswitch replaces HelloAGENTS config

CCswitch configuration conflict

Version History

v2.3.7 (current)

v2.3.6

v2.3.5

v2.3.4

v2.3.0

Contributing

License

Next Steps

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Contributors 2

Languages

Packages