Tama - AI-Powered Task Manager CLI ✨

Tama - AI 駆動のタスク管理コマンドラインツール ✨

英語

Tama は、タスク管理向けに設計されたコマンドラインインターフェイス（CLI）ツールです。AI 機能によってタスクの生成と分解を強化します。AI（特に、OpenAI 互換 API を通じて DeepSeek モデルを使用するよう設定されています）を利用して、製品要件ドキュメント（PRD）を解析し、複雑なタスクを管理しやすいサブタスクに分解します。

特長

• 標準的なタスク管理: 依存関係の追跡に対応し、タスクやサブタスクの追加、一覧表示、詳細表示、ステータスの更新、削除を行えます。
• データの永続化: SQLite データベースを使用してタスクデータを保存し、安定性と信頼性の高いデータ操作を実現します。
• 依存関係の管理: タスクの依存関係の追加、削除、追跡を行い、循環依存を自動検出します。
• AI 駆動の PRD 解析: (tama prd <ファイルパス>) .txt または .prd ファイルから構造化されたタスクリストを自動生成します。
• AI 駆動のタスク分解: (tama expand <タスクID>) AI を使用して、上位レベルのタスクを詳細なサブタスクに分解します。
• 依存関係のチェック: (tama deps) タスクの循環依存を検出して可視化します。
• レポートの生成: (tama report [markdown|mermaid]) Markdown テーブル形式のタスクレポート、または Mermaid 依存関係図を生成します。
• コードスタブの生成: (tama gen-file <タスクID>) タスクの詳細に基づいてプレースホルダーのコードファイルを作成します。
• 次のタスクの提案: (tama next) ステータスと依存関係に基づいて、次に実行可能なタスクを特定します。
• リッチな CLI 出力: rich ライブラリを使用し、テーブルやパネルなど、整形された見やすいコンソール出力を提供します。
• Git 統合: タスクの開始時と完了時に、ブランチとコミットを自動作成できます。
• ファイルの関連付け: ファイルをタスクにリンクして、タスクに関連するコードを簡単に追跡できます。

インストールとセットアップ

1. 仮想環境の作成と有効化（推奨バージョンは3.12）: uvのインストールと基本的な使い方については、uvのインストールと使い方を参照してください。

uv venv -p 3.12

# Windows
.\.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

2. tama-cli ライブラリのインストール: uv pip install --index-url https://pypi.org/simple/ tama-cli

設定 ⚙️

Tama の AI 機能を使用するには API キーが必要です。

1. プロジェクトのルートディレクトリに .env ファイルを作成します。 （サンプルファイルをそのままコピーできます）

cp .env.example .env
# Windows 下可用：
copy .env.example .env

2. DeepSeek API キーとその他の設定を追加します:

# .env 文件
# DeepSeek Configuration
DEEPSEEK_API_KEY=""
DEEPSEEK_BASE_URL="http://address:port/openai/v1" 
# Optional: Default is set in settings

# Model Names (confirm exact identifiers from DeepSeek docs)
DEEPSEEK_GENERAL_MODEL="deepseek-v3"
DEEPSEEK_REASONING_MODEL="deepseel-r1"

(テンプレートについては .env.example ファイルを参照してください) アプリケーションは src/config/settings.py で定義された設定を使用します。このファイルは .env ファイルから変数を読み込みます。

使い方 🚀

Tama コマンドは、有効化した仮想環境のターミナルで実行する必要があります。 主なコマンド:

• タスクの一覧表示:

tama list
tama list --status pending --priority high # 筛选

タスクリストには、ステータスと優先度を示す絵文字インジケーターが表示され、依存関係は見やすい Markdown テーブル形式で示されます。

• タスクの詳細表示:

tama show 1       # 显示任务 1
tama show 1.2     # 显示任务 1 的子任务 2

• タスク／サブタスクの追加:

# 添加顶级任务
tama add "实现用户认证" --desc "处理登录和会话" --priority high
# 为任务 1 添加子任务
tama add "创建登录 API 端点" --parent 1 --desc "需要处理 JWT"

• タスク／サブタスクの削除:

tama remove 2       # 移除任务 2 及其所有子任务
tama remove 1.3     # 移除任务 1 的子任务 3

