{"id":37799409,"url":"https://github.com/led-mirage/ai-assistant-cli","last_synced_at":"2026-01-16T15:24:42.205Z","repository":{"id":331731054,"uuid":"1124149149","full_name":"led-mirage/ai-assistant-cli","owner":"led-mirage","description":"ターミナルで使用する小さなAIアシスタントツール","archived":false,"fork":false,"pushed_at":"2026-01-11T06:18:33.000Z","size":150,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T08:22:30.997Z","etag":null,"topics":["ai","assistant","cli","openai","tool"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/led-mirage.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-28T12:49:39.000Z","updated_at":"2026-01-11T06:17:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/led-mirage/ai-assistant-cli","commit_stats":null,"previous_names":["led-mirage/ai-assistant-cli"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/led-mirage/ai-assistant-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/led-mirage%2Fai-assistant-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/led-mirage%2Fai-assistant-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/led-mirage%2Fai-assistant-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/led-mirage%2Fai-assistant-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/led-mirage","download_url":"https://codeload.github.com/led-mirage/ai-assistant-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/led-mirage%2Fai-assistant-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","assistant","cli","openai","tool"],"created_at":"2026-01-16T15:24:42.119Z","updated_at":"2026-01-16T15:24:42.188Z","avatar_url":"https://github.com/led-mirage.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Assistant CLI\n\n© 2025 led-mirage\n\n## ✨ 機能概要\n\nAI Assistant CLI は、ターミナルに「今日のひとこと」や  \nちょっとした質問への答えを表示するための、小さな AI アシスタントです。\n\nログイン時の一言メッセージはもちろん、`ai なんか教えて` のように  \nちょっとした疑問をその場で聞く小さなヘルプとしても使えます。\n\n- OpenAI API を利用してメッセージを生成\n- **デフォルトはチャットモード（会話の続きができる）**\n- `-1` / `--oneshot` でワンショットモードも利用可能\n- 会話履歴は `history/default.json` に保存（一定時間で自動リセット）\n- `config.yaml` で好みのプロンプトやモデル、履歴設定を変更\n- メタ変数（`\u003c\u003cdate\u003e\u003e` や `\u003c\u003cuser\u003e\u003e` など）の展開機能\n- ログイン時に自動実行してメッセージを表示\n\n端末を開いたときの挨拶から、コマンドの使い方を軽く聞くときまで、  \n「少しだけ AI に手伝ってほしい」ときにちょうどいいツールです。\n\n---\n\n## 📸 スナップショット\n\n![screenshot](doc/screenshot.png)\n\n---\n\n## 🔧 前提条件\n\nAI Assistant CLI は **Linux のターミナル環境での利用** を想定しています。\n\n- Python 3.9 以上（推奨）\n- Unix系シェル環境（bash / zsh など）\n- OpenAI API Key を取得済み\n- `git` が使えない場合は zip ダウンロードでも可\n\n---\n\n## 📁 ディレクトリ構成\n\n```text\nai-assistant-cli/\n├── ai.py              # メインのスクリプト（AI Assistant CLI 本体）\n├── ai.sh              # venv を有効化して Python を実行するシェル\n├── config.yaml        # 設定ファイル\n├── requirements.txt   # 必要なライブラリ一覧\n├── history/           # チャット履歴の保存先（実行時に自動作成）\n│   └── default.json\n└── .venv/             # このプロジェクト専用の仮想環境（後で作成）\n    └── ...\n```\n\n---\n\n## 🧰 セットアップ\n\n### 1. フォルダを配置\n\n好きな場所に `ai-assistant-cli` フォルダを配置します。  \nここでは `~/tools/ai-assistant-cli` に配置する例です。\n\n```bash\nmkdir -p ~/tools\ncd ~/tools\n\n# GitHub からクローン\ngit clone https://github.com/led-mirage/ai-assistant-cli\ncd ai-assistant-cli\n```\n\n※ git が使えない場合は、zip をダウンロードして `ai-assistant-cli` フォルダに展開してください。\n\n### 2. 仮想環境を作成してライブラリをインストール\n\n```bash\ncd ~/tools/ai-assistant-cli\n\n# venv の作成\npython3 -m venv .venv\n\n# venv の有効化\nsource .venv/bin/activate\n\n# 必要なパッケージのインストール\npip install -r requirements.txt\n```\n\n### 3. OpenAI API Key を設定（環境変数）\n\n`ai.py` は、環境変数 `OPENAI_API_KEY` から API Key を読み取ります。\n\n#### 一時的に設定する場合\n\n```bash\nexport OPENAI_API_KEY=\"ここにあなたのAPIキー\"\n```\n\nシェルを閉じると消えます。\n\n#### 毎回自動で読み込まれるようにする場合\n\n`~/.bashrc`（または `~/.bash_profile`）に次の行を追加します。\n\n```bash\nexport OPENAI_API_KEY=\"ここにあなたのAPIキー\"\n```\n\n追加後、設定を反映します。\n\n```bash\nsource ~/.bashrc\n```\n\n### 4. シェルスクリプトに実行権限を付与\n\n```bash\ncd ~/tools/ai-assistant-cli\nchmod +x ai.sh\n```\n\n`ai.sh` は以下をまとめて行います。\n\n1. 自分自身のあるディレクトリへ移動  \n2. `.venv` を有効化  \n3. `ai.py` を実行  \n\n`./ai.sh` を実行してメッセージが表示されればOKです。\n\n---\n\n## 🚀 使い方\n\n### 1. コマンド名のエイリアスを作る（任意）\n\n`~/.bashrc` にエイリアスを追加すると、どこからでも簡単に呼び出せます。\n\n```bash\n# AI Assistant CLI\nalias ai='~/tools/ai-assistant-cli/ai.sh'\n```\n\n反映:\n\n```bash\nsource ~/.bashrc\n```\n\nこれで次のように実行できます。\n\n```bash\nai\n```\n\n---\n\n### 2. チャットモードとワンショットモード\n\nAI Assistant CLI には、2つの動作モードがあります。\n\n#### 2-1. チャットモード（デフォルト）\n\n何もオプションを付けずに `ai` を実行すると、**チャットモード** で動作します。\n\n```bash\nai -p \"自己紹介して\"\nai -p \"さっきの続き教えて\"\n```\n\n- 会話履歴は `history/default.json` に保存されます\n- 同じユーザーであれば、前回の発言や回答も含めた「会話の続き」として応答します\n- 最終更新から一定時間（デフォルト: 600秒 = 10分）経過すると、履歴は自動的にリセットされます  \n  → 新しい会話として一から始まります\n\n履歴の有効期限や最大ターン数は `config.yaml` で変更できます（後述）。\n\n#### 2-2. ワンショットモード（`-1` / `--oneshot`）\n\n会話履歴を使わず、毎回独立した 1 回きりのやり取りだけ行うモードです。\n\n```bash\nai -1 -p \"ls の使い方を教えて\"\n```\n\n- そのリクエストのためだけに `system_prompt` と `user_prompt` を使って API を呼び出します\n- 会話履歴は読み込まれず、保存もされません\n- 以前のバージョン（1.0.0）と同じ挙動が欲しいときは、このモードを使ってください\n\n#### 2-3. 会話履歴を明示的に消す（`--clear-history`）\n\nチャット履歴をすぐにリセットしたいときは、次のように実行します。\n\n```bash\nai --clear-history\n```\n\n- `history/default.json` が削除されます\n- その後は終了し、API 呼び出しは行いません\n- 次に `ai` を実行したときは、新しい会話として始まります\n\n---\n\n### 3. 基本的なプロンプト指定\n\nチャットモード / ワンショットモードに共通する、プロンプトの指定方法です。\n\n#### 3-1. 何も引数を渡さずに実行\n\n`config.yaml` に `system_prompt` や `user_prompt` が設定されている場合、それに従ってメッセージを生成します。\n\n```bash\nai\n```\n\n`user_prompt` が設定されていない場合は、デフォルトで\n\n```text\nGenerate a short message.\n```\n\nというユーザープロンプトが使われます。\n\n#### 3-2. ユーザープロンプトを `-p` で指定する\n\n```bash\nai -p \"ls の使い方を教えて\"\n```\n\n`-p` / `--user-prompt` に渡した文字列が、そのままユーザープロンプトになります  \n（`\u003c\u003cdate\u003e\u003e` などのメタ変数も利用可能です）。\n\n#### 3-3. 引数をそのままユーザープロンプトとして使う\n\n`-p` を省略した場合、残りの位置引数がスペース区切りで連結され、ユーザープロンプトとして扱われます。\n\n```bash\nai ls の使い方を教えて\n```\n\n上記は、内部的に次とほぼ同じ扱いになります。\n\n```bash\nai -p \"ls の使い方を教えて\"\n```\n\n#### 3-4. システムプロンプトを一時的に上書きする\n\n```bash\nai -s \"You are a helpful UNIX command tutor.\" -p \"ls のオプション一覧を教えて\"\n```\n\n`-s` / `--system-prompt` で、`config.yaml` の `system_prompt` を一時的に上書きできます  \n（こちらもメタ変数が使えます）。\n\n#### 3-5. モデルを一時的に変更する\n\n```bash\nai --model gpt-4.1-mini -p \"今日の天気の聞き方の英語例文を教えて\"\n```\n\n`--model` で、`config.yaml` 内の `model` を一時的に差し替えることができます。\n\n#### 3-6. エラー時に詳細を表示する（デバッグ用）\n\n通常、エラーが発生してもメッセージは表示されず、ステータスコード 1 を返すだけです。  \n詳細を確認したい場合は `--debug` を付けます。\n\n```bash\nai -p \"test\" --debug\n```\n\n---\n\n### 4. ログイン時に自動でメッセージを表示する\n\n新しいシェルを開いたときに自動で「今日のひとこと」を表示したい場合、`.bashrc` に次のように書きます。\n\n```bash\n# AI Assistant CLI\nalias ai='~/tools/ai-assistant-cli/ai.sh'\n\n# ログインメッセージをシアン色で表示\necho -ne \"\\033[36m\"\nai -1\necho -e \"\\033[0m\"\n```\n\n`config.yaml` 側で「ログインメッセージ」用のプロンプトを設定しておけば、  \n毎回好みのスタイルで一言メッセージを出せます。\n\n---\n\n## ⚙️ 設定ファイル（config.yaml）\n\n`ai.py` は、同じディレクトリにある `config.yaml` から設定を読み込みます。\n\n指定できる主な項目は次のとおりです。\n\n- `api`: 使用するAPI。`openai`もしくは`azure`。デフォルトは `openai`\n- `api_key_envvar`: APIキーを格納している環境変数名。デフォルトは `OPENAI_API_KEY`\n- `azure_endpoint_envvar`: AzureOpenAI Service のエンドポイントを格納している環境変数名。デフォルトは `AZURE_OPENAI_ENDPOINT`\n- `model` : 使用するモデル名\n- `system_prompt` : システムプロンプト（アシスタント全体の振る舞い定義）\n- `user_prompt` : デフォルトのユーザープロンプト（任意）\n- `history_expire_seconds` : チャット履歴の有効期限（秒）。デフォルトは `600`（10分）\n- `max_turns` : チャット履歴に残す最大ターン数（user + assistant のペア）。デフォルトは `20`\n\n### 例: シンプルな英語ログインメッセージ\n\n```yaml\nmodel: gpt-4.1-mini\n\nsystem_prompt: \u003e\n  You are a friendly assistant that outputs a single short seasonal\n  greeting in natural English, suitable as a daily login message.\n  Keep it under 80 characters, no emojis, no quotation marks.\n\nuser_prompt: \u003e\n  Generate today's greeting.\n```\n\n### 例: 日本語の静かな一言メッセージ + チャット設定\n\n```yaml\nmodel: gpt-4.1-mini\n\n# チャット履歴が 5 分以上経ったらリセット\nhistory_expire_seconds: 300\n\n# 直近 10 ターン分だけ履歴に残す\nmax_turns: 10\n\nsystem_prompt: \u003e\n  あなたは、端末に静かに一言だけ表示される「今日のひとこと」メッセージを\n  生成するアシスタントです。穏やかで、少しだけ背中を押すような日本語の\n  メッセージを1つだけ出力してください。絵文字や顔文字は使わないでください。\n\nuser_prompt: \u003e\n  今日のひとことを40文字以内で1つだけ出力してください。\n```\n\n### メタ変数（`\u003c\u003c...\u003e\u003e`）について\n\n`system_prompt` および `user_prompt` の中では、以下のようなメタ変数を使えます。  \n実行時に、現在の日時やユーザー名などに自動で置き換えられます。\n\n| メタ変数           | 内容の例                        |\n|--------------------|---------------------------------|\n| `\u003c\u003cdatetime\u003e\u003e`     | `2025-01-15 09:30:12`           |\n| `\u003c\u003cdate\u003e\u003e`         | `2025-01-15`                    |\n| `\u003c\u003ctime\u003e\u003e`         | `09:30:12`                      |\n| `\u003c\u003ciso-datetime\u003e\u003e` | `2025-01-15T00:30:12+00:00`     |\n| `\u003c\u003cweekday\u003e\u003e`      | `Monday`, `Tuesday` など        |\n| `\u003c\u003chostname\u003e\u003e`     | 実行しているマシンのホスト名    |\n| `\u003c\u003cuser\u003e\u003e`         | 実行ユーザー名（ログイン名）    |\n\n例：\n\n```yaml\nsystem_prompt: \u003e\n  Today is \u003c\u003cdate\u003e\u003e (\u003c\u003cweekday\u003e\u003e). The current user is \u003c\u003cuser\u003e\u003e on host \u003c\u003chostname\u003e\u003e.\n  You are a calm assistant that outputs one short, encouraging login message\n  under 80 characters, no emojis.\n\nuser_prompt: \u003e\n  Generate today's login message.\n```\n\n実行時には、次のように展開されて OpenAI に渡されます（例）:\n\n```text\nToday is 2025-01-15 (Wednesday). The current user is alice on host my-laptop.\nYou are a calm assistant that outputs one short, encouraging login message\nunder 80 characters, no emojis.\n```\n\n---\n\n## 📑 コマンドライン引数のまとめ\n\n`ai`（= `ai.py`）の主なオプションは次のとおりです。\n\n- `-v`, `--version`  \n  バージョン情報を表示して終了\n- `-c`, `--config`  \n  使用する config YAML ファイルのパス（デフォルト: `config.yaml`）\n- `-s`, `--system-prompt`  \n  システムプロンプトを一時的に上書き\n- `-p`, `--user-prompt`  \n  ユーザープロンプトを一時的に上書き\n- `-m`, `--model`  \n  使用するモデル名を指定（例: `gpt-4.1-mini`）\n- `-1`, `--oneshot`  \n  チャット履歴を使わず、ワンショットで 1 回だけ応答する\n- `--clear-history`  \n  チャット履歴（`history/default.json`）を削除して終了\n- `--debug`  \n  エラー発生時やチャット送信内容を標準エラー出力に表示\n- 位置引数（`rest`）  \n  `-p` を省略した場合に、スペース区切りで結合してユーザープロンプトとして使用\n\n---\n\n## 📝 開発メモ\n\n### 直接スクリプトを実行して試す場合\n\n```bash\ncd ~/tools/ai-assistant-cli\nsource .venv/bin/activate\n\n# API Key が設定されていることを確認\necho \"$OPENAI_API_KEY\"\n\npython3 ai.py -p \"test message\"\n```\n\nチャットモードを試すときは、何度か続けて実行してみてください。\n\n```bash\npython3 ai.py -p \"自己紹介して\"\npython3 ai.py -p \"さっきの続きを教えて\"\n```\n\n履歴をリセットしたいときは:\n\n```bash\npython3 ai.py --clear-history\n```\n\n---\n\n## 📚 使用しているライブラリ\n\n### 🔖 **openai 2.14.0**\nOpenAI API へのリクエスト送信とレスポンス取得に使用しています  \nライセンス：Apache-2.0 license  \n[https://github.com/openai/openai-python](https://github.com/openai/openai-python)\n\n### 🔖 **PyYAML 6.0.3**\n設定ファイル（YAML）の読み込みに使用しています  \nライセンス：MIT License  \n[https://github.com/yaml/pyyaml](https://github.com/yaml/pyyaml)\n\n---\n\n## ❗ 免責事項\n\n- このソフトの利用によって生じた損害について、作者は責任を負いません\n- 可能な範囲で安定動作を目指していますが、完全な動作保証はできません\n- 自己の判断と責任で使ってください\n\n---\n\n## 📄 ライセンス\n\n本プロジェクトは **MIT License** の下で公開されています。  \n詳しくは [`LICENSE`](LICENSE) を参照してください。\n\n© 2025 led-mirage\n\n---\n\n## 📜 バージョン履歴\n\n### 1.2.0 (2026/01/11)\n\n- AIからの応答メッセージを逐次出力するように変更\n\n### 1.1.0 (2026/01/11)\n\n- AzureOpenAI Service に対応\n\n### 1.0.0 (2025/12/28)\n\n- ファーストリリース\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fled-mirage%2Fai-assistant-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fled-mirage%2Fai-assistant-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fled-mirage%2Fai-assistant-cli/lists"}