Installation & Initialization
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 tasks until completion. The system supports two primary installation paths: a globally installable Node.js CLI via NPM and a standalone Bash script. Initialization involves setting up a .morty/ directory that contains project-specific rules, configurations, and progress logs, enabling the AI to operate within defined boundaries and follow specific architectural patterns.
Sources: README.md:1-15, cli/package.json:1-10, morty.sh:1-10
Installation Methods
Morty can be installed using two distinct methods depending on the user's environment and preference.
Option A: NPM Installation (Recommended)
The project provides a TypeScript-based CLI package named morty-cli. This version is cross-platform, supporting macOS, Linux, and Windows. It does not require external dependencies like jq or yq as these functionalities are handled natively by the compiled binary or Node.js environment.
npm install -g morty-cli
Sources: README.md:15-22, cli/package.json:1-40
Option B: Manual Clone (Bash Script)
Users can clone the repository directly to use the morty.sh Bash script. This method requires manual management of dependencies such as jq, yq (for YAML support), and bc (for cost calculations).
git clone https://github.com/kaiandabdul/morty.git
cd morty && chmod +x morty.sh
Sources: README.md:24-30, morty.sh:560-580
System Requirements
| Component | Requirement | Note |
|---|---|---|
| Node.js | >= 18 | Required for NPM CLI version |
| Git | Installed & Initialized | Morty requires a git repo to track changes |
| AI CLI | Claude, OpenCode, etc. | At least one supported AI engine must be in PATH |
| Tools | jq, yq, bc | Required for the Bash version (morty.sh) |
Sources: README.md:160-185, cli/package.json:57-60, morty.sh:545-600
Project Initialization
Initialization is the process of creating the .morty/ configuration directory. This directory serves as the source of truth for the AI agent, providing it with project context, specific coding rules, and execution boundaries.
The Initialization Workflow
When the --init flag is passed, Morty performs a "Smart Detection" of the local environment to pre-populate configuration files.
Smart Detection Logic
Morty analyzes the root directory to identify:
- Project Name: Derived from
package.jsonor the current directory name. - Language: Detects TypeScript (via
tsconfig.json) or JavaScript. - Frameworks: Scans dependencies for Next.js, Nuxt, Remix, React, Vue, FastAPI, Django, etc.
- Commands: Identifies test, lint, and build scripts from
package.json,pyproject.toml, or language-specific patterns (e.g.,go test).
Sources: morty.sh:152-215, cli/src/config/writer.ts:68-80
Configuration Architecture
The .morty/ directory (historically .ralphy/) contains two critical files that govern the agent's behavior.
1. config.yaml
This file defines the AI's operational parameters. It includes:
- Project Info: Name, language, and framework.
- Commands: Specific strings used to execute tests, linting, and builds.
- Rules: Global instructions injected into every prompt (e.g., "Use TypeScript strict mode").
- Boundaries: File patterns the AI is strictly forbidden from modifying (e.g.,
migrations/**).
project:
name: "my-app"
commands:
test: "npm test"
rules:
- "Always use functional components"
boundaries:
never_touch:
- "*.lock"
Sources: cli/src/config/writer.ts:24-55, morty.sh:225-260, README.md:50-75
2. progress.txt
An append-only log file used to track task completion. The AI is instructed to update this file after every successful task, and Morty uses it to maintain state across iterations.
Sources: cli/src/config/writer.ts:107-124, morty.sh:345-355
Configuration Management
The system provides several CLI commands to manage the configuration after initial setup.
| Command | Function | Source File |
|---|---|---|
morty --init | Creates the .morty/ directory and files | cli/src/cli/commands/init.ts:11 |
morty --config | Displays the current active configuration | morty.sh:285 |
morty --add-rule "..." | Appends a new rule to config.yaml | cli/src/config/writer.ts:86 |
Path Resolution Logic
Morty supports legacy projects by looking for .ralphy/ if .morty/ is missing, ensuring backward compatibility.
Summary
Installation and Initialization in Morty provide the foundation for autonomous execution. By using either npm install -g morty-cli or cloning morty.sh, users gain access to a tool that, upon initialization via --init, automatically tailors its behavior to the specific tech stack of a repository. This setup ensures that AI agents operate within project-specific constraints and commands defined in the .morty/ directory.
Sources: README.md:1-50, morty.sh:1-15