# 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 CLI client for the trygo webapp built with a hybrid development environment using both uv and Nix. The project has dual entry points: `hello` (hello_world package) and `taco` (trygo_py_cliclient.cli package).

## Development Commands

### Core Commands (via justfile)
- `just test` - Run full test suite (ruff check + mypy + pytest)
- `just fmt` - Format code using nix fmt (includes ruff, nixfmt, etc.)
- `just update-snapshots` - Update test snapshots using syrupy
- `just build` - Build the Python module (currently placeholder)
- `just check` - Run nix flake check for Nix environment validation

### Direct Tool Commands
- `uv run pytest` - Run tests with coverage
- `uv run ruff check src tests` - Lint code
- `uv run mypy src` - Type checking
- `uv run pytest --snapshot-update` - Update test snapshots

## Architecture

### Package Structure
- `src/hello_world/` - Hello world demonstration package
- `src/trygo_py_cliclient/` - Main CLI client package
  - `cli/` - Command-line interface and argument parsing
  - `config/` - Configuration management with TOML support

### Configuration System
- Uses dataclasses for type-safe configuration (`src/trygo_py_cliclient/config/config.py`)
- TOML-based configuration files (`config.toml`)
- Supports logging configuration and general application settings

### Development Environment
The project supports both uv and Nix environments:
- **uv mode**: Standard Python toolchain with uv for dependency management
- **Nix mode**: Reproducible environment with integrated formatting tools
- Environment detection via `DO_NIX_CUSTOM` environment variable

### Testing
- pytest with syrupy for snapshot testing
- Coverage reporting enabled (50% minimum)
- Test configuration in pyproject.toml with XML and HTML output

### Code Quality
- ruff for linting and formatting (tab indentation style)
- mypy for type checking
- flake8 for additional linting
- treefmt.nix for comprehensive formatting in Nix environment

## Entry Points
- `hello` command maps to `hello_world:main`
- `taco` command maps to `trygo_py_cliclient.cli:main`

## Configuration Files
- `pyproject.toml` - Python project configuration and dependencies
- `config.toml` - Application runtime configuration
- `flake.nix` - Nix development environment
- `treefmt.nix` - Code formatting configuration
- `justfile` - Development task automation