docs: consolidate Claude Code documentation and fix confusion

Fixes #1550 This PR addresses the documentation chaos reported in issue #1550 by: 1. Creating a comprehensive Claude Code setup guide at apps/docs/integrations/claude-code.mdx that: - Clearly explains all 3 integration options (MCP Server, Plugin, Provider) - Includes a comparison table to help users choose the right option - Clarifies the naming confusion between task-master-ai (MCP package) and task-master (CLI) - Provides comprehensive troubleshooting for common issues 2. Simplifying README.md: - Consolidated duplicate Claude Code installation sections - Added prominent links to the comprehensive guide - Reduced confusion by pointing to single source of truth 3. Updating documentation navigation: - Added new 'Integrations' section to docs.json - Made Claude Code guide easily discoverable 4. Deprecating redundant documentation: - Added deprecation notices to docs/claude-code-integration.md - Added deprecation notices to docs/examples/claude-code-usage.md - Both files now point to the new consolidated guide 5. Adding context to existing files: - Explained CLAUDE.md auto-load purpose - Clarified CLAUDE_CODE_PLUGIN.md is for plugin users - Added setup guide link to TM_COMMANDS_GUIDE.md This creates a single landing page (docs.task-master.dev/integrations/claude-code) that new users can reference, eliminating the confusion from multiple installation methods scattered across 5+ different files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Ralph Khreish <Crunchyman-ralph@users.noreply.github.com>
2026-01-29 22:02:04 +00:00 · 2026-01-02 11:57:26 +00:00
parent 8d4ac0b646
commit 78115616ae
8 changed files with 300 additions and 22 deletions
--- a/.claude/TM_COMMANDS_GUIDE.md
+++ b/.claude/TM_COMMANDS_GUIDE.md
@@ -1,5 +1,9 @@
 # Task Master Commands for Claude Code

