Skip to content

agent.md

Latest commit

 

History

History
405 lines (302 loc) · 14.3 KB

agent.md

File metadata and controls

405 lines (302 loc) · 14.3 KB
Raw

AGENT.MD - Shared AI Agent Instructions

Auto-Terminal Project

NOTE: This file contains shared instructions for all AI agents working on Auto-Terminal.

Agent-Specific Instructions:

  • Claude agents: Read CLAUDE.md after this file
  • Gemini agents: Read GEMINI.md after this file

Quick Rules

  • Code Exploring: Use Glob/Grep for targeted searches. Read PROJECT_STRUCTURE.md first for high-level overview.
  • Process Management: NEVER kill processes directly. Use npx kill-port {ports}
  • Task Completion: Always ensure successful build after changes
  • Commits: Commit on task completion. Follow project commit message style.
  • Testing: 80%+ coverage for new code. Run tests before committing.

Phase Documentation

Load detailed docs from docs/agentic/ based on task:

Phase File When to Load
Setup 01-setup.md Environment setup, installation issues, first-time setup
Architecture 02-architecture.md Understanding codebase, design patterns, component relationships
Coding 03-coding.md Writing code, Rust/TypeScript standards, design principles
Testing 04-testing.md Creating tests, coverage requirements, test strategies
Debugging 05-debugging.md Troubleshooting, performance issues, bug investigation
Operations 06-operations.md Building, deployment, CI/CD, production concerns

Essential Reminders

Before Implementing

  • Read relevant phase documentation (see table above)
  • Consider edge cases and failure modes
  • Ensure test coverage for new functionality

Design Principles

  • SOLID, DRY, KISS, YAGNI - Details in docs/agentic/03-coding.md
  • File size limit: ~1,200 lines per file
  • Test coverage: 80%+ for new code

Commit Guidelines

  • Follow conventional commit format when possible
  • Include issue/ticket numbers if applicable
  • NO "Generated with Claude Code" or "Generated by AI" signatures

Master Agent Protocol

This section helps differentiate Master Agent from regular development.

If You Are the Master Agent

You are the Master Agent if ANY of these are true:

  • User explicitly invoked /t-as-master (Claude) or equivalent orchestration command
  • User said "act as master agent" or similar
  • Your task/todo list contains "MASTER AGENT MODE ACTIVE"

Master Agent Rules:

  1. READ docs/agentic/master-agent.md immediately for full protocol
  2. NEVER write code directly — delegate to Implementer Agent
  3. NEVER create tests directly — delegate to Test Analyst Agent
  4. ALWAYS maintain orchestration state in TodoWrite/task tracking
  5. After context limit/compaction: Check task state, re-read master-agent.md if needed

If You Are Implementing Directly

You are in direct implementation mode if:

  • User asked you to implement a feature without orchestration
  • No master agent context in conversation
  • User wants quick, focused implementation

Direct Implementation Rules:

  1. READ relevant phase docs before starting
  2. WRITE code following standards in docs/agentic/03-coding.md
  3. CREATE tests as specified in docs/agentic/04-testing.md
  4. RUN tests and ensure they pass
  5. UPDATE documentation if needed

Development Guidelines

  • Always refer to /docs/auto-terminal/implementation.md and /docs/auto-terminal/changelogs.md for progress tracking
  • When completing tasks, update the relevant documentation files in /docs folder
  • Use "npx kill-port [port]" to kill a running process when troubleshooting
  • Always check eslint accordingly

Document Management

  • Organize documents in the structure /docs/[project]/[phase]

Project Overview

Auto-Terminal Orchestration Platform is a comprehensive AI agent development ecosystem consisting of three integrated projects:

1. Auto-Terminal (Core Platform)

A cross-platform terminal emulator built with Tauri (Rust backend) and React/TypeScript frontend. Provides advanced tabbed and split-view UI with rich developer APIs for automation and integration. Embeds multiple shells (cmd, PowerShell, Git Bash) with real-time event hooks and programmatic control.

Status: Migrated from Electron to Tauri. The Electron implementation is now obsolete.

2. Terminal-Monitor (Management Client)

A React-based web application (/terminal-monitor/) for monitoring and controlling headless Auto-Terminal instances. Features JWT authentication, real-time WebSocket monitoring, and multi-terminal management capabilities.

3. Agent-Monitor (AI Orchestration)

A server-based application (/agent-monitor/) for provisioning and monitoring AI agents (Claude Code, Gemini, etc.) running in terminals. Enables intelligent team coordination, task distribution, and session persistence for collaborative development workflows.

