Mahalaxmi Terminal Orchestration

Observed Performance

1. Introduction

The AI coding assistant market has matured rapidly. Tools like Claude Code, GitHub Copilot, OpenAI Codex, and their open-source counterparts have demonstrated that LLMs can produce high-quality code given appropriate context and direction. Individual developers report 2–5× productivity gains from these tools. The bottleneck is no longer whether AI can write code — it is whether a single AI agent can handle the full scope of a complex software project without becoming a single point of serialization. A real codebase has hundreds of independent modules, services, and components that could be developed in parallel. Yet every AI coding assistant available today works in exactly one conversation at a time, with one developer watching one terminal. Mahalaxmi is the orchestration layer that changes this. Rather than one AI agent working sequentially through a task list, Mahalaxmi deploys a team of AI agents organized into a Manager-Worker hierarchy. Manager agents analyze the codebase, deliberate on an execution plan, and produce a dependency-ordered task graph. Worker agents execute tasks in parallel, each isolated in its own Git worktree, with context pre-filtered to only the code they need. The results are automatically integrated via pull requests, tested through a post-cycle validation pipeline, and surfaced through a real-time desktop UI.

2. Problem Statement

3. Architecture Overview

Mahalaxmi is a cross-platform desktop application built on Tauri 2.x (Rust + WebView), providing a native application experience on Windows, macOS, and Linux without requiring a cloud backend.

4. The Consensus Engine

The Consensus Engine is the component responsible for merging multiple manager agents' execution plans into a single, coherent, deduplicated task graph. When the Manager Phase begins, N manager agents (configurable, 1–8) independently analyze the codebase and requirements document. Each manager produces a proposed execution plan — a set of tasks with names, descriptions, target files, complexity estimates, and dependencies. The Consensus Engine then merges these proposals using one of four strategies: Union: includes all unique tasks from all managers. Semantic deduplication identifies tasks that describe the same work with different words and merges them. Best for maximizing coverage. Intersection: includes only tasks that appeared in every manager's plan. Produces a minimal, high-confidence plan. Best for conservative or safety-critical work. WeightedVoting: tasks weighted by the historical performance reputation of the provider that proposed them. Best when provider quality varies significantly. ComplexityWeighted: tasks weighted by their complexity scores. Ensures high-complexity tasks from any manager are included. Best for complex projects where missing a hard task is costly. The deduplication pipeline is CamelCase-aware — it tokenizes task names into constituent words before computing similarity. Multi-field Jaccard similarity is computed across the task name, description, and file scope. Tasks in the ambiguous zone are sent to LLM arbitration: a prompt asks the model to determine whether two candidate tasks should be merged, kept separate, or synthesized into a new task that captures the intent of both.

5. PTY-Native Terminal Control

Mahalaxmi controls AI coding tools by taking ownership of their terminal (PTY — pseudoterminal). This is architecturally distinct from screen capture or clipboard injection approaches. When Mahalaxmi spawns an AI coding tool, it spawns the process with a PTY attached. Mahalaxmi's PTY engine (mahalaxmi-pty) reads raw bytes from the PTY output stream and writes commands to the PTY input stream. The byte stream is parsed using a VT100/ANSI state machine to extract semantic content — text, cursor positions, colors — without rendering the content to a screen. This architecture provides several properties not achievable with screen capture: Reliability. The byte stream is deterministic for a given tool version. OCR errors do not occur because there is no image processing. Universality. Any terminal-based AI CLI tool can be controlled — the approach is not specific to a font, color scheme, or terminal emulator. Latency. Reading raw bytes from a PTY is faster than screen capture pipelines, which typically require frame capture, image decoding, and OCR. Completeness. The full output, including color codes and terminal control sequences, is available for analysis.

6. Intelligent Context Routing

Workers do not receive the full codebase as context. The full codebase context problem is one of the fundamental failure modes of single-agent AI coding: as context grows, quality degrades. Mahalaxmi's context routing system selects a minimal, maximally relevant subset of files for each worker task. Files are scored using three signals: Lexical Jaccard (α): the Jaccard similarity between the vocabulary of the task description and the vocabulary of the file's content. Import-graph proximity (β): the BFS distance in the codebase's import dependency graph from the task's explicitly named target files to each candidate file. Files closer in the import graph to the task's targets score higher. Historical co-occurrence (γ): files that have been modified together in previous cycles involving similar tasks score higher. The combined score is: score(f) = α · lexical(f) + β · proximity(f) + γ · cooccurrence(f) Files are ranked by this score and added to the worker's context window until the configured token budget is exhausted. Workers receive exactly the files they need — not the whole repository.

7. Technology Stack