tsumugi-agent 0.3.0

Tsumugi AI Agent — Claude Code-like coding assistant

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 — プロジェクト別の永続メモリ。セッションを跨いで知見を蓄積
• プランモード — /plan で READ のみ実行可能なモードに切替。コード調査と実装計画の設計に集中できる
• ペルソナ搭載 — 組み込みペルソナ「つむぎ」が会話をサポート
• プラグイン — カスタムツールを Python ファイルで追加可能
• クロスプラットフォーム — Windows / Linux / macOS で動作。Python 3.10+

インストール

pip install tsumugi-agent

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

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

クイックスタート

1. 設定ファイルを作成

~/.tsumugi/config.json:

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

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

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

2. 起動

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]	現在のモデルを表示、または変更
/plan [on|off]	プランモードの切り替え (READ のみ実行、WRITE/EXECUTE はシミュレーション)
/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 ファイルを置くことで、カスタムツールを追加できる。

# ~/.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 の例

{
  "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 キーは環境変数でも設定できる:

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

開発

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

ライセンス

MIT