EV-Agents

EV-Agents is a safety-first local AI agent orchestration layer for code changes.

It is designed to let AI agents propose patches while keeping the workflow controlled, reviewable, and recoverable through Git and GitHub.

What it does

EV-Agents runs a structured agent pipeline that can:

• analyse a coding goal
• build a patch for an approved file
• normalise and validate patch output
• verify patch applicability with git apply --check
• verify Python syntax with py_compile
• create preview branches for review
• support GitHub pull request workflows
• expose run state through a lightweight terminal UI

Why it exists

AI code generation is useful, but unsafe by default.

EV-Agents adds guardrails around AI-assisted development so changes are:

• restricted
• reviewable
• testable
• reversible
• mergeable through proper Git workflows

Core safety features

• patch output restricted to approved files
• markdown fence stripping and patch normalisation
• rejection of structural diffs such as /dev/null, new file mode, deleted file mode
• rejection of malformed or suspicious patches
• git apply --check before any branch workflow
• Python compile gate with py_compile
• preview-first workflow
• branch-based review instead of direct overwrite
• GitHub PR-friendly workflow
• no-op detection when the requested change is already satisfied
• anchor-based builder context to reduce hallucinated edits
• retry path for failed patch application attempts

Current workflow

Goal
→ Researcher
→ Planner
→ Builder
→ Patch hygiene
→ Patch safety checks
→ Goal/patch validation
→ git apply --check
→ Compile check
→ Preview branch
→ GitHub PR / merge

Repository scope

EV-Agents is focused on safe agent orchestration for local development workflows.

This repository is not intended to be:

• a full autonomous coding platform
• a hosted multi-tenant agent service
• a replacement for human code review
• a universal patch engine for unrestricted repositories

Current use case

EV-Agents is currently used as the agent orchestration layer for the broader EV Core ecosystem.

It was built and tested in a local Linux environment and is designed to work well with Git-based review workflows and local AI model integrations.

Requirements

• Python 3.10+
• Git
• a valid Gemini API key for the configured models
• a local repository you want to operate on safely

Environment variables

Create a .env file based on .env.example.

Example variables:

• GEMINI_API_KEY
• GEMINI_MODEL
• EVCORE_CTX_CHARS

Quick start

Install dependencies:

pip install -r requirements.txt

## Documentation

Project design documents are available in `/docs`:

- **AI_ORIENTATION.md** – context for AI systems assisting development
- **long_term_roadmap.md** – long-term architecture and system evolution