claude-code-station

v0.2.2

Published

a month ago

Claude Code Station — fzf-powered launcher and session picker for Claude Code with multi-repo support and SQLite-backed state cache

0High
0Medium
0Low

daiske

claude claude-code fzf cli session launcher

Claude Code Station — ccs

A fast, fzf-powered launcher and session picker for Claude Code. Pick a project to launch fresh or resume any past session — all from a single fuzzy finder, across every repo you own.

複数プロジェクトを横断するClaude Code用のfzf起動＆セッション再開ランチャー。新規起動も過去セッション再開も、同じfzfから一発で。

What's new in v0.2.0 / v0.2.0 の新機能

Mixed-mode launcher — NEW repos and RESUME sessions in a single fzf list / 新規リポジトリ起動と過去セッション再開を同じfzfで混在表示
Repository state badges — git status, handoff/, pendings/, integration links at a glance / リポジトリの状態（git・handoff・pendings・連携先）をバッジで一目把握
SQLite-backed state cache — ~/.cache/ccs/state.db keeps multi-repo overview fast / マルチリポ状態キャッシュ（SQLite）で高速起動
Per-repo custom integration fields — Plane, Attio, Notion, Linear, Slack, GitHub, Figma (and any custom key) / リポジトリごとの連携情報（Plane/Attio/Notion/Linear/Slack/GitHub/Figma ほか任意のカスタムキー）
Renamed: claude-code-recall (ccr) → claude-code-station (ccs). See the migration section below. / claude-code-recall (ccr) から改名。移行は下記セクション参照。

Why? / なぜ？

claude --resume only shows sessions from the current directory and provides no search. And when you have a dozen active projects, you also want to launch a fresh session in the right repo without cd-ing around.

claude --resume はカレントディレクトリのセッションしか出さず、検索もできない。プロジェクトが増えると「新規起動したいリポ」も「続きをやりたいセッション」も、どちらを探すのも手間。

ccs solves both / ccs が両方まとめて解決：

Fuzzy search across all projects (repo name, session title, timestamp, content) / 全プロジェクトのファジー検索
Mixed list: NEW repo rows + RESUME session rows side by side / 新規起動行と再開行を同じリストに
Live preview — git status, handoff/pendings summary, integration badges, conversation head / ライブプレビュー（git状態・handoff/pendings・連携バッジ・会話冒頭）
Enter once, launched in the correct cwd with the correct command / Enter一回で正しいcwd・正しいコマンドで起動

Install / インストール

Prerequisites / 前提条件

Node.js 20+
fzf ≥ 0.42.0 — fuzzy finder (the change-header binding used by the copy-toast requires 0.42+; released Aug 2023)
Claude Code CLI (claude)
tsx — TypeScript runner. Bundled as a package dependency; a global tsx (npm install -g tsx) is only needed for the bare-checkout workflow. / npmインストール時は同梱されるため、グローバルtsxは checkout 直接運用時のみ必要

Quick install (npm, recommended) / クイックインストール（npm直接・推奨）

npm install -g claude-code-station

Installs from the npm registry. All runtime deps (better-sqlite3, yaml, tsx) come bundled, and ccs lands on your PATH via npm's global bin. / npm レジストリから取得。実行時依存は全部同梱、ccs はnpmのグローバルbinでPATHに乗る。

From GitHub (latest unreleased) / GitHub直接（未リリース版を使いたい時）

npm install -g github:indigo-gr/claude-code-station

Copy install (checkout) / コピーインストール

git clone https://github.com/indigo-gr/claude-code-station.git
cd claude-code-station
npm install
./install.sh

install.sh --with-deps で npm install も install.sh に任せられる。install.sh はランタイム依存解決のため checkout の node_modules をインストール先に symlink する（checkout は残しておくこと）。

Manual install / 手動インストール

npm install
cp bin/ccs bin/ccs-*.ts bin/ccs-*.sh ~/.claude/scripts/
chmod +x ~/.claude/scripts/ccs ~/.claude/scripts/ccs-delete.sh

# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.claude/scripts:$PATH"

Quick start / クイックスタート

Run ccs init --auto-discover — scans $HOME (depth 5, --depth N to change) for git repos and lets you multi-select which to register via fzf (TAB to toggle). / $HOME をスキャンして登録するリポをfzfで複数選択
Or edit ~/.config/ccs/repos.yml by hand (ccs init scaffolds the template; see Configuration) / 手で書くなら ccs init でテンプレート生成
Run ccs — fzf opens with your repos + past sessions. / ccs 実行でfzfが起動

