Metadata-Version: 2.4
Name: claude-helpers
Version: 0.1.2
Summary: Cross-platform voice and HIL tools for Claude Code
Project-URL: Homepage, https://github.com/claude-helpers/claude-helpers
Project-URL: Repository, https://github.com/claude-helpers/claude-helpers.git
Project-URL: Issues, https://github.com/claude-helpers/claude-helpers/issues
Project-URL: Documentation, https://github.com/claude-helpers/claude-helpers/blob/main/README.md
Author-email: Vladimir Loskutov <claude-helpers@modus.dev>
License: MIT
License-File: LICENSE
Keywords: ai,claude,human-in-the-loop,transcription,voice
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: claude-code-sdk>=0.0.20
Requires-Dist: click>=8.1.0
Requires-Dist: dspy>=2.5.0
Requires-Dist: fastmcp>=0.2.0
Requires-Dist: keyboard>=0.13.5
Requires-Dist: litellm[proxy]>=1.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: sounddevice>=0.4.6
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: linux
Requires-Dist: python-xlib>=0.33; extra == 'linux'
Provides-Extra: macos
Requires-Dist: pyobjc-framework-cocoa>=9.0; extra == 'macos'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

# Claude Helpers

Cross-platform Python utility for seamless Claude Code integration providing voice input and human-in-the-loop (HIL) capabilities for enhanced AI agent workflows.

## Features

### 🎤 Voice Input
- Record voice prompts and get instant OpenAI Whisper transcription
- Configurable audio devices and recording settings
- Auto-language detection for transcription

### 🤝 Human-in-the-Loop (HIL)
- MCP (Model Context Protocol) integration for Claude Code
- Multi-agent support with unique agent identification
- File-based message exchange for reliable communication
- Background listener with text/voice response options

### 🖥️ Cross-Platform
- Native support for Linux and macOS
- Platform-specific optimizations
- Terminal and GUI dialog support

## Installation

### Using UV (recommended)
```bash
uv tool install claude-helpers
```

### Using pip
```bash
pip install claude-helpers
```

## Quick Start

### 1. Initial Setup
```bash
# Configure global settings (API keys, audio devices)
claude-helpers setup

# Initialize project for Claude Code integration
claude-helpers init
```

### 2. Voice Transcription
```bash
# Record voice and output transcription
claude-helpers voice
```

### 3. Human-in-the-Loop

Start the HIL listener in your project:
```bash
claude-helpers listen
```

In Claude Code, the agent can ask questions using the MCP tool:
- `ask-question` - Ask human for input (they can respond via text or voice)

## Configuration

Global configuration is stored in:
- Linux: `~/.config/claude-helpers/`
- macOS: `~/Library/Application Support/claude-helpers/`

Project-specific HIL configuration in `.helpers/` directory.

## Requirements

- Python 3.10+
- OpenAI API key (for Whisper transcription)
- Audio input device (for voice features)

## MCP Integration

Claude Helpers provides MCP server for seamless Claude Code integration:

```json
{
  "type": "stdio",
  "command": "claude-helpers",
  "args": ["mcp-server"]
}
```

The MCP server exposes the `ask-question` tool that allows Claude to request human input with automatic voice/text switching in the UI.

## Development Status

This project is actively maintained and welcomes contributions. Current version focuses on core HIL and voice functionality.

## License

MIT License - see LICENSE file for details.

## Support

- GitHub Issues: [Report bugs or request features](https://github.com/claude-helpers/claude-helpers/issues)
- Documentation: [Full documentation](https://github.com/claude-helpers/claude-helpers)

## Author

Vladimir Loskutov (claude-helpers@modus.dev)