tco-spec: A Multi-AI Agent Collaborative Workflow Framework Based on tmux

This article will introduce the tco-spec framework, an innovative multi-AI agent collaboration framework that enables structured communication between multiple AI coding tools via the tmux terminal multiplexer. The framework introduces a spec-driven development model, supporting a complete collaborative loop covering feature design, task distribution, code review, and feedback iteration, aiming to solve the problem that single AI agents struggle to handle multi-role collaboration in complex software development.

Background: From Single-Agent to Multi-Agent Collaboration

With the rapid development of AI coding assistants (such as Claude Code, Codex, OpenCode, etc.), developers have become accustomed to collaborating with a single AI agent to complete programming tasks. However, complex software development often requires collaboration among multiple professional roles like architects, developers, and reviewers, which the traditional single-agent model cannot meet. The tco-spec project emerged as a solution, using the tmux terminal multiplexer as the underlying communication infrastructure to build a multi-AI agent collaborative workflow framework. Through structured specification documents and standardized message protocols, it achieves a complete development loop from requirement analysis to code delivery.

Project Overview and Core Concepts

tco-spec's core concept is "Spec-driven Development", emphasizing structured communication between AI agents—each agent has a clear role, and tasks and feedback are transmitted through predefined specification documents, forming a traceable and reproducible collaboration process. The project name "tco" stands for Terminal-based Collaborative Orchestration, leveraging tmux's session management capabilities to organize multiple AI coding tool instances in the same terminal environment, enabling concurrent execution via pane isolation and coordinated synchronization via message passing.

Architecture Design: Three-Tier Collaboration Model

Role Layer: Defines three core roles—Designer (design agent), Implementer (implementation agent), and Reviewer (review agent). Role separation avoids cognitive overload for single agents.

Spec Layer: Introduces three document types—Feature Spec, Change Spec, and Review Spec—as the communication medium between agents.

Communication Layer: Based on tmux's inter-pane message passing mechanism, it enables asynchronous communication. Each agent runs in an independent tmux pane, and message types are identified via structured message tags to route responses.

Detailed Explanation of Core Workflow

tco-spec defines a complete collaborative workflow covering all stages of software development:

Feature Design Phase: The designer agent generates structured specification documents using the spec-feature or spec-change skill, emphasizing "design first, code later".

Task Distribution Phase: The designer agent uses the spec-implement skill to send the specification document to the implementer agent's tmux pane, including task descriptions, acceptance criteria, and feedback instructions.

Code Implementation Phase: After completing coding, the implementer agent calls the spec-feedback skill to return results.

Review Iteration Phase: Upon receiving feedback, the designer agent triggers spec-handle-feedback and calls spec-review to check code quality, supporting up to 3 rounds of repair iterations.

Cross-Validation Phase: Critical code changes can be sent to other agents for cross-validation via the spec-fix-review skill.

Skill System and Extension Mechanism

tco-spec provides a rich set of built-in skills corresponding to collaboration links:

• spec-feature: Generate feature design documents
• spec-change: Generate change documents
• spec-implement: Distribute specification documents
• spec-review: Review code implementation
• spec-feedback: Send execution results
• spec-handle-feedback: Process feedback and decide next steps
• spec-check-review: Verify the accuracy of review documents
• spec-fix-review: Send review documents to other agents for fixes
• tmux-send: Send text to a specified tmux pane

Skills can be installed via the plugin market or developed locally, supporting user-level (~/.agents/skills/tco-spec) and project-level (.agents/skills/tco-spec) installation. Once installed, they are automatically discovered and invoked.

Technical Implementation and Integration Methods

tco-spec leverages tmux's IPC capabilities to send text input to other panes via the tmux-send skill, ensuring simple and reliable communication. It supports integration with various AI coding tools such as Claude Code, Codex, and OpenCode. Developers can run different tool instances in different tmux panes. Installation methods are flexible: plugin market commands, $skill-installer from GitHub, or direct cloning of the repository to the local skill directory.

Application Scenarios and Practical Value

Applicable to various complex development scenarios:

• Large-scale feature development: The designer agent completes the architecture, implementer agents develop modules in parallel, and the reviewer agent ensures quality.
• Code refactoring projects: Decompose tasks for parallel processing while maintaining change consistency.
• Multi-language projects: Collaboration between agents specialized in different languages.
• Automated code review: The reviewer agent automatically checks code and generates repair suggestions.
• Knowledge transfer: Specification documents serve as knowledge precipitation, helping new members understand the system.

Limitations and Future Outlook

Limitations of the current implementation:

• Dependency on tmux restricts application in graphical or remote development scenarios, and some developers are unfamiliar with its operation, increasing learning costs.
• Message passing is based on text protocols, which are inefficient for processing complex data structures.
• Agent role divisions are fixed, lacking flexible definition and dynamic switching mechanisms.

Future outlook:

• Introduce more structured message formats (e.g., JSON or Protocol Buffers).
• Support more flexible role definitions and dynamic switching.
• Promote the maturity and popularization of multi-agent collaborative development technology.

Conclusion: Exploration of Collaborative AI Development

tco-spec presents a future vision of multi-professional AI agents collaborating to complete complex software engineering tasks, introducing structured engineering practices such as spec-driven development, role separation, and iterative optimization. It will not replace human creative thinking; instead, it delegates tedious details and repetitive work to agents, allowing humans to focus on high-level design and innovation.

The open-source nature of the project provides space for community contributions. We look forward to more extensions and optimizations to promote the maturity of multi-agent collaborative development technology.