Introduction to Morty
Relevant source files
The following files were used as context for generating this wiki page:
Morty is an autonomous AI coding loop designed to run AI agents on programming tasks until they are completed. It functions by interfacing with various AI Command Line Interfaces (CLIs) to implement features, fix bugs, and manage task lists defined in Product Requirements Documents (PRDs). Morty supports both single-task execution and complex, multi-task workflows involving parallel execution via Git worktrees.
The system acts as an orchestrator that manages the lifecycle of a task: from initialization and environment detection to execution, testing, linting, and final Git commits or Pull Requests. It supports a wide array of AI engines, including Claude Code, OpenCode, Codex, Cursor, Qwen-Code, Factory Droid, and GitHub Copilot.
Sources: README.md:1-15, morty.sh:1-10
Core Operational Modes
Morty operates in two primary modes to accommodate different developer workflows: Single Task mode and Task List mode.
Single Task (Brownfield Mode)
In this mode, the user provides a direct task description as a command-line argument. Morty then executes this specific task within the current repository context without requiring a formal task list.
Sources: README.md:19-25, morty.sh:1210-1240
Task List (PRD Mode)
Morty can consume task lists from various sources to work through a project systematically. It supports:
- Markdown: Parses
PRD.mdor similar files for- [ ]task markers. - YAML: Reads structured tasks from a YAML file, allowing for
parallel_groupdefinitions. - GitHub Issues: Fetches open issues from a specified repository, optionally filtered by labels.
Sources: README.md:27-35, morty.sh:588-660, cli/src/config/types.ts:81-85
System Architecture and Data Flow
The architecture of Morty is built around a centralized configuration system and a robust execution loop. It uses a .morty/ directory (historically .ralphy/) to store project-specific context, rules, and progress logs.
Execution Workflow
The following diagram illustrates the high-level logic for a single task iteration within Morty:
Morty orchestrates the environment, invokes the AI engine, and manages the post-processing steps like testing and committing.
Sources: morty.sh:915-1015, cli/src/config/writer.ts:108-125
Parallel Execution with Worktrees
Morty supports parallel execution by utilizing Git worktrees. Each agent runs in an isolated directory with its own Git branch, preventing file system conflicts during concurrent operations.
This allows scaling to multiple agents (defaulting to 3, configurable via --max-parallel).
Sources: README.md:105-115, morty.sh:1034-1100, cli/src/git/worktree.ts:31-50
Configuration and Project Context
Project-specific behavior is governed by the .morty/config.yaml file. This file stores metadata and constraints that are injected into every AI prompt to ensure the agent follows established conventions.
Configuration Schema
| Component | Description | Example / Default |
|---|---|---|
project | Metadata about the application | name, language, framework |
commands | CLI commands for lifecycle steps | test: "npm test", lint: "npm run lint" |
rules | Explicit instructions the AI MUST follow | "Always use TypeScript strict mode" |
boundaries | Files or folders the AI should never modify | never_touch: ["src/legacy/**"] |
capabilities | Optional tool integrations | browser: "auto" |
Sources: cli/src/config/writer.ts:25-60, cli/src/config/types.ts:5-40
Config Management Functions
Key functions for managing these configurations include:
init_morty_config()/initConfig(): Performs smart detection of languages (TypeScript, Python, Go, Rust) and frameworks (Next.js, FastAPI, etc.) to generate the initial config.load_morty_rules()/loadRules(): Retrieves rules to be appended to AI prompts.add_morty_rule()/addRule(): Persists new rules to the YAML configuration.
Sources: morty.sh:137-250, cli/src/config/writer.ts:94-106, cli/src/config/loader.ts:93-100
AI Engine Integration
Morty abstracts the specific requirements of various AI CLIs. It handles the different flags required for non-interactive ("auto") mode across engines.
Supported Engines and Integration Details
| Engine | CLI Command | Key Flags / Environment |
|---|---|---|
| Claude Code | claude | --dangerously-skip-permissions |
| OpenCode | opencode | OPENCODE_PERMISSION='{"*":"allow"}' |
| Cursor | agent | --force, --print |
| Factory Droid | droid | exec --auto medium |
| Qwen-Code | qwen | --approval-mode yolo |
| Codex | codex | exec --full-auto |
Sources: README.md:183-195, morty.sh:815-865
Browser Automation
Morty integrates with agent-browser to allow agents to perform UI verification. When enabled, Morty injects specific instructions into the prompt, enabling the AI to use commands like agent-browser open <url> and agent-browser snapshot.
Sources: README.md:135-155, morty.sh:95-130
Git and Branch Management
The system enforces a clean workflow through automated branch management.
- Branch per Task: When
--branch-per-taskis enabled, Morty creates a branch namedmorty/<slugified-task>. - Pull Request Integration: If
--create-pris active, Morty uses the GitHub CLI (gh) to push the branch and open a PR (optionally as a draft) once the task is complete. - Conflict Resolution: In parallel mode, Morty attempts to merge branches back to the base. If conflicts occur, it invokes the AI engine with a specific
resolve_promptto intelligently combine changes and remove conflict markers.
Sources: README.md:124-133, morty.sh:702-745, morty.sh:1165-1200
Conclusion
Morty provides a robust framework for automating the software development lifecycle by leveraging AI agents. By combining project-specific context, automated testing/linting, and sophisticated Git management (including parallel worktrees and AI-assisted merge resolution), it allows developers to delegate complex task lists to autonomous agents with high reliability.