Mahalaxmi Architecture
An overview of the core systems that power Mahalaxmi's multi-agent orchestration platform.
Manager-Worker Consensus Engine
The Manager is the orchestration brain. It analyzes incoming requirements, decomposes them into discrete tasks, and distributes those tasks to autonomous Worker agents. Each Worker executes independently inside an isolated environment and reports its results back to the Manager.
When multiple Workers produce overlapping or conflicting outputs, the consensus engine reconciles them using one of four configurable merge strategies:
- Union — Combines all non-duplicate results from every Worker. Best when you want maximum coverage.
- Intersection — Retains only results agreed upon by all Workers. Best when high confidence is required.
- WeightedVoting — Each Worker casts a weighted vote; the result with the highest aggregate weight wins.
- ComplexityWeighted — Tasks with higher complexity scores carry more influence in the final merge decision.
For conflicts that no voting strategy can resolve cleanly, the Manager invokes LLM arbitration — sending the conflicting outputs to the configured language model and asking it to reason about which result is authoritative. Semantic deduplication using Jaccard similarity prevents near-duplicate outputs from inflating result sets before the merge strategy is applied.
DAG Task Graph
Every Mahalaxmi run is represented internally as a Directed Acyclic Graph (DAG). Each node in the graph is a discrete task; each directed edge encodes a dependency relationship — the target node may not begin execution until all of its source nodes have completed successfully.
Workers observe the graph and immediately claim any node whose dependencies are fully resolved, enabling maximal parallelism without manual coordination:
The Manager constructs the DAG from the requirement analysis phase and updates edge weights dynamically as Workers report completion or failure, allowing downstream tasks to be re-queued or retried automatically.
PTY Control
Mahalaxmi controls AI CLI tools through native pseudo-terminal (PTY) sessions — not screen capture or OCR. This means Mahalaxmi reads and writes directly to the terminal byte stream, giving it deterministic, low-latency control over any AI CLI tool that runs in a standard terminal.
Because PTY control is protocol-agnostic, Mahalaxmi works with any provider whose CLI speaks to a terminal. Adding support for a new provider requires only a PTY adapter — no proprietary integration or API access is needed beyond what the CLI already provides.
Git Worktree Isolation
Every Worker operates inside a dedicated git worktree — a lightweight checkout of the repository at a unique branch. Workers can read, modify, and commit code without interfering with one another because each worktree is fully isolated at the filesystem level.
When a Worker finishes its task, the Manager opens a Pull Request from the Worker's branch. The PR is reviewed, merged, and the worktree is cleaned up. This workflow keeps the main branch stable while giving Workers the freedom to experiment and fail safely.
Provider Routing
The ProviderRouter sits between the Manager and the underlying AI CLI tools. When a task is dispatched, the router selects the appropriate provider based on the session configuration. If the primary provider becomes unavailable, the router applies fallback logic — automatically retrying on the next configured provider in priority order until the request succeeds or all options are exhausted.
Providers are pluggable via the Provider Plugin SDK. Custom providers slot into the routing chain without any changes to the core orchestration logic.