48 lines
1.9 KiB
Markdown
48 lines
1.9 KiB
Markdown
# 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
|