DevAgent

A local, evidence-driven software engineering agent that turns a requirement into a tested, independently reviewed patch, prints a developer-grade engineering report, and only publishes a branch when the result is VERIFIED.

From requirement to evidence-backed verified branch.

DevAgent runs against a developer's local repository. It discovers the application, gathers source evidence, compiles explicit acceptance criteria, plans a bounded change, creates backups, implements the minimum necessary patch, runs repository-supported verification, independently reviews the final diff, and decides VERIFIED, PARTIALLY_VERIFIED, or BLOCKED from evidence rather than model confidence.

For a normal verified run the deterministic harness prints the complete engineering report first, then commits reviewed paths and fast-forward pushes the developer's current non-protected branch. If the developer starts on main, master, or trunk, DevAgent creates a new safe branch instead. Runtime DevAgent never creates a pull request, merges, rebases, force-pushes, or deploys.

Why DevAgent?

Many coding agents optimize first for code generation. DevAgent is built around a different question:

Can this change be supported by repository evidence and verified on the current revision?

Core principles:

• Evidence before modification — insufficient source evidence blocks implementation.
• Explicit acceptance contracts — required criteria are SATISFIED, UNPROVEN, or CONTRADICTED; passing tests do not blanket-prove unrelated requirements.
• False-VERIFIED resistance — unsupported required criteria, missing final verification, known regressions, failed review, or source-state violations prevent a trustworthy success result.
• Minimal-change discipline — prefer the smallest correct diff over broad speculative refactors.
• Backups before edits — existing files are backed up before first modification.
• Local-first isolation — clean repositories use retained external detached worktrees by default; dirty developer work is protected.
• Repository-native verification — manifests, package scripts, test layouts, build files, and bounded CI evidence determine verification capabilities.
• Independent review — the final diff is reviewed separately from implementation.
• Developer-grade reporting — implementation logic, symbols, tests, acceptance evidence, verification, failures, gaps, and source-control status are recorded before publication.
• Bring your own model — OpenAI, Anthropic/Claude, xAI/Grok, Google Gemini, and OpenAI-compatible endpoints use one engineering workflow.
• Deterministic branch publication — only a VERIFIED isolated run can be committed and normally fast-forward pushed; --no-publish keeps the result local.

Install

From PyPI:

python -m pip install devagent-ai

For an isolated CLI installation:

pipx install devagent-ai

For development from source:

git clone https://github.com/tomha85/devagent.git
cd devagent
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest -q

The PyPI distribution is devagent-ai; the Python package and CLI command are both devagent.

Configure a provider

OpenAI:

devagent setup --provider openai --model YOUR_MODEL
export OPENAI_API_KEY=...
devagent doctor
devagent doctor --live

Anthropic / Claude:

devagent setup --provider anthropic --model YOUR_MODEL
export ANTHROPIC_API_KEY=...
devagent doctor

xAI / Grok:

devagent setup --provider xai --model YOUR_MODEL
export XAI_API_KEY=...
devagent doctor

Google Gemini:

devagent setup --provider gemini --model gemini-3.7-flash
export GEMINI_API_KEY=...
devagent doctor

Gemini uses Google's documented OpenAI-compatible Gemini endpoint so DevAgent can reuse the same bounded provider interface and deterministic local schema validation. --provider google is an alias for the same integration.

OpenAI-compatible local or private endpoint:

devagent setup \
  --provider compatible \
  --model local-model \
  --base-url http://127.0.0.1:11434/v1

DevAgent stores the provider configuration and the name of the API-key environment variable. It does not store the API key itself.

Model routing by engineering role

DevAgent can use one default model or route different models to stable roles:

investigator → understand repository/problem
planner      → produce bounded implementation/verification plan
implementer  → implement, diagnose, repair/replan
reviewer     → independently review final diff

The deterministic harness remains responsible for safety, tool execution, verification validity, acceptance adjudication, final status, reporting, and source-control publication regardless of which model handles a role.

Run

From the application repository:

devagent "Fix websocket reconnect bug and add regression tests"

