Development

English · Русский

Hacking on familiar

The Homebrew build is for everyday use. To work on familiar, clone the repo and point your config at the checkout, then restore the released build when you're done — all on your working ~/.config/kitty:

brew install denoby/familiar/familiar
familiar enable --all          # everyday use — the released build

git clone https://github.com/DenoBY/familiar && cd familiar
./bin/familiar enable --all    # switch your live config to this checkout
# edit plugins/**, reload kitty (Cmd+Ctrl+,) to see your changes

familiar enable --all          # switch back to the Homebrew build

Both the Homebrew familiar and the repo ./bin/familiar write the same ~/.config/kitty/familiar.conf, so switching is just re-running the other one — no duplication, nothing to clean up. familiar bakes absolute paths from wherever it runs: the brew build points at /opt/homebrew/opt/familiar/libexec, the checkout at your clone. familiar status prints wired root: — the installation kitty actually runs — next to the app root: of the copy you invoked, and warns when the two differ; familiar disable removes it entirely.

Tests

Standard-library unittest, no external dependencies, run outside kitty:

python3 -m unittest discover -s tests -t tests

What's covered is in tests/README.md in the repo. Style is checked with ruff check . (configured in pyproject.toml).

The demo stand

Every screenshot in this wiki is taken on a reproducible demo stand — a generated git repo with photogenic history and uncommitted changes (for review and log) plus a fake Claude Code storage with live sessions and a rich transcript (for session). Regenerate it any time the UI changes and retake the shots:

python3 tools/demo_stand.py --dir /tmp/familiar-demo    # --wipe to recreate

Then launch a dedicated kitty instance pointed at the fake storage:

CLAUDE_CONFIG_DIR=/tmp/familiar-demo/claude \
  /Applications/kitty.app/Contents/MacOS/kitty --detach --directory /tmp/familiar-demo/repo

(The environment variable must reach the kitty process — the kittens inherit it from there. Launching from a shell is the simplest way; an env line in kitty.conf works too but needs a full restart and edits your real config.)

Inside that window:

• Cmd+Shift+S — session: three projects; the repo project has a busy and a waiting live session, a ◆ background agent, a custom-titled session, and a rich transcript ("Fix sunset rounding bug") for the preview.
• Cmd+Shift+R — review: the tree shows every status (staged utils.py, modified core.py / test_core.py, renamed app.py, untracked notify.py); the core.py diff has word-diff lines (int(raw_minutes) → round(raw_minutes)) and symbols for go-to-definition (normalize_degrees, minutes_to_time live in utils.py).
• Cmd+Shift+L — log: ~18 commits, a --no-ff merge of feature/moon-phase, and an unmerged feature/timezones (press a for all branches, i for the details panel).