Installation

English · Русский

The familiar helper wires everything into kitty for you: it writes an include into your kitty.conf and generates the kitten maps with absolute paths (kitty resolves a relative kitten path from ~/.config/kitty, not from the file that maps it — so the path can't just be relative). No manual editing, no sed, and it survives updates.

Homebrew (recommended)

brew tap denoby/familiar https://github.com/DenoBY/familiar
brew install denoby/familiar/familiar   # full name = trust just this formula
familiar enable --all                    # kittens + the terminal config

The full name denoby/familiar/familiar is required by Homebrew 6.0+ Tap Trust: third-party taps aren't loaded until trusted, and a fully-qualified install trusts only this formula. Alternatively trust the whole tap once with brew trust denoby/familiar, then brew install familiar works bare.

Bleeding edge from master: brew install --HEAD denoby/familiar/familiar.

From a clone (no Homebrew)

git clone https://github.com/DenoBY/familiar && cd familiar
./bin/familiar enable --all

Same command either way. Then reload the config — Cmd+Ctrl+, — or restart kitty. (Ctrl+Shift+F5 is kitty's Linux reload default; on macOS it's Cmd+Ctrl+,.)

Install modes

Pick how much to wire in:

Command	What it enables
familiar enable --all	all kittens + the terminal config (look, splits, tabs, Russian layout) + restore (window snapshots)
familiar enable --kittens	all kittens only, leaves your terminal config untouched
familiar enable session review log	only the named overlays (add --terminal for the terminal config too)
familiar enable --terminal	only the terminal config, no kittens
familiar enable --all --theme darcula	same as --all, but with the Darcula palette (JetBrains) instead of the default one — see Themes
familiar enable … --restore-session	add restore to any selection (--no-restore-session drops it from --all)
familiar enable … --icon	use the familiar app icon for kitty (--no-icon keeps kitty's own; on by default with the terminal config)
familiar disable	remove the familiar block (--restore reverts kitty.conf from the backup taken on first enable)
familiar status	show what's currently enabled

Every mode that pulls in the terminal config — --all, --terminal, or --terminal next to kitten names — asks for confirmation first, since it overrides your kitty settings; -y / --yes skips the prompt for scripts.

Cyrillic key duplicates (S→ы, R→к, L→д) for the Russian layout are generated automatically.

Language servers

Go to definition in review and log is answered by a language server, so it needs one per language. familiar enable review offers to install what is missing; you can also do it directly:

familiar lsp status              # what is configured, what is found
familiar lsp install php python  # brew or npm, per the registry
familiar lsp warm php            # index a project up front, with progress
familiar lsp clean               # drop cached indexes, keep the servers

Servers installed through npm live under ~/.cache/familiar/lsp/servers; indexes live beside them in ~/.cache/familiar/lsp/index and survive restarts, which is what makes the second and every later start fast. Nothing runs in the background between sessions.

The registry

Which server serves which language is declared in config/lsp.conf — 27 languages ship out of the box, from PHP, Python, TypeScript/JS, Go, Rust and Java to Elixir, Haskell, Scala, Clojure, Terraform, Markdown and the web stack (Vue, Svelte, Dockerfile, YAML, JSON/HTML/CSS). Three levels are merged, field by field, the nearest one winning:

1. the built-in config/lsp.conf
2. ~/.config/familiar/lsp.conf — yours
3. <repo>/.familiar/lsp.conf — this project's

So you can point one project at a different server, pin a monorepo to a single root (roots-mode git), or switch PHP from intelephense to the MIT-licensed phpactor by moving one disabled yes line. A block can also list shebang names, which is how files with no extension (bin/familiar, git hooks) find their server. To add a language that is not listed, familiar lsp status <language> prints a block to copy and fill in.

Updating

When a new release is tagged, a kitten lets you know: once a day it checks GitHub in the background and shows a one-time footer hint — familiar X.Y.Z is out — brew upgrade familiar. familiar status prints the installed version, and its latest: line reads either up to date or the number of the new release with a brew upgrade familiar hint. Then:

brew update && brew upgrade denoby/familiar/familiar   # Homebrew
git pull                                               # clone

The wired paths are stable across upgrades — but the set of map lines in ~/.config/kitty/familiar.conf belongs to the version that generated it: only familiar enable ever writes that file, brew upgrade and git pull leave it alone. So after an update that adds keys (the generator changed in 0.23.0 and 0.24.0) re-run familiar enable … with the same arguments — familiar status shows the mode currently wired. Otherwise Cmd+F inside review/log is caught by kitty's search_scrollback instead of the kitten, and an overlay opened from a split takes the size of that split rather than the whole tab.

Set FAMILIAR_UPDATE_CHECK=0 in the environment to disable both the daily check and the hint; the latest: line then disappears from familiar status too.

Uninstall / rollback

familiar only ever adds a fenced block to your kitty.conf, writes a familiar.conf beside it and — with the terminal config — a kitty.app.icns (the app icon kitty reads from the config directory); nothing else is touched, so removal is clean:

familiar disable            # drop the familiar block + familiar.conf + the icon
familiar disable --restore  # ...and restore kitty.conf from the backup

disable removes the icon only while it is still the one familiar installed, so kitty goes back to its own; an icon of your own from before is kept in kitty.app.icns.familiar.bak and put back, and one you dropped in yourself afterwards is left alone. The Dock caches app icons — if the old one lingers after kitty restarts, run killall Dock.

On the first enable, familiar copies your kitty.conf once to kitty.conf.familiar.bak (the pre-familiar state). --restore puts it back byte-for-byte; the .bak stays afterwards, so you can restore later too. familiar status shows where it lives.

Prefer to do it by hand? Delete the block between the # >>> familiar >>> / # <<< familiar <<< markers in kitty.conf, remove familiar.conf, or just copy kitty.conf.familiar.bak back over kitty.conf.

Open with Cmd+Shift+S / Cmd+Shift+R / Cmd+Shift+L.