messirve 0.1.0

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 and onboard your project:

   # Initialize messirve configuration
   messirve init
   
   # Onboard: detect tech stack, explore codebase with Claude Code
   messirve onboard
   

2. Plan your tasks interactively:

   # Start a planning session to generate tasks from goals
   messirve planning
   

   Or create a tasks file manually (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
   

Typical Workflow

# 1. First time setup
messirve init              # Create .messirve/ config
messirve onboard           # Explore codebase, generate context

# 2. Plan your sprint/tasks
messirve planning          # Interactive: goals -> tasks

# 3. Execute tasks
messirve run               # Execute all tasks
messirve run --dry-run     # Preview what would run

# 4. Analyze code quality
messirve analyze --before main   # Check for regressions

CLI Reference

Project Onboarding

# Onboard to a project (recommended first step)
# This explores the codebase with Claude Code and generates context
messirve onboard

# Quick detection only (skip Claude Code exploration)
messirve onboard --skip-exploration

# Force regenerate context
messirve onboard --force

# Skip setup/verification commands
messirve onboard --skip-setup --skip-verify

Task Planning

# Interactive planning session - generate tasks from high-level goals
messirve planning

# With pre-specified goals
messirve planning -g "Add user authentication" -g "Improve test coverage"

# Non-interactive mode (for CI/scripting)
messirve planning --goal "Add caching" --non-interactive -o tasks.yaml

# Specify output file
messirve planning -o my-sprint-tasks.yaml

Running Tasks

# 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

# Run with code analysis
messirve run --analyze

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

Project Context

# Generate context from auto-detection (without Claude Code exploration)
messirve context generate

# Force regenerate
messirve context generate --force

# Show current context
messirve context show
messirve context show --format yaml

# Edit context file in your editor
messirve context edit

# Set specific context values
messirve context set description "My project description"
messirve context set business_description "Enterprise solution for..."

Code Analysis

# Analyze current directory
messirve analyze

# Analyze specific paths
messirve analyze src/ tests/

# Compare against a git ref (e.g., detect regressions)
messirve analyze --before main

# Output to file
messirve analyze --output report.json --format json
messirve analyze --output report.md --format markdown

# Fail CI if regression detected
messirve analyze --before main --fail-on-regression

# Disable specific analysis
messirve analyze --no-complexity
messirve analyze --no-quality

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

Templates

# List available task templates
messirve list-templates

# Show template details
messirve show-template api-endpoint

# Generate tasks from template
messirve generate api-endpoint --output tasks.yaml

# List available task flavors
messirve list-flavors

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.