Go-based server application providing containerized development environments with Git worktree management, WebSocket PTY sessions, and AI agent integration.

The container application consists of several key components:

• Unified CLI (catnip): Single binary providing both TUI for container management and HTTP/WebSocket API server
• Container Runtime: Docker-based isolated development environments

container/
├── cmd/
│   └── cli/main.go         # catnip unified binary entry point
├── internal/
│   ├── models/             # Data models and structures
│   ├── services/           # Business logic layer
│   ├── handlers/           # HTTP/WebSocket request handlers
│   ├── git/                # Git operations and worktree management
│   └── tui/                # Terminal UI components
├── docs/                   # Swagger documentation
└── setup/                  # Container environment setup scripts

Data structures and domain models:

• git.go: Repository, Worktree, GitStatus models
• claude.go: Claude AI session and message structures
• gemini.go: Google Gemini integration models
• settings.go: Application configuration

Business logic and core functionality:

• git.go: Git repository and worktree management service
• worktree_manager.go: Worktree lifecycle operations
• claude.go: Claude AI integration service
• session.go: PTY session management
• port_allocation.go: Dynamic port allocation
• commit_sync.go: Automated commit synchronization

HTTP/WebSocket request handlers:

• git.go: Git operations API endpoints
• pty.go: WebSocket PTY session handling
• claude.go: Claude AI chat integration
• ports.go: Port management and proxy
• auth.go: Authentication handling

Git operations and abstractions:

• operations.go: Core git operation interfaces
• worktree_manager.go: Git worktree lifecycle management
• branch.go: Branch operations and validation
• executor/: Git command execution (shell, go-git, in-memory)
• utils.go: Git utilities and branch naming

• Custom Namespace: Uses refs/catnip/ to isolate workspace branches
• Dynamic State Detection: Automatically syncs metadata with actual git state
• Comprehensive Cleanup: Removes branches, worktrees, and dangling references
• Live Repository Support: Mounts local repositories with "live" remotes

• Claude Code Support: WebSocket-based Claude chat integration
• Session Management: Persistent conversation history
• File Context: Automatic file content inclusion in conversations

• Port Detection: Automatic discovery of development servers
• Proxy System: Built-in reverse proxy for containerized services
• Volume Management: Persistent workspace and configuration storage

• Swagger Documentation: Auto-generated API documentation at /docs
• WebSocket PTY: Real-time terminal access via WebSocket
• Hot Reload: Live recompilation during development

/v1/git/repositories     # Repository management
/v1/git/worktrees        # Worktree operations
/v1/claude/sessions      # AI chat sessions
/v1/ports               # Port management
/v1/auth                # Authentication

/ws/pty                 # Terminal sessions
/ws/events              # Real-time event streaming
/ws/claude              # AI chat interface

• Go 1.21+
• Docker
• just command runner

# Build both CLI and server
just build

# Run tests
just test

# Run linter
just lint

# Generate Swagger docs
just docs

# Development server (auto-rebuild)
just dev

# Build development image
docker build -f Dockerfile.dev -t catnip-dev .

# Run development container
docker run -e CATNIP_DEV=true -p 8080:8080 -v $(pwd):/live catnip-dev

• CATNIP_DEV: Enable development mode
• CATNIP_PORT: Server port (default: 8080)
• WORKSPACE_DIR: Workspace directory path
• GIT_STATE_DIR: Git state persistence directory

• Uses refs/catnip/ namespace for workspace branches
• Automatically configures git credentials via GitHub CLI
• Supports both local and remote repository workflows

The codebase includes comprehensive test coverage:

• Unit Tests: Individual component testing
• Integration Tests: Service interaction testing
• Functional Tests: End-to-end workflow testing
• In-Memory Tests: Fast isolated testing with mock git

# All tests
go test -v ./...

# Specific package
go test -v ./internal/services

# With integration tests
RUN_INTEGRATION_TESTS=1 go test -v ./...

1. Create service in internal/services/
2. Add models in internal/models/
3. Create handlers in internal/handlers/
4. Update Swagger documentation

Implement the CommandExecutor interface in internal/git/executor/:

• ShellExecutor: Shell command execution
• GitExecutor: go-git library integration
• InMemoryExecutor: Testing and mocking

Add new WebSocket handlers following the pattern in internal/handlers/pty.go

• Git operations are sandboxed within container
• Authentication required for sensitive operations
• File system access limited to workspace directories
• Network access controlled via container networking

• Swagger UI: Available at /docs for API exploration
• Health Check: GET /health endpoint
• Metrics: Built-in request/response logging
• Debug Mode: Enable with CATNIP_DEV=1