sasacode ドキュメント

01はじめに

インストール

curl -fsSL https://sasanokusa.com/sasacode/install.sh | sh

macOS（Apple Silicon / Intel）と Linux（x64 / arm64、glibc / musl、AVX2 のない CPU 向けの baseline 版）の単一バイナリが ~/.local/bin/sasacode に入る。Bun も Node.js も要らない。Windows は WSL から使う。

• インストーラーとバイナリは GitHub Releases の最新版から取り、SHA256 を確かめてから置く。
• 版を固定する：SASACODE_VERSION=v0.9.9。置き場所を変える：SASACODE_INSTALL_DIR=/usr/local/bin。
• 更新は sasacode update（インストーラーと同じ検証つき。--check で確かめるだけ）か、同じインストールコマンドをもう一度実行する。新しい版が出ると起動時に一度だけ知らせる（設定の "updateCheck": false で止まる）。削除は ~/.local/bin/sasacode と ~/.sasacode（設定・セッション・プラグイン）を消す。

最初の設定

sasacode --version          # 初回起動で ~/.sasacode/.env ができる
$EDITOR ~/.sasacode/.env    # 使うプロバイダーのキーだけ埋める
sasacode                    # 対話モードで始める

.env には対応するプロバイダーのキーが空欄で並んでいる。空欄は「未設定」として扱うので、使うものだけ埋めればよい。キーの代わりに OS のキーチェーンに入れることもできる（キーの探し方）。

どのモデルで始まるか

起動してからは /model で一覧から選び直せる。

02TUI（対話モード）

画面の構成

• 会話：あなたの入力（背景色つき）、推論（∴、既定では最後の2行だけ）、ツール呼び出し（● の色：灰=待ち、黄=実行中、緑=完了、赤=エラー）、応答。ctrl+o で推論とツール出力の全文を開く。
• 状態：実行中の表示と、実行中に送った（次のターンに届く）メッセージ。
• フッター：左から、モデル、推論の深さ、権限モード、コンテキストの使用量（使用量/上限と割合）、セッション ID、料金（分かるときだけ）。2行目はプラグインの状態（TODO、ゴール、MCP の接続数、バックグラウンドジョブ、要約中など）。

キー操作

コマンド

TUI の設定

03モデルとプロバイダー

キーの探し方

自前のサーバー

sasacode endpoint add pgx http://gpu-box:8000/v1          # 形式を判別して保存
sasacode endpoint add mygw https://llm.example.com/v1 --key-env MYGW_KEY
sasacode endpoint list
sasacode -m pgx/<モデル名>

GET /v1/models の応答から、OpenAI 形式か Anthropic 形式かを判別し、URL も SDK に合わせて整える。llama.cpp は /props、Ollama は /api/show から実際のコンテキスト長も取る。判別の結果は ~/.sasacode/endpoints.json にキャッシュする。表にないモデルのコンテキスト長が違うときは modelOverrides で直す。

{ "modelOverrides": { "pgx/qwen3.8-flash-next": { "contextWindow": 262144, "maxOutput": 32000 } } }

ChatGPT プラン

sasacode login でブラウザが開き、ChatGPT アカウントでログインすると openai-codex/… のモデルが API キーなしで使える。利用分はプランの Codex の枠から引かれ、残りは /usage plan で見られる。SSH の先などブラウザがこのマシンに戻れないときは、ログイン後にブラウザが表示した URL を貼り付ける。認証情報は ~/.sasacode/codex-auth.json（本人だけが読める）に置き、期限が近づけば自動で更新する。

推論の深さ（/effort・--thinking）

off / low / medium / high / xhigh / max の6段階。既定は high。送り方は API 形式ごとに違う。

OpenAI 形式のサーバーは受け付ける値がまちまちなので、断られたら次の候補で送り直し、通った値を覚えて次からはそれを使う（サーバーとモデルごと）。

04権限

ツールを実行する前に、ルール・権限モード・プラグインの順に判定する。判定は実行前の確認であって、隔離（サンドボックス）ではない。

判定の流れ

権限モード

agent モードで判定するのは呼び出しを作ったのと同じモデルで、呼び出しの引数も読むため、モデルを誘導する文が判定も誘導しうる。利便のための機能で、プロンプトインジェクションへの防御ではない（それには deny / ask ルールと guard プリセットを使う）。

切り替えは shift+tab、/permission <mode>、--permission、設定の permissions.mode。

ルールの書き方