$ ccs
ccs> my-project                         ┃ ━━━ Repo ━━━
                                        ┃ 📁 ~/projects/my-project
  NEW   ClaudeCode                      ┃ 🌿 main (clean)
        Claude Code設定                 ┃ 📨 handoff: 2 files
> NEW   My Project                      ┃ 📌 pendings: 1
        Main development repository     ┃ ━━━ Integrations ━━━
  RESUME ~/projects/my-project  2h ago  ┃ Plane:  abc12345-…
         Fix the billing webhook…       ┃ Slack:  #dev-general
  RESUME ~/projects/my-project  1d ago  ┃ GitHub: acme-corp/my-project
         Plane work item sync…          ┃

Configuration / 設定

Full schema: docs/design/repos-yml-schema.md

Minimal / 最小構成

version: 1
repos:
  - name: ClaudeCode
    path: ~/.claude
  - name: my-project
    path: ~/projects/my-project
    description: Main development repository
    tags: [work]

With integrations / 連携情報付き

version: 1
repos:
  - name: My Project
    path: ~/projects/my-project
    description: Main development repository
    tags: [work]
    custom:
      plane_project_id: "abc12345-xxxx"
      plane_url: "https://plane.example.com/my-project"
      slack_channel: "#dev-general"
      github_repo: "acme-corp/my-project"
      notion_db: "abc123"

Known keys: plane_project_id, plane_url, attio_workspace, notion_db, linear_team, slack_channel, github_repo, figma_file. Unknown keys are rendered verbatim under "Other Integrations". / 未知キーは "Other Integrations" にそのまま表示。

Special command (CMS dev server) / 特殊コマンド

version: 1
defaults:
  command: "claude"
repos:
  - name: CMS
    path: ~/sites/blog-cms
    command: "npm run develop"   # overrides claude entirely
    icon: "🚀"
    scan: false                  # not a Claude repo — skip state scan
    tags: [dev-server]

Precedence: repos[].command > defaults.command > $CCS_CMD > "claude".

Preview pane sample / プレビュー表示例

━━━ Repo: My Project ━━━
📁 ~/projects/my-project  🌿 main (2 modified)
📨 handoff: 2 files       📌 pendings: 1

━━━ Integrations ━━━
Plane:    ✅ abc12345-xxxx → https://plane.example.com/my-project
Slack:    ✅ #dev-general
GitHub:   ✅ acme-corp/my-project
Notion:   ✅ abc123

Usage / 使い方

Flags / フラグ

| Flag | Action | |---|---| | (none) | Mixed list: NEW repos + RESUME sessions / 混在表示 | | . | Only sessions whose cwd is under current dir / カレント配下のセッションのみ | | --new | Only NEW repo entries / 新規起動行のみ | | --resume | Only past sessions / 再開行のみ | | --refresh | Force DB rebuild before showing list / 走査を強制してから表示 | | --no-scan | Skip implicit pre-scan (use stale DB) / 事前走査をスキップ | | --help / -h | Help / ヘルプ | | --version / -v | Version / バージョン | | anything else | Passed through to the launched command / 起動コマンドへパススルー |

Keyboard / キーボード

| Key | Action | |---|---| | Enter | Launch (NEW) or resume (RESUME) / 起動または再開 | | Ctrl-Y | Copy cd … && cmd [--resume …] to clipboard; fzf stays open with a "📋 Copied" header / クリップボードコピー後もfzfは開いたまま、ヘッダーに📋通知 | | Ctrl-I | Copy session UUID or repo path; fzf stays open / コピー後も開いたまま | | Ctrl-R | Refresh DB and reload list / DB再走査してリロード | | Ctrl-D | Delete session (RESUME rows only). To remove a repo, edit ~/.config/ccs/repos.yml directly / セッション削除はRESUME行のみ。リポ削除はrepos.ymlを直接編集 | | Esc / Ctrl-C | Cancel / キャンセル |

Visual cues / 見た目のガイド:

NEW rows and RESUME rows are separated by a dim ── Past Sessions ── divider. Selecting the divider is a no-op.
RESUME sessions mapped to a registered repo show that repo's icon (e.g., 🔄 📁 ClaudeCode). Unmapped sessions (cwd that isn't in repos.yml) show ❓ — a visual cue that the session was either a one-off or that the repo isn't registered yet.

Workflows / 主な使い方

1. Launch a project fresh / プロジェクトを新規起動

ccs --new
# pick repo → Enter → claude starts in repo cwd

2. Resume yesterday's work / 昨日の続き

