# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Python-based local AI assistant called "halp" that provides a GUI interface for running shell commands via an AI agent. The application uses a local language model (Yi-Coder-1.5B-Chat) to interpret user requests and execute shell commands accordingly.

## Key Components

- **local_agent_ui.py**: Main application with GUI interface using customtkinter, AI model integration, and shell command execution capabilities
- **install_right_click.py**: Windows registry installer that adds a right-click context menu option to launch the assistant from any folder

## Dependencies

The project requires these Python packages:
- customtkinter (GUI framework)
- torch (PyTorch for model inference)
- transformers (Hugging Face transformers library)
- pynput (keyboard hotkey detection)
- protobuf (protocol buffers for tokenizer)
- sentencepiece (tokenizer backend)

### Installation
```bash
pip install customtkinter torch transformers pynput protobuf sentencepiece
```

## Development Commands

### Running the Application
```bash
python3 local_agent_ui.py [optional_working_directory]
```

### Installing Right-Click Context Menu (Windows)
```bash
python3 install_right_click.py
```

### Uninstalling Right-Click Context Menu (Windows)
```bash
python3 install_right_click.py uninstall
```

## Architecture

The application follows a multi-threaded architecture:
1. **Main UI Thread**: Handles the customtkinter GUI, message display, and user input
2. **AI Processing Thread**: Runs the language model inference and command execution logic
3. **Keyboard Listener**: Global hotkey detection (backtick key by default) for showing/hiding the window

### Key Features
- **Global Hotkey**: Press backtick (`) to toggle window visibility
- **Context-Aware**: Launches with the current working directory as context
- **Command Execution**: AI agent can execute shell commands and observe results
- **Conversational Loop**: Multi-step reasoning with up to 5 iterations per task

### AI Agent Workflow
1. User provides a task
2. AI generates reasoning and potential shell commands
3. Commands are executed with stdout/stderr captured
4. Results are fed back to the AI for next steps
5. Process continues until "DONE" or iteration limit reached

## Configuration

Key configuration constants in local_agent_ui.py:
- `MODEL_ID`: "01-ai/Yi-Coder-1.5B-Chat" (can be changed to other compatible models)
- `HOTKEY`: Backtick key for window toggle
- Iteration limit: 5 steps per task to prevent loops

## Platform Notes

- Designed primarily for Windows (uses Windows registry for context menu)
- Shell commands executed with `shell=True` for Windows compatibility
- Working directory context passed via command line arguments