# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Hako is a Docker container management tool designed specifically for Claude Code. It provides sandboxed environments to prevent Claude from accidentally affecting files outside the current working directory.

## Architecture

- **main.go**: CLI entry point using Cobra framework with commands: init, up, down, ps, sync
- **commands.go**: Command implementations that orchestrate Docker operations and file syncing
- **docker.go**: Core Docker operations (image building, container lifecycle, file copying)
- **git.go**: Git integration for project detection and container naming
- **utils.go**: Utility functions for command execution with logging to stderr

## Key Design Patterns

- Container names follow pattern: `hako-{language}-{project}-{subdirs}` (sanitized, max 60 chars)
- All Docker commands are logged to stderr for transparency
- File syncing respects .gitignore and excludes .git directory for security
- Images are versioned (HAKO-VERSION=1, as a Docker label) for upgrade management
  - NOTE: changes to the base Dockerfiles should involve bumping the hako version

## Development Commands

Build and run:
```bash
go run . <command>
```

Build binary:
```bash
go build -o hako
```

## Core Workflows

1. **Image Management**: Base image (hako-userland) + language variants (hako-userland-{lang})
2. **Container Lifecycle**: Create → Start → Copy workspace → Enter shell
3. **File Syncing**: Uses git ls-files to copy only tracked/untracked (non-ignored) files
4. **Project Isolation**: Must run within git repositories, containers scoped to project+path

## Configuration

- Base Dockerfile stored in `~/.config/hako/Dockerfile.base`
- Language Dockerfiles in `~/.config/hako/Dockerfile.{lang}`
- Mounts Claude config directory/file if present for seamless integration