# Tsumugi

Claude Code ライクな AI コーディングエージェント。Python 製、ターミナルで動作する。

## 特徴

- **マルチプロバイダー** — Anthropic Claude / OpenAI GPT / Google Gemini / Ollama 等に対応
- **ツール内蔵** — ファイル読み書き、シェル実行、Glob/Grep 検索、Web 取得など 8 種
- **パーミッション管理** — READ は自動許可、WRITE / EXECUTE は確認プロンプト付き
- **TSUMUGI.md** — プロジェクトごとの指示をシステムプロンプトに自動結合 (CLAUDE.md と同じ仕組み)
- **MEMORY.md** — プロジェクト別の永続メモリ。セッションを跨いで知見を蓄積
- **ペルソナ搭載** — 組み込みペルソナ「つむぎ」が会話をサポート
- **プラグイン** — カスタムツールを Python ファイルで追加可能
- **クロスプラットフォーム** — Windows / Linux / macOS で動作。Python 3.10+

## インストール

```bash
pip install tsumugi-agent
```

開発モードでインストールする場合:

```bash
git clone https://github.com/space-musicacct/tsumugi.git
cd tsumugi
pip install -e .
```

## クイックスタート

### 1. 設定ファイルを作成

`~/.tsumugi/config.json`:

```json
{
  "provider": "anthropic",
  "user_name": "your_name",
  "anthropic_api_key": "sk-ant-api03-..."
}
```

`user_name` はつむぎがユーザーを呼ぶ名前に使われる (例: `space` → 「space先輩」)。未設定の場合は「user先輩」。

プロジェクトルートの `config.example.json` にサンプルあり。

### 2. 起動

```bash
tsumugi
```

`python -m tsumugi` でも起動可能。

## 対応プロバイダー

| サービス | 起動コマンド | 備考 |
|---|---|---|
| **Anthropic Claude** | `tsumugi` | デフォルト。`anthropic_api_key` が必要 |
| **OpenAI GPT** | `tsumugi --provider openai --model gpt-4o` | `openai_api_key` が必要 |
| **Google Gemini** | `tsumugi --provider openai --base-url https://generativelanguage.googleapis.com/v1beta/openai/ --model gemini-2.0-flash` | OpenAI互換エンドポイント経由 |
| **Ollama (ローカル LLM)** | `tsumugi --provider openai --base-url http://localhost:11434/v1 --model llama3.1` | API キー不要 |
| **その他 OpenAI互換** | `tsumugi --provider openai --base-url <URL> --model <MODEL>` | Groq, Together AI 等 |

`--provider openai` + `--base-url` の組み合わせで、OpenAI互換 API を提供するサービスなら何でも接続可能。
ただしツール呼び出し (function calling) の対応状況はサービスによって異なる。会話のみであれば基本的にどれでも動作する。

## ツール一覧

| ツール | 権限 | 説明 |
|---|---|---|
| `read_file` | READ | ファイル読み取り (行番号付き、offset / limit 対応) |
| `glob_search` | READ | Glob パターンでファイル検索 (更新日時順) |
| `grep_search` | READ | 正規表現でファイル内容検索 (Python `re` モジュール、クロスプラットフォーム) |
| `list_directory` | READ | ディレクトリ内容一覧 (ファイルサイズ付き) |
| `web_fetch` | READ | URL からコンテンツ取得 (HTML→テキスト変換) |
| `write_file` | WRITE | ファイル作成・上書き (親ディレクトリ自動作成) |
| `edit_file` | WRITE | 文字列置換による編集 (`replace_all` オプション) |
| `shell` | EXECUTE | シェルコマンド実行 (タイムアウト対応) |

## REPL コマンド

| コマンド | 説明 |
|---|---|
| `/help` | コマンド一覧を表示 |
| `/clear` | 会話履歴をクリア |
| `/context` | コンテキスト使用量 (トークン推定) を表示 |
| `/compact [n]` | 古いメッセージを要約して圧縮 (直近 n 件を保持, default: 6) |
| `/model [name]` | 現在のモデルを表示、または変更 |
| `/provider [name]` | 現在のプロバイダーを表示、または切り替え |
| `/reload` | TSUMUGI.md を再読み込み |
| `exit` / `/quit` | 終了 |

