Skip to content

reference.md

Latest commit

 

History

History
152 lines (112 loc) · 11.2 KB

reference.md

File metadata and controls

152 lines (112 loc) · 11.2 KB
Raw

リファレンス

このリポジトリで管理しているコンポーネント

コンポーネント パス 概要
Fish 設定 configs/fish/ シェル設定・カスタム関数・エイリアス
Ghostty 設定 configs/ghostty/ ターミナルエミュレータ設定
Neovim 設定 configs/nvim/ エディタ設定（lazy.nvim）
herdr 設定 configs/herdr/ ターミナルマルチプレクサ設定（キーバインド・サイドバー・agent integration）
Claude Code 設定 configs/claude/ CLAUDE.md・スクリプト・statusline
Claude Code スクリプト configs/claude/scripts/ 通知・リダイレクト・worktree ガードなどの補助スクリプト
Claude Code skills configs/claude/skills/ codex-sync（skill を Codex CLI にも展開）
Claude Code permissions ベースライン configs/claude/permissions-baseline.json どの端末でも必要な deny と推奨 allow の定義。配布物ではなく検査基準で、setup.sh が欠落を指摘する（--fix で追加のみ実行、ADR-092）
GitHub 認証 configs/ghtkn/ ghtkn agent と用途別 GitHub App（ADR-094）
aqua 設定 aqua.yaml CLIツールバージョン管理
Nix (home-manager) flake.nix / nix/ 静的 symlink 配置と OS レベルパッケージの宣言（Spike 中、ADR-084）

管理対象外（別リポジトリ）

コンポーネント 管理場所
herdr herdrdev/herdr — エージェント認識ターミナルマルチプレクサ（Rust 製）。公式 install script（~/.local/bin/herdr）で導入し、configs/herdr/setup.sh が herdr update で自動更新する
agmsg-go（dispatch / review-loop skills + IPC コア） ishii1648/agmsg-go — 共有 SQLite を通信路とするエージェント間 IPC binary（agmsg）と、その上で動く dispatch / review-loop skills を同梱。dotfiles からの自動配布（bootstrap）は herdr 移行に伴い廃止した（ADR-076）。手動で使う場合は go install github.com/ishii1648/agmsg-go/cmd/agmsg@latest → agmsg skills install

ツールスタック

カテゴリ ツール 設定ファイル
terminal Ghostty configs/ghostty/config
multiplexer herdr configs/herdr/config.toml
editor Neovim (lazy.nvim) configs/nvim/
shell Fish configs/fish/
coding agent Claude Code configs/claude/
package manager (バージョン固定 CLI) aqua aqua.yaml
package manager (OS レベル) Homebrew → Nix (home-manager) へ移行中 nix/home.nix / scripts/lib/deps-macos.sh
VCS Git (SSH署名) configs/git/gitconfig
stacked PR git-spice（コマンド名は git-spice。gs は fish の abbr で展開する。v0.25.0 で公式配布物から gs バイナリが削除された） aqua.yaml / configs/fish/conf.d/aliases.fish

GitHub 認証（ghtkn）

macOS の full / remote profile は configs/ghtkn/setup.sh を実行する。事前に configs/ghtkn/ghtkn.yaml.example を ~/.config/ghtkn/ghtkn.yaml へコピーし、 read / write / loop の異なる GitHub App Client ID を設定する。XDG_CONFIG_HOME を使う場合は その配下へ配置する。未設定では認証の切り替え前にセットアップが失敗する。

App は Device Flow と User Access Token の有効期限を有効にし、Webhook を無効にする。 インストール先は必要なリポジトリだけに限定する。read は必要な読み取り権限、write / loop は Issues・Pull requests・Contents を中心とする必要な書き込み権限を付与し、CI確認などの 追加権限は利用するAPIに合わせて確定する。loop の現在のCI確認には Checks と Commit statuses の read 権限が必要になる。Metadata は read、Workflows の write は workflow ファイルの変更を 許可する場合だけ追加する。Client Secret・秘密鍵は作成しない。

aqua install 後に bash configs/ghtkn/setup.sh を実行すると、launchd agent、 ~/.local/bin/gh、GitHub専用の HTTPS credential helper が設定される。 ~/.local/bin と aqua の bin を PATH に含め、command -v gh がラッパーを指すことを確認する。 既存 clone の SSH remote URL と個別の pushurl は別途 HTTPS に変更する。コミット署名用のSSH鍵は継続して使う。

初回とagent再起動後は ghtkn agent unlock --enable-refresh を手動実行し、 必要なら ghtkn auth read、ghtkn auth write、ghtkn auth loop で認証する。 ghtkn info で状態を確認できる。トークンそのものを表示する ghtkn get は使わない。 通常の gh は read、変更時は GHTKN_APP=write gh ... を使う。Git は既定で write を使い、 GHTKN_APP / GHTKN_GIT_APP で切り替えられる。git_owner は環境変数より優先されるので設定しない。

