Guided Tutorials

Create an Evolve Pipeline

Set up Autohand Evolve to continuously improve your codebase with automated refactoring and optimization. Evolve runs on a schedule, identifies improvement opportunities, and creates pull requests for your team to review and approve.

Advanced 30 min

autohand "Set up an Evolve pipeline that runs nightly to identify code smells, suggest refactoring opportunities, and create PRs for approved improvements."

What you'll learn

How to write evolution rules that target specific code improvement patterns
How to configure a scheduled Evolve pipeline with cron syntax
How to review, approve, and auto-merge Evolve-generated pull requests
How to create custom evolution targets for project-specific patterns

Before you start

Autohand Code installed
An Autohand Team or Enterprise account (Evolve uses scheduled background agents; contact sales)
A GitHub or GitLab repository with a token that can create branches and open pull requests
A passing test suite (Evolve only creates PRs when tests pass)
An AGENTS.md with project context so Evolve follows your conventions

Tip: Run Evolve manually a few times before scheduling it. The first few runs let you calibrate the evolution rules and review quality before you start waking up to automated PR notifications every morning.

What is Autohand Evolve

Evolve is a scheduled improvement loop. Each run follows the same cycle: analyze your codebase against your evolution rules, identify areas that match an improvement target, implement changes in an isolated branch, run your tests, and open a pull request if tests pass.

What makes Evolve different from a one-shot refactoring session is that it accumulates improvements incrementally over weeks and months. Each PR is small and focused on one type of improvement. Your team reviews and merges them at their own pace. Over time the codebase gradually trends toward the quality targets you defined.

Typical evolution targets include:

Functions longer than 50 lines that can be extracted into smaller functions
Duplicated logic across modules that belongs in a shared utility
Missing error handling in async functions that currently let rejections go unhandled
Inconsistent naming conventions across files written at different times
Outdated API usage where a newer, simpler approach is available

Configure the evolution rules

Evolution rules live in a file at the root of your project called .autohand/evolve.json. Create it with Autohand.

Here is a representative evolve.json for a Node.js API project.

Set up the schedule

The schedule field in evolve.json uses standard cron syntax. "0 2 * * *" means 2:00 AM UTC every day.

For most teams, a nightly run is the right cadence. It gives Evolve time to find improvements without flooding your PR queue. Some teams prefer weekly runs on Sunday night so the queue is fresh at the start of the work week.

After evolve init, Autohand adds a webhook to your repository. This allows it to trigger runs on schedule and post status updates when a PR is created.

Review generated proposals

After the first run, Evolve opens pull requests against your base branch. Each PR targets one rule and includes a description of what was changed and why.

A typical Evolve PR description looks like this.

Review these PRs the same way you review human-authored refactoring PRs. Check that the behavior is unchanged, that the new function names are clear, and that the split makes logical sense. Approve and merge the ones you agree with. Close the ones you do not.

Tip: If you consistently reject PRs from a specific rule, either tighten the rule's match criteria or disable it. Evolve learns from your merge patterns over time, but explicit configuration is faster than waiting for it to infer your preferences.

Approve and merge

Evolve PRs go through your normal review process. You can add required reviewers, status checks, or any other branch protection rules you use for regular PRs.

If you want to add an automated approval gate for low-risk changes, you can configure Evolve to auto-merge PRs that meet specific criteria.

With this configuration, add-missing-error-handling PRs that change three or fewer files auto-merge after CI passes. All other rules still require human approval.

Most teams start with auto-merge disabled and enable it selectively after they have reviewed a few runs of each rule and are confident in the quality.

Monitor improvements over time

The Autohand platform tracks metrics across every Evolve run. Check them via the CLI or the web dashboard.

The summary output looks like this.

A high rejection rate on a specific rule is a signal to refine its criteria. Ask Autohand to help you tighten the rule based on your closed PRs.

Customize evolution targets

Beyond the built-in improvement types, you can define custom targets for project-specific patterns.

Migrate a deprecated internal API to a new one.

Enforce a consistent response shape across all API handlers.

Tip: Provide a reference_file for pattern-matching rules whenever you have a file that represents the ideal implementation. Evolve uses it as the transformation template, which produces much more consistent output than a purely textual instruction.

What you learned

You created an evolve.json configuration with rules targeting specific code improvement patterns
You registered a scheduled Evolve pipeline that runs on a cron schedule and creates pull requests
You configured auto-merge conditions for low-risk rules and reviewed generated proposals
You wrote custom evolution targets for project-specific migrations and consistency enforcement

Try next autohand "Review the last 5 Evolve PRs for this repository. Identify any patterns in the rejected ones and suggest improvements to evolve.json to reduce false positives."