# 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.