+> 📖 **New to Claude Code + Task Master?** See the [Complete Claude Code Setup Guide](https://docs.task-master.dev/integrations/claude-code) for installation options.
+
+This guide is specifically for users who have installed the **Task Master plugin** and want to use slash commands.
+
 Complete guide to using Task Master through Claude Code's slash commands.

 ## Overview
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,5 +1,9 @@
 # Claude Code Instructions

+> **What is this file?** This file is auto-loaded by Claude Code to provide context about this project's development guidelines.
+>
+> 📖 **Setting up Claude Code + Task Master?** See the [Complete Setup Guide](https://docs.task-master.dev/integrations/claude-code)
+
 ## Task Master AI Instructions

 **Import Task Master's development workflow commands and guidelines, treat as if import is in the main CLAUDE.md file.**
--- a/CLAUDE_CODE_PLUGIN.md
+++ b/CLAUDE_CODE_PLUGIN.md
@@ -1,6 +1,8 @@
-# Taskmaster AI - Claude Code Marketplace
+# Taskmaster AI - Claude Code Plugin Marketplace

-This repository includes a Claude Code plugin marketplace in `.claude-plugin/marketplace.json`.
+> 📖 **Looking for Claude Code setup?** See the [Complete Claude Code Setup Guide](https://docs.task-master.dev/integrations/claude-code) for all integration options (MCP, Plugin, Provider).
+
+This document is specifically for **plugin marketplace** installation. The repository includes a Claude Code plugin marketplace in `.claude-plugin/marketplace.json`.

 ## Installation

--- a/README.md
+++ b/README.md
@@ -60,17 +60,18 @@ The following documentation is also available in the `docs` directory:

 > **Note:** After clicking the link, you'll still need to add your API keys to the configuration. The link installs the MCP server with placeholder keys that you'll need to replace with your actual API keys.

-#### Claude Code Quick Install
+#### Claude Code Setup

-For Claude Code users:
+For Claude Code users, we offer multiple integration options:

 ```bash
+# Quick MCP install
 claude mcp add taskmaster-ai -- npx -y task-master-ai
 ```

-Don't forget to add your API keys to the configuration:
- in the root .env of your Project
- in the "env" section of your mcp config for taskmaster-ai
+📖 **[Complete Claude Code Setup Guide](https://docs.task-master.dev/integrations/claude-code)** - Learn about MCP server, plugin marketplace, and Claude Code provider options.
+
+> **Note:** `task-master-ai` is the MCP server package name. The CLI command is `task-master`.


 ## Requirements
@@ -320,20 +321,15 @@ Add `TASK_MASTER_TOOLS` to your MCP configuration file's `env` section:
 }
 ```

-#### Method 2: Claude Code CLI (One-Time Setup)
+#### Method 2: Claude Code CLI

-For Claude Code users, you can set the mode during installation:
+For Claude Code users, you can set the mode during installation. See the [Complete Claude Code Setup Guide](https://docs.task-master.dev/integrations/claude-code) for details.

 ```bash
 # Core mode example (~70% token reduction)
 claude mcp add task-master-ai --scope user \
  --env TASK_MASTER_TOOLS="core" \
  -- npx -y task-master-ai@latest
-
-# Custom tools example
-claude mcp add task-master-ai --scope user \
-  --env TASK_MASTER_TOOLS="get_tasks,next_task,set_task_status" \
-  -- npx -y task-master-ai@latest
 ```

 ### Tool Sets Details
@@ -353,13 +349,13 @@ claude mcp add task-master-ai --scope user \

 ## Claude Code Support

-Task Master now supports Claude models through the Claude Code CLI, which requires no API key:
+Task Master offers comprehensive Claude Code integration:

- **Models**: `claude-code/opus` and `claude-code/sonnet`
- **Requirements**: Claude Code CLI installed
- **Benefits**: No API key needed, uses your local Claude instance
+- **MCP Server**: Natural language task management in chat
+- **Plugin**: 49 slash commands for quick workflows
+- **Provider**: Use Claude Code models (no API key required)

-[Learn more about Claude Code setup](docs/examples/claude-code-usage.md)
+📖 **[Complete Claude Code Setup Guide](https://docs.task-master.dev/integrations/claude-code)** - Choose the best option for your workflow.

 ## Troubleshooting

--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -53,6 +53,10 @@
 							"capabilities/task-structure"
 						]
 					},
+					{
+						"group": "Integrations",
+						"pages": ["integrations/claude-code"]
+					},
 					{
 						"group": "AI Providers",
 						"pages": ["providers/azure"]
--- a/apps/docs/integrations/claude-code.mdx
+++ b/apps/docs/integrations/claude-code.mdx
@@ -0,0 +1,254 @@
+---
+title: Claude Code Setup
+sidebarTitle: "Claude Code"
+description: "Complete guide to using Task Master with Claude Code"
+---
+
+# Claude Code Integration
+
+Task Master works seamlessly with Claude Code through multiple integration methods. This guide consolidates all Claude Code setup options in one place.
+
+## Understanding the Options
+
+Task Master offers **three ways** to integrate with Claude Code:
+
+1. **MCP Server** (Recommended) - Use `task-master-ai` MCP server for AI-powered task management
+2. **Plugin Marketplace** - Install Task Master plugin with slash commands
+3. **Claude Code Provider** - Use Claude Code's local models (no API key needed)
+
+<Note>
+**Package naming clarity:**
+- `task-master-ai` = The MCP server package (what you install via `npx`)
+- `task-master` = The CLI command (what you run in terminal)
+- These are the same package, just different names for different contexts
+</Note>
+
+---
+
+## Option 1: MCP Server (Recommended)
+
+The MCP server lets Claude Code directly manage your tasks through natural language.
+
+### Quick Install
+
+```bash
+claude mcp add taskmaster-ai -- npx -y task-master-ai
+```
+
+### What You Get
+
+- Direct task management from Claude Code chat
+- AI-powered PRD parsing, task expansion, and complexity analysis
+- Natural language task queries and updates
+- 7-44 MCP tools (configurable)
+
+### Configuration
+
+After installation, add your API keys to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "task-master-ai": {
+      "command": "npx",
+      "args": ["-y", "task-master-ai"],
+      "env": {
+        "TASK_MASTER_TOOLS": "core",  // Options: "core", "standard", "all"
+        "ANTHROPIC_API_KEY": "YOUR_KEY_HERE",
+        "PERPLEXITY_API_KEY": "YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### Tool Loading Modes
+
+Control which tools are loaded to optimize context usage:
+
+| Mode | Tools | Use Case |
+|------|-------|----------|
+| `core` | 7 | Daily development workflow |
+| `standard` | 15 | Common task management |
+| `all` | 44+ | Full feature set |
+
+See the [MCP Tools documentation](/capabilities/mcp#configurable-tool-loading) for details.
+
+### Usage Examples
+
+Once configured, interact with Task Master naturally in Claude Code:
+
+```
+You: Parse my PRD at .taskmaster/docs/prd.md
+You: What's the next task I should work on?
+You: Show me task 1.2 details
+You: Mark task 1.2 as done
+You: Expand task 3 into subtasks
+```
+
+---
+
+## Option 2: Plugin Marketplace
+
+The plugin provides 49 slash commands and 3 specialized AI agents for comprehensive task management.
+
+### Installation
+
+```bash
+# Add the marketplace
+/plugin marketplace add eyaltoledano/claude-task-master
+
+# Install the plugin
+/plugin install taskmaster@taskmaster
+```
+
+### What You Get
+
+- 49 slash commands organized by category
+- Quick commands like `/tm:next`, `/tm:list`, `/tm:show`
+- Setup commands like `/tm:init`, `/tm:parse-prd`
+- Workflow automation with `/tm:workflows/*`
+
+### Quick Start Commands
+
+```bash
+/tm:init                    # Initialize project
+/tm:parse-prd              # Parse requirements
+/tm:next                   # Get next task
+/tm:set-status/to-done 1.2 # Mark task complete
+```
+
+See [Plugin Documentation](https://github.com/eyaltoledano/claude-task-master/blob/main/CLAUDE_CODE_PLUGIN.md) for the complete command list.
+
+---
+
+## Option 3: Claude Code Provider
+
+Use Claude Code's local models for Task Master AI operations (no API key required).
+
+### Setup
+
+1. Install and authenticate Claude Code CLI:
+```bash
+claude setup-token
+```
+
+2. Configure Task Master to use Claude Code:
+```bash
+task-master models --set-main claude-code/sonnet
+```
+
+Or update `.taskmaster/config.json`:
+
+```json
+{
+  "models": {
+    "main": "claude-code/sonnet",
+    "fallback": "claude-code/opus"
+  }
+}
+```
+
+### Available Models
+
+- `claude-code/sonnet` - Claude 3.5 Sonnet
+- `claude-code/opus` - Claude 3 Opus
+
+### Benefits
+
+- No API key required (uses your Claude Code authentication)
+- Native structured outputs with schema compliance
+- Works with all Task Master AI-powered commands
+
+### Usage
+
+Once configured, all Task Master commands automatically use Claude Code:
+
+```bash
+task-master parse-prd .taskmaster/docs/prd.md
+task-master expand --id=1 --research
+task-master analyze-complexity
+```
+
+See [Claude Code Provider docs](/providers/claude-code) for advanced configuration.
+
+---
+
+## Comparison: Which Option Should I Use?
+
+| Feature | MCP Server | Plugin | Provider |
+|---------|------------|--------|----------|
+| **Natural language in chat** | ✅ Yes | Limited | ❌ No |
+| **Slash commands** | ❌ No | ✅ 49 commands | ❌ No |
+| **No API key needed** | ❌ Requires API key | ❌ Requires API key | ✅ Yes |
+| **AI-powered operations** | ✅ Yes | ✅ Yes | ✅ Yes |
+| **Context optimization** | ✅ Configurable | ✅ Built-in | N/A |
+| **Best for** | Chat-first workflow | Command-first workflow | Cost-conscious users |
+
+<Tip>
+**Recommended Setup:** Use **MCP Server + Claude Code Provider** together:
+- MCP Server for natural language task management in chat
+- Claude Code Provider to eliminate API key costs
+- Best of both worlds!
+</Tip>
+
+---
+
+## Troubleshooting
+
+### "0 tools enabled" in MCP settings
+
+**Solution:** Restart your editor and verify API keys are correctly configured in `.mcp.json`.
+
+### Confusion between task-master-ai and task-master
+
+- `task-master-ai` is the **MCP server package name** (used in npx commands)
+- `task-master` is the **CLI command name** (used in terminal)
+- They're the same package, just different contexts
+
+### Claude Code authentication failures
+
+```bash
+# Re-authenticate
+claude setup-token
+
+# Verify token
+claude setup-token --verify
+```
+
+### Plugin not appearing
+
+```bash
+# Update marketplace
+/plugin marketplace update taskmaster
+
+# Reinstall
+/plugin install taskmaster@taskmaster
+```
+
+---
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Quick Start Guide" icon="rocket" href="/getting-started/quick-start/quick-start">
+    Get started with Task Master in minutes
+  </Card>
+  <Card title="MCP Tools Reference" icon="toolbox" href="/capabilities/mcp">
+    Complete MCP tools documentation
+  </Card>
+  <Card title="Command Reference" icon="terminal" href="/command-reference">
+    All CLI commands
+  </Card>
+  <Card title="Configuration" icon="gear" href="/configuration">
+    Customize Task Master
+  </Card>
+</CardGroup>
+
+---
+
+## Additional Resources
+
+- [Claude Code CLI Documentation](https://docs.anthropic.com/en/docs/claude-code)
+- [Task Master Discord Community](https://discord.gg/taskmasterai)
+- [GitHub Issues](https://github.com/eyaltoledano/claude-task-master/issues)
--- a/docs/claude-code-integration.md
+++ b/docs/claude-code-integration.md
@@ -1,6 +1,12 @@
-# TODO: Move to apps/docs inside our documentation website
+# ⚠️ DEPRECATED

-# Claude Code Integration Guide
+**This documentation has been moved and consolidated.**
+
+📖 **See the new comprehensive guide:** https://docs.task-master.dev/integrations/claude-code
+
+---
+
+# Claude Code Integration Guide (Legacy)

 This guide covers how to use Task Master with Claude Code AI SDK integration for enhanced AI-powered development workflows.

--- a/docs/examples/claude-code-usage.md
+++ b/docs/examples/claude-code-usage.md
@@ -1,4 +1,12 @@
-# Claude Code Provider Usage Example
+# ⚠️ DEPRECATED
+
+**This documentation has been moved and consolidated.**
+
+📖 **See the new comprehensive guide:** https://docs.task-master.dev/integrations/claude-code
+
+---
+
+# Claude Code Provider Usage Example (Legacy)

 The Claude Code provider allows you to use Claude models through the Claude Code CLI without requiring an API key.