agy-cli-runtime

agy Runtime

Use this skill only inside the agy:agy-explorer subagent or the agy:* commands.

Primary helper:

• node "${CLAUDE_PLUGIN_ROOT}/scripts/agy-companion.mjs" <mode> "<raw arguments>"

Modes:

• explore — read-only codebase exploration. The companion injects a read-only frame and never grants write permission. This is the default for the subagent.
• ask — general one-shot prompt, forwarded as written. Read-only unless --write.
• setup — diagnose the local agy install (binary, version, model list).

Execution rules:

• The explorer subagent is a forwarder, not an orchestrator. Invoke the helper once and return its stdout unchanged.
• Prefer the helper over hand-rolled agy strings, direct file reads, or grep.
• Do not inspect the repository, solve the task yourself, or add analysis of your own.
• Return the stdout of the command exactly as-is. If it fails, return nothing extra.

Flags recognized inside the raw argument string (everything else is the prompt):

• --model "<name>" — EXPERIMENTAL. Pass a model to agy. On agy v1.0.6 the display names from agy models were observed to hang in --print mode. Leave unset to use agy's fast default (a Gemini Flash tier); that is the recommended path.
• --add-dir <path> — add a directory to agy's workspace (repeatable).
• --timeout <dur> — Go duration for the print timeout (e.g. 90s, 10m). Default 5m.
• --write — (ask mode only) allow writes via --dangerously-skip-permissions.

How the helper maps to agy:

• Builds agy --print --print-timeout <dur> [--model <name>] [--add-dir <path>]... [--dangerously-skip-permissions].
• The prompt is piped to agy over stdin, never as a CLI argument, so a prompt that starts with -- cannot be misparsed as a native agy flag.
• --print runs a single prompt non-interactively and prints the response (no TUI).
• The binary is agy (not antigravity). Override with the AGY_BIN env var.
• Flags are matched only as whole tokens at word boundaries; prose like --foo--timeout stays in the prompt. --flag=value and quoted values are accepted.

Safety rules:

• explore never enables writes. Only ask --write does, and only on explicit request.
• Preserve the user's prompt text as-is apart from extracting the routing flags above.
• Do not poll, resume, or run follow-up invocations. One call per request.