a5eb09f40f
- Add main GUI application (local_agent_ui.py) with customtkinter interface - Add Windows right-click context menu installer (install_right_click.py) - Add project documentation (CLAUDE.md) with setup and usage instructions - Add .gitignore for Python project files 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
77 lines
2.8 KiB
Markdown
77 lines
2.8 KiB
Markdown
# 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 |