Read in English

# Shelly — ユーザーマニュアルこれがマニュアルです。[README.ja.md](../README.ja.md) がこのアプリの紹介だとすれば、こちらは実際に手を動かすための手順書にあたります。初めてアプリを開いたとき、そしてそれ以降ずっと、何をどの順番でやればいいのかを書きました。前提にしているのはAPKをインストール済みであることだけです。まだの方は、先にそちらから済ませてください: [クイックスタート → インストール](../README.ja.md#インストール)。 --- ## 1. 始める前に Shellyは一般的なアプリより多くのAndroidパーミッションを要求します。理由ははっきりしていて、これはターミナルだからです。自分のファイルに触れないターミナルは、ターミナルとは呼べません。いちばん重要なのは **全ファイルへのアクセス**（`MANAGE_EXTERNAL_STORAGE`）です。初回起動の直後にShellyが要求します。ここは許可してください。断ってもアプリ専用の内部ストレージの中だけなら一通り動きますが、`/sdcard/Download` をはじめとする共有ストレージは、`cd` した瞬間、あるいはそこにあるスクリプトを `source` した瞬間に `Permission denied` を返します。これはAndroidのScoped Storageが設計どおりに働いているだけで、Shellyの不具合ではありません。うっかり拒否してしまっても後から戻せますが、自動では戻りません。**設定 → アプリ → Shelly → 権限 → ファイルとメディア → すべてのファイルの管理を許可**（Settings → Apps → Shelly → Permissions → Files and media → Allow management of all files）をたどって許可し、そのうえでShellyを完全に終了してから開き直してください。このパーミッションの再チェックは起動時にしか走らないので、動かしたままでは反映されません。それ以外 — 通知、フォアグラウンドサービス、マイク — は、その機能を実際に使う場面に近いタイミングで個別に聞きます。断った場合もその機能が使えなくなるだけで、アプリ全体が壊れることはありません。何がどう動かなくなり、何は動き続けるのかは [README → 権限](../README.ja.md#権限) に一覧があります。私はShellyをGalaxy Z Fold6の上で作り、その上でテストしています。まともに通しで動かした端末はこの1台だけ、つまりN=1です。大部分はお使いの端末でも同じように動くはずですが、本当に端末依存が大きい部分 — 主に画面オフのまま自律エージェントが起動するかどうかで、これはメーカーごとのバッテリー管理に左右されます — については、出てくるたびにここでも、READMEの[ステータス](../README.ja.md#ステータス)表でも明示しています。 --- ## 2. 最初のセッションアプリを開くと、ターミナルペインが1枚だけ表示されます。ターミナル風のテキストボックスではなく、本物のシェルです。カーソルが点滅していてプロンプトが出ている、ノートPCでターミナルを開いたときとまったく同じ状態です。まずは何でもない普通のコマンドを打ってみてください。 ``` ls pwd git status ``` 驚くところは何もないはずです。Shellyがやっている他のすべての土台には本物のPTY（擬似端末。ノートPCのターミナルが話している相手と同じものです）があり、その上で本物のbashと本物のcoreutilsが動いています。次はわざと失敗させて、エラーを読むために画面をさかのぼる代わりに、AIに聞いてみます。 ``` npm run build ``` 空のディレクトリなら当然失敗しますが、スタックトレースを追いかける必要はありません。**AIペイン**を出します。ペインが1枚しかないなら、ヘッダーにあるペイン種別のピル（`[TERMINAL ▾]` と表示されています）をタップして `AI` に切り替えるか、Command Paletteからターミナルの隣にもう1枚追加してください。そして、こう言います。 > エラーを直して送信すると、AIペインはその時点のターミナルの表示内容をスナップショットとして取り込み、それを読んで考えます。こちらが何かを貼り付ける必要はありません。何が起きたのかを説明したうえで、実行できる修正案を **[▶ Run]** ボタン付きで返してきます。タップすれば、その修正がそのままターミナルペインに入って実行されます。壊す、聞く、Runを押す。このループのためにShellyは存在しています。このマニュアルの残りは、そのループを豊かにする話（ペインを増やす、文脈を増やす、AIのバックエンドを増やす）か、そもそもループを回さなくて済むようにする話（スケジュールに従って、スマホがポケットの中にある間にループを代わりに回してくれるエージェント）のどちらかです。 --- ## 3. AIペインと話す AIペインは、最初からあなたのターミナルが見えています。普通のチャットアプリに絶対にできないのは、この一点です。 **既定では、Shelly本人と話しています。** ローカル人格のチャットは、内部で応答したモデル名を前面に出すのではなく、Shellyという一人の常駐する相棒として話します——実際にどのモデルが答えたかにかかわらず、返信にプロバイダー名タグが付くことは一切ありません。今どのプロバイダーがそのペインにバインドされているか知りたければ、ペインヘッダーに一度だけ表示されます。メッセージごとに繰り返し出るわけではありません。エージェントの登録と確認もフォームではなく会話として進みます。この既定人格にバインドされたAIペインはすべて一つの連続した会話を開くため、別のペインや分割へ移っても最初からやり直しません。Geminiなどの外部プロバイダーへ明示的にバインドしたペイン（ペインヘッダーのエージェントバッジ経由でも`@mention`経由でも）は独立したペイン別履歴を保ちます。 **ペインのバインドを切り替えると、文脈が少しだけ引き継がれます。** ペインをコンパニオンから明示的なプロバイダーへ切り替えるときも、その逆のときも、Shellyは抜ける側のスレッドから直近の話題に沿ったメッセージ数件を、入る側のスレッドへコピーし、引き継ぎを説明する小さなシステム通知を添えます。あくまで継続性のための橋渡しであって、二つの履歴を完全に統合するわけではありません。行き来を繰り返してもメッセージが重複することはなく、ペイン単位のコピーはアプリを再起動すると残りません（共有コンパニオンスレッド自体だけは残ります）。 **Shellyは、自分自身とすべてのエージェントのために好みを覚えられます。** 既定のコンパニオンチャットで「デプロイブランチはstagingだと覚えておいて」のように自然に伝えてください。全エージェントを示すスコープ表現や特別な構文は要りません。ノートを書き込む前にShellyが確認を求め、確認後はその`_global`メモリを将来のコンパニオン会話で思い出し、すべてのスケジュール済みエージェントの実行コンテキストにも含めます。（「〜が好き」のような好み表現は、Shellyの周辺的な利用パターン学習が別途拾うことがあります——[プライバシー](../README.ja.md#プライバシー)参照——そのため両方の言い回しを1文に混ぜると、意図した1件ではなく2件のノートが残ることがあります。事実だけを述べる「〜だと覚えておいて」の形なら、この重複は起きません。） **それとは別に、Shellyは確認なしで自分専用の日誌もつけています。** ペインがコンパニオンから切り替わるたびに、Shellyはオンデバイスのローカル LLM を使ってその会話で分かったことを短いノートへ蒸留し、自分専用の`_companion`メモリスコープへ保存します。これはコンパニオン限定のもので、上記の`_global`ノートとは異なり、バックグラウンドエージェントへ渡されることはありません。以降のコンパニオンの返信は、いま尋ねていることに関連する日誌のノートだけを引き戻すので（BM25と新しさで順位付けし、最大5件までのキャップ）、これまで話したことすべてが積み上がった壁にはなりません。これらのノートは**Settings → Companion Memory**からいつでも閲覧・編集・削除できます——このスクリーンは、エージェントを1つも登録していない段階でも到達できます。 **スレッド全体を消さずに、メッセージを一つだけ削除できます。** AIペインの任意のメッセージ吹き出しを長押しし、**削除**を確認してください。そのメッセージだけが会話から削除されます。 **`@mention` で回答者を指名する。** 既定では、Shellyが内容に応じて設定済みのプロバイダーの中から適したものへ自動で振り分けます。指名したいときは `@gemini`、`@cerebras`、`@perplexity`、`@openrouter`、端末内のモデルなら `@local` と書きます。`@team` もあって、これは同じプロンプトを設定済みの全プロバイダーへ一斉に投げます。回答を並べて比べたいときには便利ですが、確認のステップを挟まずに全プロバイダーのクレジットを同時に消費するので、使うときは意識して使ってください。（Groqはプロバイダーとして設定でき、音声の文字起こしもGroqが担当していますが、`@groq` という専用のメンションはまだ用意されていません。） **読んでいるのはターミナルであって、こちらの意図ではありません。** ターミナルが複数ある分割レイアウトでは、AIペインはまず自分のすぐ左にあるターミナルを優先し、次にその時点でフォーカスされているターミナル、最後に最初のターミナル、という順で選びます。シェルを複数走らせているなら、聞きたい相手のターミナルをAIペインの隣に置いておくのが確実です。 **```bash```のフェンス付き返信ブロックは、そのままターミナルに送り込めます。** **Copy**の隣に**挿入**ボタンが表示され、タップするとフォーカス中のTerminalペインの入力行にコードが入ります(自動Enterはしないので、実行前に確認できます)。ターミナルペインが開いていなければ、Shellyが新しく開いて挿入をキューします。 **ファイルを実際に書き換える正攻法が AI Edit です。** サイドバーのFile Treeでファイルをタップすると、Markdown以外のファイルはPreviewペインのCodeタブで開きます（Markdownファイルは別のMarkdownペインで開き、そちらは今のところAI Editのステージングに対応していません）。Codeタブのツールバーにある **`[✨ AI]`** ボタンを押すと、そのファイルがAIペインのコンテキストに載ります。あとは普通の言葉で変更内容を伝えるだけです。「fetchの呼び出しにエラー処理を足して」でも何でも構いません。モデルはunified diffで返し、Shellyはそれを **InlineDiff** として描画します。追加は緑、削除は赤、ハンクごとに **Accept** / **Reject** のボタンが付きます。Acceptしたハンクはその場でディスクに書き込まれます。ただし、書き込んだあとにPreviewペインが必ず自動で描き直されるとは限りません。表示が更新されていないように見えたら、Diff/Fullのトグルを切り替えるか、ファイルを開き直してください。先のハンクがすでにファイルを変えたせいで後のハンクの行番号がずれた場合は、Shellyが今読んでいる位置から**前方に**そのハンクの元のコンテキストを探して張り直します。探索は前方向にしか進まないので、直前の編集位置よりファイルの手前に当たるべきハンクは見つかりません。その場合は代わりに「再生成してほしい」という表示が出ます。 **音声も同じ経路を通ります。** ターミナルのアクションバーにあるマイクアイコンを長押しするとVoiceChatが開きます。発話はGroqの文字起こしを通り、そこで得られたテキストはキーボード入力と同じinput routerに流れます。（音声入力そのものは動作を確認済みです。） **ローカルは本当にローカルです。** `@local` は、同梱のllama.cpp / llama-server経由で動かしているGGUFモデルへ向かいます。ネットワークへは一切出ないので完全にプライベートですが、その代わりクラウドのプロバイダーより遅く、能力も劣ります。速度と品質のバランスを取った既定はQwen3.5-2Bで、Settingsにはもっと軽いものも重いものも用意してあります。 --- ## 4. レイアウトを組む折りたたんだ状態のShellyはターミナル1枚です。それだけで完結した使い方として成立します。とはいえスマホの画面 — とくに折りたたみ端末の内側の画面 — は同時に複数のものを開いておけるので、レイアウトの仕組みがあります。上部バー（AgentBar）の **`+`** をタップするとシートが開き、ADDタブとLAYOUTタブが並びます。配置を選ぶのはLAYOUTタブです。同時に生かしておけるペインは最大4枚（うちターミナルは最大3枚まで）で、プリセットは8種類。単一、左右2分割、上下2分割、左右どちらかを起点にした3分割、上下起点の3分割、そして4分割グリッドです。小さいプリセットに切り替えても、他のペインが閉じられることはありません。隠れているだけで失われてはいないので、大きいプリセットに戻せばそのまま戻ってきます。各ペインのヘッダーには種別のピル（`[TERMINAL ▾]`、`[AI ▾]`、`[BROWSER ▾]` …）があり、タップすればそのスロットの中身をその場で差し替えられます。 **Foldクラスの端末では、この4分割こそがShellyが前提にしているレイアウトです。** 折りたたんでいるときは単一ペインのターミナル。これ単体でも、十分に良いスマホ用ターミナルです。開くと、同じ生きたセッション — 同じシェル、同じスクロールバック、同じ実行中のプロセス — が、何ひとつ再起動せずに最大4ペインへ広がります。リポジトリとファイルのサイドバー、作業しているターミナル、その肩越しに読んでいるAIペイン、ドキュメントや `localhost:3000` のプレビューを出しておくブラウザペイン。ひとつ注意があります。CLIの出力が流れている最中（ビルドの途中、AIの応答の途中）に**開閉を素早く繰り返す**のは、Shellyがきれいに乗り切ることを保証できない操作です。Androidが裏のActivityを作り直すことがあるためです。長く走るものが動いている最中なら、終わるまで待つか Ctrl-C で止めてから開閉してください。普通の使い方 — 作業の区切りで閉じて、次の作業を始めるときに開く — であれば問題ありません。サイドバー（表示できる幅があるときは常に出ています）には、リポジトリとファイル以外にもいろいろ入っています。Tasks（登録済み・実行中のエージェント）、Skills、Quick Launchのショートカット、最近のCodexセッション、リポジトリ、worktree、ファイルツリー、端末内のよく使うフォルダ、保存済みのSSHプロファイル。リポジトリをタップするとFile Treeのルートがそこへ移ります。変わるのは閲覧している場所であって、既に開いているターミナルペインの作業ディレクトリは動きません。まっさらな新規インストールでは、サイドバーはTasksとSkillsを展開した状態で開き、より開発者寄りのセクション — Repositories、File Tree、Device、Worktrees、Quick Launch、Codex Sessions — は単一の**DEVELOPER**という区切りの下に折りたたまれた状態で始まります。何かが削除されたり恒久的に隠されたりするわけではなく、ワンタップで開けます。すでにShellyをインストール済みで、自分なりに開閉状態を選んでいる場合、この既定値が既存の選択を上書きすることはありません。 --- ## 5. AIプロバイダーを設定する ShellyはAIへのアクセスを2種類にはっきり分けています。設定を触る前に、なぜ分けているのかを知っておく価値があります。 **Codexはフォアグラウンドで動くCLIです。** ChatGPTのサブスクリプション（Plus / Pro / Business / Enterprise）を、ネイティブのターミナル上で、ノートPCでのやり方とまったく同じように動かします。サインインは、どれかのターミナルペインで引数なしの `codex` と打つだけです。`~/.codex/auth.json` がまだ存在しなければ、Shellyがアプリ内蔵のBrowserペインにデバイスコードのログインページを開きます。そこで承認すると、Shellyが認証ファイルを書き込み、そのまま通常のCodex TUIに入ります。APIキーは不要で、すでに払っているサブスクリプションに相乗りする形です。放置すると15分でタイムアウトするので、その場合はもう一度 `codex` を実行してください。認証ファイルがあるかどうかは `shelly-doctor` が報告します。 **それ以外はすべて、明示的なAPIキーです。** これは意図的な設計です。Gemini、Cerebras、Groq、Perplexity、OpenRouter、そしてOpenAI互換のローカルサーバーは、**Settings → API Keys**（またはターミナルから `shelly config`）で、プロバイダーごとにマスク表示された入力欄1つずつという形で設定します。これは実装上のたまたまではなく、コンプライアンス上の線引きです。バックグラウンドのエージェントやAIペインの自動ルーティングが、あなたのCodexサブスクリプションを黙って使い回すことはありません。バックグラウンドのエージェントがクラウドの知能を必要とするなら、そのための鍵をあなた自身が明示的に設定する必要があります。（OpenRouterはさらに厳しく、有人時専用です。鍵を設定していても、無人のエージェント実行がOpenRouterを経由することはありません。）全部揃える必要はありません。現実的な出発点はこのあたりです。Codexにサインインしておくこと、AIペイン用に速いAPIキーを1つ（GeminiでもCerebrasでも十分に使えます）、そして出典付きで調べ物をするエージェントが欲しければPerplexity。ネットワークに一切依存したくないなら、APIキーは飛ばしてローカルモデルを用意してください。[AIペインと話す](#3-aiペインと話す)の `@local` の項を参照。 --- ## 6. 最初の自律エージェントを登録するここまでは全部、あなたがその場にいて手を動かす話でした。この章は、あなたがいなくても動く部分の話です。エージェントの正体は、普通の言葉で書いた指示 + スケジュールです。どのペインでもいいので `@agent` に続けてその両方を1文で書けば登録できます。私が実際に動かしているのはこれです。 ``` @agent 月・火・水・木・金の朝8時に、STEAM×AI教育に関する最新の論文とニュースを集めて、一次情報のリンクと短い要約を私のObsidianのvaultに書き出して ``` 曜日は「平日」とまとめず、`月・火・水・木・金` のように区切って並べてください。スケジュールの解析は「平日」という語を繰り返し指定として認識しません。また、曜日の並びの直後に時刻を続けるのも条件のうちです（`…金の朝8時に` の形）。送信すると、Shellyはスケジュールとタスクを別々に解釈し、何をどう理解したかを見せてきます。こちらが確認すると、本物のAndroidのアラームとして登録されます。そこから先は、何かを開いておく必要はありません。アラームが鳴ると、スマホはタスクを走らせるのに必要なぶんだけ目を覚まし、結果を指定した場所へ置きます。実行されたことは通知で分かりますし、Shellyは共有コンパニオン会話でも結果を発話するため、後からアプリを開いたときにはすでにチャットに残っています。手動の **Run Now** が完了したときも同じようにチャットへ戻ります。サイドバーのTasksセクションにあるそのエージェントの行には、前回の実行時刻と次回の予定時刻が出ます。走るはずだった実行が起きなかった場合は、行の詳細ビューに未実行のフラグが立ちます。この手のエージェントを実際に書いたとおりに動かすために、ひとつ先に設定しておくことがあります。**既定では、無人の実行はCodexと端末内のツールしか使えず、クラウドのAPIキーは使えません。** つまり上の書き方でそのまま登録したエージェントは、無人で起動したときにPerplexityではなくCodex経由の調べ物にフォールバックします。これを変えるのが **Settings → Autonomous Cloud**（既定はオフ）で、あなたが見ていない間にスケジュール実行のエージェントが設定済みのクラウドAPIキーを消費することを、明示的に許可する唯一の場所です。上のエージェントに、自力で起動したときもPerplexityを使ってほしいなら、ここをオンにしてください。他にも知っておくと良いことがいくつかあります。 **曖昧な依頼には、1問だけの定型質問ではなく本物の会話が返ります。** `@agent ちょっと手伝って` のように目的語も分野もない入力に対しては、固定スクリプトではなく**LLM自身が**会話の続きを自分の言葉で主導し、十分な情報が集まるまで1問ずつ聞き返します（設定済みならまず高速なクラウドプロバイダ、次にオンデバイスモデル、それも届かなければ従来の固定の1問ずつの質問へ）。答えが複数の手順に分かれると分かった場合——「調べて→要約して→投稿して」——は1本のpromptに潰さず、実際の複数ステップのチェーンとして登録されます。これはデフォルトONです。常に固定の1問ずつの質問がよければ、**設定 → Agents → LLM-Led Agent Registration**でオフにできます。どちらの場合も、確認するまで何も登録されず、モデルが提案する値は必ず独立に再検証されます——スケジュール表現は同じ決定論的パーサーを通り、投稿先は実際に登録済みの接続先としか一致しません。 **「来週から」はそのままの意味です。** `@agent 来週から、毎朝ニュースをチェックして` と書くと、エージェントはその場で登録されますが、最初の実行は解決された日付まで保留されます。開始時期を表す言い方として今理解できるのは「来週から / 来月から / 明日から / N日から（その月の指定日）」で、「月曜から」のような曜日での指定はまだ認識されません。（登録時のふるまい自体は確認済みです。） **トリガーはスケジュールだけではありません。** `@agent 通知が来たら、内容を要約してメモに保存して` のように書くと、時計ではなく、条件に合うアプリの通知が届いたときに走るエージェントとして登録されます。登録の途中で、Shellyはどのアプリの通知をきっかけにするのかを尋ねます。既定で実行のきっかけになるのは通知が「届いた」ことだけで、通知の本文そのものは読みません。サイドバーでそのエージェントの行を長押しして、送信者の表示名を正確に登録しておくと、送信者がその名前と完全に一致したときにかぎり本文がエージェントへ渡されます。渡される場合でも本文は常に、指示ではなく信用できないデータとして扱われます。それ以外の相手からの通知は、読まれることなく捨てられます。 **出力先はメモだけではありません。** エージェントの結果は、通知にもObsidianの下書きにも送れますし、Bluesky、Discord、Slack、Telegram、Mastodon、Misskey、WordPress、X、あるいはWebhookへ出すこともできます。各プラットフォームの鍵を一度登録しておけば使えます。1文で複数のプラットフォームを名指しする——「ブルースカイとXに投稿して」——と、名指しした各プラットフォームにちょうど1件ずつコネクタが登録されている限り、それら全てに投稿する単一のエージェントとして登録できます。名指ししたプラットフォームにコネクタが無い（または2件以上ある）場合は、解決できたプラットフォームだけにフォールバックし、何を対象外にしたかを伝えます。Blueskyは実際のアカウントに対して通しで検証済みです。1つのエージェントから2プラットフォームへ同時投稿する機能自体は実装済みですが、実際に複数コネクタを登録した状態での本番投稿はまだ検証していません。「投稿して、通知して」のように1つの依頼で両方を頼むと、ローカル通知の方が優先され、投稿は登録されません——これは意図的な設計です。プライベートな通知を公開投稿に変えてしまう方向だけは取り消しがきかないので、Shellyはその方向だけは明示的に頼まれない限りやりません（投稿を登録したうえで、実行時に通知してほしいと別途頼んでください）。さらに、投稿先のホストをallowlistに追加していない限り、SNSへの投稿は実際に出ていく前にあなたの承認タップを待ちます。既定で無人のまま投稿することはありません。 **うまくいった実行は、覚えて再利用できます。** エージェントの指示文に「結果を覚えておいて」と入れておくと、実行が成功するたびにメモが残り、次の実行からエージェントがそれを思い出します。Shellyはさらに、成功した実行を再利用できるスキル ―― うまくいった手順、使ったプロバイダー、予算 ―― に蒸留して、あとで似たことを頼んだときにその段取りを黙って使い回すこともできます。あなたが見ている場での実行は、保存する前に「スキルとして保存しますか？」と尋ねます。記憶するエージェントが無人で走ったときは、あなたの手を止める代わりにスキルを自動で保存し、ワンタップの **スキルを削除** を添えた通知を出します。その上に、全エージェントで共有される層もあります。明示的な`@agent`コマンドでは、`@agent どのエージェントでも、返答は簡潔にすることを忘れないで`のように、「覚えておく」と「全エージェント向け」の両方の表現が必要です。一方、既定のShellyとの会話では、その依頼がすでにコンパニオン本人へ向けられているため、普通の「覚えておいて」だけで十分です。どちらの経路でも、Shellyとすべてのエージェントが思い出す共有ノートを書き込む前に必ず確認を求めます。 **アプリを開いていなくても登録できます。** 同じ `@agent` の書き方は、Shellyのホーム画面にあるScouterウィジェットのASKボックスからも使えます。入力してもいいですし、マイクボタンで話しかけてもかまいません（認識結果はレビュー用にテキスト欄へ入るだけで、自動送信はされません）。ウィジェットから打った `@agent` コマンドは、AIペインに直接打ったときとまったく同じ確認を経ます。この確認を省いて、ウィジェット発の登録だけは即座に済ませたい（代わりに登録後に通知を受け取りたい）場合は、**Settings → Widget No-Confirm Register**（既定はオフ）をオンにしてください。これが変えるのは「ウィジェットから登録したエージェント」の確認のしかただけで、AIペインに直接 `@agent` と打った場合は、この設定に関わらず常に先に確認を求めます。 **いちばん正直に伝えておくべき注意点。** Androidにおける無人のバックグラウンド実行は、メーカーごとのバッテリー管理に左右され、ばらつきます。Samsung、Xiaomi、Oppo、OnePlusはいずれも、アプリ側からは制御できない設定に応じて、程度の差はあれバックグラウンドの処理を凍結します。そして、Androidが正確なアラームの権限をShellyに与えなかった場合、Shellyは大きな音を立てて失敗するのではなく、精度の落ちるアラームへ黙ってフォールバックします。Androidがバッテリー最適化の除外を尋ねてきたら許可してください。そのうえで、最初の何回かは、自分の端末で信用できると納得できるまでエージェントの実行履歴を確認してください。 --- ## 7. ターミナルそのものについてここまでの話はすべて、本物のターミナルの上に乗っています。そしてターミナルをスマホで使い物にする要素の大半は、一から作り直す必要がありました。その結果できたものを並べます。 **取ってくるのではなく、同梱しています。** bash、GNU coreutils、Node.js、Python 3、git、curl、ssh、sqlite3、ripgrep、jq、tmux、vim、make、less、`gh`、nano、unzip。これらはすべて実際にコンパイル済みのバイナリとしてAPKの中に入っていて、初回起動時にアプリ専用ストレージへ展開されます。Termuxへの依存も、ディストリのブートストラップも、`pkg install` の一手間も、アプリを開いてから道具が揃うまでの間に挟まりません。（同梱セットの外にあるものが必要なら、TermuxをShellyと並べて使う分には問題なく動きます。`busybox` と `htop` は入っていない例です。） **Fig風オートコンプリートはまだありません。** 旧JS補完エンジンはアプリから到達不能だったため削除しました。ターミナル入力はネイティブPTYへ直接流れ、入力途中のバッファやカーソル位置がJavaScriptへ公開されません。したがってポップアップの復活には、今すぐオンにできる設定ではなく、範囲を絞ったネイティブ（Kotlin）の入力イベントと新しいJS側の接続が必要です。ターミナル出力のハイライト、タップできるファイルパスやスタックトレース行、**SmartKeyBar** は現在利用できます。SmartKeyBarは既定で文脈に合わせた4つのキーセット — Default / Git / REPL / Navigate — を切り替えられるので、実際に必要な記号（`|`、`~`、`Ctrl`、矢印キー）が記号ピッカーの奥ではなくワンタップの位置にあります。5つ目(Vim)はSettings → Terminal → 「Show Vim key bar」から有効化でき、Vimを使わない人のバーが混み合わないよう既定OFFになっています。 **セッションはバックグラウンドに回っても生き残ります。** アプリを切り替えても画面がロックされても、tmuxが裏でシェルを生かし続けます。名前を付けたセッションなら、後から中断したところにそのまま戻れます。vimで編集の途中でも、カーソル位置も未保存のバッファもそのままです。 **gitの状態はサイドバーに常に出ています。** そしてファイルの編集は — 自分で打ったものでも、AI Editのハンクが書いたものでも — バックグラウンドで隠しのsavepointインデックスに自動コミットされます。おかげで、本物のgit履歴に手を触れないまま、ワンタップで任意の時点へ戻せます。コミット前のシークレットスキャナが、APIキーや秘密鍵がsavepointに紛れ込むのを、あなたが気づく前の段階でブロックします。 **SSHプロファイルはサイドバーにあります。** 接続先を一度保存しておけば（ホスト、ユーザー、ポート、鍵ファイル）、タップするだけで `ssh -i KEY user@host -p PORT` の完全なコマンドがアクティブなターミナルペインに入り、あとは実行するだけです。長押しで編集と削除。`Import from ~/.ssh/config` を使えば、既に別の場所で設定済みのホストをまとめて取り込めます。対応しているのは鍵ファイル認証だけで、Shellyはパスワードもパスフレーズも保存しません。 **スニペット** は、よく使う短いコマンドを一度保存しておいて、Command Palette(先頭20件を表示)から呼び出す仕組みです。アプリ内の作成/取込/編集UIは以前のクリーンアップで削除されたまま再構築されていません。スニペットはプレーンなファイルではなくAndroidのAsyncStorage(`store/snippet-store.ts`)に保存されているため、現状この削除されたUI以外で一括追加する公式な手段はありません。 **キーボードに[Nacre](https://github.com/RYOITABASHI/Nacre)を使っている場合、ShellyとNacreは互いにやり取りします。** Shellyが前面表示中、現在のディレクトリ・gitブランチ・安全な直近コマンド用語の一部(生コマンドや秘密情報は含まない)を小さなコンテキストファイルに書き出し、Nacreがそれを読んでかな漢字変換の候補を実際の作業内容に寄せます。このファイルはShellyが前面から外れた瞬間に削除されます。Nacre側では、Shellyにフォーカスがあることを検出する「Dev Mode」が自動変換の誤変換を抑制し(コマンド中の`!=`が勝手に`≠`にされることがなくなります)、記号パネルをプログラミング向けタブにデフォルトで開きます。デフォルトでONになっています。Nacreを使わない場合は設定 → Nacre連携でOFFにできます。 --- ## 8. うまくいかないときいつかは必ず、思ったとおりに動かないものが出てきます。確認する順番を書いておきます。 **まず `shelly-doctor` を実行してください。** アプリの中核となるネイティブバイナリが揃っているかどうかと、それとは別に、Codexが実際に `--version` に応答するかどうかを見ます。手早い健全性チェックですが、限界も知っておいたほうがいいです。ローカルLLMのサーバーに実際に到達できるかどうかは確かめていません（確認**しに行くはずのアドレス**を表示するだけです）。同梱のシェルツール類についても、動くことを確かめるために実際に実行しているわけではありません。存在と生存の確認であって、完全なスモークテストではありません。 **問題がCodexに限った話なら**、`shelly-codex-diagnose` でより深いスモーク／カナリア／編集／パッチのチェックを走らせるか、`shelly-update-clis codex --check-only` で実際にどのランタイムが有効になっているのかを調べてください。`codex --version` がそもそも失敗する場合は、**Settings → Updates → Repair Codex / Reset** でAPKに同梱されたランタイムへ戻せます。こちらは少なくとも起動することが保証されています。 **`/sdcard` のパスが `Permission denied` になる場合**、ほぼ確実に全ファイルへのアクセス権限の話です。設定画面の正確な場所は[第1章](#1-始める前に)にあります。許可したあとにアプリを完全に開き直すのを忘れずに。 **スケジュールしたエージェントが動かなかった場合**、まずサイドバーのTasksセクションでそのエージェントの行を開いて未実行フラグを確認し、次にお使いの端末のバッテリー最適化設定でShellyが除外されているかを確認してください。ここはこのアプリでいちばん端末依存が大きい部分で、[第6章](#6-最初の自律エージェントを登録する)に包み隠さず書いてあります。 **危なそうなコマンドなのにShellyが止めなかった場合。** Shellyのコマンド安全機構は、5段階の深刻度を持つ正規表現ベースのリスク分類器であって、サンドボックスではありません。シートベルトであってファイアウォールではない、という位置づけです。実行する前にコマンドを読んでください。とくにAIが生成したものは。脅威モデルの全体は [SECURITY.md](../SECURITY.md) にあります。 **このマニュアルと `shelly-doctor` で解決しないもの**については、[issueトラッカー](https://github.com/RYOITABASHI/Shelly/issues)が最後の受け皿です。すでに把握している粗い部分はREADMEの[既知の制限](../README.ja.md#既知の制限)にひととおり書いてあるので、先にそちらを検索してみる価値はあります。 --- ## 9. レトロテーマ、リアルタイム音声、PCからShellyへ届く経路比較的新しい4つの機能について、短くまとめておきます。いずれもデフォルトOFFのオプトイン機能です。 **Case Fileテーマ。** `Settings → Theme` に5つ目のカラープリセット、**Case File** が追加されました。クリーム色の紙に黒い罫線という、古いデータベース端末風の見た目で、既存の4つのネオン系プリセットとは方向性が異なります。独立したフォント選択（`Settings → Font`）と組み合わせて使えます — **Default** か **DotGothic16**（ドット絵風フォント）のどちらでも、カラーテーマに関係なく選べます。Case Fileに切り替えると一瞬ブートフラッシュ風の演出が入り、切り替えている間は設定中の壁紙が一時的に無効になります。 **リアルタイム音声。** `Settings → Realtime Voice` をONにすると、既存のタップ録音式VoiceChatとは別の、全二重の音声モードが有効になります。ONにすると、話しかければ声で返事が返ってくる状態が続き、電話のように割り込みにも対応します — 録音→文字起こし→送信→待機、という一往復ずつのやり取りではありません。Gemini APIキーの設定（`Settings → API Keys`）が必要です。ONにする前に知っておいた方がいいこと: Shellyの他のGemini利用と違い、このAPI経由の音声は無料枠のキーでもトークン課金の対象です — アプリの他の箇所のテキスト利用には影響しません。 **PCからShellyに届く経路（A2A / MCP）。** どちらも `Settings → Developer` の下にあるトグルで、ONにすると同じネットワーク上のツールから話しかけられる小さなローカルサーバーが端末上で起動します。 - **A2A Server** は [Agent2Agentプロトコル](https://a2a-protocol.org/) のエンドポイントを起動し、読み取り専用のスキル `list_agents` を1つだけ持ちます。他のA2A対応エージェントツールを試していて、Shellyに登録済みのエージェント一覧を見せたい場合に使えます。 - **MCP Server** はベアラートークンで保護された [Model Context Protocol](https://modelcontextprotocol.io/) エンドポイントを起動し、読み取り専用ツールを4つ持ちます: `read_terminal_output`、`git_status`、`list_agents`、`list_repos`。PCからShelly自体を開発している場合はこちらの方がすぐ役に立つはずです — Claude CodeやClaude DesktopのMCPクライアントをこのエンドポイントに向ければ、端末のターミナル出力やリポジトリ状態を直接読めます。トグルをONにしてから `Settings → MCP Server → Copy Token` でベアラートークンを取得し、MCPクライアント側に `http://:8767/mcp` とそのトークンを設定してください。どちらも今のところ意図的に読み取り専用です — 端末の外からコマンドを実行したりファイルを書き込んだりする経路はまだありません。これは見落としではなく、明確なスコープ上の制限です。理由が気になる場合は [`docs/superpowers/DEFERRED.md`](superpowers/DEFERRED.md) を参照してください。 --- ## 10. アップデート、セキュリティ、そして残りの詳細がある場所 **アップデート**はアプリの中から行えます。上部バーのクラウドダウンロードのアイコン、または **Settings → Updates** です。公開されているリリースマニフェストを読み、ダウンロードしたAPKのSHA-256を検証してからAndroidのインストーラーへ渡します。ShellyはPlayストアの外で配布しているので、最後にAndroid自身がインストールの確認を求めてきます。中身は普通のAndroidアプリの上書きアップグレードなので、データも設定もそのままです。 **Codexのランタイムはアプリ本体とは別に**、独自のリリース経路で更新されます。次のAPKリリースを待つ必要がない、ということです。候補となるランタイムは、ハッシュを検証したうえでスモークテスト（`--version`、`exec --help`）を通ったものだけが、有効なランタイムに昇格します。 **セキュリティについて手短に。** Shellyは普通のAndroidアプリのサンドボックスであって、堅牢化された仮想マシンではありません。ターミナルのコマンドも、承認されたAIエージェントの動作も、アプリ自身のuidで動き、アプリが触れるものにはすべて触れられます。APIキーはExpoのSecureStoreに保存され、端末が対応していればKeystoreで暗号化されます。ログに書き出されることはありません。テレメトリもありません。解析も、クラッシュレポートも、利用状況の追跡もなし。ただし、Profile Learningが有効な間にクラウドAIプロバイダーへメッセージを送ると、応答品質を上げる目的で端末内の利用パターンプロファイルがリクエストに含まれます。**設定 → Agents → Profile Learning**で無効化でき、**Reset Profile**で学習済みプロファイルを削除できます。全体像は [README → セキュリティ](../README.ja.md#セキュリティ) と [SECURITY.md](../SECURITY.md) にあります。このマニュアルに書いた機能は、どれも私自身が使っているものです。そして不完全なところや不安定なところは、体裁よく丸めずにそのまま書くようにしました。[`docs/superpowers/DEFERRED.md`](superpowers/DEFERRED.md) はこのプロジェクト自身の台帳で、何が出荷済みで、何がフラグで無効化されていて、何が壊れていると分かっているかが記録されています。このマニュアルが歯切れの悪い書き方をしているとき、その根拠はそこにあります。それでもここに書いてあることと実際のアプリの挙動が食い違っていたら、[issueを立ててください](https://github.com/RYOITABASHI/Shelly/issues)。