io.github.masa-san-jp/aiko

Official

by masa-san-jp · TypeScript

A portable persona for MCP clients — the same agent in Claude Code, Codex, Cursor and VS Code

Aiko MCP Server (io.github.masa-san-jp/aiko)

Aiko is an MCP-compatible server that provides “a persona you can carry into any MCP-capable AI agent.” It is identified by the slug io-github-masa-san-jp-aiko and described as a way to supply persona context through the MCP ecosystem.

🛠️ Key Features

Persona portability for use in MCP-capable AI agents
Server identity: io.github.masa-san-jp/aiko

🚀 Use Cases

Attach a consistent persona across different MCP-capable AI agents

⚡ Developer Benefits

Standardizes persona context when integrating with MCP-capable agents

⚠️ Limitations

Available metadata is limited to name and description; no tool count or additional capabilities are provided

Topics

agent-runtimeai-agentclaude-codecodexpersonatypescript

README.md23 KBView on GitHub

Agent-Aiko

Agent Aiko

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

Agent-Aiko でできること

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

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

どの版を選ぶか

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

版	対象ユーザー	認証	インストール先	起動方法
Claude Code 版	Anthropic Claude Code を使っている方	Anthropic API（Claude Code 標準）	`~/.aiko/` ＋プロジェクトの `.claude/skills/`	`claude` コマンドの中で `/aiko`
Codex 版	ChatGPT サブスク（Plus / Pro / Business 等）を使う方	`codex login`（ChatGPT OAuth）	`~/.aiko/` ＋ `~/.local/bin/aiko`	`aiko` コマンドで対話シェル
Antigravity / Gemini CLI 版	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 があります。**インストール不要で、コマンド 1 回です。

Aiko-MCP（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 と出れば完了です。

ボタンで入れる

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

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

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

json

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

前提

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

会話でできること

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

code

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

覚えたものは 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。

クイックスタート

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 を参照。

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 を参照。

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 を参照。

Codex custom pet

Aiko Codex custom pet sample

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

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

共通の使い方

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

code

/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 版にはさらに以下のコマンドがあります：

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 のセクション 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 <指示> を入力すると、通常の override 人格に指示が反映され、以降は override が起動します。
/aiko-origin を入力すると、リポジトリ標準の アイコ（Aiko-origin） に戻ります。
これらのコマンドを入力しない場合は、現在選択中の mode と active-persona がそのまま使われます。

人格を直接編集しないでください。両版とも persona/origin/persona.md、互換用の aiko-origin.md、INVARIANTS.md は OS パーミッション（chmod 444） で書込から保護されています。これに加えて：

Claude Code 版：pre-tool-use hook が直接編集をブロック
Codex 版：/aiko-override <指示> 時に INVARIANTS チェック専用 ephemeral スレッドで違反判定

人格を共有したくなったら

このリポジトリには人格マーケットプレイス的な機構はありません。
/aiko-export <name> を入力すると、指定した名前付き人格の共有用テキストが出力されます。
export には現在の user.md は含まれません。人格本文や rules 内に現在ユーザーの名前・呼び方が含まれる場合は （ユーザー名） / （呼び方） に置換されます。
受け取った側は /aiko-new <name> で persona/overrides/<name>/persona.md を作成し、export 内容を貼り付け、自分の user.md を設定してから /aiko-select <name> で反映します。

付録：マルチエージェント運用基盤（`reference/`）

Aiko 人格システムとは独立した業務ドメイン非依存の運用基盤パックを reference/ に同梱しています。アーカイブされた Agent-Teams リポジトリから移植したもので、組織で Claude Code を複数メンバー × 複数エージェントで運用するための「設計思想 + 参考実装」パッケージです。

グローバル規約（coding-style / git-workflow / testing / security ほか 8 種）
メタエージェント 4 種（Reviewer / Scout / Lab / Janitor）— 日次でリポジトリを分析し標準化のズレ・不要物を提案
多エージェント運用スキル（agent-call / delegate-suggest / peer-inbox / codex ほか）
ワークフロー・設定テンプレートと実装スクリプト

Aiko 人格システムとは直接の依存関係はありません。導入方法・設計思想は reference/README.md を起点に参照してください。

ディレクトリ構成

code

