Use when an agent needs a human decision, approval, or clarification. This skill explains how to set up and run consult-human for blocking and non-blocking human consultations, including ask flags, setup flows, config reset behavior, and storage/cache clearing commands. Better ask than assume.
Use consult-human whenever an agent needs a human decision, approval, or clarification instead of assuming things.
--help. Its supported universally in the command.consult-human ask [flags] <question>consult-human setup [flags]consult-human config <path|show|init|set|reset>consult-human storage <path|clear>consult-human skill <install>command not found: consult-human, the default ~/.zshrc/~/.bashrc shell profiles are not loaded. Login profiles are sourced instead (~/.zshenv, ~/.zprofile, ~/.zlogin, , ).~/.bash_profile~/.bash_loginRun consult-human setup before the first consultation or when re-linking a provider (ex Telegram).
setup auto-ensures the current consult-human binary directory is on PATH in the detected shell login profile in both interactive and non-interactive modes. It prints what it changed and does not require extra prompts for PATH.
Choose setup mode based on who is doing the setup:
--non-interactive mode: use when the agent will run steps turn-by-turn in via bash commands.Supported setup flags:
--non-interactive: prints a list of setup steps without TTY prompts, and still auto-ensures shell PATH. Agent-friendly.--provider telegram: restrict setup to a specific messaging provider Telegram.--link-chat: wait for Telegram /start and save telegram.chat_id without setup prompts.consult-human setup.Use this mode when you want explicit steps without TTY or terminal interactivity. Agent-friendly. This mode still performs shell PATH ensure automatically.
consult-human setup --non-interactiveconsult-human setup --non-interactive --provider telegramconsult-human setup --provider telegram --link-chatconsult-human config resetconsult-human config reset --keep-storageconsult-human config reset --provider telegramconsult-human config reset --provider telegram --keep-storageconsult-human setup --provider telegramconsult-human setup --provider telegram --link-chatconsult-human storage clearconsult-human storage pathconsult-human storage clear --provider telegramconsult-human storage path --provider telegramconsult-human skill install --target claudeconsult-human skill install --target codexconsult-human skill install --target bothAll ask flags are optional. The only required input is the positional <question>.
--choice <id:label|label> (optional, repeatable, default none): adds one selectable option for the human reply. Use id:label for stable IDs (example: A:Ship now) or plain label for auto-generated IDs.--allow-other (optional, default false): allows a free-text answer outside the listed choices, so the human is not forced to pick only from predefined options. Requires at least one --choice.--provider <name> (optional, default is the config field active_provider): overrides the active provider used for this ask call. Current active support is Telegram (whatsapp is temporarily disabled).--timeout <duration in seconds> (optional, default configured request_timeout): sets how long ask waits before timing out for this call. Format examples: 30s, 5m, 30m.Use this when execution must pause until the human answers.
consult-human ask "<question>".Examples:
consult-human ask "Should I run the migrations now?"
consult-human ask \
--choice "A:Ship now" \
--choice "B:Wait for review" \
--allow-other \
"Please make a Release decision"
If you are Claude Code:
Execute the consult-human ask ... command via your Bash tool, setting the run_in_background parameter as false, and timeout as 600000 (10 min).
Use this when the agent should continue work while waiting for a human response.
The only way to do async/non-blocking consultation is via leveraging the capabilities in your (the agent's) harness.
If you are Claude Code:
Execute the consult-human ask ... command via your Bash tool, setting the run_in_background parameter as true, and timeout as 600000 (10 min).
--timeout for longer waits, for example --timeout 30m.ask request.askUsage:
consult-human ask [flags] <question>Flags:
--choice <id:label|label>: Add one choice. Repeatable.--allow-other: Allow free-text answer outside listed choices. Requires at least one --choice.--provider <name>: Override configured provider for this call.--timeout <duration>: Override request timeout for this call (30s, 5m, 30m).setupUsage:
consult-human setup [--provider telegram] [--link-chat]consult-human setup --non-interactive [--provider telegram]Flags:
--non-interactive: Print checklist instead of prompting, while still auto-ensuring shell PATH.--provider <name>: Restrict setup to a provider (currently telegram).--link-chat: Wait for Telegram /start and save chat id without setup prompts.configUsage:
consult-human config pathconsult-human config showconsult-human config initconsult-human config set <key> <value>consult-human config reset [--provider telegram|whatsapp] [--keep-storage]Flags:
config reset --provider <telegram|whatsapp>: Reset one provider section only.config reset --keep-storage: Skip clearing local storage/cache files during reset.Supported keys for config set:
default-provider (aliases: provider, active_provider)request_timeouttelegram.bot_tokentelegram.chat_idtelegram.poll_interval_secondstelegram.pending_store_path (alias: telegram.store_path)whatsapp.recipientwhatsapp.store_pathstorageUsage:
consult-human storage pathconsult-human storage path --provider <all|telegram|whatsapp>consult-human storage clearconsult-human storage clear --provider <all|telegram|whatsapp>Flags:
storage path --provider <all|telegram|whatsapp>: restrict path output scope.storage clear --provider <all|telegram|whatsapp>: restrict storage clearing scope.Usage:
consult-human skill install [--target claude|codex|both] [--repo <path>] [--source <path>] [--copy]consult-human install-skill [--target claude|codex|both] [--repo <path>] [--source <path>] [--copy]Defaults:
<config-dir>/SKILL.md where <config-dir> is the directory of consult-human config path.consult-human storage clear (all scope) and consult-human config reset delete this managed skill file.skill install also appends/updates an IMPORTANT consult-human reminder block in runtime instruction files:
<base>/.claude/CLAUDE.md<base>/.codex/AGENTS.md<base>/.agents/AGENTS.md<base> is home for global install, or --repo path for repo-scoped install.Flags:
skill install --target <claude|codex|both>: choose runtime destination(s); default is both.skill install --repo <path>: install under this repository path (<repo>/.claude/skills/... or <repo>/.codex/skills/...) instead of user-global directories.skill install --source <path>: read SKILL.md from a specific local file.skill install --copy: copy file contents instead of using symlinks.