Back to blog
X24LABS

Getting started with Stitch 2.0

A practical walkthrough of Stitch 2.0: install, run, watch. No config files, no API keys, no new pipeline jobs. Just your existing CI, running locally, with an AI agent on call.

Stitch 2.0 is a local-first CLI. It reads the CI config already in your repository, runs the same jobs on your machine, and hands any failure to an AI agent (Claude Code or Codex) to fix. This post is the five-minute version of the documentation.

Prerequisites

That is the entire dependency list. Stitch does not need an API key, a Docker image, or a platform token. It runs as you, on your machine, with the agent that is already signed in.

Install and run

There is no install step. The package is published on npm. Run it directly:

npx stitch-agent run claude

Or, if you prefer Codex:

npx stitch-agent run codex

On first run, Stitch will detect which CI config you have, parse it, and show you the jobs it is about to run. Infrastructure jobs (deploy, publish, release, image pushes) are filtered out automatically. Verify jobs (lint, typecheck, test, build) are the ones that run locally.

The terminal switches into an interactive TUI. You will see:

You can watch or walk away. Stitch will stop at the first green full pipeline, at the attempt ceiling (default three attempts per job), or at the first thing it decides to escalate to you.

What happens when a job fails

Stitch hands the failing job to your agent with a short prompt and the relevant context. The agent does its thing: it reads the files in the error, it tries a fix, it tells Stitch to re-run the job. Stitch validates by actually re-running the same job. If the re-run passes, the attempt counts as a fix. If it fails, the agent tries again, up to the per-job ceiling.

The loop is bounded on purpose. If three attempts do not land a fix, Stitch stops and shows you the state: the last diagnosis, the last patch, the last log. You take over with full context.

Commit and push

When a fix cycle ends with every job green, Stitch can commit and push the result. This only happens if two conditions are true:

  1. You were on a clean branch when Stitch started. If there were uncommitted changes, Stitch leaves the working tree alone. Your in-progress work is not touched, ever.
  2. You asked for auto-commit. Off by default. The flag is --auto-commit.

This is deliberately conservative. The fastest way to lose trust in a tool like Stitch is to have it overwrite your local work. We would rather you opt in than wonder what happened.

Watch mode

For tight iteration loops, Stitch can stay running and re-verify on file changes:

npx stitch-agent run claude --watch

In watch mode, saving a file triggers a re-run of the affected jobs. You edit, you save, you see green or red in the TUI in seconds, without leaving your editor. This replaces the “push to see if CI is happy” habit with “save and see.”

Configuration, if you want it

Zero config is the default and it handles most repositories. If you want to tune behavior, drop a .stitch.yml at the repo root:

max_attempts: 3
auto_fix: [lint, format, simple_types, config_ci]
escalate: [logic_errors, breaking_changes, dependency_conflicts]

You do not need this file to use Stitch. It exists for teams that want explicit policy.

What Stitch is not

Stitch does not replace your CI. The remote pipeline still runs on push. Stitch just gives you a faster, local, AI-assisted version of the same thing, so you can arrive at the push with confidence instead of hope.

Stitch does not train on your code. It does not phone home. There is no telemetry to turn off because there is nothing reporting anywhere. Logs and fixes stay local unless you explicitly configure a notification channel.

Stitch does not need a subscription for itself. The only paid service in the loop is the agent (Claude Code or Codex), and that is billed to the account you already have.

Where to go next

The repository is on GitHub at x24labs/stitch. Issues are tracked there. The npm package is stitch-agent. The rest is in the code and in the previous posts in this series, which explain why v2 looks the way it does.

If you try it and something breaks, open an issue. The point of local-first is that you have everything you need to reproduce the problem in front of you.

Back to blog