tsumugi-agent 0.1.0

Tsumugi AI Agent — Claude Code-like coding assistant

Tsumugi — AI Agent (2026/02/25 開始)

Claude Code ライクな AI コーディングエージェント。Python 製。 Anthropic / OpenAI互換API (GPT, Ollama, Gemini 等) に対応し、Windows (ローカル) と Ubuntu (VPS) の両環境で動作する。

ペルソナ「つむぎ」を組み込みで搭載。TSUMUGI.md によるプロジェクト固有の指示にも対応。

1. アーキテクチャ概要

ユーザー入力 → LLM ストリーミング呼び出し
  ├→ テキスト応答 → 表示して終了
  └→ ツール呼び出し → パーミッションチェック → 実行 → 結果を LLM にフィード → ループ先頭へ

技術スタック

コンポーネント	技術
言語	Python 3.10+ (3.10 / 3.11 / 3.12 / 3.13)
LLM	Anthropic Claude / OpenAI互換 (GPT, Ollama, Gemini)
UI	Rich (表示) + prompt_toolkit (入力・履歴)
ツール実行	subprocess (shell) / pathlib (ファイル操作) / re (grep)

依存パッケージ

パッケージ	用途
anthropic	Anthropic API SDK
openai	OpenAI互換 API SDK
rich	ターミナル表示 (Markdown, Panel, シンタックスハイライト)
prompt_toolkit	入力 (履歴, 補完, 複数行)

2. ディレクトリ構成

Tsumugi/
├── pyproject.toml          # パッケージ定義・依存・エントリポイント
├── .gitignore
├── README.md
├── CLAUDE.md               # Claude Code 用指示書 (.gitignore 済み)
└── src/tsumugi/
    ├── __init__.py          # パッケージ定義
    ├── __main__.py          # python -m tsumugi エントリポイント
    ├── cli.py               # REPL メインループ + コマンドハンドラ
    ├── agent.py             # エージェントループ (ツール実行・リトライ含む)
    ├── config.py            # 設定ローダー (config.json / env / TSUMUGI.md)
    ├── context.py           # コンテキスト管理 (トークン推定・会話圧縮)
    ├── permissions.py       # パーミッションシステム (READ / WRITE / EXECUTE)
    ├── persona.py           # デフォルトペルソナ + システムプロンプト構築
    ├── plugins.py           # プラグインシステム (外部ツールの動的読み込み)
    ├── providers/
    │   ├── base.py          # 抽象基底クラス + 統一データ型
    │   ├── anthropic.py     # Anthropic プロバイダー (ストリーミング)
    │   └── openai_compat.py # OpenAI互換プロバイダー (GPT / Ollama / Gemini)
    ├── tools/
    │   ├── __init__.py      # ToolRegistry + create_default_registry()
    │   ├── base.py          # BaseTool / PermissionLevel / ToolSpec
    │   ├── read_file.py     # ファイル読み取り
    │   ├── write_file.py    # ファイル作成・上書き
    │   ├── edit_file.py     # 文字列置換による編集
    │   ├── shell.py         # シェルコマンド実行
    │   ├── glob_search.py   # Glob パターンでファイル検索
    │   ├── grep_search.py   # 正規表現でファイル内容検索
    │   ├── list_directory.py # ディレクトリ内容一覧
    │   └── web_fetch.py     # URL からコンテンツ取得
    └── ui/
        ├── display.py       # Rich ベースの表示 (レインボーロゴ等)
        └── prompt.py        # prompt_toolkit ベースの入力

3. セットアップ

前提条件

• Python 3.10 以上 (3.10 / 3.11 / 3.12 / 3.13 で動作)
• pip

Python と pip さえあれば動作するため、Windows / Linux / macOS / Docker コンテナ等、環境を問わない。

3-1. インストール

# 開発モード (推奨)
pip install -e .

# または直接インストール
pip install .

3-2. API キーの設定

方法A: 設定ファイル (推奨)

~/.tsumugi/config.json を作成:

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

設定ファイルのパス:

• Windows: C:\Users\<username>\.tsumugi\config.json
• Linux / macOS: ~/.tsumugi/config.json

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

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

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

方法B: 環境変数

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export OPENAI_API_KEY=sk-...

方法C: CLI 引数

tsumugi --api-key sk-ant-...

4. 使い方

4-1. 起動

# デフォルト (Anthropic Claude)
tsumugi

# python -m でも起動可能
python -m tsumugi

4-2. 対応プロバイダー

サービス	起動コマンド	備考
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) の対応状況はサービスによって異なる。会話のみであれば基本的にどれでも動作する。

4-3. REPL コマンド

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

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

4-4. 終了

REPL 内で exit / quit / /quit / Ctrl+D のいずれか。

5. ツール

ツール	権限	説明
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	シェルコマンド実行 (タイムアウト対応)

パーミッション

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

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

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

プラグイン

~/.tsumugi/plugins/ または ./tsumugi_plugins/ に 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!"

6. TSUMUGI.md (プロジェクト指示)

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

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

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

7. 設定

設定ファイル

~/.tsumugi/config.json:

{
  "provider": "anthropic",
  "user_name": "space",
  "max_tokens": 8192,

  "anthropic_api_key": "sk-ant-...",
  "anthropic_model": "claude-sonnet-4-20250514",

  "openai_api_key": "sk-...",
  "openai_model": "gpt-4o",
  "openai_base_url": null
}

Ollama や Gemini を使う場合は openai_base_url を設定:

{
  "provider": "openai",
  "openai_api_key": "ollama",
  "openai_model": "llama3.1",
  "openai_base_url": "http://localhost:11434/v1"
}

優先順位

~/.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	OPENAI_BASE_URL	--base-url	(なし)
最大トークン	max_tokens	TSUMUGI_MAX_TOKENS	--max-tokens	8192
ユーザー名	user_name	USER_NAME	-	user

8. 設計方針

方針	説明
Anthropic 寄りの内部フォーマット	メインターゲットが Claude のため、内部メッセージ形式を Anthropic API に合わせて変換コストを最小化
プロバイダー抽象化	ProviderBase ABC で Anthropic / OpenAI の差異を吸収。新プロバイダーの追加が容易
クロスプラットフォーム	grep_search は Python re で実装 (ripgrep 不要)。Windows / Ubuntu 両対応
最小依存	外部依存は 5 パッケージのみ。pip だけで完結
プラグイン拡張	~/.tsumugi/plugins/ に Python ファイルを置くだけでツール追加可能

9. 経緯

日付	出来事
2026/02/25	プロジェクト開始。Day 1+2 実装完了 (コア全体 + ツール 6 種 + OpenAI互換)
2026/02/26	Phase 1-9, 11 実装 (エラーハンドリング, UI改善, コンテキスト管理, REPLコマンド, ツール追加, プラグイン, 外部プロバイダー対応)

10. ライセンス

MIT