messirve 0.0.3

A CLI tool that orchestrates Claude Code to execute development tasks autonomously

Messirve

A CLI tool that orchestrates Claude Code to execute development tasks autonomously in a loop. It takes a list of Jira-like tasks from a YAML file and executes them one-by-one using Claude Code, with comprehensive logging, git integration, and quality gates.

Features

• Sequential Task Execution: Execute tasks in dependency order
• YAML Task Files: Define tasks using a simple, structured YAML format
• Git Integration: Multiple git strategies (commit-per-task, branch-per-task, etc.)
• Hooks System: Run commands before/after tasks and runs
• Retry Logic: Configurable retry attempts with delays
• Comprehensive Logging: Per-task and master logs in JSON and Markdown
• Quality Gates: Post-task hooks for testing and linting
• Rich CLI: Colored output with multiple verbosity levels

Installation

pip install messirve

Or with pipx:

pipx install messirve

Quick Start

1. Initialize messirve in your project:

   messirve init
   

2. Create a tasks file (tasks.yaml):

   version: "1.0"
   tasks:
     - id: TASK-001
       title: "Add user authentication"
       description: |
         Implement JWT-based authentication for the API.
       context: |
         We're using FastAPI with SQLAlchemy.
       acceptance_criteria:
         - "POST /auth/login returns JWT token"
         - "Unit tests cover all auth endpoints"
   

3. Run the tasks:

   messirve run
   

CLI Reference

Main Commands

# Run all tasks
messirve run

# Run tasks from specific file
messirve run --tasks path/to/tasks.yaml

# Run specific task(s)
messirve run --task TASK-001 --task TASK-002

# Dry run (show what would execute)
messirve run --dry-run

# Run with different git strategy
messirve run --git-strategy branch-per-task

# Run with different verbosity
messirve run --quiet          # Minimal output
messirve run -v               # Normal (default)
messirve run -vv              # Verbose
messirve run -vvv             # Debug

# Continue from failed task
messirve run --continue

Task Management

# Create a new task interactively
messirve create-task

# Create task with inline values
messirve create-task --id TASK-003 --title "Add feature X"

# List tasks
messirve list-tasks
messirve list-tasks --tasks path/to/tasks.yaml

# Show task details
messirve show-task TASK-001

# Validate task file
messirve validate --tasks path/to/tasks.yaml

Configuration

# Initialize messirve in current project
messirve init

# Show current configuration
messirve config show

# Set configuration value
messirve config set defaults.max_retries 5

# Add a rule
messirve config add-rule "Use async/await for I/O operations"

# Add a boundary
messirve config add-boundary "*.secret" --type never_modify

Logs and Reports

# Show execution history
messirve logs

# Show specific run
messirve logs --run 2024-01-20-143052

# Show specific task log
messirve logs --task TASK-001 --run 2024-01-20-143052

# Export report
messirve report --format json --output report.json
messirve report --format markdown --output report.md

Task File Format

version: "1.0"

tasks:
  - id: TASK-001
    title: "Add user authentication"
    description: |
      Implement JWT-based authentication for the API.
      This includes login, logout, and token refresh endpoints.
    context: |
      We're using FastAPI with SQLAlchemy.
      The User model already exists in models/user.py.
    acceptance_criteria:
      - "POST /auth/login returns JWT token on valid credentials"
      - "POST /auth/logout invalidates the token"
      - "Unit tests cover all auth endpoints"
    depends_on: []
    hooks:
      pre_task:
        - "ruff check src/"
      post_task:
        - "pytest tests/auth/"

  - id: TASK-002
    title: "Create user dashboard endpoint"
    description: |
      Create a GET /dashboard endpoint that returns user stats.
    context: |
      Requires authentication from TASK-001.
    acceptance_criteria:
      - "GET /dashboard returns user profile data"
      - "Requires valid JWT token"
    depends_on:
      - TASK-001

Task Fields

Field	Type	Required	Description
id	string	Yes	Unique task identifier
title	string	Yes	Short task title
description	string	Yes	Detailed task description
context	string	Yes	Project context, existing code references
acceptance_criteria	list[string]	Yes	List of criteria to verify completion
depends_on	list[string]	No	List of task IDs that must complete first
hooks.pre_task	list[string]	No	Commands to run before this task
hooks.post_task	list[string]	No	Commands to run after this task

Configuration File

Configuration is stored in .messirve/config.yaml:

version: "1.0"

defaults:
  max_retries: 3
  retry_delay_seconds: 5
  verbosity: normal
  git_strategy: branch-per-task
  base_branch: main
  create_pr: false
  claude_code_permissions: skip

hooks:
  pre_run:
    - "echo 'Starting messirve execution'"
  post_run:
    - "echo 'Execution complete'"
  pre_task:
    - "ruff check src/ --fix"
  post_task:
    - "pytest tests/ -x -q"

rules:
  - "Use type hints for all functions"
  - "Follow PEP 8 conventions"
  - "Write docstrings for public functions"

boundaries:
  never_modify:
    - "poetry.lock"
    - ".env"
  read_only:
    - "pyproject.toml"

Git Strategies

Strategy	Description
none	No git operations (user manages git)
commit-per-task	Auto-commit after each task on current branch
branch-per-task	Create new branch per task (messirve/{task-id}-{slug})
single-branch	All work on one branch (messirve/run-{timestamp})

Logging

Messirve creates comprehensive logs in .messirve/logs/:

.messirve/logs/
├── master.json                    # Master log with all runs
└── runs/
    └── 2024-01-20-143052/        # Run ID
        ├── run.json               # Run metadata & summary
        ├── TASK-001.json          # Task log (JSON)
        ├── TASK-001.md            # Task log (Markdown)
        └── ...

Architecture

See ARCHITECTURE.md for detailed architecture documentation.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: poetry run pytest
5. Run linting: poetry run ruff check src/ tests/
6. Submit a pull request

License

MIT License - see LICENSE for details.