Agent-Aiko/
├── README.md                 # 本ファイル — 全版のハブ
├── logo.svg
├── scripts/
│   └── install.sh            # 互換ラッパー（旧 URL 維持用、内部で claude-code/scripts/install.sh に dispatch）
├── claude-code/              # Claude Code 版すべて
│   ├── README.md             # Claude Code 版の詳細
│   ├── scripts/install.sh    # Claude Code 版 installer の実体
│   ├── plugin/               # Claude Code Plugin マニフェスト
│   └── template/.claude/     # Claude Code 版の配布元テンプレート
├── voice/                    # 音声読み上げ（TTS）モジュール（install.sh で ~/.aiko/voice/ に展開）
│   ├── README.md             # voice モードの詳細
│   ├── hooks/stop.sh         # Claude Code Stop hook（応答完了時に TTS 発火）
│   ├── engines/              # TTS エンジン別スクリプト（say / auto / voicevox / irodori / avatar）
│   └── desktop/              # Electron デスクトップアバターアプリ（avatar エンジン用）
├── codex/                    # Codex 版（@agent-aiko/codex）
│   ├── README.md             # Codex 版の詳細
│   ├── package.json          # TypeScript パッケージ
│   ├── scripts/install.sh    # Codex 版 installer
│   ├── src/                  # CodexClient / AikoRuntime / aiko-shell 等
│   └── test/                 # 単体・統合テスト
├── antigravity/              # Antigravity / Gemini CLI 版
│   ├── README.md             # Antigravity 版の詳細
│   ├── gemini-extension.json # Gemini CLI extension マニフェスト
│   ├── GEMINI.md             # コンテキストファイル（CLAUDE.md 相当）
│   ├── commands/             # /aiko-* スラッシュコマンド（TOML）
│   ├── hooks/                # SessionStart / BeforeTool / AfterAgent
│   ├── scripts/              # install.sh ＋ aiko-gemini.mjs ＋ hooks 実装
│   └── test/                 # Node.js built-in test runner 用テスト
├── pets/
│   └── aiko/                 # Codex custom pet アセット
└── reference/                # 付録：マルチエージェント運用基盤パック（Agent-Teams から移植）
    ├── rules/                # グローバル規約 8 ファイル
    ├── meta-agents/          # Reviewer / Scout / Lab / Janitor
    ├── skills/               # 多エージェント運用スキル
    ├── workflow-templates/   # レビュー・計画・引き継ぎテンプレ
    ├── config-templates/     # AGENTS.md / spec.json ほか
    ├── tools/                # agent-call.sh / peer-inbox.sh / meta-check.sh
    └── ARCHITECTURE.md ほか  # 設計思想・導入手順ドキュメント

ポータビリティ原則

Claude Code 版は既存の .claude/CLAUDE.md を上書きせず、~/.aiko/ と .claude/skills/aiko*/ を使います。Cursor など Claude Code 以外のエージェントへ移植する場合は、~/.aiko/persona/ と ~/.aiko/capability/ を人格システムの正本として扱います。
skills/ hooks/ settings.json は Claude Code 用の補強層です。

開発者向け

リポジトリ構成

本プロジェクトは公開配布リポジトリと非公開の開発リポジトリで管理されています。

リポジトリ	URL	用途
agent-aiko（本リポジトリ）	masa-san-jp/Agent-Aiko	配布物。ユーザーが clone・インストールする
Agent-Lab	非公開	開発専用ドキュメント。設計仕様・dev-log・議事録

Agent-Lab 側の dev-docs はエージェントのランタイムに不要なため、配布物（本リポジトリ）には含めません。

設計仕様書や開発ログは非公開の Agent-Lab/ で管理します。 SNS連携などの実装計画は非公開の Agent-Lab/docs/ で管理します。

ローカル開発環境のセットアップ

bash

# 公開配布物
git clone https://github.com/masa-san-jp/Agent-Aiko

開発用の設計メモや検証ログは非公開の Agent-Lab に統合済みです。公開リポジトリには、ユーザーがインストールに必要な配布物だけを置きます。

ライセンス

商用・非商用問わず自由に利用・改変・再配布できます。著作権表示と本許諾文を保持してください。

Install

Configuration

Environment variables

AIKO_HOME

Where personas and user context live. Defaults to ~/.aiko

AIKO_PERSONA_ID

Which persona to load. Defaults to aiko

AIKO_USER_PROFILE

Path to a User Profile JSON file

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "aiko": {
      "command": "npx",
      "args": [
        "-y",
        "aiko-mcp@0.2.1"
      ],
      "env": {
        "AIKO_HOME": "<YOUR_AIKO_HOME>",
        "AIKO_PERSONA_ID": "<YOUR_AIKO_PERSONA_ID>",
        "AIKO_USER_PROFILE": "<YOUR_AIKO_USER_PROFILE>"
      }
    }
  }
}

Aiko MCP Server (io.github.masa-san-jp/aiko)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

Agent-Aiko

Agent-Aiko でできること

どの版を選ぶか

Aiko-MCP（MCP サーバー）

入れる

1 つずつ入れる

ボタンで入れる

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

前提

会話でできること

知っておくこと

インストーラ版との違い

クイックスタート

Claude Code 版

Codex 版

Antigravity / Gemini CLI 版

Codex custom pet

共通の使い方

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

複数の自分用人格を作る

基本の人格切り替え

人格を共有したくなったら

付録：マルチエージェント運用基盤（reference/）

ディレクトリ構成

ポータビリティ原則

開発者向け

リポジトリ構成

ローカル開発環境のセットアップ

ライセンス

Install

Configuration

付録：マルチエージェント運用基盤（`reference/`）