invoking-cli-agents

name: invoking-cli-agents description: Use when needing to programmatically invoke a CLI coding agent (Claude Code, OpenCode) from Python, delegate work to a sub-agent, or orchestrate multiple agents. Covers AgentShell instantiation, prompt execution, response streaming, session resumption, tool scoping, and cost tracking.

Invoking CLI Agents with AgentShell

AgentShell is a Python library that runs CLI coding agents headlessly and returns structured output. It hides agent-specific CLI differences behind a unified interface so your code works regardless of which agent runs underneath.

When to Use

• You need to invoke Claude Code, OpenCode, or another CLI agent from Python
• You want to delegate a coding task to a sub-agent and collect the result
• You need to orchestrate multi-step workflows across agents
• You want to stream agent output in real-time

When NOT to Use

• You want to call the Anthropic API directly (use the SDK instead)
• The CLI agent is already running interactively and you just need its output

Installation

uv add agent-shell-py

Core Concepts

AgentShell has two methods: execute() for collecting a complete response, and stream() for real-time event processing. Both are async.

Execute: Run and Collect

Use when you want the final answer and don't need intermediate output.

from agent_shell.shell import AgentShell
from agent_shell.models.agent import AgentType

shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)

response = await shell.execute(
    cwd="/path/to/project",
    prompt="Analyse the authentication module and list all public functions",
    allowed_tools=["Read", "Glob", "Grep"],
    model="sonnet",
)

print(response.response)      # Full text output
print(f"Cost: ${response.cost:.4f}")
print(f"Session: {response.session_id}")

Stream: Real-Time Events

Use when you need progress feedback, want to display output incrementally, or need to react to specific event types (tool use, thinking, errors).

async for event in shell.stream(
    cwd="/path/to/project",
    prompt="Refactor the auth module to use dependency injection",
    allowed_tools=["Read", "Edit", "Bash"],
    model="sonnet",
    effort="high",
    include_thinking=True,
):
    if event.type == "system":
        print(f"Session: {event.session_id}")
    elif event.type == "thinking":
        print(f"[thinking] {event.content}")
    elif event.type == "tool_use":
        print(f"[tool] {event.content}")
    elif event.type == "text":
        print(event.content)
    elif event.type == "result":
        print(f"Done. Cost: ${event.cost:.4f}, Duration: {event.duration:.1f}s")

Session Resumption

Pass session_id from a previous response to continue the conversation. This enables multi-turn workflows where each step builds on the last.

# Step 1: Analyse
analysis = await shell.execute(
    cwd="/path/to/project",
    prompt="Analyse this codebase and identify areas that need refactoring",
    allowed_tools=["Read", "Glob", "Grep"],
    model="sonnet",
)

# Step 2: Act on the analysis (same session)
refactor = await shell.execute(
    cwd="/path/to/project",
    prompt="Now refactor the top priority item you identified",
    allowed_tools=["Read", "Edit", "Bash"],
    model="sonnet",
    session_id=analysis.session_id,
)

Parameters

Agent parity warning: OpenCode currently only maps model and session_id to CLI flags. Parameters like allowed_tools, effort, include_thinking, and auto_approve are accepted but silently ignored. Do not rely on allowed_tools for safety when using OpenCode.

Supported Agents

from agent_shell.models.agent import AgentType

AgentType.CLAUDE_CODE   # Claude Code CLI
AgentType.OPENCODE      # OpenCode CLI

Gemini CLI, Copilot CLI, and Codex have enum values but no adapter yet.

Tool Scoping (Claude Code Only)

Restrict what the agent can do by passing allowed_tools. This is critical for safety when delegating work.

Important: Tool scoping only works with Claude Code. OpenCode ignores allowed_tools — the agent will have access to all tools regardless of what you pass. Do not use OpenCode for safety-sensitive delegation where tool restriction is required.

Gotcha: allowed_tools=[] (empty list) is falsy in Python, so no --allowed-tools flag is sent — the agent gets full tool access. To restrict tools, always pass a non-empty list. There is no way to disable all tools via this parameter.

# Read-only analysis (Claude Code)
shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)

response = await shell.execute(
    cwd=project_path,
    prompt="Review this code for security issues",
    allowed_tools=["Read", "Glob", "Grep"],  # No write access
)

# Full write access for implementation
response = await shell.execute(
    cwd=project_path,
    prompt="Implement the fix you recommended",
    allowed_tools=["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
)

Error Handling

AgentShell raises exceptions for some errors, but CLI agent failures are reported as events, not exceptions.

from pathlib import Path

# cwd validation - raises ValueError if directory doesn't exist
try:
    response = await shell.execute(cwd="/nonexistent", prompt="hello")
except ValueError as e:
    print(f"Bad directory: {e}")

# Unsupported agent type - raises ValueError at construction
try:
    shell = AgentShell(agent_type=AgentType.GEMINI_CLI)
except ValueError as e:
    print(f"No adapter: {e}")

# KeyboardInterrupt - AgentShell cancels the subprocess cleanly
try:
    response = await shell.execute(cwd=project_path, prompt="long task...")
except KeyboardInterrupt:
    print("Agent cancelled")

CLI agent failures do not raise exceptions. execute() returns an AgentResponse with whatever text was accumulated (which may be empty) and gives no indication of failure. When streaming, failures surface in two ways:

• StreamEvent(type="error") — CLI process errors or OpenCode agent errors
• StreamEvent(type="result", content="error") — Claude Code agent-level failures

Check for both when streaming:

async for event in shell.stream(cwd=project_path, prompt="do something"):
    if event.type == "error":
        print(f"Agent error: {event.content}")
        break
    elif event.type == "result" and event.content == "error":
        print("Agent reported failure")
        break
    elif event.type == "text":
        print(event.content)

Logging

import logging

logging.getLogger("agent_shell").setLevel(logging.DEBUG)
logging.getLogger("agent_shell").addHandler(logging.StreamHandler())

INFO captures tool calls, session IDs, costs, errors. DEBUG adds raw JSON events.

Quick Reference

Common Mistakes

API Reference

For detailed model definitions, event types, and adapter protocol: see api-reference.md.