hosts/CLAUDE.md

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.