Treesap

AI Agent Framework for Distributed Development Teams

Treesap is a revolutionary development platform that enables multiple AI agents and human developers to collaborate in real-time through persistent terminal sessions and WebSocket-based coordination. Built for the future of software development where AI agents work alongside humans in coordinated teams.

🌟 Key Features

• Multi-Agent Terminal Orchestration - Multiple AI agents can work simultaneously across different terminal sessions
• Real-Time Cross-Session Monitoring - External agents can observe and control multiple terminal sessions
• Mobile-Responsive Terminal Interface - Chat-style input for better mobile development experience
• WebSocket-Based Architecture - Real-time bidirectional communication between terminals, web UI, and external agents
• Framework Agnostic - Works with any development stack (Hono, Vite, React, etc.)
• Persistent Terminal Sessions - Sessions survive across browser refreshes and disconnections
• Live Preview Integration - Built-in development server with live reload

🚀 Quick Start

Installation

npm install treesap

Basic Setup

1. Create a treesap.config.ts file in your project root:

import type { TreesapConfig } from 'treesap';

const config: TreesapConfig = {
  port: 1235,              // Treesap server port
  previewPort: 5173,       // Your app's dev server port
  devCommand: "npm run dev", // Command to start your dev server
  devPort: 5173,           // Port your dev server runs on
  projectRoot: process.cwd()
};

export default config;

2. Add scripts to your package.json:

{
  "scripts": {
    "dev:treesap": "treesap dev",
    "treesap": "treesap start"
  }
}

3. Start Treesap:

npm run dev:treesap

Visit http://localhost:1235 to access the Treesap interface with integrated terminal and live preview.

🏗️ Core Concepts

Terminal Sessions

Each terminal session is persistent and can be shared across multiple clients (browsers, agents, etc.). Sessions survive disconnections and can be resumed at any time.

WebSocket Communication

All terminal I/O, resize events, and cross-session communication happens over WebSockets, enabling real-time collaboration between humans and AI agents.

Agent Coordination

External AI agents can:

• Monitor multiple terminal sessions simultaneously
• Send commands to specific terminals
• Receive real-time output from all monitored sessions
• Coordinate complex multi-step tasks across multiple environments

📱 Mobile-First Design

Treesap features a responsive terminal interface with:

• Chat-style input - Familiar textarea interface for mobile users
• Two-step command execution - Send to input field, then execute
• Automatic terminal resizing - Adapts to mobile screen sizes and orientation changes
• Touch-optimized controls - Better interaction on mobile devices

⚙️ Configuration

The TreesapConfig interface supports these options:

interface TreesapConfig {
  port?: number;           // Treesap server port (default: 1235)
  previewPort?: number;    // Preview iframe port (default: 3000)
  devCommand?: string;     // Command to auto-start dev server
  devPort?: number;        // Dev server port to auto-start
  projectRoot?: string;    // Project root directory
}

🧠 Multi-Agent Development

Treesap enables unprecedented AI agent collaboration:

Agent Orchestration

• Supervisor Agents - Monitor multiple coding agents across different terminals
• Specialized Agents - Each agent can work in its dedicated terminal session
• Cross-Agent Communication - Agents can coordinate through the WebSocket infrastructure

Human-AI Collaboration

• Seamless Handoffs - Switch between human and AI control of terminal sessions
• Real-time Monitoring - Watch AI agents work while maintaining override capability
• Collaborative Debugging - Multiple agents can work on the same problem simultaneously

🛠️ Architecture

WebSocket Terminal Service

• Persistent terminal sessions using node-pty
• Multi-client session sharing
• Cross-session monitoring and control
• Real-time input/output streaming

Sapling Islands Components

• Reactive terminal interface
• Live preview integration
• Mobile-responsive design
• Chat-style input system

External Agent Integration

// Connect to WebSocket for monitoring
const ws = new WebSocket('ws://localhost:1235/terminal/ws');

// Join a terminal session
ws.send(JSON.stringify({
  type: 'join',
  sessionId: 'terminal-1',
  terminalId: 'terminal-1'
}));

// Send commands
ws.send(JSON.stringify({
  type: 'input',
  sessionId: 'terminal-1',
  data: 'npm test\r'
}));

🎯 Use Cases

AI Development Teams

• Multiple AI agents working on different parts of a large codebase
• Coordinated testing and deployment across multiple environments
• Real-time code review and collaboration between AI agents

Educational Platforms

• Instructors monitoring multiple student coding sessions
• AI tutors providing real-time assistance
• Collaborative coding exercises with mixed human-AI teams

DevOps Orchestration

• Coordinated deployments across multiple servers
• Real-time monitoring and intervention capabilities
• Automated testing with human oversight

📚 API Reference

WebSocket Message Types

• join - Join a terminal session
• leave - Leave a terminal session
• input - Send input to terminal
• resize - Resize terminal dimensions
• ping/pong - Connection health checks

Terminal Service Methods

• getActiveSessions() - List all active sessions
• sendCommandToSession(sessionId, command) - Send command to session
• getSessionClients(sessionId) - Get connected clients
• closeSession(sessionId) - Terminate a session

🔧 Development

Prerequisites

• Node.js >=18.0.0
• TypeScript support

Building from Source

git clone https://github.com/withtreesap/treesap.git
cd treesap/packages/treesap
npm install
npm run build

Development Scripts

npm run dev        # Start with hot reload
npm run dev:css    # Watch CSS changes
npm run build      # Build for production
npm run clean      # Clean build artifacts

🤝 Contributing

We welcome contributions! Treesap is building the foundation for the future of AI-powered development.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub Repository
• Issues & Bug Reports
• NPM Package

Treesap - Growing the future of collaborative development 🌳