Execution Lifecycle
Relevant source files
The following files were used as context for generating this wiki page:
The Execution Lifecycle in Morty represents the end-to-end process of autonomous task completion, spanning from initial argument parsing and environment validation to iterative AI agent execution and final Git state synchronization. The system supports two primary operational modes: Sequential, where tasks are processed one after another in the main working directory, and Parallel, where multiple agents operate simultaneously in isolated Git worktrees.
Morty functions as an autonomous coding loop that integrates with various AI engines (Claude, OpenCode, Cursor, etc.) to implement features described in a Product Requirements Document (PRD) or single-task command. The lifecycle ensures that every task undergoes a structured path of implementation, optional testing, linting, and automatic Git commits or Pull Request creation.
Sources: morty.sh:5-15, cli/src/cli/args.ts:40-75
Core Operational Modes
Morty provides two distinct pathways for task execution, determined by the presence of the --parallel flag.
Sequential Execution
In sequential mode, the system iterates through a task source (Markdown, YAML, or GitHub Issues) and executes them one by one. For each task, the lifecycle includes branch creation, prompt building, AI execution with a progress monitor, and cleanup.
Sources: morty.sh:1105-1135, cli/src/execution/sequential.ts:50-85
Parallel Execution
Parallel mode leverages Git worktrees to run multiple agents concurrently without workspace interference. The lifecycle manages a pool of isolated worktrees, each with its own branch and workspace, and includes a final merge phase where AI-assisted conflict resolution may be employed to integrate disparate changes.
Sources: morty.sh:1100-1103, cli/src/execution/parallel.ts:130-180, cli/src/git/worktree.ts:20-45
The following diagram illustrates the high-level decision flow between these modes:
Task Execution Phases
Regardless of the mode, individual task execution follows a strict multi-step pipeline.
1. Pre-flight and Context Building
Before the AI engine is invoked, Morty validates environmental requirements (Git, jq, AI CLI availability) and builds a comprehensive prompt. This prompt includes project rules from .morty/config.yaml, boundary definitions (files never to touch), and browser automation instructions if enabled.
Sources: morty.sh:470-520, morty.sh:800-850, cli/src/cli/args.ts:120-135
2. Implementation Loop (The AI Command)
The system executes the specific AI CLI (e.g., claude, opencode, agent) with the generated prompt. During this phase, a background process monitors the output to provide real-time status updates (e.g., "Implementing", "Testing", "Committing").
Sources: morty.sh:730-775, morty.sh:865-900
3. Verification and Completion
After the AI finishes, Morty parses the results to extract token usage, cost, and response text. If the AI engine does not automatically handle Git operations (depending on the engine and configuration), Morty may create Pull Requests via the GitHub CLI (gh).
Sources: morty.sh:940-1000, cli/src/execution/sequential.ts:125-150
| Phase | Description | Key Functions/Tools |
|---|---|---|
| Setup | Validates Git repo and AI CLI dependencies. | check_requirements |
| Prompting | Compiles task, rules, and project context. | build_prompt, load_morty_rules |
| Execution | Spawns AI CLI process and monitors stdout. | run_ai_command, monitor_progress |
| Parsing | Extracts tokens, costs, and success status. | parse_ai_result, check_for_errors |
| Cleanup | Closes branches or merges worktrees. | cleanup_agent_worktree, return_to_base_branch |
| Sources: morty.sh:470-490, morty.sh:865-1000, cli/src/execution/sequential.ts:25-45 |
Retry and Error Handling
Morty implements a robust retry mechanism to handle flaky AI API responses or transient execution failures. The system uses a fixed delay between retries and supports a configurable maximum retry limit (default is 3).
Parallel Isolation and Synchronization
When running in parallel, Morty manages the lifecycle of multiple "Agents" using isolated Git worktrees.
Worktree Management
Each agent is assigned a unique worktree directory (usually under .morty-worktrees/) and a dedicated branch. This isolation prevents agents from seeing each other's uncommitted changes or interfering with the primary working directory.
Sources: cli/src/git/worktree.ts:20-40, cli/src/execution/parallel.ts:60-80
Integration and Conflict Resolution
After agents complete their tasks, Morty enters the Merge Phase. It attempts to merge agent branches back into the base branch sequentially. If a merge conflict occurs, Morty can invoke the AI engine specifically to resolve the conflict by analyzing the conflict markers and combining changes intelligently.
Sources: morty.sh:1375-1420, cli/src/execution/parallel.ts:215-245
Conclusion
The Morty Execution Lifecycle provides a structured and resilient framework for autonomous coding. By abstracting AI engine specifics and handling complex Git operations like worktree management and conflict resolution, it enables reliable execution of multi-task requirements in both sequential and high-concurrency environments.
Sources: morty.sh:1440-1460, cli/package.json:2-5