Terminal Rendering: Uses modern @xterm/* packages (v5.5.0) for optimal performance, including WebGL rendering support for enhanced display and reduced CPU usage.

Essential Commands

Auto-Terminal (Core Platform)

# Development Setup
npm install                    # Install dependencies
npm run dev                   # Start development (Tauri + renderer)
npm run dev:renderer          # Start renderer dev server only

# Building
npm run build                 # Build all components
npm run build:tauri           # Build Tauri application
npm start                     # Start built application

# Testing
npm test                      # Run Jest unit tests
npm run test:e2e              # Run Playwright E2E tests
npm run test:e2e:headed       # Run E2E tests with browser UI
npm run test:e2e:debug        # Debug E2E tests
npm run test:all              # Run all tests (unit + E2E)

# Rust Backend
cd src-tauri
cargo build                   # Build Rust backend
cargo test                    # Run Rust tests
cargo clippy                  # Lint Rust code

Terminal-Monitor (Management Client)

cd terminal-monitor

# Development
npm install                   # Install dependencies
npm start                     # Start React development server
npm run build                 # Build production bundle
npm test                      # Run tests

Agent-Monitor (AI Orchestration)

cd agent-monitor

# Setup
npm install                   # Install dependencies
npm run build                 # Build TypeScript
cp env.example .env           # Configure environment

# Operation
npm start                     # Start monitoring
npm run team:start <config>   # Start team orchestration
npm run team:session <config> # Check team status
npm run team:start <config> --resume # Resume session

Orchestration Workflow

# 1. Start core platform with API
npm run dev

# 2. Launch web monitoring (separate terminal)
cd terminal-monitor && npm start

# 3. Start AI agent team (separate terminal)
cd agent-monitor && npm run team:start team-config.json

# Access web interface at http://localhost:3000
# API endpoints available at http://localhost:3001
# WebSocket events on ws://localhost:9876

Architecture Overview

Platform Architecture

The three projects form a comprehensive orchestration ecosystem:

  1. Auto-Terminal - Core platform providing terminal infrastructure and APIs
  2. Terminal-Monitor - Web client for monitoring and controlling terminals
  3. Agent-Monitor - AI orchestration server for team coordination

Auto-Terminal Architecture (Tauri-based)

⚠️ CRITICAL: Migration Status

  • ACTIVE: src-tauri/ (Rust backend using Tauri framework)
  • OBSOLETE: src/main/ (Electron main process), src/api/ (Node.js API server)
  • SHARED: src/renderer/ (React frontend, works with Tauri)

Core Components:

Tauri Backend (src-tauri/)

  • lib.rs: Main entry point, command registration
  • state.rs: Application state (thread-safe)
  • pty_manager.rs: Terminal process management using portable-pty
  • api_server.rs: Embedded Axum API server for external integration
  • commands.rs: Tauri command handlers (IPC layer)

React Frontend (src/renderer/)

  • components/Terminal/: xterm.js integration, terminal display
  • components/Tabs/: Tab management UI
  • components/Panes/: Split pane layout
  • store/: Redux state management (tabs, panes, settings)
  • services/: Business logic (TerminalService, etc.)

Terminal-Monitor Architecture

  • React Frontend: Web-based monitoring interface
  • Redux Store: State management for terminals and authentication
  • WebSocket Client: Real-time communication with Auto-Terminal
  • JWT Authentication: Secure API access with automatic token refresh

Agent-Monitor Architecture

  • Team Orchestrator: Core coordination logic
  • Agent Detection: AI agent identification and monitoring
  • Session Persistence: Save/restore team state
  • ChatHub Integration: Communication layer for agent coordination

Key Architectural Components

Shell Integration (PTY Management)

Current Implementation (Tauri/Rust):

  • portable-pty: Cross-platform PTY abstraction
  • Process spawning: Rust-based process management
  • I/O handling: Async reads/writes using Tokio
  • Platform support: Windows (ConPTY), macOS/Linux (native PTY)

Legacy (Obsolete):

  • src/shell/PTYManager.ts: Old Node.js implementation
  • src/shell/pty-wrapper.ts: Electron-based PTY wrapper

State Management

Frontend (Redux Toolkit):

  • tabsSlice: Tab creation, selection, and management
  • panesSlice: Split pane layout and terminal assignments
  • settingsSlice: Shell profiles, themes, and user preferences

Backend (Rust):

  • AppState: Shared application state using Arc<Mutex<>>
  • Thread-safe access to PTY manager and API server state

Terminal Display

  • xterm.js v5.5.0: Modern terminal rendering
  • Addons: fit, web-links, webgl, unicode11
  • Performance: WebGL rendering for reduced CPU usage
  • Component: TerminalDisplay.tsx handles PTY data and user input

Developer API

Current (Tauri/Axum):

  • REST endpoints for terminal control
  • WebSocket for real-time event streaming
  • JWT authentication for external access

Legacy (Obsolete):

  • src/api/WebSocketServer.ts: Old Node.js WebSocket server
  • src/api/RESTServer.ts: Old Express server

IPC Communication Flow (Tauri)

  1. Frontend calls Tauri command via invoke('command_name', params)
  2. Rust backend receives command in command handler
  3. Command handler interacts with PTY manager or state
  4. Response sent back to frontend
  5. Events emitted from Rust to frontend via window.emit()

Technology Stack

Core

  • Backend: Rust (2021 edition) with Tauri 2.x
  • PTY: portable-pty
  • API: Axum (embedded Rust web server)
  • Frontend: React 19, Redux Toolkit, TypeScript 5.x
  • Terminal: xterm.js v5.5.0 (@xterm/* packages)

Communication

  • IPC: Tauri commands and events
  • WebSocket: For real-time event streaming
  • REST: For external API access

Build & Tools

  • Rust: Cargo, rustfmt, clippy
  • Frontend: Webpack, Babel, TypeScript
  • Testing: Rust (cargo test), Jest, Playwright
  • Linting: ESLint (TS), clippy (Rust)

Component Relationships

Tab Management Flow

  • NewTabDropdown: Shell selector and settings
  • TabManager: Drag-and-drop reordering, keyboard shortcuts (Ctrl+T, Ctrl+W)
  • TerminalContainer: Maintains separate panes per tab
  • TerminalPane: One-to-one mapping with terminal processes

Shell Profile System

  • Shell types: cmd, PowerShell, Git Bash, and others
  • Profiles detected in Rust backend
  • Default profile selection persists in Redux settings
  • Shell resolution: profile ID → executable path

Package Standardization

All projects use modern @xterm/* packages:

  • Unified Dependencies: @xterm/xterm v5.5.0 across all projects
  • WebGL Acceleration: Optimal rendering performance
  • Enhanced Features: Better TypeScript support, frequent security updates
  • Consistent API: Standardized addon loading patterns

Development Patterns

Error Handling Strategy

  • Rust: Use Result<T, E> with custom error types, avoid .unwrap() in production
  • TypeScript: Try-catch for async, proper error typing
  • Terminal operations use graceful degradation (warnings vs errors)
  • PTY spawn failures logged but don't crash application

Testing Architecture

  • Rust: Built-in #[cfg(test)] modules, #[tokio::test] for async
  • TypeScript: Jest for unit tests, React Testing Library for components
  • E2E: Playwright with Tauri launcher utilities
  • Coverage: 80%+ threshold for branches, functions, lines, statements

Build System

  • Tauri: Cargo builds Rust backend, Webpack builds frontend
  • Development: Hot reload for both frontend and backend
  • Production: Optimized builds with LTO and minification

Key Files for Common Tasks

Adding New Shell Types

  • Update shell detection in src-tauri/src/pty_manager.rs
  • Add shell path resolution logic
  • Update frontend shell selector UI if needed

Terminal Display Issues

  • Check src/renderer/components/Terminal/TerminalDisplay.tsx for xterm.js integration
  • Verify PTY data flow in src/renderer/services/TerminalService.ts
  • Debug Tauri IPC in src-tauri/src/commands.rs

Tab/Pane Management

  • Tab logic in src/renderer/components/Tabs/TabManager.tsx
  • Pane splitting in src/renderer/components/Panes/PaneManager.tsx
  • State management in Redux slices

API Integration

  • Rust API server in src-tauri/src/api_server.rs
  • Event system integrated with Tauri events
  • Client examples in docs/api/client-example.js

Performance Considerations

  • Tab switching uses show/hide rather than recreating terminals (preserves session state)
  • Terminal processes persist during UI changes
  • Target: <200ms latency for UI operations
  • Scalability: Support 20+ concurrent panes
  • Memory: <500MB for 20 concurrent terminals
  • Agent orchestration supports up to 10 concurrent AI agents per team
  • WebSocket connections optimized for real-time event streaming

Next Steps for AI Agents

After reading this file:

  1. Read your agent-specific file (CLAUDE.md or GEMINI.md)
  2. Read relevant phase documentation from docs/agentic/ based on your task
  3. Check project structure in PROJECT_STRUCTURE.md for detailed file inventory
  4. Review PRD in docs/auto-terminal/requirements.md for requirements context

End of Shared Agent Instructions