タスクを削除すると、そのタスクに依存する他のすべてのタスクが自動的に更新され、影響を受ける依存関係が通知されます。

ワークフローコマンド:

• タスクのステータスを設定:

tama status 1 done
tama status 1.2 in-progress
# 级联更新子任务/依赖任务状态
tama status 1 done --propagate

(有効なステータス: pending, in-progress, done, deferred, blocked, review)

--propagate パラメーターの説明：

• --propagate は、ステータスの変更をすべてのサブタスクまたは依存タスクに連鎖させるかどうかを制御します。
• デフォルトの動作は設定ファイルで決まります（settings.PROPAGATE_STATUS_CHANGE）。
• --propagate を明示的に追加すると、今回の操作で連鎖更新を強制できます。

• タスクの開始: このコマンドはタスクのステータスを in-progress に設定し、Git ブランチを自動作成します。

tama start 1

• タスクの完了: このコマンドはタスクのステータスを done に設定します。--commit フラグを使用すると、ステージされた変更も自動的にコミットします。

tama complete 1
tama complete 1 --commit

• 次のタスクを検索:

tama next

依存関係コマンド:

• 依存関係の管理:

tama add-dep 1 2      # 设置任务 1 依赖于任务 2
tama add-dep 1.2 2.1  # 设置子任务 1.2 依赖于子任务 2.1
tama remove-dep 1 2   # 移除任务 1 对任务 2 的依赖

• 依存関係のチェック:

tama deps

AI コマンド:

• PRD の解析:（入力ファイルは .txt または .prd である必要があります）

tama prd path/to/your/document.txt

• タスクの分解:（親タスク ID を指定します）

tama expand 1

ファイル管理コマンド:

• プレースホルダーファイルの生成:

tama gen-file 1
tama gen-file 2 --output-dir src/generated

• ファイルの関連付け: 1 つ以上のファイルをタスクにリンクします。

tama link 1 src/main.py

• ファイルの関連付け解除: 1 つ以上のファイルのリンクをタスクから削除します。

tama unlink 1 src/main.py

• ファイルからタスクを検索: 指定したファイルに関連付けられているすべてのタスクを検索します。

tama find-task src/main.py

その他のコマンド:

• レポートの生成:

tama report markdown       # 在控制台打印 Markdown 表格
tama report mermaid       # 打印 Mermaid 图定义
tama report markdown --output report.md # 保存到文件

シェルの自動補完:

• 次のコマンドで、シェルの自動補完を設定する手順を確認できます:

tama --install-completion

(注意: シェルとオペレーティングシステムの設定によっては、管理者権限が必要になる場合があります)

開発 🔧

ソースコードを変更した場合は、CLI に変更を反映するため、パッケージを再インストールしてください:

uv pip install -e .

MCP サーバーの使い方

Tama は MCP（モデルコンテキストプロトコル）サーバーとして使用でき、他のアプリケーションからプログラムで操作できます。MCP サーバーは次のツールを提供します：

• list_tasks：すべてのタスクを一覧表示します。ステータスまたは優先度で絞り込み、Markdown テーブルを返します。
• show_task：ID に基づいて、指定したタスクまたはサブタスクの詳細を表示します。
• set_status：タスクまたはサブタスクのステータスを設定します。
• next_task：次に実行可能なタスクを検索します。
• add_task：新しい親タスクを追加します。
• add_subtask：親タスクにサブタスクを追加します。
• remove_item：タスクまたはサブタスクを削除し、依存関係を自動的に整理します。
• add_dependency：タスクまたはサブタスクに依存関係を追加します。
• remove_dependency：タスクまたはサブタスクの依存関係を削除します。
• check_dependencies：すべてのタスクで循環依存をチェックします。

サーバーを起動するには、次を実行します：

uv --directory /path/to/your/TAMA_MCP run python -m src.mcp_server

クライアント設定の例：

{
  "mcpServers": {
    "TAMA-MCP-Server": {
        "command": "uv",
        "args": [
            "--directory",
            "/path/to/your/TAMA_MCP",
            "run",
            "python",
            "-m",
            "src.mcp_server"
        ],
        "disabled": false,
        "transportType": "stdio",
        "timeout": 60
    },
  }
}

ライセンス

MIT ライセンス

本プロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。