bake/halp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a5eb09f40f
halp/CLAUDE.md
bake a5eb09f40f Initial commit: Python-based local AI assistant 
- 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>
2025-06-23 10:50:34 -05:00

2.8 KiB
Raw Blame History

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

pip install customtkinter torch transformers pynput protobuf sentencepiece

Development Commands

Running the Application

python3 local_agent_ui.py [optional_working_directory]

Installing Right-Click Context Menu (Windows)

python3 install_right_click.py

Uninstalling Right-Click Context Menu (Windows)

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