Development Setup¶

Prerequisites¶

This project uses mise to manage tool versions. With mise installed, all dependencies are set up automatically:

mise install

This installs the correct versions of Go and golangci-lint as defined in .mise.toml.

Alternatively, install manually:

Go 1.24+
tmux
golangci-lint v2 (brew install golangci-lint on macOS, or see install docs)

External Tools¶

Tool	Required	Purpose
tmux	Yes	Terminal multiplexing
shed	No	Remote container management
claude	No	Claude Code AI assistant
opencode	No	OpenCode AI assistant
codex	No	Codex AI assistant
lazygit	No	Git terminal UI

Build¶

make build

This compiles the binary to bin/codely.

To build and install to ~/.local/bin:

make install

Test¶

make test

Runs all Go tests with verbose output.

Lint¶

make lint

Requires golangci-lint v2. The project configuration is in .golangci.yml.

Project Structure¶

codely/
├── cmd/codely/            # Entry point
│   └── main.go
├── internal/
│   ├── cli/               # Cobra CLI setup, version
│   ├── config/            # YAML configuration loading
│   ├── constants/         # Default values
│   ├── debug/             # Debug logging
│   ├── domain/            # Core data structures (Project, Session, Command, Status)
│   ├── pathutil/          # Path expansion utilities
│   ├── shed/              # Remote container client
│   ├── status/            # Tool-aware status detection
│   ├── store/             # Session/project persistence
│   ├── tmux/              # tmux client
│   └── tui/               # Bubble Tea TUI
│       ├── skin.go        # Skin interface and factory
│       ├── skin_tree.go   # Tree skin (hierarchical view)
│       ├── skin_flat.go   # Flat skin (card list view)
│       └── components/    # Tree, pickers, dialogs
├── docs/                  # Documentation (this site)
├── testdata/              # Test fixtures
├── .golangci.yml          # Linter configuration
├── .goreleaser.yaml       # Release configuration
├── Makefile               # Build targets
├── mkdocs.yml             # Documentation site config
└── go.mod

Documentation Site¶

The documentation site uses MkDocs with the Material theme. It requires Python and uv.

# Install dependencies
uv sync --group docs

# Serve locally
uv run mkdocs serve

# Build static site
uv run mkdocs build

The local dev server runs at http://127.0.0.1:7070.