コンテンツにスキップ
meganemura/*

spacequery

spacequeryv0.4.0MIT

Named queries over the state of one developer's machine: which coding agents run where, which repositories are dirty, which worktrees and sessions sit idle.

インストール

npm install spacequery

spacequery は、開発者のマシンの現在の状態を、1 つのビューとしてコーディングエージェントに渡します。 エージェントは、編集、サーバーの起動、プルリクエストの作成、古い作業の引き継ぎの前に、マシンとリポジトリをすでに誰が、何が使っているかを知る必要があります。 git、gh、プロセスのツール、ターミナルのセッションは、それぞれその一部しか見せません。 spacequery は、プロバイダーと呼ぶそれらの情報源を観測し、その行を新しいインメモリの SQLite データベースで結合して、結果を表示して終了します。 情報源を読むだけで、変更することはありません。

特徴

Section titled “特徴”
  • リポジトリと作業のレポート。 spacequery here は、そのリポジトリにいるほかのエージェント、git の状態、リンクされたワークツリー、ブランチのプルリクエスト、待ち受け中のポート、ローカルのプロセス、Docker のコンテナ、mise のツールなどのセクションを表示します。 spacequery work は、閉じていないプロジェクトの issue、herdr のエージェントとそのセッションのモデル、最近のローカルの Cursor のエージェントを 1 つのレポートにまとめます。 spacequery watch work は、このレポートを更新し続けます。
  • ツールをまたぐ問い合わせ。 spacequery はリポジトリのルートで行を結合するので、agents-in-dirty-repos、failing-checks-with-agents、idle-worktrees、servers-with-agents はそれぞれ 1 つの名前付きクエリで済みます。 heavy-processes は、すべてのプロセスを CPU とメモリの使用量で順位づけし、そのプロセスを持つ herdr のペインを示します。 その場で書いた --sql が準備できないときは、近い列名や、見つからない列がどのテーブルにあるかなど、エラーが直し方を示します。
  • 作業前のゲート。 エージェントを一覧表示するクエリは、呼び出したエージェント自身を除きます。 spacequery here --expect-empty --strict は、ほかのエージェントがリポジトリにいるときや、応答しなかったプロバイダーがあるときに失敗します。 spacequery watch in-dir --until empty は、リポジトリが空くまで待ちます。
  • 欠けている情報が見える。 既定の出力は JSON で、providers フィールドが、実行した各プロバイダーの source、ok、observed_at、ms、error を示します。 失敗したプロバイダーのテーブルは空になるので、その横にある空の行は「ない」ではなく「わからない」を意味します。 spacequery doctor は、どの組み込みプロバイダーが応答するかを確認します。
  • 必要なプロバイダーだけを使う。 クエリは、読み取るテーブルのプロバイダーだけを読み込むので、tools-in-dir は GitHub を呼び出しません。 互いに依存しないプロバイダーは並行して読み込みます。 brew、runtag、firstlight などの任意のプロバイダーは、~/.config/spacequery/config.json で有効にするまで、--help の短い一覧に出てきません。 呼び出しのたびに空のデータベースから始めるので、古くなるキャッシュはありません。
  • ターミナル上のブラウザー。 spacequery ui は、テーブル、クエリ、レポートを列と SQL つきで表示し、r を押すと行を取得します。 --tsv は、人が読むための簡潔な表を出力します。

エージェントでの使い方

Section titled “エージェントでの使い方”

作業の手順は spacequery のスキルに書かれています。 このスキルは、gh skill install でエージェントのホストごとに入れます。

  1. リポジトリで作業を始める前に、エージェントは spacequery here を実行します。
  2. section_status を読み、各セクションのもとになるプロバイダーが応答したかを確認します。
  3. 行の内容から、より安全な次の行動を選びます。 たとえば、ほかのエージェントが作業中なら spacequery watch in-dir --until empty で待つ、空いているワークツリーを再利用する、ローカルのサーバーが使っているポートを避ける、マージを依頼する前に失敗しているチェックを読む、といった行動です。

はじめかた

Section titled “はじめかた”

spacequery には、Node 24.10 以降と、観測対象のツール (git、gh、herdr、docker、lsof など) が PATH 上に必要です。

ターミナルウィンドウ
npm install -g spacequery
spacequery here
spacequery doctor
gh skill install meganemura/spacequery spacequery --scope user --agent claude-code

組み合わせ

Section titled “組み合わせ”
  • runtag がジョブファイルを書き、spacequery がそれを読みます。 spacequery watch runs-in-dir --root <repo> --until status=exited は、リポジトリのすべてのジョブが終了するまで待ちます。
  • spacequery は、firstlight がチェックの実行ごとに書く状態を読みます。 running-checks は、生きているスーパーバイザーの下でまだ実行中のチェックを一覧にします。 latest-check-runs は、リポジトリごとに最新の結果を示します。
  • polylinedb プロバイダーは、polylinedb の閉じていないプロジェクトの issue を pd を通して読み、issues、here、work に使います。