For a normal VERIFIED result:

DISCOVER / UNDERSTAND
        ↓
COMPILE ACCEPTANCE CONTRACT
        ↓
BASELINE / PLAN / GATHER CONTEXT
        ↓
IMPLEMENT MINIMAL PATCH
        ↓
TARGETED + BROAD VERIFICATION
        ↓
DIAGNOSE / REPLAN if needed
        ↓
INDEPENDENT REVIEW
        ↓
FINAL CURRENT-REVISION VERIFICATION
        ↓
FULL ENGINEERING REPORT
        ↓
VERIFIED ONLY: COMMIT + FAST-FORWARD PUSH BRANCH
        ↓
STOP — NO PR, NO MERGE

Repeated prompts on a normal local development branch continue that same branch when local/remote history is safely compatible. A protected starting branch (main, master, trunk) causes a new branch such as:

devagent/20260825T020000Z-ab12cd

Explicitly start a new branch:

devagent \
  --publish-branch feature/devagent-csv-export \
  "Add CSV export to reports"

Run without commit/push:

devagent --no-publish "Add CSV export to reports"

Long requirements can be read from any bounded UTF-8 text file path; the filename extension is unrestricted:

devagent --input requirements/customer-feature.md
devagent --input ./task
devagent --input ../specs/release.requirement

Binary data, invalid UTF-8, secret-like paths, and files above the input-size bound are refused.

Useful commands:

devagent --help
devagent --version
devagent setup --help
devagent doctor
devagent models
devagent status
devagent benchmark --help

Pinned real-world benchmark

DevAgent 0.5 adds an opt-in benchmark runner for pinned GitHub repositories. A benchmark case injects a deterministic defect into an exact commit and uses an external oracle before and after DevAgent. This avoids treating DevAgent's own report as the benchmark oracle.

devagent benchmark \
  --catalog /path/to/realworld-cases.json \
  --report .devagent/realworld-benchmark.json

A VERIFIED result with a failing external oracle is explicitly counted as a false VERIFIED. See docs/realworld-benchmark.md for the catalog contract and safety boundary.

Outcome contract

VERIFIED

Used only when required acceptance criteria are satisfied by admissible evidence, applicable final verification passes on the current revision, no known new regression remains, scope is acceptable, and independent review approves the final diff.

Only VERIFIED is eligible for automatic commit/push.

PARTIALLY_VERIFIED

Used when meaningful implementation evidence exists but complete proof cannot be obtained, for example because of unavailable hardware, VPNs, credentials, external services, or environment limitations.

It is never auto-published.

BLOCKED

Used when DevAgent cannot safely understand, implement, or verify the request. It is never auto-published.

A truthful conservative result is preferable to a false VERIFIED.

Safety boundary

DevAgent uses defense-in-depth controls around repository modification, command execution, and publishing:

• external isolated worktrees for clean repositories by default;
• dirty tracked and real untracked developer files are protected;
• backups before first file modification;
• workspace confinement and symlink-escape checks;
• secret-like path exclusions;
• engineering commands executed as argv without a general shell;
• credential environment scrubbing for verification where appropriate;
• model-facing command policy blocks Git write operations;
• publication is a separate deterministic post-report step and disables repository-controlled Git hooks for commit/push;
• only reviewed changed paths are staged;
• remote branch state is captured and rechecked to block publication races;
• protected targets are refused and force push is never used;
• no runtime PR, merge, rebase, force-push, or deployment automation.

DevAgent is not an operating-system sandbox. Review the report and pushed branch before integrating customer or production code.

Repository intelligence and verification

Discovery understands common evidence from:

• Python: pyproject.toml, requirements, pytest/unittest conventions;
• JavaScript/TypeScript: package.json, scripts, TypeScript configuration, React/Vite/Next-style repositories;
• Go: go.mod;
• Rust: Cargo.toml;
• Java: Maven/Gradle;
• C/C++: CMake/Make/Meson;
• .NET: solution/project files;
• CI: GitHub Actions, Jenkins, GitLab CI, Azure Pipelines;
• multi-component repositories and repository documentation.

