limen/CLAUDE.md

CLAUDE.md

Project memory for AI assistants working in this repo. Read this first.

What is limen

limen is a terminal launcher TUI: pick a host, pick a tmux session, exec into it. Written in Go using bubbletea. See docs/DESIGN.md for the canonical specification — that document is the source of truth for behavior, architecture, and scope.

Current status

Early implementation. The repository contains:

• docs/DESIGN.md — full design and requirements document.
• internal/ packages for config, state, probing, SSH, tmux parsing, exec planning, formatting, and UI.
• main.go, go.mod, and flake.nix for the working binary and Nix package.
• .github/ — CI and release workflows, issue templates, PR template.

The next implementation milestones are to:

1. Harden the terminal UI with real-world tmux and SSH smoke testing.
2. Keep release automation green for tagged releases and downstream package managers.
3. Continue from docs/DESIGN.md; if behavior changes, update the design doc in the same PR.

Key conventions

Topic	Convention
Language	Go 1.24+, no CGO
TUI framework	bubbletea + lipgloss
Default branch	develop (PRs target this); main reserved for tagged releases
Commit style	Conventional Commits (feat:, fix:, docs: …) — see CONTRIBUTING.md
License	GPL-3.0
Build	Nix flake (packages.default) + plain go build for dev
Release	GitHub Actions tag workflow, direct Go cross-builds, GitHub Releases, Homebrew tap
Test framework	Standard testing package; teatest for TUI integration
Go modules	One internal/ per concern (config, state, probe, ssh, ui, exec, format)

Boundaries to respect

• Don't drift from the design doc. If a proposed change conflicts with docs/DESIGN.md, update the doc in the same PR (or in a preceding PR) — never let code and design diverge silently.
• internal/ packages don't import bubbletea. Only internal/ui/* does. Keep the logic layer TUI-agnostic.
• No shelling out for things Go does natively. Exceptions: invoking ssh and tmux for the actual session work (that's the whole point).
• syscall.Exec, not os/exec, for the final hand-off. The user expects limen to disappear, not fork a child.
• No mouse handling, no themes (yet), no auto-discovery of SSH hosts. These are explicit non-goals — see §4 of DESIGN.md.

Distribution

Targets in order of priority:

1. Nix flake (nix run github:KofTwentyTwo/limen) — primary distribution channel.
2. Homebrew tap at KofTwentyTwo/homebrew-tap — brew install KofTwentyTwo/tap/limen.
3. GitHub Releases with direct Go-built binaries for macOS/Linux × amd64/arm64.

Eventual goal: submit to homebrew-core once the tool stabilizes.

When to ask the user

• License changes (currently GPL-3.0 — anything else is a deliberate decision, not a default).
• Scope additions beyond what DESIGN.md specifies (e.g., adding mouse support, plugins, themes).
• Renaming binaries, packages, or the project itself.
• Anything that changes the public-facing CLI surface in a breaking way.

Helpful pointers

• Latin name etymology: limen = threshold / doorsill. Symbolic of the boundary the user crosses on entering work each day.
• Sister tools in the KofTwentyTwo org with similar Latin naming: Munitor (fortifier), Concilium (council), Aestimare (to estimate), Claritas (clarity), ArmariumMinutum (small cabinet).
• The user's nix-darwin config repo at github.com/KofTwentyTwo/nix is where limen integrates downstream (via a home/limen/default.nix module that pins this repo as a flake input). Changes here that affect that integration should be reflected on that side.