Echomancer Documentation

Overview

Echomancer automates routine software development tasks from the command line. It scans your project for actionable items, generates code using AI (via Cursor), runs only relevant tests, and commits or reverts changes based on results. This reduces manual effort, keeps your codebase consistent, and accelerates development. Echomancer adapts to your hardware for efficient operation and learns from your codebase to improve over time. It is ideal for developers and teams seeking to automate maintenance, enforce standards, and streamline workflows.

3. Adding and Discovering Tasks

Echomancer discovers tasks by scanning your codebase for TODO comments, FIXME notes, and other actionable markers. You can add tasks by including comments like // TODO: implement feature X or // FIXME: handle edge case in your code. You can also use echomancer analyze to trigger a scan for new tasks. Echomancer will automatically queue these for automation.

4. Core Features

• Resource-Aware Automation: Profiles your system and configures itself to avoid overloading your machine, whether it's a laptop or server.
• Groundhog Methodology: Automates the cycle: scan for tasks, generate code, run only necessary tests, and commit or revert changes. Keeps your project moving with minimal manual input.
• AI Learning System: Learns your code style and patterns using Cursor, improving code suggestions and patches over time. This helps Echomancer produce code that matches your project's conventions and reduces manual review.
• Smart Test Runner: Runs only tests affected by your changes, saving time and resources.
• Structured Logging: Logs all actions and errors in a structured format for easy debugging and review.
• Cross-Platform CLI: Works on Linux, macOS, and Windows.
• Open Source: MIT licensed and extensible for custom workflows.
• Cursor Integration: Leverages Cursor for advanced code generation, review, and learning.
• Phases and Roles: Supports development phases (design, implementation, testing, quality) and role assignment for fine-grained automation control.

5. CLI Reference

• echomancer init [path] – Initialize a project in the current directory or at [path] with hardware detection and Cursor integration.
• echomancer config [--max-instances N] [--project path] – View or update configuration.
• echomancer start [--single-instance] [--test-mode affected-only|progressive|full] [--phase PHASE] [--role ROLE] – Start automation (single or multi-instance, with test mode, phase, and role selection).
• echomancer status – Show running status and resource usage.
• echomancer stop [--instance-id ID] – Stop automation (all or by instance).
• echomancer logs [--follow] [--instance-id ID] – View logs. --follow streams log output in real time, similar to tail -f.
• echomancer cleanup --project path – Clean up project artifacts.
• echomancer analyze – Scan project for tasks, TODOs, and automation opportunities.
• echomancer roles --assign [cursor-id] [role] – Assign roles to Cursor instances (e.g., implementation, testing, quality).
• echomancer roles --add-custom [role] --description "desc" – Add custom roles for your project.
• echomancer learn --enable – Enable AI learning from your codebase and patches.
• echomancer learn --status – Show current AI learning status and patterns.
• echomancer phase --set [phase] – Set the current development phase (design, implementation, testing, quality).
• echomancer phase --status – Show the current phase and options.

Task Management Commands

• echomancer task list – List all discovered and manually added tasks.
• echomancer task add "Description of new task" [--file path] [--line N] – Manually add a new task to the queue, optionally specifying file and line.
• echomancer task remove [task-id] – Remove a task by its ID.
• echomancer task update [task-id] --desc "New description" [--file path] [--line N] – Update a task's description or location.
• echomancer task info [task-id] – Show detailed information about a specific task.

6. Automation Workflow

1. Scan: echomancer analyze inspects your project for tasks and opportunities.
2. Code: Generates code patches using AI and project context.
3. Test: Runs only affected tests for efficiency.
4. Commit/Revert: Auto-commits successful changes, reverts on failure.
5. Learn: Adapts to your code style and improves over time.

7. AI Learning

AI learning is enabled by default in Echomancer. It analyzes your codebase, recognizes patterns, and adapts its code generation to match your project's style and conventions. This reduces the need for manual corrections and reviews, and helps maintain consistency as your project evolves. AI learning allows Echomancer to become more effective and context-aware over time, improving the quality and relevance of generated code.

8. Advanced Usage

• Run in single-instance mode for low-resource systems: echomancer start --single-instance
• Use test modes for faster feedback: echomancer start --test-mode affected-only
• Monitor logs in real time: echomancer logs --follow
• Assign roles and phases for advanced automation: echomancer roles --assign cursor-1 implementation
• Add custom roles: echomancer roles --add-custom movement --description "Handles player movement logic"
• Enable AI learning: echomancer learn --enable
• Set or query the current phase: echomancer phase --set implementation, echomancer phase --status
• Manually manage tasks: echomancer task add, echomancer task remove, echomancer task update, echomancer task list, echomancer task info

9. Troubleshooting

• System requirements not met: Run echomancer config to check and optimize.
• Project not found: Re-initialize with echomancer init in your project directory.
• High resource usage: Limit instances: echomancer config --max-instances 1
• Logs: Check ~/.echomancer/logs/ for detailed logs.

10. CLI Example

# Install Cursor (required)
# See https://www.cursor.so/ for installation instructions

# Project setup
cd /path/to/project
# Initialize with hardware detection and Cursor integration
echomancer init
# Configure as needed
echomancer config [--max-instances N]

# Start automation
echomancer start --phase implementation --role implementation [--single-instance] [--test-mode affected-only]

echomancer status   # Check running status
echomancer stop     # Stop automation

echomancer logs --follow [--instance-id ID]  # View logs in real time

11. Links

• Back to Home
• Download Releases
• GitHub Repository
• Main Site
• Cursor Website