Use ai-devkit agent send --wait for Programmatic Agent Calls

ai-devkit agent send --wait lets a script send a prompt to an already-running interactive coding agent, wait for the next assistant response, and print that response to stdout.

This is useful when you want the ergonomics of an interactive agent session but need a programmatic interface similar to claude -p or codex exec.

Prerequisites#

Before using this workflow:

• Install AI DevKit and make sure ai-devkit is available in your shell.
• Start a supported agent in the project you want to control: Claude Code, Codex, GitHub Copilot, Gemini CLI, Grok CLI, Kiro CLI, Antigravity CLI, opencode, Pi, Devin, or Muse Code.
• Keep that agent running in a supported terminal session: tmux, WezTerm, Ghostty, iTerm2, or Apple Terminal.
• Run ai-devkit agent list and confirm the session appears.

Quick Example#

Start your coding agent normally in one terminal:

claude
# or codex
# or gemini
# or copilot
# or grok
# or opencode
# or pi

In another terminal, find the session identifier:

ai-devkit agent list

Look for the Agent column. Use that value, or a unique partial match, as --id.

Agent        CWD                  Type         Status
my-project   ~/code/my-project    Claude Code  wait

Then send a prompt and wait for the response:

ai-devkit agent send "Summarize the current git diff and identify risks." --id my-project --wait

The assistant response is printed to stdout. Status messages and warnings are written to stderr, so scripts can pipe or capture the response cleanly.

Why use this instead of claude -p or codex exec?#

Use agent send --wait when you want to talk to an existing interactive session instead of starting a fresh one-off process.

That means the agent keeps its current:

• conversation context
• working directory
• loaded project state
• configured tools and MCP servers
• authentication and permission state
• terminal session and interactive approvals

This makes it a strong fit for automation that should continue work inside the same supported interactive agent session.

When should I still use claude -p or codex exec?#

Use a native non-interactive command when you want a brand-new isolated run, predictable startup behavior, and no dependency on a live terminal session.

Use ai-devkit agent send --wait when the existing interactive session is the feature: you want to preserve context, reuse approvals, and keep the session visible for a human to inspect.

Which agents are supported?#

agent send --wait uses the same agent detection system as ai-devkit agent list.

Current interactive adapters include:

• Claude Code
• Codex
• GitHub Copilot
• Gemini CLI
• Grok CLI
• Kiro CLI
• Antigravity CLI
• opencode
• Pi
• Devin
• Muse Code

Support depends on AI DevKit being able to detect the live process, find its terminal, and read its session transcript.

Run this to confirm what AI DevKit can see on your machine:

ai-devkit agent list

How do I select the target session?#

Use --id with the agent name or a unique partial match from agent list.

ai-devkit agent send "What are you working on?" --id frontend --wait

If multiple agents match the same identifier, AI DevKit asks you to use a more specific value.

For scripts, prefer exact or highly specific identifiers.

Can I pipe a prompt from stdin?#

Yes. Use --stdin, or pipe input without a message argument.

git diff -- src/ tests/ | ai-devkit agent send --id my-project --stdin --wait

You can also compose a prompt around command output:

{
  printf 'Review this diff for bugs and missing tests:\n\n'
  git diff
} | ai-devkit agent send --id my-project --stdin --wait

Can I get JSON output?#

Yes. Add --json with --wait.

ai-devkit agent send "Return a short implementation plan." --id my-project --wait --json

The JSON output includes the target metadata, prompt, captured response messages, elapsed time, and final agent status.

This is useful when your script needs more than plain text:

response_json="$(ai-devkit agent send "List the next 3 tasks." --id my-project --wait --json)"
printf '%s\n' "$response_json"

How long does --wait wait?#

By default, AI DevKit waits up to 10 minutes.

Use --timeout to set a custom limit in milliseconds:

ai-devkit agent send "Run the focused tests and report failures." --id my-project --wait --timeout 30000

--timeout only works together with --wait.

What exactly is printed?#

In plain text mode, AI DevKit prints new assistant messages created after the prompt was sent.

It does not print older conversation history, and it does not print the user prompt back to stdout.

Warnings, status messages, and timeout errors are sent to stderr. This keeps stdout suitable for command substitution and pipelines.

Does this execute commands directly?#

No. AI DevKit sends text into the agent's existing terminal session. The agent decides how to respond, including whether it needs to ask for tool approval or run commands through its normal interactive flow.

This is why agent send --wait can be a practical bridge between automation and interactive coding agents: scripts can request work, while the agent still follows its normal permission and tool behavior.

What are common failure cases?#

No running agents found#

Start one of the supported interactive agents listed above, then run:

ai-devkit agent list

No agent found matching the id#

Check the displayed agent names:

ai-devkit agent list

Then pass a more specific --id.

Cannot find terminal for the agent#

AI DevKit needs to find the terminal that owns the running agent process. Supported terminals are tmux, WezTerm, Ghostty, iTerm2, and Apple Terminal.

On macOS, terminal focusing and sending may require Accessibility permissions for your terminal application.

Timed out waiting for response#

The agent did not return to a waiting or idle state before the timeout. Increase --timeout, check the interactive terminal, or answer any approval prompt the agent is waiting on.

Example: shell helper function#

ask_agent() {
  local agent_id="$1"
  shift
  ai-devkit agent send "$*" --id "$agent_id" --wait
}

ask_agent my-project "Explain the failing test and suggest the smallest fix."

Example: use an agent as a review step#

review_output="$(
  {
    printf 'Review this change. Focus on bugs, regressions, and missing tests.\n\n'
    git diff --stat
    printf '\n'
    git diff
  } | ai-devkit agent send --id my-project --stdin --wait --timeout 120000
)"

printf '%s\n' "$review_output"

Mental model#

claude -p and codex exec are closer to "start a new programmatic run."

ai-devkit agent send --wait is closer to "send a message to the interactive agent I already have running, then wait until it answers."

Choose the second model when session continuity matters.