Project Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• cli/src/config/loader.ts
• cli/src/config/types.ts
• cli/src/config/writer.ts
• cli/src/cli/commands/config.ts
• cli/src/cli/commands/init.ts
• morty.sh

Project Configuration in Morty provides the necessary context and constraints for AI agents to operate effectively within a repository. It serves as a centralized mechanism to define project-specific information, execution commands, operational rules, and file system boundaries. By establishing these parameters, the system ensures that AI agents follow project conventions and avoid modifying sensitive or out-of-scope files.

The configuration is primarily stored in a .morty/ directory (with legacy support for .ralphy/), containing a config.yaml for structured settings and a progress.txt for activity logging. This system supports both automated detection during initialization and manual refinement via CLI commands or direct file editing.

Sources: cli/src/config/loader.ts:9-12, cli/src/config/writer.ts:18-40, morty.sh:110-140

Configuration Structure and Schema

Morty utilizes a structured schema defined via Zod to ensure type safety and validation of configuration data. The configuration is divided into four primary segments: Project Information, Commands, Rules, and Boundaries.

Data Model

The configuration schema is defined in cli/src/config/types.ts and includes the following structures:

Section	Field	Type	Description
Project	name	String	The name of the project.
	language	String	Primary programming language (e.g., TypeScript, Python).
	framework	String	Web or application framework (e.g., Next.js, FastAPI).
	description	String	A brief overview of the project's purpose.
Commands	test	String	Command to run the test suite.
	lint	String	Command to run linting/static analysis.
	build	String	Command to compile or build the project.
Rules	rules	Array	Global instructions the AI MUST follow for every task.
Boundaries	never_touch	Array	Glob patterns of files/folders the AI should not modify.

Sources: cli/src/config/types.ts:6-38, morty.sh:176-210

Class Diagram of Configuration Schema

This diagram illustrates the relationship between the various schema objects used to validate the config.yaml file.

Configuration Lifecycle

The configuration lifecycle involves initialization, loading, and runtime modification.

Initialization (The Init Mode)

When a user runs morty --init, the system performs "Smart Detection" to identify the project name, language, and frameworks by inspecting files like package.json, pyproject.toml, or go.mod. It then populates a default .morty/config.yaml and creates an empty .morty/progress.txt.

Loading and Resolution

At runtime, Morty resolves the configuration directory by checking for .morty first, falling back to the legacy .ralphy directory if present. The loadConfig function reads the YAML content and parses it through the MortyConfigSchema.

Runtime Configuration Options

In addition to the persistent config.yaml, Morty uses RuntimeOptions to manage settings passed via CLI arguments. These options determine the behavior of the AI engine and the execution loop.

Option	Default	Description
aiEngine	"claude"	The AI CLI to use (claude, opencode, cursor, etc.).
maxIterations	0	Limit on the number of tasks to process (0 is unlimited).
maxRetries	3	Number of times to retry a failed task.
parallel	false	Whether to run tasks in parallel using git worktrees.
branchPerTask	false	Automates git branch creation for every task.
browserEnabled	"auto"	Controls browser automation via agent-browser.

Sources: cli/src/config/types.ts:51-100, morty.sh:400-545

Management Commands

Morty provides specific CLI subcommands to interact with the project configuration without manual file editing.

• View Configuration: morty --config displays a formatted summary of the project settings, detected commands, active rules, and boundaries.
• Add Rule: morty --add-rule "rule text" appends a new instruction to the rules array in config.yaml.
• Progress Tracking: The logTaskProgress function (or log_task_history in the shell script) automatically updates progress.txt whenever a task is completed or fails, providing an audit trail of the autonomous loop's actions.

Sources: cli/src/cli/commands/config.ts:13-56, cli/src/config/writer.ts:114-142, morty.sh:220-300

Conclusion

Project Configuration is the backbone of the Morty ecosystem, enabling AI agents to act as informed contributors rather than generic tools. By combining static YAML-based project definitions with dynamic runtime options, Morty provides a flexible yet controlled environment for autonomous coding. The use of strict Zod schemas ensures that configuration remains valid as the project evolves, while the .morty/ directory structure provides a clear, version-controlled home for project-specific AI instructions.