loop の登録・再登録時は ~/.local/libexec/ghtkn-loop を PATH の先頭に置き、 登録される gh / git とサービスの PATH がそのディレクトリを指すことを確認する。 稼働中loopへの反映は作業状態を確認してから行う。ラッパーはloop用Appを明示してAPI操作ごとに トークンを取得し、Gitもloop用Appを選択する。GitHub Connectorなど gh を使わない経路は対象外。

ラッパー導入だけでは保存済みOAuthトークンやSSH認証鍵へのアクセスは除去されない。 専用Appでの動作を確認してから、旧認証の失効・削除と自動実行環境からのアクセス除去を行う。 導入完了の判定は ADR-094 の受け入れ条件による。

ライト / ダークの追随

macOS の外観設定に合わせて 3 層がそれぞれ配色を切り替える。1 層でも固定のままだと、その層だけ反対の配色が残る（サイドバーだけ暗い、mode 表示だけ読めない、等）。

層 設定 切り替えの仕組み
ターミナル configs/ghostty/config の theme = light:Catppuccin Latte,dark:Dracula Ghostty が OS の外観設定を直接見る
マルチプレクサ configs/herdr/config.toml の [theme] auto_switch = true herdr の UI（サイドバー・ペイン境界）は端末パレットではなく自前の配色で描くため、端末とは別に指定が必要
Claude Code configs/claude/settings.json の "theme": "auto" OSC 11 で端末に背景色を問い合わせて light / dark を判定（ADR-093）。判定は起動時のみで、外観を切り替えても走っているセッションは切り替え前の配色のまま残る

ライト背景で薄い前景色が沈む分は Ghostty の minimum-contrast = 3.0 が持ち上げる。透過（background-opacity）を掛けるとこの補正が見た目とずれるため 1.0 で使う。

並列スケール開発アーキテクチャ（廃止）

独立タスクの並列実行のため /dispatch・/orchestrate・/session-log skill と tmux-sidebar の popup picker を使う仕組みがあったが、herdr 移行（ADR-076）に伴い廃止した。orchestrate・session-log は dotfiles vendor を削除、dispatch・review-loop（agmsg-go 配布）は自動配布（bootstrap）を止めた。並列実行は herdr の agent 機能（agent start/agent send 等）への置き換えを検討中（未実装）。

手動並列作業

Ghostty 起動時に herdr が起動する（command = ~/.local/bin/herdr）。セッション（herdr の workspace）とタブの管理は herdr 側のキーバインドで行う（configs/herdr/config.toml の [keys] を参照。prefix は ctrl+space）。

スコープ 方法
リポジトリ単位 herdr workspace（prefix+s の workspace picker / prefix+g の goto で切替）
リポジトリ内の並列 git worktree（gw_add で作成、herdr の prefix+shift+g / prefix+shift+o でも操作可能）
エージェント単位 prefix+a（Cmd+A）のエージェントピッカーで一覧を j/k で辿って移動（ADR-079）。番号指定は prefix+alt+1..9

space / tab を開いたときの自動処理

Cmd+Shift+S（repo ピッカー）・Cmd+T（新しい tab）・prefix+shift+n（新しい workspace）では、開くのと同時に以下が自動で走る。

処理 内容 ADR
default worktree で開く linked worktree に居ても、repo のメインチェックアウトを cwd にする ADR-087
claude 自動起動 新しい pane で Claude Code を起動（repo ピッカー経由のみ） ADR-086
default branch を pull git pull --ff-only origin <default branch> ADR-088

自動 pull は pane に何も表示されない。 pane のシェルに入力するのではなく独立プロセスとして走るため（画面を占有せず、popup のクローズや claude 起動を待たせないための設計）、確認はログで行う。

tail -5 ~/.local/state/herdr/pull-default-branch.log
ログの行 意味
pulled <branch> (dir=...) 成功
skip: <理由> (dir=...) 意図的なスキップ（linked worktree / default branch 以外に居る / origin remote が無い / git 管理外）
warn: ... 失敗（fast-forward できない等）。space / tab 自体は使えるので処理は続行される

主要な運用フロー

Worktree 管理 — gw_add / gw_cd / gw_rm

コマンド 概要
gw_add <name> worktree 作成 + cd。--claude で Claude Code を自動起動
gw_cd [branch|path|/] worktree 間を fzf または引数で移動。/ でメイン worktree に戻る
gw_rm [--dry-run] [--days N] マージ済み・古い worktree を一括削除（デフォルト 30 日）

worktree 配置先: <リポジトリ>@<worktree名>（例: dotfiles@feat-herdr）

セットアップ

scripts/setup.sh + scripts/setup-manifest.yml で dotfiles のセットアップを宣言的に管理（ADR-018）。

scripts/setup.sh                    # full プロファイルで実行
scripts/setup.sh --profile remote   # remote プロファイルで実行
scripts/setup.sh --dry-run          # チェックのみ

マニフェストにコンポーネントごとの symlink 定義・セットアップスクリプト委譲を記述。

ADR 一覧

→ issues.md（サマリ・対応状況・ADR リンクを一元管理）

ツール詳細

Neovim プラグイン・Fish カスタム関数・aqua 管理ツールの詳細は → reference-tools.md