Add CLAUDE.md for project guidance and development instructions

CLAUDE.md

@@ -0,0 +1,87 @@
+# 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 TUI (Terminal User Interface) application for managing `/etc/hosts` files. The application provides a two-pane interface built with Textual, allowing users to view, edit, activate/deactivate, and reorder hostname entries in their system's hosts file with proper sudo permission handling.
+
+## Development Commands
+
+### Package Management (uv)
+- `uv sync` - Update project environment and install dependencies
+- `uv add <package>` - Add new dependency to project
+- `uv run <command>` - Run commands in the project environment
+
+### Running the Application
+- `uv run hosts` - Launch the TUI application (main entry point)
+- `uv run python -m hosts.main` - Alternative way to run the application
+
+### Testing
+- `uv run pytest` - Run all tests
+- `uv run pytest tests/test_<module>.py` - Run specific test module
+- `uv run pytest -k <test_name>` - Run tests matching pattern
+
+### Code Quality
+- `uv run ruff check` - Run linter checks
+- `uv run ruff check --fix` - Auto-fix linting issues
+- `uv run ruff format` - Format code
+
+## Architecture
+
+### Core Structure
+The application follows a modular architecture with clear separation of concerns:
+
+```
+src/hosts/
+├── core/           # Core business logic
+│   ├── config.py   # Configuration management
+│   ├── manager.py  # HostsManager with sudo permission handling
+│   ├── models.py   # Data models (HostEntry, HostsFile)
+│   └── parser.py   # Hosts file parsing/serialization
+├── tui/            # Textual UI components
+│   ├── app.py      # Main application class (HostsManagerApp)
+│   └── ...         # Various handlers and modals
+└── main.py         # Entry point
+```
+
+### Key Components
+
+**HostsManager** (`src/hosts/core/manager.py:106`): Central component that handles all edit operations with proper sudo permission management. Key features:
+- Permission management through PermissionManager class
+- Edit mode with backup creation and restoration
+- Safe file operations with validation
+- Entry manipulation (toggle, move, update)
+
+**HostsParser** (`src/hosts/core/parser.py`): Handles reading/writing hosts files and maintains original formatting.
+
+**HostsManagerApp** (`src/hosts/tui/app.py:26`): Main Textual application providing the two-pane interface with reactive state management.
+
+### Permission Model
+The application operates in two modes:
+- **Read-only mode** (default): Safe browsing of hosts file entries
+- **Edit mode**: Requires sudo permissions for modifications, includes automatic backup creation
+
+### Memory Bank Integration
+This project uses Cline's Memory Bank system (see `.clinerules`) for maintaining project context across sessions. Key files are in `memory-bank/` directory.
+
+## Development Guidelines
+
+### Testing Approach
+- Tests are located in `tests/` directory
+- Uses pytest framework
+- Test individual modules with `uv run pytest tests/test_<module>.py`
+
+### Code Style
+- Uses ruff for both linting and formatting
+- Configuration is embedded in `pyproject.toml`
+- Run `uv run ruff check --fix && uv run ruff format` before committing
+
+### Dependencies
+- **Textual**: TUI framework for the interface
+- **pytest**: Testing framework
+- **ruff**: Linting and code formatting
+- Managed via uv with dependencies declared in `pyproject.toml`
+
+### File Permissions
+When working on permission-related code, be aware that the application needs to handle sudo operations safely. The PermissionManager class in `src/hosts/core/manager.py:17` manages this complexity.