Tama - AI-Powered Task Manager CLI

Tama - AI-Powered Task Manager CLI ✨

中文

Tama is a Command-Line Interface (CLI) tool designed for managing tasks, enhanced with AI capabilities for task generation and expansion. It utilizes AI (specifically configured for DeepSeek models via their OpenAI-compatible API) to parse Product Requirements Documents (PRDs) and break down complex tasks into manageable subtasks.

Features

• Standard Task Management: Add, list, show details, update status, and remove tasks and subtasks with dependency tracking.
• Dependency Management: Add, remove, and track task dependencies with automatic cycle detection.
• AI-Powered PRD Parsing: (tama prd <filepath>) Automatically generate a structured task list from a .txt or .prd file.
• AI-Powered Task Expansion: (tama expand <task_id>) Break down a high-level task into detailed subtasks using AI.
• Dependency Checking: (tama deps) Detect and visualize circular dependencies within your tasks.
• Reporting: (tama report [markdown|mermaid]) Generate task reports in Markdown table format or as a Mermaid dependency graph.
• Code Stub Generation: (tama gen-file <task_id>) Create placeholder code files based on task details.
• Next Task Suggestion: (tama next) Identify the next actionable task based on status and dependencies.
• Rich CLI Output: Uses rich for formatted and visually appealing console output (e.g., tables, panels).

Installation & Setup

1. Clone the Repository:

git clone https://github.com/Gitreceiver/TAMA-MCP.git
cd TAMA-MCP

2. Create and Activate Virtual Environment（Recommend python 3.12）:

uv install and usage

uv venv -p 3.12

# Windows
.\.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

3. Install Dependencies & Project: (Requires uv - install with pip install uv if you don't have it)

   uv pip install -e .
   

(Alternatively, if you use conda ,using pip: pip install -e .)

Configuration ⚙️

Tama requires API keys for its AI features.

1. Create a .env file in the project root directory. (You can copy the example file:)

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

2. Add your DeepSeek API key:

# .env file
DEEPSEEK_API_KEY="your_deepseek_api_key_here"

(See .env.example for a template)

The application uses settings defined in src/config/settings.py, which loads variables from the .env file.

Usage 🚀

Tama commands are run from your terminal within the activated virtual environment. Core Commands:

• List Tasks:

tama list
tama list --status pending --priority high # Filter

The task list now includes emoji indicators for status and priority, and displays dependencies in a clear markdown table format.

• Show Task Details:

tama show 1      # Show task 1
tama show 1.2    # Show subtask 2 of task 1

• Add Task/Subtask:

# Add a top-level task
tama add "Implement user authentication" --desc "Handle login and sessions" --priority high

# Add a subtask to task 1
tama add "Create login API endpoint" --parent 1 --desc "Needs JWT handling"

• Set Task Status:

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

(Valid statuses: pending, in-progress, done, deferred, blocked, review)

--propagate 参数说明：

• --propagate 控制是否将状态变更级联到所有子任务或依赖任务。
• 默认行为由配置文件决定（settings.PROPAGATE_STATUS_CHANGE）。
• 显式添加 --propagate 可强制本次操作级联更新。

• Remove Task/Subtask:

tama remove 2       # Remove task 2 and all its subtasks
tama remove 1.3     # Remove subtask 3 of task 1

When removing a task, all dependent tasks will be automatically updated, and you'll be notified of any affected dependencies.

• Manage Dependencies:

tama add-dep 1 2      # Make task 1 depend on task 2
tama add-dep 1.2 2.1  # Make subtask 1.2 depend on subtask 2.1
tama rm-dep 1 2       # Remove dependency of task 1 on task 2

• Find Next Task:

tama next

AI Commands:

• Parse PRD: (Input file must be .txt or .prd)

tama prd path/to/your/document.txt

• Expand Task: (Provide a main task ID)

tama expand 1

Utility Commands:

• Check Dependencies:

tama deps

• Generate Report:

tama report markdown      # Print markdown table to console
tama report mermaid       # Print mermaid graph definition
tama report markdown --output report.md # Save to file

• Generate Placeholder File:

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

Shell Completion:

• Instructions for setting up shell completion can be obtained via:

tama --install-completion

(Note: This might require administrator privileges depending on your shell and OS settings)

Development 🔧

If you modify the source code, remember to reinstall the package to make the changes effective in the CLI:

uv pip install -e .

MCP Server Usage

Tama can be used as an MCP (Model Context Protocol) server, allowing other applications to interact with it programmatically. The MCP server provides the following tools:

• list_tasks: List all tasks with optional status/priority filters in markdown format
• show_task: Display detailed information about a specific task
• set_status: Update task status with automatic propagation
• next_task: Find the next actionable task
• add_task: Create a new main task
• add_subtask: Create a new subtask
• remove_item: Remove a task or subtask with dependency cleanup
• add_dependency: Add a dependency between tasks
• remove_dependency: Remove a dependency between tasks
• check_dependencies: Check for circular dependencies

To start the server:

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

in your mcp client: (cline,cursor,claude)

{
  "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
    },
  }
}

This will start the Tama MCP server, which provides the following tools

•   get_task: Finds and returns a task or subtask by its ID.
•   find_next_task: Finds the next available task to work on.
•   set_task_status: Sets the status for a task or subtask.
•   add_task: Adds a new main task.
•   add_subtask: Adds a new subtask.
•   remove_item: Removes a subtask or a main task.
• add_dependency: Add a dependency between tasks
• remove_dependency: Remove a dependency between tasks
•   get_tasks_table_report: Generates a Markdown table representing the task structure.

License

MIT License This project is licensed under the MIT License. See the LICENSE file for details.

=======

TAMA-MCP

AI-Powered Task Manager CLI with MCP Server

Contact me by wechat: