Agent Teams - Claude Code session team orchestration

• कई Claude Code instances को एक टीम के रूप में बनाकर parallel में काम बाँटने और समन्वय करने वाली experimental सुविधा, जिसमें lead session teammates बनाता है, काम असाइन करता है और नतीजों को संकलित करता है
• मौजूदा subagents से अलग, teammates एक-दूसरे को सीधे message भेज सकते हैं, और user भी lead के बिना किसी individual teammate से सीधे बात कर सकता है
• code review, debugging hypotheses की parallel जाँच, और frontend·backend·test जैसी cross-layer tasks में प्रभावी, जबकि sequential tasks या एक ही file में बदलाव के लिए single session अधिक उपयुक्त है
• हर teammate के पास independent context window होने से token usage काफ़ी बढ़ जाता है, और teammates की संख्या के अनुपात में cost बढ़ सकती है
• tmux या iTerm2 के जरिए split-screen mode को support करता है, और parallel exploration व collaboration automation के माध्यम से complex development tasks की productivity और quality सुधारने में मदद करता है

---

Agent Teams का अवलोकन

• कई Claude Code sessions को एक team unit के रूप में समन्वित करके parallel में काम करवाता है
  • team lead tasks distribute करता है और results compile करता है
  • हर teammate independent context window में अलग-अलग चलता है
• Subagent से अलग, teammates के बीच direct messaging संभव है
• यह एक experimental feature है और default रूप से disabled रहता है; CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable सेट करके इसे enable किया जा सकता है

Agent Teams कब उपयोगी हैं

• research और review: कई teammates समस्या के अलग-अलग पहलुओं की एक साथ जाँच करते हैं, फिर results share और cross-check करते हैं
• नए module या feature development: हर teammate अलग file/module संभालकर बिना conflict के parallel में काम कर सकता है
• competing hypothesis debugging: अलग-अलग hypotheses को एक साथ test करके root cause जल्दी खोजा जा सकता है
• cross-layer coordination: frontend, backend, test जैसी layers के हिसाब से teammates बाँटकर एक साथ बदलाव किए जा सकते हैं
• sequential tasks, एक ही file का editing, या high-dependency work के लिए single session या subagents अधिक efficient हैं

Subagent vs. Agent Team

• subagent: अपना context window रखता है, लेकिन result केवल caller को लौटाता है; main agent पूरा काम manage करता है, और token cost अपेक्षाकृत कम रहती है
• agent team: पूरी तरह independent context window, teammates के बीच direct messages संभव, shared task list के जरिए self-coordination, और हर teammate अलग Claude instance होने से token cost ज़्यादा
• जहाँ केवल result चाहिए वहाँ subagent बेहतर है, जबकि teammates के बीच discussion और collaboration वाली complex tasks के लिए agent team अधिक उपयुक्त है

पहली agent team शुरू करना

• default रूप से यह disabled रहता है; CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable को 1 पर सेट करके या settings.json में यह environment variable जोड़कर इसे enable करें
• enable करने के बाद natural language में team structure और task समझाएँ; Claude team बनाएगा, teammates spawn करेगा, और काम का समन्वय करेगा
  • > I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.
  • TODO tracking के लिए CLI tool डिज़ाइन करते समय UX, technical architecture, और विरोधी दृष्टिकोण की भूमिका वाले तीन teammates से अलग-अलग जाँच करवाकर फिर results compile करना
  • ऐसा करने पर Claude shared task list बनाकर teammates तैयार करेगा, हर मुद्दे की जाँच करेगा, results compile करेगा, और काम पूरा होने पर team clean up करने की कोशिश करेगा
• lead terminal पर पूरी teammate list और task status दिखती है, और Shift+Up/Down से teammate चुनकर सीधे message भेजा जा सकता है

Agent team control

• display mode चुनना

  • In-process mode: सभी teammates main terminal के भीतर चलते हैं; Shift+Up/Down से teammate चुनकर message भेज सकते हैं; अलग setup की ज़रूरत नहीं
  • Split panes mode: हर teammate अलग pane में दिखता है; output एक साथ देखा जा सकता है; tmux या iTerm2 आवश्यक है
  • default "auto" tmux session के भीतर चलने पर split pane और अन्यथा in-process mode चुनता है
  • "tmux" setting split-pane mode activate करती है और tmux व iTerm2 को auto-detect करती है
  • settings.json में teammateMode से override किया जा सकता है, या claude --teammate-mode in-process flag से single-session mode चुना जा सकता है

• teammates और model तय करना

  • Claude task के हिसाब से teammates की संख्या अपने-आप तय कर सकता है, लेकिन "Create a team with 4 teammates" जैसे command से exact count और model (जैसे Sonnet) manually specify किया जा सकता है

• plan approval की आवश्यकता

  • complex या risky tasks में teammates पर read-only plan mode लागू किया जा सकता है, ताकि lead की approval तक implementation रुका रहे
  • teammate plan पूरा होने पर lead से approval माँगता है; lead approve करे तो implementation शुरू होती है, reject करे तो feedback लेकर फिर submit किया जाता है
  • lead के decision criteria prompt में शर्तें देकर प्रभावित किए जा सकते हैं, जैसे "Approve only plans that include test coverage"

• delegate mode

  • lead खुद implementation करने के बजाय केवल coordination tools (teammate spawn, message, terminate, task management) तक सीमित रह सकता है
  • team शुरू करने के बाद Shift+Tab दबाकर delegate mode में जाएँ

• teammates से direct conversation

  • हर teammate पूरी तरह independent Claude Code session है, इसलिए अतिरिक्त निर्देश, follow-up सवाल, या approach change सीधे भेजे जा सकते हैं
  • in-process mode में Shift+Up/Down से select करके message भेजें, Enter से session देखें, Escape से current turn रोकें, और Ctrl+T से task list toggle करें
  • split-pane mode में संबंधित pane पर click करके सीधे interact करें

• task assignment और claim

  • shared task list के जरिए पूरी team का काम समन्वित होता है, और task state तीन चरणों में रहती है: pending, in progress, completed
  • tasks के बीच dependencies सेट की जा सकती हैं; unresolved dependency होने पर task claim नहीं किया जा सकता
  • lead explicit task assign कर सकता है, या teammate एक task पूरा करने के बाद अगला unassigned और unblocked task auto-claim कर सकता है
  • एक ही task को कई teammates द्वारा एक साथ claim करने से रोकने के लिए file locking इस्तेमाल होती है

• teammate termination और team cleanup

  • lead किसी specific teammate को terminate करने का अनुरोध कर सकता है; teammate इसे approve या reject कर सकता है और reason भी बता सकता है
  • team cleanup के समय lead shared team resources हटाता है; अगर active teammates बचे हों तो cleanup fail होगा, इसलिए पहले उन्हें terminate करना ज़रूरी है

Agent teams अंदर से कैसे काम करती हैं

• team शुरू होने के रास्ते

  • user team request करता है: parallel work के लिए उपयुक्त task समझाकर स्पष्ट रूप से agent team creation माँगता है
  • Claude team suggest करता है: Claude अगर समझे कि task parallel processing से बेहतर होगी, तो वह team creation suggest करता है; user confirmation के बाद आगे बढ़ता है
  • दोनों ही मामलों में user approval के बिना team नहीं बनती

• architecture components

  • Team lead: main Claude Code session, जो team creation, teammate spawn और task coordination संभालता है
  • Teammates: अलग Claude Code instances, जो assigned tasks पर काम करते हैं
  • Task list: shared task items list जिसे teammates claim और complete करते हैं
  • Mailbox: agents के बीच communication के लिए messaging system
  • task dependencies auto-manage होती हैं; एक teammate के task complete करते ही blocked tasks बिना manual intervention के unblock हो जाते हैं
  • team config ~/.claude/teams/{team-name}/config.json में और task list ~/.claude/tasks/{team-name}/ में locally store होती है
  • config में members array शामिल होती है, जिसमें हर teammate का नाम, agent ID, और agent type दर्ज होता है

• permissions

  • teammates lead की permission settings inherit करके शुरू होते हैं; अगर lead --dangerously-skip-permissions के साथ चला हो तो वही सब teammates पर भी लागू होगा
  • spawn के बाद individual teammate का mode बदला जा सकता है, लेकिन spawn समय per-teammate permission settings संभव नहीं हैं

• context और communication

  • हर teammate का independent context window होता है, और spawn के समय CLAUDE.md, MCP server, skills आदि सहित सामान्य session जैसा project context load होता है
  • lead की conversation history teammates को नहीं भेजी जाती; केवल spawn prompt भेजा जाता है
  • automatic message delivery: teammate द्वारा भेजे गए messages recipient तक automatically पहुँचते हैं; lead को polling नहीं करनी पड़ती
  • idle notification: teammate काम पूरा करके रुक जाए तो lead को auto-notify किया जाता है
  • shared task list: सभी agents task status देख सकते हैं और available tasks claim कर सकते हैं
  • messaging के लिए message (एक specific teammate को) और broadcast (पूरी team को; cost team size के अनुपात में बढ़ती है, इसलिए संयम से उपयोग करें) उपलब्ध हैं

• token usage

  • single session की तुलना में agent teams में token usage काफ़ी बढ़ती है, और active teammates की संख्या के अनुपात में बढ़ती जाती है
  • research, review, और नए features पर यह अतिरिक्त token cost आम तौर पर उचित है, लेकिन routine tasks में single session अधिक cost-efficient रहता है

उपयोग के मामले

• parallel code review

  • एक single reviewer अक्सर एक समय में केवल एक तरह की issue पर ध्यान देता है, इसलिए review criteria को security, performance, test coverage जैसे independent domains में बाँटना उपयोगी है
  • हर reviewer उसी PR पर अलग filter लागू करता है, और lead अंत में पूरे results compile करता है

• competing hypothesis investigation

  • single agent को एक explanation मिलते ही वह आगे की खोज रोक देने की प्रवृत्ति रख सकता है, इसलिए teammates को स्पष्ट रूप से adversarial structure में संगठित किया जा सकता है
  • हर teammate अपनी hypothesis की जाँच करते हुए साथ ही दूसरे teammates के theories को गलत साबित करने की कोशिश करता है; यह scientific debate जैसा तरीका है
  • इससे sequential investigation में होने वाले anchoring bias से बचा जा सकता है, और जो theory बचती है उसके असली root cause होने की संभावना बढ़ती है

best practices

• teammates को पर्याप्त context दें: project context अपने-आप load होता है, लेकिन lead की conversation history नहीं जाती, इसलिए spawn prompt में task-related details शामिल करें
• task size सही रखें: बहुत छोटे tasks में coordination overhead फ़ायदे से ज़्यादा हो सकता है; बहुत बड़े tasks में बिना check-in लंबे समय तक काम होने से waste बढ़ सकता है; function, test file, review जैसे self-contained units उपयुक्त हैं
• अगर lead teammates की जगह खुद implementation शुरू करे, तो उसे "Wait for your teammates to complete their tasks before proceeding" कहकर निर्देशित करें
• पहली बार उपयोग करते समय code writing के बिना स्पष्ट boundaries वाले research और review tasks (PR review, library investigation, bug investigation आदि) से शुरुआत करें
• file conflict से बचें: अगर दो teammates एक ही file edit करेंगे तो overwrite हो सकता है, इसलिए tasks को ऐसे बाँटें कि हर teammate अलग file set संभाले
• teammates की progress नियमित रूप से जाँचें, ineffective approaches की दिशा बदलें, और जैसे-जैसे results आएँ उन्हें compile करते जाएँ

troubleshooting

• अगर teammate दिखाई न दे: in-process mode में Shift+Down से active teammates के बीच switch करें; देखें कि task team setup के लिए काफ़ी complex है या नहीं; split pane request के लिए जाँचें कि tmux PATH में installed है; iTerm2 के लिए it2 CLI installed और Python API enabled होनी चाहिए
• बहुत ज़्यादा permission prompts: teammates की permission requests lead तक bubble up होती हैं, इसलिए teammate spawn से पहले permission settings में common tasks pre-approve करें
• error के बाद teammate रुक जाए: उस teammate का output देखें, फिर सीधे अतिरिक्त निर्देश दें या replacement teammate spawn करके काम जारी रखें
• lead काम पूरा होने से पहले exit कर जाए: lead को आगे काम जारी रखने का निर्देश दें, या delegate mode में जाने से पहले teammates के पूरा होने का इंतज़ार करने को कहें
• orphaned tmux session: team खत्म होने के बाद tmux session बचा रहे तो tmux ls से जाँचें और tmux kill-session -t <session-name> से हटाएँ

सीमाएँ

• in-process teammates के लिए session restore नहीं: /resume और /rewind in-process teammates को restore नहीं करते; restore के बाद lead ऐसे teammate को message भेजने की कोशिश कर सकता है जो अब मौजूद नहीं है, इसलिए नए teammates spawn करने होंगे
• task state delay: teammate अगर task complete mark न करे, तो dependent tasks blocked रह सकते हैं; status manually update करें या lead से teammate को remind करने को कहें
• termination delay: teammate current request या tool call पूरा करने के बाद ही terminate होगा
• प्रति session केवल एक team: नई team शुरू करने से पहले current team clean up करनी होगी
• nested teams नहीं: teammates अपनी team या नए teammates spawn नहीं कर सकते; केवल lead ही team manage कर सकता है
• fixed lead: जिसने team बनाई वही उसका permanent lead है; किसी teammate को lead promote करना या leadership transfer संभव नहीं
• spawn के समय bulk permission setting: सभी teammates lead के permission mode में शुरू होते हैं; spawn समय per-teammate permissions सेट नहीं की जा सकतीं
• split pane के लिए tmux या iTerm2 आवश्यक: VS Code integrated terminal, Windows Terminal, और Ghostty में split-pane mode supported नहीं है