Contributing 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 execute tasks until a Product Requirements Document (PRD) is complete. It supports multiple AI engines, including Claude Code, OpenCode, Codex, Cursor, Qwen-Code, Factory Droid, and GitHub Copilot. Contributors can engage with the project through its two primary implementations: a portable Bash script (morty.sh) and a TypeScript-based CLI (morty-cli).
The project architecture focuses on task automation, parallel execution using Git worktrees, and integrated browser automation via agent-browser. It enforces project-specific conventions through a centralized configuration system located in the .morty/ directory.
Sources: README.md:1-10, morty.sh:1-10, cli/package.json:1-15
Development Environment Setup
Morty supports development using either the Bash implementation or the TypeScript implementation. The TypeScript version uses Bun for building and execution.
Toolchain and Dependencies
| Tool | Purpose | Implementation |
|---|---|---|
| Bun | Runtime, package manager, and compiler | CLI |
| Biome | Linting and code formatting | CLI |
| Commander | CLI argument parsing | CLI |
| Simple-Git | Programmatic Git operations | CLI |
| jq | JSON processing | Bash |
| yq | YAML processing | Bash |
Sources: cli/package.json:30-60, morty.sh:580-600
Build Scripts
The TypeScript CLI provides several scripts for development and cross-platform compilation:
dev: Runs the CLI using Bun:bun run src/index.ts.check: Executes Biome for linting and formatting.build:all: Compiles the project for Darwin (arm64/x64), Linux (x64/arm64), and Windows (x64).
Sources: cli/package.json:20-28
Project Configuration and State Management
Morty utilizes a structured configuration system stored within the .morty/ directory (backward compatible with .ralphy/). This system manages project identity, AI behavioral rules, and execution progress.
Configuration Structure
The config.yaml file defines the operational boundaries and instructions for the AI agents. It includes:
- Project Metadata: Name, language, and framework.
- Commands: Test, lint, and build commands used for verification.
- Rules: Mandatory instructions injected into AI prompts.
- Boundaries: File paths and directories that the AI is prohibited from modifying.
Sources: cli/src/config/writer.ts:16-55, cli/src/config/types.ts:5-40
Progress Tracking
Execution state is maintained in progress.txt. Each task completion or failure is appended with a timestamp and a status icon (✓ for success, ✗ for failure).
The diagram shows the initialization and configuration loading flow for Morty agents. Sources: cli/src/config/writer.ts:70-100, cli/src/config/loader.ts:55-80
AI Engine Integration
Morty abstracts interactions with various AI CLIs. Each engine is handled with specific permission flags and output parsing logic to extract token usage or execution duration.
Supported Engines and Permissions
| Engine | CLI Command | Permission/Mode Flag |
|---|---|---|
| Claude | claude | --dangerously-skip-permissions |
| OpenCode | opencode | --approval-mode full-auto |
| Cursor | agent | --force / --dangerously-skip-permissions |
| Qwen | qwen | --approval-mode yolo |
| Droid | droid | --auto medium |
Sources: morty.sh:350-400, README.md:200-215
Prompt Engineering
The system dynamically constructs prompts by aggregating:
- Project Context: Loaded from
config.yaml. - Rules: Global instructions for the agent.
- Boundaries: Restricted files.
- Browser Instructions: Tool usage for
agent-browser(if enabled). - Task Details: Specific goals for the current iteration.
Sources: morty.sh:268-310, cli/src/config/loader.ts:115-135
Parallel Execution Architecture
Parallelism in Morty is achieved through Git worktrees, allowing multiple agents to work on separate tasks simultaneously without file system conflicts.
Worktree Workflow
- Isolation: For each task, a new Git worktree is created in a temporary directory.
- Branching: A dedicated branch (
morty/agent-...) is checked out in the worktree. - Task Execution: The AI agent runs within the isolated worktree directory.
- Conflict Resolution: Once tasks are complete, Morty attempts to merge branches back into the base branch. If conflicts occur, an AI-assisted resolution process is triggered.
This sequence illustrates how Morty manages lifecycle of a parallel agent using Git worktrees. Sources: morty.sh:1090-1150, cli/src/git/worktree.ts:55-75
Testing and Verification
Morty enforces code quality by running tests and linting before marking a task as complete.
- Test Command: Auto-detected (e.g.,
npm test,pytest,go test) or defined inconfig.yaml. - Lint Command: Auto-detected (e.g.,
npm run lint,ruff check .,golangci-lint) or defined inconfig.yaml. - Verification Loop: Agents are instructed to run tests and ensure they pass. The execution loop can be configured to skip these steps using
--no-tests,--no-lint, or--fast.
Sources: morty.sh:110-170, cli/src/config/types.ts:65-75, cli/src/cli/args.ts:90-100
Summary
Contributing to Morty involves maintaining and extending its autonomous coding capabilities across its Bash and TypeScript implementations. The system relies heavily on a robust configuration engine in .morty/, sophisticated prompt construction, and isolated parallel execution via Git worktrees to ensure reliable automated software development.