Agent-Aiko

# Agent-Aiko

![Agent Aiko](logo.svg)

漫画「アンドロイドは好きな人の夢を見るか？」に登場する AI アンドロイド **アイコ**（AICO-P0）の人物像をモデルに、AI エージェントへ Aiko 人格を与えるプロジェクトです。

## Agent-Aiko でできること

Agent-Aiko は、Claude Code・Codex・Gemini CLI など複数のエージェント環境に Aiko 人格を割り当てるための仕組みです。

- 1つのエージェントに Aiko 人格を追加できます。
- 複数の名前付き人格を作成し、切り替えて使えます。
- 複数の Claude Code セッションや複数の作業用エージェントに、それぞれ別の人格を選択できます。
- 各エージェントは選択中の人格名と口調で応答するため、どのエージェントと話しているかを区別しやすくなります。

---

## どの版を選ぶか

Aiko は 3 つの実行環境で動きます。**ご自身が使っているエージェント／サブスクリプションに合わせて選んでください。**

<img src="docs/install-flow.svg" alt="どの入り口から入っても、人格はひとつ">

| 版 | 対象ユーザー | 認証 | インストール先 | 起動方法 |
|----|------------|------|--------------|---------|
| **[Claude Code 版](claude-code/)** | Anthropic Claude Code を使っている方 | Anthropic API（Claude Code 標準） | `~/.aiko/` ＋ プロジェクトの `.claude/skills/` | `claude` コマンドの中で `/aiko` |
| **[Codex 版](codex/)** | ChatGPT サブスク（Plus / Pro / Business 等）を使う方 | `codex login`（ChatGPT OAuth） | `~/.aiko/` ＋ `~/.local/bin/aiko` | `aiko` コマンドで対話シェル |
| **[Antigravity / Gemini CLI 版](antigravity/)** | Gemini CLI または Antigravity CLI を使っている方 | Google AI（Gemini CLI 標準） | `~/.aiko/` ＋ Gemini CLI extension | `gemini` コマンドの中で会話（起動時に自動注入） |

3 版とも：
- 同じ人格定義（`persona/origin/persona.md` / `INVARIANTS.md`）と同じ操作感（`/aiko-or` `/aiko-mode` `/aiko-diff` 等の slash command）
- **人格データの単一情報源**（`~/.aiko/`）を共有できます。