{
  "permissions": {
    "allow": ["bash(bun test*)", "bash(git diff*)"],
    "ask": ["bash(git push*)"],
    "deny": ["read(**/.env)", "edit(**/.env)", "write(**/.env)", "bash(curl * | sh)"],
    "softDeny": ["bash(git reset --hard*)"]
  }
}

パスのルールは書いたツールにだけ効くので、.env を守るなら read / edit / write を並べ、サブディレクトリも含めるには **/ を付ける。コマンドのルールはコマンドの文字列に合わせるだけなので、オプションの順を変えたり絶対パスで呼んだりすれば当たらない。間違いを防ぐ柵であって、完全な防御ではない。

プリセット

plugins.settings["permission-presets"].presets で選ぶ（既定 ["guard"]）。/presets で一覧。

できないこと

• 許可した bash コマンドの中身（スクリプトが何をするか）までは見ない。
• 判定から実行までの間にリンクを差し替えるような競合は防げない。
• 信頼できないコードを扱うときは、コンテナなど OS の側で隔離する。
• 中断（esc）した後は、承認済みでもまだ始まっていないツールは実行しない。

Jev による判定（配布プラグイン jev-guard）

判断専用モデル Jev に、呼び出しが安全かを確率で答えさせ、上の permission フックで判定を変えるプラグイン。0.9.5 までは同梱していたが、既定で無効でキーも要るので、配布プラグインに分けた。入れた後は TUI で /jev on と打てばそのセッションで有効になり（/jev off で無効。/resume 後も保たれる）、いつも使うなら設定に書く。0.9.5 までの設定はそのまま使え、設定があるのにプラグインが入っていなければ起動時に入れ方を知らせる。

sasacode plugin install sasacode-plugin-jev-guard

{ "plugins": { "settings": { "jev-guard": { "enabled": true } } } }

送るのは、ハーネスが集めた事実（コマンド、変更されうるパスとその git の状態、作業ディレクトリの内か外か）と、ユーザー自身の直近の依頼だけ。ツールの出力やファイルの中身は送らない。キーやトークンらしい文字列は伏せる。設定の全項目は 下の表。

05プロジェクトの信頼

クローンしたリポジトリの .sasacode/ は、そのままでは「制限を強める」ことしかできない。コードを実行するか、データの送り先を変えうるものは、最初に一覧を出して信頼するかを尋ねる（ヘッドレスは --trust-project）。

答えは ~/.sasacode/trust.json に保存し、上の設定かプラグインのコードが変わったら、また尋ねる。全体の設定の trustedProjects に入れたプロジェクトは尋ねずに信頼する。

06設定リファレンス

~/.sasacode/config.json（全体）と <project>/.sasacode/config.json（プロジェクト）を合わせ、プロジェクトが優先する。権限ルールと disabled の配列は両方を合わせるので、全体の deny や無効化をプロジェクトから消すことはできない。型の合わない値と未知のキーは、警告を出して無視する。

環境変数

ファイルの置き場所

07同梱プラグインと設定

設定は plugins.settings.<名前> に書く。どれも plugins.disabled で外せ、~/.sasacode/plugins やプロジェクトに同じ名前のプラグインがあれば、同梱版の代わりにそちらを読み込む。

{ "plugins": { "settings": { "compaction": { "threshold": 0.7 }, "loop-guard": { "noProgressTurns": 0 } } } }

小型モデル向けの修復と抑止

文脈とエージェント

バックグラウンド実行（background-sessions）

モデルが bg_start で長いコマンドを裏で動かし、終わったら終了コードと出力の末尾が会話に届く（待機中なら続きを自動で始める）。bash と同じ権限ルールで判定する。sasacode を終了してもジョブは続き、次の起動で結果を知らせる。/bg で一覧、/bg <id> で詳細、/bg kill <id> で停止。POSIX のみ。

接続の復旧待ち（auto-reconnect）

実行がエラーで終わり、使っているモデルの接続先に届かないとき、復旧を待ってから「中断した作業を再開して」と送る。オンラインで別の理由（キーの誤りなど）のエラーなら何もしない。

使用量（usage）

記録は ~/.sasacode/sessions のセッションログから読む。/compact の要約とサブエージェントの分はログに残らないので含まない。プランの残りは ChatGPT にログインしているときだけ出る。

Web

Jev（配布プラグイン jev-guard）の設定

08プラグイン

探す・入れる・公開する