ccs --resume
# fuzzy search by content → Enter → cd + claude --resume <id>

3. Resume in current directory / カレントディレクトリで再開

cd ~/projects/my-project
ccs .

State cache / 状態キャッシュ

ccs keeps a SQLite cache at ~/.cache/ccs/state.db (or $XDG_CACHE_HOME/ccs/state.db) with repo metadata, git state badges, session summaries, and handoff/pending file lists.

~/.cache/ccs/state.db にリポジトリ情報・git状態・セッション要約などをキャッシュ。

Auto-refresh on every ccs run (cheap — 10s TTL per repo) / 毎回の起動で自動走査（リポジトリ単位で10秒TTL）
Manual force: ccs --refresh or press Ctrl-R in fzf / 手動強制: --refresh または fzf 内で Ctrl-R
Reset: rm ~/.cache/ccs/state.db — next ccs run rebuilds it / リセットは DB を削除するだけ（設定 repos.yml は無事）

Schema details: docs/design/sqlite-schema.md.

Migration from ccr v0.1.x / ccr v0.1.x からの移行

Existing sessions are stored under ~/.claude/projects/*/*.jsonl — nothing to migrate manually. ccs auto-discovers them on first scan.

既存の JSONL セッション（~/.claude/projects/*/*.jsonl）は初回走査で自動発見される。手動移行不要。

Command & env rename / コマンド・環境変数のリネーム

| Before (ccr v0.1.x) | After (ccs v0.2.0) | |---|---| | ccr | ccs | | CCR_CMD env | CCS_CMD env | | GitHub: indigo-gr/claude-code-recall | indigo-gr/claude-code-station |

CCR_CMD is still honored for now (with a deprecation warning to stderr). Rename it in your shell rc at your earliest convenience. / CCR_CMD は当面 deprecation warning 付きで尊重。なるべく早めに CCS_CMD にリネームを。

Uninstall old ccr / 旧 ccr のアンインストール

rm -f ~/.claude/scripts/ccr ~/.claude/scripts/ccr-*.ts ~/.claude/scripts/ccr-*.sh
# Remove any `export CCR_CMD=...` from ~/.zshrc or ~/.bashrc

Architecture / 設計

ccs (bash)
 ├─ ccs-scan.ts           → scans repos, orchestrates, writes state.db
 │   └─ ccs-scan-sessions.ts  (session walk, JSONL parse, cwd→repo resolve)
 ├─ ccs-list.ts           → reads DB, emits fzf rows (NEW + RESUME)
 ├─ ccs-preview.ts        → preview pane renderer (repo badges)
 │   └─ ccs-preview-session.ts (session conversation head)
 ├─ ccs-config.ts         → loads/validates ~/.config/ccs/repos.yml
 ├─ ccs-init.ts           → `ccs init` scaffold / $HOME repo auto-discovery
 ├─ ccs-db.ts             → better-sqlite3 wrapper (WAL, FK, migrations)
 ├─ ccs-delete.sh         → Ctrl-D session delete handler
 │   └─ ccs-delete-session.ts  (cache row removal, bound params)
 └─ shared helpers (imported by scan / list / preview):
    ├─ ccs-sanitize.ts    (SHELL_METACHARS, stripControlChars)
    ├─ ccs-secrets.ts     (26-pattern maskSecrets)
    ├─ ccs-time.ts        (UTC-safe DB timestamp parsing)
    └─ ccs-utils.ts       (truncate, relative time, extractText, UUID_RE)

Design docs: docs/design/.

Security / セキュリティ

Session IDs validated as UUID before shell execution / セッションIDはUUID形式を検証してからシェル実行
$HOME-rooted path validation for every cwd / 全cwdが$HOME配下であることを検証
Known secret patterns (API keys, tokens) masked in preview / プレビュー内の既知シークレットパターンはマスク
SQLite DB created with 0600 permissions; config/cache dirs 0700 / DBは0600、設定/キャッシュディレクトリは0700
No eval; all invocations are direct / eval不使用
Prepared statements only for SQLite; foreign keys enforced / SQLiteはprepared statementsのみ、FK有効
50MB per-file cap when parsing JSONL sessions / JSONLパーサは1ファイル50MB上限

Trust note / 注意: the command: field in repos.yml is validated for shell metacharacters at load time — only safe, sanitized commands are executed. / repos.yml の command: はロード時にシェルメタ文字を検証し、安全な文字列のみが実行される。

Contributing / コントリビュート

Issues and PRs welcome. See REVIEW.md for review standards and CHANGELOG.md for release history.

License / ライセンス

MIT. See LICENSE.