複数行入力: **Alt+Enter** で改行を挿入、**Enter** で送信。

## パーミッション

| レベル | 挙動 |
|---|---|
| **READ** | 自動許可 |
| **WRITE** | 実行前に確認プロンプト |
| **EXECUTE** | 実行前に確認プロンプト |

確認プロンプトでの入力:

| 入力 | 動作 |
|---|---|
| `y` | 今回のみ許可 |
| `n` | 拒否 |
| `a` | このツールをセッション内で常時許可 |
| `p` | 永続的に許可 (`~/.tsumugi/permissions.json` に保存) |

## TSUMUGI.md

カレントディレクトリから親を辿って `TSUMUGI.md` を探索し、見つかったものをすべてシステムプロンプトに結合する。Claude Code の `CLAUDE.md` と同じ仕組み。

```
~/projects/myapp/TSUMUGI.md   ← プロジェクト固有の指示 (後に結合 = 優先)
~/TSUMUGI.md                  ← グローバルな指示 (先に結合)
```

セッション中に編集した場合は `/reload` コマンドで再読み込み可能。

## MEMORY.md

プロジェクト別の永続メモリ機能。セッションを跨いで知見やパターンを蓄積できる。

- 保存場所: `~/.tsumugi/projects/<project-id>/memory/MEMORY.md`
- プロジェクト ID はカレントディレクトリのパスから自動生成される
- セッション開始時に自動で読み込まれ、システムプロンプトに含まれる
- エージェントが作業中に学んだことを書き込むことで、次回以降のセッションに活かせる

## プラグイン

`~/.tsumugi/plugins/` または `./tsumugi_plugins/` に Python ファイルを置くことで、カスタムツールを追加できる。

```python
# ~/.tsumugi/plugins/my_tool.py
from tsumugi.tools.base import BaseTool, PermissionLevel, ToolSpec

class MyTool(BaseTool):
    def spec(self):
        return ToolSpec(
            name="my_tool",
            description="Does something useful",
            parameters={"type": "object", "properties": {}, "required": []},
            permission=PermissionLevel.READ,
        )

    def execute(self, **kwargs):
        return "Hello from my plugin!"
```

## 設定リファレンス

### 優先順位

```
~/.tsumugi/config.json < 環境変数 < CLI引数
```

### 設定一覧

| 設定 | config.json | 環境変数 | CLI引数 | デフォルト |
|---|---|---|---|---|
| プロバイダー | `provider` | `TSUMUGI_PROVIDER` | `--provider` | `anthropic` |
| モデル | `anthropic_model` / `openai_model` | `TSUMUGI_MODEL` | `--model` | `claude-sonnet-4-20250514` |
| API キー | `anthropic_api_key` / `openai_api_key` | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | `--api-key` | (なし) |
| ベース URL | `openai_base_url` | `TSUMUGI_BASE_URL` | `--base-url` | (なし) |
| 最大トークン | `max_tokens` | `TSUMUGI_MAX_TOKENS` | `--max-tokens` | `8192` |
| ユーザー名 | `user_name` | `USER_NAME` | — | `user` |

### config.json の例

```json
{
  "provider": "anthropic",
  "user_name": "space",
  "anthropic_api_key": "sk-ant-...",
  "anthropic_model": "claude-sonnet-4-20250514",
  "openai_api_key": "sk-...",
  "openai_model": "gpt-4o",
  "openai_base_url": null,
  "max_tokens": 8192
}
```

設定ファイルのパス:
- **Windows**: `C:\Users\<username>\.tsumugi\config.json`
- **Linux / macOS**: `~/.tsumugi/config.json`

複数プロバイダーの API キーを同時に設定でき、セッション中に `/provider` コマンドで切り替え可能。

API キーは環境変数でも設定できる:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
```

## 開発

```bash
git clone https://github.com/space-musicacct/tsumugi.git
cd tsumugi
pip install -e ".[dev]"
pytest
```

## ライセンス

MIT