sasacode plugin search                      # 全部
sasacode plugin search 天気                  # 語で絞る
sasacode plugin install sasacode-plugin-foo  # npm
sasacode plugin install https://github.com/you/plugin   # git
sasacode plugin install ./my-plugin          # 手元のパッケージ（公開前の確認）
sasacode plugin install foo --project        # このプロジェクトの .sasacode/plugins へ
sasacode plugin update [名前]
sasacode plugin list
sasacode plugin remove <名前>

入れる前に見せるもの

• npm：版、説明、公開者と公開日、ファイル数と大きさ、依存パッケージ、install スクリプトの有無（実行はしない）、sasacode フィールドの有無、ソースのリポジトリ。
• git：URL。入れた後にコミットを出す。update では新しいコミットの一覧と変更の規模を見せてから更新する。
• 端末がない（スクリプトから実行する）ときは --yes が要る。

公開する

sasacode plugin publish my-tool.ts --license MIT --dry-run   # 中身の確認
sasacode plugin publish my-tool.ts --license MIT             # 公開（npm へのログインが必要）

ほかのファイルを import しているプラグインは、package.json に sasacode フィールドを書いたフォルダごと sasacode plugin publish <フォルダ> で出す。おすすめ一覧に載せたいときは、site/plugins.json に1件足す pull request を送る。

{ "name": "my-tool", "source": "sasacode-plugin-my-tool", "description": "何をするか", "author": "you" }

書く

~/.sasacode/plugins/hello.ts に置くだけで読み込む（ビルド不要）。@sasacode/plugin-api は入れなくても import できる（型補完が欲しければ npm i -D @sasacode/plugin-api）。

import { text, type Plugin } from "@sasacode/plugin-api";

export default ((api) => {
  api.registerTool({
    name: "hello",
    description: "Greet someone by name.",
    parameters: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
    kind: "read",
    execute: async ({ name }) => ({ content: [text(`Hello, ${name}!`)] }),
  });
  api.registerCommand({ name: "hello", description: "挨拶する", run: ({ args }) => api.ui.notify(`こんにちは ${args}`) });
}) satisfies Plugin;

組み込みの Skill を使えば、モデルに書かせることもできる：/skill:tool-authoring 天気を返すツールを作って。

フックの順序

API の版

マニフェスト、API の全項目、互換性の約束は docs/plugins.md。

MCP と Skills

{
  "mcpServers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } },
    "remote": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ${REMOTE_TOKEN}" } }
  }
}

• stdio と Streamable HTTP に対応。ツール名は mcp__<server>__<tool>、prompts はスラッシュコマンドになる。接続はバックグラウンドで行うので、起動を待たせない。
• Skills は ~/.sasacode/skills/<name>/SKILL.md、.sasacode/skills/、プラグインの skills から読む。システムプロンプトには名前と説明だけを載せ、本文はモデルが必要なときに読む。
• ツールが多いとき（定義がコンテキストの 10% 以上か 30 個以上）は、tool_search で必要なものだけ読み込ませる。

09セッション

会話は ~/.sasacode/sessions/<作業ディレクトリ>-<ハッシュ>/<日時>_<id>.jsonl に、1件ずつ追記して保存する。途中で強制終了しても、最後に保存したところから再開できる。

• 結果が保存される前に止まったツール呼び出しは、「実行されたか分からない」としてモデルに伝え、状態を確かめてからやり直させる。
• 書きかけの最終行は <ファイル>.torn に退避する。
• セッション ID は、フッター、/session、終了時の要約、ヘッドレスの出力に出る。

10ヘッドレスと自動化

sasacode -p "テストを直して"                         # 答えは stdout、進捗は stderr
sasacode -p "…" --output jsonl                      # 全イベントを1行ずつ JSON で
git diff | sasacode -p "このdiffをレビューして"          # パイプした入力は -p の後ろに付く
sasacode -p "…" --permission auto --trust-project   # CI など確認できない環境で

• 終了コード：最後まで終われば 0、それ以外（中断、エラー、上限、プラグインによる停止）は 1。止まった理由は stderr に [stopped: …] で出る。
• 確認が必要な呼び出しは実行せず、理由をモデルに返す。何を許すかはルールで決めておく（--permission auto でも deny と ask のルールは効く）。
• MCP サーバーなどの起動処理は、最初のリクエストの前に待つ。
• テキストモードでは最後に session <id> · continue: sasacode -r <id> -p "…" が stderr に出る。

JSONL のイベント

最初の行は {"type":"session","id":…,"path":…}。そのあとはイベントが1行ずつ出る。

11困ったとき