What is Ask Claude

Ask-Claude is a lightweight Python wrapper for the Claude Code CLI, designed to enhance its functionality with features such as MCP/tool auto-approval, session management, and error handling.

Use cases

Use cases include automating repetitive tasks, managing complex conversations with context, and integrating Claude Code CLI functionalities into larger systems or applications.

How to use

To use Ask-Claude, first install the Claude Code CLI and authenticate with your Anthropic API key. Then, you can install Ask-Claude via pip and utilize its simple API for one-line queries.

Key features

Key features include a simple API for one-line queries, automatic retries with exponential backoff, session management for multi-turn conversations, MCP auto-approval to bypass manual prompts, real-time response streaming, and comprehensive error handling.

Where to use

Ask-Claude can be used in various fields such as software development, data analysis, and any application requiring interaction with the Claude Code CLI for enhanced productivity.

Ask Claude - Claude Code SDK Wrapper

A lightweight Python wrapper for the Claude Code CLI that adds enterprise features like error handling, session management, and MCP auto-approval.

Features

• 🚀 Simple API - One-line queries with ask_claude()
• 🔄 Automatic Retries - Built-in resilience with exponential backoff
• 💬 Session Management - Multi-turn conversations with context
• 🤖 MCP Auto-Approval - Bypass manual tool approval prompts
• 🌊 Streaming Support - Real-time response streaming
• 🛡️ Enterprise Ready - Comprehensive error handling and logging

Prerequisites

Before using this wrapper, you must have Claude Code CLI installed and authenticated:

1. Install Claude Code CLI (requires Node.js)

   npm install -g @anthropic-ai/claude-code
   

2. Authenticate with your Anthropic API key

   claude login
   

3. Verify installation

   claude --version
   

Installation

Option 1: From PyPI (Coming Soon - Phase 4)

pip install ask-claude

Option 2: Development Installation

# Clone and install with Poetry
git clone https://github.com/Spenquatch/ask-claude.git
cd ask-claude
poetry install

# Verify it works
poetry run python getting_started.py

Option 3: Traditional pip install

git clone https://github.com/Spenquatch/ask-claude.git
cd ask-claude
pip install -e .

Quick Start

from ask_claude import ask_claude

# Simple query
response = ask_claude("What is Python?")
print(response.content)

# With streaming
from ask_claude import ask_claude_streaming
for chunk in ask_claude_streaming("Write a haiku"):
    print(chunk.get('content', ''), end='')

Common Use Cases

CLI Usage

# After Poetry install
ask-claude ask "What is Python?"
ask-claude stream "Write a tutorial"
ask-claude session --interactive

# During development
poetry run python -m ask_claude.cli ask "What is Python?"
poetry run python -m ask_claude.cli stream "Write a tutorial"

Session Management

from ask_claude import ClaudeCodeWrapper

wrapper = ClaudeCodeWrapper()
with wrapper.session() as session:
    session.ask("I need help with Python")
    session.ask("How do I read CSV files?")
    response = session.ask("Show me an example")

MCP Auto-Approval

from ask_claude import ClaudeCodeConfig, ClaudeCodeWrapper

# Auto-approve specific tools
config = ClaudeCodeConfig(
    mcp_auto_approval={
        "enabled": True,
        "strategy": "allowlist",
        "allowlist": ["mcp__sequential-thinking__*"]
    }
)

wrapper = ClaudeCodeWrapper(config)
response = wrapper.run("Think through this step by step: How do I optimize this code?")

Error Handling

from ask_claude import ClaudeCodeError, ClaudeCodeTimeoutError

try:
    response = wrapper.run("Complex query", timeout=30.0)
    print(response.content)
except ClaudeCodeTimeoutError:
    print("Request timed out")
except ClaudeCodeError as e:
    print(f"Error: {e}")

Documentation

Project Structure

ask_claude/
├── __init__.py             # Public API exports
├── wrapper.py              # Core ClaudeCodeWrapper class
├── cli.py                  # Command-line interface
├── session.py              # Session management
├── approval/               # MCP approval system
│   ├── server.py          # Approval server
│   └── strategies.py      # Approval strategies
├── docs/                   # Documentation
├── examples/               # Example scripts
└── tests/                  # Test suite

Requirements

• Python 3.10+ (required for MCP support)
• Node.js (for Claude Code CLI installation)
• Claude Code CLI installed and authenticated

Contributing

We welcome contributions! Please see our Development Guide for detailed setup instructions.

Quick Start for Contributors:

1. Fork the repository
2. Set up development environment: pyenv local 3.10.17 && pip install pre-commit && pre-commit install
3. Create your feature branch (git checkout -b feature/amazing-feature)
4. Make changes and ensure all quality checks pass: pre-commit run --all-files
5. Commit your changes (hooks run automatically)
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Quality Standards:

• ✅ 100% type safety with mypy
• ✅ Code formatting and linting with Ruff
• ✅ All tests must pass

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

Built with ❤️ for the Claude community