System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Morty is an autonomous AI coding loop designed to execute technical tasks until completion, supporting both single-task "brownfield" modes and multi-task Product Requirements Document (PRD) workflows. The system functions as an orchestration layer between various AI coding engines (such as Claude Code, OpenCode, and Cursor) and a local development environment, managing task discovery, git operations, and execution validation.
The architecture is built on two primary implementations: a portable Bash script (morty.sh) and a structured TypeScript CLI (morty-cli). Both implementations share a common operational logic: they ingest tasks from sources like Markdown, YAML, or GitHub Issues, inject project-specific rules from a .morty/ configuration directory, and manage task isolation through git branches or parallel worktrees.
Sources: morty.sh:8-20, cli/src/config/types.ts:47-90, README.md:12-30
Core Component Architecture
The system is divided into three primary layers: the Interface Layer (CLI/Script), the Management Layer (Config and Tasks), and the Execution Layer (AI Engines and Git).
Operational Flow Diagram
The following diagram illustrates the high-level flow of a task from definition to completion.
Task Management and Configuration
Morty centralizes project intelligence in the .morty/ directory. This directory contains instructions that ground the AI agent's behavior to specific project conventions.
Configuration Structure
The system uses a standardized schema to define project metadata and operational boundaries.
| Component | Description | Data Structure |
|---|---|---|
| Project Info | Metadata including name, language, and framework for AI context. | ProjectSchema |
| Commands | Defined paths for test, lint, and build operations. | CommandsSchema |
| Rules | Mandatory instructions the AI must follow in every prompt. | z.array(z.string()) |
| Boundaries | File paths and patterns the AI is prohibited from modifying. | BoundariesSchema |
Sources: cli/src/config/types.ts:3-45, cli/src/config/writer.ts:18-50
Task Sources
Morty supports multiple entry points for defining work.
- Markdown: Parses
- [ ]markers inPRD.mdor a directory of markdown files. - YAML: Supports structured task lists with
parallel_groupidentifiers for ordering. - GitHub Issues: Fetches open issues via the GitHub CLI (
gh), filtering by labels if specified.
Sources: morty.sh:425-540, cli/src/cli/args.ts:88-105
Execution Engine
The Execution Engine abstracts the complexities of different AI CLIs into a unified interface. It handles prompt construction, token usage tracking, and error handling.
AI Engine Integration Logic
The system maps internal execution requests to specific vendor CLI commands, as shown in the sequence below.
Engine Capabilities
The system supports diverse engine outputs and permission models:
- Token Tracking: Available for Claude, OpenCode, and Qwen.
- Duration Tracking: Used for Cursor and Factory Droid.
- Permission Handling: Automates approvals using flags like
--dangerously-skip-permissionsor--approval-mode yolo.
Sources: morty.sh:751-850, README.md:214-225
Parallel Execution and Isolation
Morty utilizes git worktree to allow multiple AI agents to operate simultaneously without workspace conflicts.
Isolation Strategy
Each parallel agent is assigned a unique identifier and a dedicated branch. The system creates a temporary directory and mounts a git worktree linked to that branch.
Conflict Resolution
After parallel agents complete their tasks, Morty performs a multi-stage merge process:
- Batch Completion: Agents finish and unmount worktrees.
- Sequential Merge: Morty attempts to merge agent branches into the base branch.
- AI Resolution: If standard git merges fail due to conflicts, Morty invokes the AI engine with a specific
resolve_promptcontaining the conflict markers to intelligently combine changes.
Sources: cli/src/execution/parallel.ts:245-295, morty.sh:1350-1420
Summary
The Morty architecture provides a robust framework for autonomous development by combining rigid configuration boundaries with flexible AI execution. By leveraging git's native worktree and branching capabilities, it ensures that AI agents operate in isolated environments, while its multi-engine abstraction layer allows developers to swap between leading models like Claude and GPT-4o. The inclusion of AI-assisted conflict resolution completes the loop, allowing the system to handle the complexities of concurrent code modifications.
Sources: README.md:1-10, morty.sh:1520-1560