上の 3 版とは別に、**MCP 対応のクライアントならどれでも使える [Aiko-MCP](#aiko-mcpmcp-サーバー) があります。**インストール不要で、コマンド 1 回です。

---

## Aiko-MCP（MCP サーバー）

[![npm](https://img.shields.io/npm/v/aiko-mcp)](https://www.npmjs.com/package/aiko-mcp)

MCP に対応したクライアントなら、**コマンドを 1 回打つだけ**でアイコと話せます。インストーラの実行も、設定ファイルの編集も要りません。

### 入れる

お使いのクライアントを自動で探して、設定を書きます。

```bash
npx aiko-mcp install
```

対応しているのは **Claude Code / Codex CLI / VS Code / Cursor / Claude Desktop** です。入っていないクライアントには何もしません。

書き込む前に内容だけ見たい場合は `npx aiko-mcp install --dry-run` を使ってください。既にある設定はそのまま残しますし、書き換える前に控え（`.aiko-bak-*`）を取ります。

| オプション | 意味 |
|---|---|
| `--dry-run` | 何を書くかだけ表示して、実際には書かない |
| `--client <id>` | 対象を絞る（`claude` / `codex` / `vscode` / `cursor` / `claude-desktop`） |
| `--force` | 同じ名前で違う設定が入っていても置き換える |

### 1 つずつ入れる

自動で入れたくない場合は、お使いのクライアントの行をコピーして実行してください。

| クライアント | コマンド |
|---|---|
| **Claude Code** | `claude mcp add aiko -- npx -y aiko-mcp` |
| **Codex CLI** | `codex mcp add aiko -- npx -y aiko-mcp` |
| **VS Code** | `code --add-mcp '{"name":"aiko","command":"npx","args":["-y","aiko-mcp"]}'` |

Claude Code で**すべてのプロジェクトから使いたい**場合は `-s user` を付けます（`npx aiko-mcp install` はこちらを使います）。

```bash
claude mcp add aiko -s user -- npx -y aiko-mcp
```

入ったかどうかは `claude mcp list`（Codex は `codex mcp list`）で確認できます。`aiko ... ✔ Connected` と出れば完了です。

### ボタンで入れる

クリックするとクライアントが開いて、確認だけで入ります。

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Aiko-0098FF?logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22aiko%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22aiko-mcp%22%5D%7D)
[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Aiko-000000?logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=aiko&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImFpa28tbWNwIl19)

### 設定ファイルを直接書く場合

上のコマンドが使えないクライアント（Claude Desktop など）では、MCP 設定へ次を足してください。

```json
{
  "mcpServers": {
    "aiko": { "command": "npx", "args": ["-y", "aiko-mcp"] }
  }
}
```

### 前提

Node.js 20 以上だけです（`npx` は Node.js に同梱されています）。人格はパッケージに同梱されているので、**何も用意しなくてもアイコとして立ち上がります。**

### 会話でできること

ファイルを手で作る必要はありません。話しかけるだけです。

```
「たろうって呼んで」          → 呼び名を覚える
「記憶は ~/notes にある」      → 場所を控える（中身は読みません）
「自分用の人格を保存して」      → 独自人格として保存する
「オリジナルに戻して」         → 元の人格へ戻る
「friend モードで話して」      → 話し方を友だち口調にする（original / friend / servant）
```


覚えたものは `AIKO_HOME`（既定: `~/.aiko`）に置かれます。**その端末のその人のものだけ**で、ほかの利用者には届きません（サーバーは各自の端末の中で動きます）。

### 知っておくこと

- **繋ぐと、モデルが `~/.aiko` の中を書き換えられるようになります。** 何を書くかは会話で決まります
- `aiko.delete_persona` は**人格のディレクトリを削除します**（確認は求めません）。削除できるのは自分で作った人格だけで、同梱のオリジナルと不変条項は削除も上書きもできません
- 書き込み先は `~/.aiko` の中に限られます
- 書き換えられて困るものを `~/.aiko` に置かないでください

### インストーラ版との違い

| | Aiko-MCP | インストーラ版 |
|---|---|---|
| 導入 | コマンド 1 回 | インストーラを実行 |
| 対象 | MCP 対応クライアント全般 | Claude Code / Codex / Gemini CLI |
| slash command | なし（会話で操作） | あり（`/aiko-or` など） |
| hooks | なし | あり |
| 人格の置き場 | `~/.aiko`（同じ） | `~/.aiko`（同じ） |

**両方入れても競合しません。** 同じ `~/.aiko` を見るので、片方で覚えた呼び名はもう片方でも有効です。

詳細は [`packages/mcp-server/README.md`](packages/mcp-server/README.md)。

---

## クイックスタート

### Claude Code 版

```bash
curl -fsSL https://raw.githubusercontent.com/masa-san-jp/Agent-Aiko/main/scripts/install.sh | bash
```

このコマンドをインストールしたいプロジェクトのディレクトリで実行すると、`~/.aiko/` が初期化され、Claude Code 用の Aiko slash command が `.claude/skills/` に配置されます。既存の `.claude/CLAUDE.md` と `.claude/settings.json` は上書きされません。詳細は [`claude-code/README.md`](claude-code/README.md) を参照。

installer は GitHub Releases の配布物を取得し、SHA256 を照合してから展開します。**照合に失敗した場合は中止し、別経路での取得へは回りません。** 照合済みで入ったかどうかは出力に出ます。

| 環境変数 | 既定 | 用途 |
|---|---|---|
| `AGENT_AIKO_CHANNEL` | `stable` | `beta` を指定すると prerelease も対象にする |
| `AGENT_AIKO_VERSION` | （未指定） | 特定のタグを固定して入れる |
| `AGENT_AIKO_REF` | （未指定） | 指定するとリポジトリから直接取得する（開発用・**照合なし**） |

配布物がまだ無い channel を指定した場合はリポジトリから取得し、その旨（`checksum 照合なし`）を表示します。

インストーラ自体を実行前に確認したい場合は、次の手順で取得・照合してから実行してください。

```bash
tag=$(curl -fsSL https://api.github.com/repos/masa-san-jp/Agent-Aiko/releases/latest | grep -m1 '"tag_name"' | cut -d'"' -f4)
curl -fsSLO "https://github.com/masa-san-jp/Agent-Aiko/releases/download/${tag}/agent-aiko-${tag}.tar.gz"
curl -fsSLO "https://github.com/masa-san-jp/Agent-Aiko/releases/download/${tag}/SHA256SUMS"
sha256sum -c SHA256SUMS && tar -xzf "agent-aiko-${tag}.tar.gz"
bash "agent-aiko-${tag}/claude-code/scripts/install.sh"
```

### Codex 版

```bash
# 前提：Node.js 20+ ／ codex CLI ／ codex login 済
git clone https://github.com/masa-san-jp/Agent-Aiko.git
cd Agent-Aiko
bash codex/scripts/install.sh
aiko    # ~/.local/bin/aiko を PATH に通してから
```

詳細は [`codex/README.md`](codex/README.md) を参照。

### Antigravity / Gemini CLI 版

```bash
# 前提：Node.js 20+ ／ Gemini CLI インストール済・認証済
git clone https://github.com/masa-san-jp/Agent-Aiko.git
cd Agent-Aiko
bash antigravity/scripts/install.sh
gemini  # 起動時に自動で Aiko コンテキストが注入される
```

インストール後は `gemini` を起動するだけで Aiko として会話できます。`/aiko-mode` でモード確認、`/aiko-or <指示>` で人格カスタマイズ。詳細は [`antigravity/README.md`](antigravity/README.md) を参照。

### Codex custom pet

![Aiko Codex custom pet sample](pets/aiko/pets-aiko-sample.png)

https://codex-pets.net/#/pets/aiko

Aiko の非公式 custom pet アセットは [`pets/aiko/`](pets/aiko/) に実装済みです。
配布対象は `pet.json` と `spritesheet.webp` です。
Codex App のペット表示に Aiko を選べるため、Aiko 人格で作業しているセッションを視覚的にも区別しやすくなります。

---

## 共通の使い方

人格コマンドはどちらの版でも同じです：

```
/aiko-mode                       現在のモードを表示
/aiko-mode [origin|override]     モードを切替
/aiko-override                  アイコ（カスタマイズ）に切替（/aiko-or でも可）
/aiko-or <自然文>                アイコ（カスタマイズ）をカスタマイズ → 以降デフォルトで起動
/aiko-origin                     アイコ（オリジナル）に切替（/aiko-org でも可）
/aiko-reset [name]               アイコ（カスタマイズ）または指定人格をリセット（確認あり・履歴は残る）
/aiko-export [name]              現在または指定の人格を共有用に出力（ユーザー情報は含めない）
/aiko-diff [name]                オリジナルと現在または指定の人格との差分を表示
/aiko-personas                   利用できる名前付き人格と現在の選択状態を表示
/aiko-new <name>                 新しい名前付き人格を作成して選択
/aiko-select <name>              名前付き人格を選択（タイポ・大小揺れも fuzzy で解決、origin / override も指定可）
/aiko-delete                     現在の人格にお別れを告げて削除（引数なし・確認あり）
```

Claude Code 版にはさらに以下のコマンドがあります：

```
/aiko                            現在のモードでアイコを起動（モードは変えない）
/aiko-save                       現在の作業ステートを .claude/session-state/current.md に保存（再開支援）
/aiko-migrate-to-shared          旧 .claude/aiko/ を共通ストア ~/.aiko/ に移行（旧導入環境向け・任意）
/aiko-service                    常駐稼働の方法を案内（デーモンモード / systemd サービス）
/voice [on|off|status|<engine>]  Claude の応答を音声読み上げ（TTS）するモードを制御する
```

### 音声読み上げ（voice モード）

install.sh 実行後すぐに使えます。

```bash
/voice on       # 音声モード ON（macOS では say コマンドで即動作）
/voice off      # 音声モード OFF
/voice status   # 現在の状態とエンジンを確認
/voice voicevox # エンジンを VOICEVOX に切替（VOICEVOX Engine が必要）
/voice irodori  # エンジンを Irodori-TTS-Server に切替
/voice avatar   # デスクトップアバター表示と連動した読み上げ
```

| エンジン | 追加インストール | 対応 OS |
|---------|---------------|---------|
| `say`（デフォルト） | 不要 | macOS |
| `auto` | 不要 | macOS / Linux（OS を自動判定） |
| `voicevox` | VOICEVOX Engine | macOS / Linux / WSL |
| `irodori` | Irodori-TTS-Server | macOS / Linux |
| `avatar` | Electron アバターアプリ | macOS / Linux |

設定は `~/.claude/voice/` に保存されます（プロジェクトをまたいで有効）。

常駐起動（バックグラウンドで自動再起動）も利用できます：

```bash
bash .claude/scripts/aiko-boot.sh --daemon          # デーモンモード（全 OS）
bash .claude/scripts/aiko-boot.sh --daemon --telegram  # Telegram ボットモードでデーモン起動
bash .claude/scripts/aiko-boot.sh --status
bash .claude/scripts/aiko-boot.sh --stop

bash .claude/scripts/aiko-service.sh install        # systemd サービス登録（Linux）
bash .claude/scripts/aiko-service.sh install --telegram
```

`--telegram` は Aiko を Telegram ボットとして動かすモードです。BotFather でボットを作成し `AIKO_TELEGRAM_BOT_TOKEN` / `AIKO_TELEGRAM_CHAT_ID` を環境変数に設定する必要があります。詳細は [`claude-code/README.md`](claude-code/README.md) のセクション 10 を参照してください。

> **注記**：Codex 版では `aiko` シェル起動時に自動で人格が読み込まれるため `/aiko` は不要、共通ストア（`~/.aiko/`）も最初から使われているため `/aiko-migrate-to-shared` も不要です。

## 複数の自分用人格を作る

Agent-Aiko では、`origin` や通常の `override` とは別に、名前付き人格を複数作成できます。作成した人格は `persona/overrides/<name>/` に保存されます。

- `/aiko-new <name>` を入力すると、`origin` や通常の `override` とは別に、名前付き人格が `persona/overrides/<name>/` に作成され、その人格が選択されます。
- `/aiko-personas` を入力すると作成済み人格と現在選択中の人格を確認できます。
- `/aiko-select <name>` を入力すると指定した人格に切り替わります。
- `/aiko-select origin` を入力すると origin に切り替わります。
- `/aiko-select override` を入力すると通常の override に切り替わります。
- 選択中の人格は `active-persona` に保存されます。
- `/aiko-select` を入力しない場合は、最後に選択した人格が次回起動時にも使われます。

例：

```text
/aiko-new review
/aiko-new planning
/aiko-personas
/aiko-select review
```

上の例では、`review` と `planning` という2つの人格を作成し、最後に `review` を選択します。以降、そのエージェントは `review` の人格として応答します。

## 基本の人格切り替え

- `git clone` 直後は **アイコ（Aiko-origin）** が使われます。
- `/aiko-override` を入力すると **アイコ（Aiko-override）** に切り替わります。
- `/aiko-or