Verification can include baseline tests, targeted tests, component/broad checks, integration/e2e commands, builds, lint/type checks, and git diff --check. Every verification result records phase and revision so an edit invalidates success from an older tree.

Production qualification

DevAgent 0.5.0 uses production qualification v4. It extends the v3 release gate with large-repository bounded-retrieval and real-world benchmark truthfulness contracts while preserving the primary invariant:

false_verified == 0

It covers end-to-end engineering behavior, acceptance truthfulness, task scope, provider contracts/parity, model routing, worktree and Git publication safety, CLI input, review/repair loops, report/evaluation integrity, release integrity, and actual repository-native toolchain execution for:

Python / pytest
Node + TypeScript repository discovery
Go
Rust / Cargo
C++ / Make

Run the release qualification locally on a machine with those toolchains:

python -m devagent.qualification \
  --catalog evaluation/benchmark_v4.json \
  --report .devagent/production-qualification-v4.json

Production CI runs Python 3.10/3.11/3.12, a clean wheel install, and this production qualification gate. The qualification JSON is retained as CI evidence.

100% qualified means 100% of this explicit catalog passed. It does not mean mathematical correctness for every unseen repository, environment, model response, language, or engineering task.

See docs/production-readiness.md for the evidence behind the 0.4.0 production-readiness assessment and its explicit limitations.

Provider architecture

Currently supported:

Provider choice affects reasoning quality, cost, latency, and privacy characteristics. It does not change DevAgent's deterministic acceptance, safety, verification, reporting, and publication rules. devagent models labels deterministic adapter status as CONTRACT-QUALIFIED or SUPPORTED; devagent doctor --live is the explicit real API/model structured-output readiness probe and consumes provider usage.

Engineering report

The report is emitted before source-control publication and includes:

• implementation logic summary first;
• requirement, task type, and risk;
• root cause or design gap;
• implementation decisions;
• deterministically extractable changed symbols and test cases;
• acceptance criteria with status, evidence, and reasons;
• verification matrix with command, phase, revision, exit code, duration, and test counts;
• failed-check output and failure classification;
• independent-review result;
• completeness and known gaps;
• recommendations;
• source-control plan/status and developer review checklist.

After a successful verified publication, a separate receipt records remote, branch, exact commit SHA, committed/pushed status, and confirms no PR or merge was performed.

Local run data

Run artifacts are stored under the target repository's .devagent/ state, including metadata, per-run backups, observations, verification records, report.json, retained worktrees, and evidence-backed repository/strategy memory.

Repository facts carry source fingerprints so stale evidence can be invalidated when source files change.

Development

python -m compileall -q devagent
pytest -q
git diff --check
python -m devagent.qualification

Automated provider tests normally use deterministic or mocked clients and do not consume cloud-model credits. Source-control tests use disposable local Git repositories. Production qualification deliberately executes its real local toolchain fixtures.

Project status

DevAgent 0.5 is beta software. Its qualification and benchmark results are bounded claims tied to explicit cases, pinned revisions, and external oracles; they are not a claim of universal correctness or parity with every hosted coding platform.

Remaining gaps include a larger published corpus of pinned upstream benchmark cases, browser/UI runtime qualification, a broader Java/.NET/database-migration matrix, very large monorepo stress runs above the current bounded inventory, parallel multi-agent orchestration, operating-system sandboxing, and continuous paid real-provider testing across every model/provider combination.

The project intentionally prioritizes trustworthy outcomes over feature count.

Contributing

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. Changes to safety, verification, reporting, acceptance semantics, providers, or bounded publication behavior should include regression evidence and must not give model-generated actions unrestricted Git publishing authority.

Security

Please do not publish sensitive vulnerability details in a public issue. See SECURITY.md for the reporting process and security scope.

License and attribution

DevAgent is open source under the MIT License.

Copyright (c) 2026 Tom Ha

DevAgent was created by Tom Ha. Original repository: https://github.com/tomha85/devagent. See NOTICE and COPYRIGHT for project attribution.