Core Concepts & Safety Guarantees

Understanding Warpai’s underlying design principles will help you unlock the full power of autonomous multi-agent engineering.

1. The Agent Session as the Unit of Work

In traditional IDEs and chat-centric AI tools, an AI assistant is typically confined to a floating chat box or sidebar. Every request is an ephemeral conversational thread, and the human developer remains the sole router responsible for copying code, switching files, and validating changes.

Warpai treats an Agent session as an autonomous unit of work:

• An agent has its own execution process, working directory, and environment context.
• It can receive structured tasks dispatched dynamically at any time, with explicit deliverables and acceptance criteria.
• Tasks are tracked in the supervising agent’s dynamic supervision list and automatically exit once completed and handled.
• It can report progress, ask other agents for clarification, request code reviews, and deliver verified diffs.
• Warpai provides the terminal substrate and coordination bus to let multiple agents collaborate like an organized engineering squad.

2. Dual Collaboration Modes: Project vs. Worktree

Warpai supports two complementary collaboration models, toggled at the top of the collaboration panel:

┌─────────────────────────────────┬─────────────────────────────────┐
│          PROJECT MODE           │          WORKTREE MODE          │
│                                 │                                 │
│ • Omnidirectional mesh network  │ • Coordinator-led oversight     │
│ • All agents act as Commander/  │ • Tailored for Git repositories │
│   Worker dynamically            │ • Physically isolated worktrees │
│ • Cross-agent messaging & tasks │ • Zero build cache collisions   │
│ • Works in any standard folder  │ • Ideal for: Concurrent feature │
│ • Heavily supports non-coding:  │   coding, large refactors, and  │
│   research, design, finance, IP │   parallel regression suites    │
└─────────────────────────────────┴─────────────────────────────────┘

Project Mode (Omnidirectional Collaboration Beyond Coding)

Most multi-agent tooling treats the Git Worktree as the sole unit of parallel execution. While effective for traditional coding, this model is overly rigid for research writing, visual design, quantitative finance, patent drafting, and content strategy.

Warpai heavily champions cross-domain and non-coding applications with Project Mode:

• Dynamic Role Reversals: Break rigid master-worker hierarchies. Any agent can act as Commander to dispatch roadmaps, or as Worker to execute and submit deliverables.
• Omnidirectional Communication: Agents freely send messages, initiate structured Q&A, and claim work items from a shared task pool.
• Zero Git Lock-In: Launch directly within standard folders or cloud drives, collaboratively processing Markdown, DOCX drafts, PDFs, CSV datasets, PNGs, and SVG assets.
• Broad Domain Coverage: Powering six major fields including scientific research & peer review, creative design, quant finance, patent compliance, media operations, and due diligence intelligence.

Worktree Mode (Parallel Software Engineering)

In serious software development, having multiple agents edit the same Git branch causes merge conflicts, lock contention, and corrupted build caches.

Worktree Mode eliminates this friction with physical isolation:

• Each feature or module is assigned its own isolated physical Git worktree directory, allowing agents to develop independent features concurrently.
• Agents operate in complete isolation. Worktree A’s experimental changes cannot dirty Worktree B’s build artifacts or tests.
• A designated Coordinator Agent presides over the team, orchestrating tasks, supervising automated peer review, and integrating approved code into the main branch.
• Dedicated Manuals: For comprehensive workflows, see our specialized guides: Project Mode: Omnidirectional Collaboration & Cross-Domain Guide and Worktree Mode: Parallel Git Software Engineering.

3. Screen State Machine & Lifecycle Detection

CLI agents are terminal applications running over a pseudo-terminal (PTY). To coordinate them automatically without invasive wrapper hacks, Warpai implements an in-engine VT100 screen observer.

Using dedicated behavioral manifests (crates/agent_bus/src/screen_detection/manifests/*.toml), Warpai continuously samples the terminal output stream and derives the agent’s exact lifecycle state:

4. Guarded PTY Delivery

Unlike naive script injection that blindly sends characters over a pipe—often resulting in truncated commands or interrupted outputs—Warpai enforces Guarded PTY Delivery:

1. Prompt Synchronization: Commands are injected only when the VT100 parser verifies an active, stable prompt line.
2. Draft Collision Guard: If you have begun typing a manual command, automated delivery halts immediately so your input is never overwritten or submitted prematurely.
3. Approval Interception: When an agent requests user consent, the session stays strictly interactive until you approve or reject.