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:

go run . <command>

Build binary:

go build -o hako

Core Workflows

Image Management: Base image (hako-userland) + language variants (hako-userland-{lang})
Container Lifecycle: Create → Start → Copy workspace → Enter shell
File Syncing: Uses git ls-files to copy only tracked/untracked (non-ignored) files
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

1.9 KiB Raw Permalink Blame History