〈 XEC 〉

Developer CLI tool for local LLM patching

Xec is a local developer CLI agent that continuously repairs failing workflows instead of stopping on the first error. Xec is an agentic orchestrator that uses local LLMs running on the developer's machine to patch developer-defined workflow schemas.

Instead of manually reading stack traces, searching logs, and iterating on fixes, developers define executable workflows in a Xecfile. Xec then executes each step, monitors for failures, and automatically attempts recovery when something breaks.

Not every task needs to be executed in a Claude Code, Codex, or Cursor interface. Repeatedly sending errors and source code to cloud-hosted AI tools for common development issues is sometimes simply a waste of tokens.

Xec is designed exactly for this purpose: to reduce the LLM and opportunity cost of repetitive simpler debugging loops.

On top of automated debugging, Xec acts as a local workflow runner. Multi-step development tasks that normally require several commands can be captured once in a Xecfile and executed with a single command. Xec handles orchestration, failure recovery, and retries across the entire workflow.

You define your build, test, and run steps in a simple xecfile — like a Dockerfile or CI pipeline, but living on your machine. When something breaks, xec extracts stack traces to pull in relevant source context, and asks a local LLM (via Ollama) to determine out what went wrong.

Depending on the failure, Xec can:

• Apply code patches
• Execute recovery commands
• Resolve dependency issues
• Retry failed workflow steps
• Escalate to developer for more complex tasks

No cloud API keys required. All that's required is your repo, and a model running locally.

Warning

Xec edits source files directly when it applies code fixes, and may run shell commands suggested by the model for environment issues. Use version control, review changes before committing, and run xec in a repo you are comfortable modifying.

Note

See ARCHITECTURE.md for the full breakdown on how Xec works.

Prerequisites

• Ollama running locally (default http://localhost:11434)
• A pulled model matching your xecfile (e.g. ollama pull llama3.1)

Install

Prebuilt (recommended):

Download the binary for your OS from GitHub Releases and add it on your PATH.

xec version

From Go module:

go install github.com/SatvikVejendla/xec@latest

Requires Go 1.22+. @latest installs the newest tagged release. Ensure $(go env GOPATH)/bin is on your PATH.

From a clone (development):

git clone https://github.com/SatvikVejendla/xec.git
cd xec
make install   # stamps version from git describe (e.g. v0.1.0 on a tagged checkout)

Plain go install . from a clone works but prints dev unless you build from a tagged commit with ldflags. Prefer make install when working from source.

Build locally without installing:

make build    # outputs bin/xec

Quick start

1. Create a xecfile (manually, from a Dockerfile, or as a default):

xec init                      # parses ./Dockerfile if it exists. otherwise initializes an empty template xecfile
xec init path/to/Dockerfile   # parses from ./path/to/Dockerfile

2. Run the workflow:

xec run                     # reads from ./xecfile, ./xecfile.yaml, or ./xecfile.yml
xec run -f xecfile.yaml     # reads from custom named xecfiles
xec run -f ./my-project/    # reads xecfile, xecfile.yaml, or xecfile.yml in directory

On first run, if the chosen model is missing, xec prompts user to pull it. It is recommended to have an existing pulled model, however.

Xecfile

Minimal example:

name: my-app

config:
  model:
    provider: Ollama
    model: llama3.1

steps:
  - npm test
  - python main.py

post_step: npm run dev   # optional (for continuous blocking commands); runs once after workflow succeeds

See EXAMPLES.md for what each file in examples/ does.

Config reference

All fields under config are optional unless noted. Defaults are applied on xec run.

Section	Field	Default	Notes
model	provider	—	Required. Currently Ollama
	model	—	Required. Ollama model name
	base_url	http://localhost:11434
	api_key	—	For remote Ollama
	temperature	0.5	(0, 1]
	max_completion_tokens	2048
context	stack_trace_limit	3	Frames extracted per failure
	context_radius	5	Lines of source around each frame
injector	retry_limit	3	LLM fix attempts per failure
	escalation_threshold	0.7	Min confidence to apply a fix
orchestrator	max_iterations	10	Outer retry loop cap
	stagnation_count	1	Successful passes before done
	restart_on_fix	false	Re-run all steps after a patch
	allow_stacking_errors	false	Continue past first failing step
logging	level	info	debug, warn, error, silent
	path	—	Write logs to file instead of stdout

Commands

Command	Description
xec run	Execute workflow steps
xec init [dockerfile]	Generate xecfile.yaml from a Dockerfile
xec version	Print version

xec run flags

Flag	Description
-f, --file	Path to xecfile or directory (default: xecfile)
-d, --debug	Debug logging
-w, --warn	Warn-level logging
-e, --error	Error-level logging
-s, --silent	No logging

CLI log flags override the level set in the xecfile.

Development

Requires Go 1.22+.

git clone https://github.com/SatvikVejendla/xec.git
cd xec
make build
make test
make coverage
make check
make run ARGS="run -f examples/xecfile.yaml"

See CONTRIBUTING.md for development and PR guidelines.