Simple Claude Agent

An interactive Claude Agent CLI with streaming responses and HTTP proxy configuration.

✨ Features

• 🔄 Interactive REPL Mode - Continuous query loop until /exit
• 📡 Streaming Responses - Real-time output as Claude processes
• 🌐 Proxy Support - Built-in HTTP/HTTPS proxy configuration
• ⚡ Quick Commands - /exit, /help, /clear for better UX
• 🎯 Flexible Tools - Configurable tool permissions
• 🔧 Dual Modes - Interactive or single-query command-line mode

Prerequisites

1. Claude Code CLI - Install from claude.ai/code

   # macOS/Linux
   curl -fsSL https://claude.ai/install.sh | bash
   
   # Or with Homebrew
   brew install --cask claude-code

2. Claude Code Authentication - Login to Claude Code

   claude login

3. HTTP Proxy - Running at 127.0.0.1:7897

Setup

1. Install dependencies:

   uv sync

2. Login to Claude Code (if not already logged in):

   claude login

   Check login status:

   claude login --status

Usage

🎮 Interactive Mode (Recommended)

Start the interactive REPL:

# Using the quick start script
./start.sh

# Or directly
uv run python main.py

Example session:

======================================================================
🤖 Claude Agent - Interactive Mode
======================================================================

📋 Available Commands:
  /exit  - Exit the agent
  /help  - Show this help message
  /clear - Clear the screen

💡 Tips:
  - Type your question or command and press Enter
  - Responses are streamed in real-time
  - Press Ctrl+C to interrupt current query

📡 Proxy: 127.0.0.1:7897
🔐 Using local Claude Code authentication
======================================================================

💬 You: List all Python files in the current directory

🤖 Claude Agent: [streaming response here...]

💬 You: Explain what agents.py does

🤖 Claude Agent: [streaming response here...]

💬 You: /exit

👋 Goodbye!

⚡ Single Query Mode

Execute a single query and exit:

# Basic query
./start.sh "Say hello"

# Or with uv
uv run python main.py "List all Python files"

# Complex query
uv run python main.py "Analyze the agents.py file and explain its main functions"

🎯 Special Commands

Command	Description
/exit	Exit the interactive agent
/help	Show help message
/clear	Clear the screen
Ctrl+C	Interrupt current query (doesn't exit)

Configuration

The agent is configured with:

• Authentication: Uses local Claude Code login (no API key needed)
• Proxy: http://127.0.0.1:7897 (both HTTP and HTTPS)
• Tools: Bash, Read, Write, Glob, Grep, Skill
• Permission Mode: bypassPermissions (auto-accept for testing)
• Setting Sources: ["project"] (loads .claude/ config)

Modify Proxy Settings

Edit ezagent/claude/agents.py and change the default proxy:

def create_agent_options(
    # ...
    proxy: Optional[str] = "http://YOUR_PROXY:PORT",  # Change this
    # ...
):

Modify Allowed Tools

Edit the allowed_tools list in main.py:

async for message in query(
    prompt=user_input,
    allowed_tools=["Bash", "Read", "Write", "Glob", "Grep", "Skill"],  # Customize
    setting_sources=["project"]
):

Available tools: Bash, Read, Write, Edit, Glob, Grep, Skill, Task, etc.

Troubleshooting

"Claude Code CLI not found"

Install Claude Code CLI (see Prerequisites above)

"Not logged in" or authentication errors

Login to Claude Code:

claude login

Proxy connection errors

1. Verify proxy is running: curl -x http://127.0.0.1:7897 https://api.anthropic.com
2. Check proxy logs for connection attempts
3. Try without proxy by removing the env parameter

Check Claude Code status

claude --version          # Check version
claude login --status     # Check authentication status

📁 Project Structure

simple-agent/
├── ezagent/                    # Agent package
│   └── claude/
│       ├── __init__.py        # Package exports
│       ├── agent.py           # (placeholder)
│       └── agents.py          # Core query & config functions
├── main.py                    # Interactive CLI entry point
├── start.sh                   # Quick start script
├── USAGE.md                   # Detailed usage guide
├── README.md                  # This file
├── pyproject.toml             # Project metadata
└── uv.lock                    # Dependency lock file

💡 Programming Interface

You can also use the agent programmatically:

import asyncio
from ezagent.claude.agents import query, simple_query, query_in_ezagent

# Streaming query
async def stream_example():
    async for message in query("Hello"):
        if hasattr(message, 'text'):
            print(message.text, end="", flush=True)

# Simple query (non-streaming)
async def simple_example():
    result = await simple_query("Say hello")
    print(result)

# Query in specific directory
async def dir_example():
    async for message in query_in_ezagent("List files"):
        print(message)

asyncio.run(stream_example())

See USAGE.md for more examples.

Next Steps

1. Explore the API - Check ezagent/claude/agents.py for all functions
2. Customize tools - Add or remove tools based on your needs
3. Create workflows - Chain multiple queries together
4. Add custom skills - Extend functionality with Claude Code skills
5. Build integrations - Use the programmatic API in your applications

Resources

• Claude Agent SDK Docs
• Python SDK Reference
• Example Agents

SDK Version

• claude-agent-sdk: 0.1.21
• Python: 3.11+