A deterministic AI coding engine featuring AST syntax validation, atomic diff patching, and approval gating.
🧠 Intelligence • 🛠️ Tools • 🛡️ Verification
Uncontrolled LLM code generation often suffers from hallucinated syntax, destructive accidental file overwrites, and unreviewed modifications. Micro Coding Agent solves these challenges by enforcing a strict four-stage verification loop:
- Pre-flight Dry-Run: Computes precise unified diffs in memory before touching disk.
- Human-in-the-Loop Gating: Allows developers or policy hooks to inspect and approve diffs.
- Atomic Modification: Replaces exact target chunks rather than rewriting entire files.
- Post-write AST Verification: Uses Python's Abstract Syntax Tree (
ast) parser to verify syntax integrity before declaring success.
Goal ──► Planner ──► Workspace Reader ──► Diff/Patch ──► Approval Gate ──► AST Verification ──► Result
Indexes repository files while automatically filtering standard ignore directories (.git, __pycache__, virtualenvs) and preventing directory traversal escapes.
Generates unified diffs (difflib), runs in-memory dry-run validations, and applies targeted text replacements atomically.
Parses modified Python source files with ast.parse to catch SyntaxError exceptions and broken code blocks before finalizing changes.
Provides programmable callback hooks and interactive approval prompts to authorize or reject proposed unified diffs.
Exposes cleanly typed tools (list_workspace_files, read_file, preview_patch, verify_file_syntax) ready for LLM tool calling interfaces.
# Clone repository
git clone https://github.com/dax0056/micro-coding-agent.git
cd micro-coding-agent
# Install with development dependencies
pip install -e .[dev]from pathlib import Path
from coding_agent import MicroCodingAgent, CodingPlanner
# Initialize agent in target repository
agent = MicroCodingAgent(workspace_dir=Path("./my_project"), auto_approve=True)
planner = CodingPlanner()
# Plan an atomic refactoring
plan = planner.plan_refactor(
task="Update math helper function to return float",
file_path="math_utils.py",
old_code="return int(a / b)",
new_code="return float(a / b)"
)
# Apply and verify
result = agent.apply_plan(plan)
print(f"Success: {result.success}, Message: {result.message}")
Here is the actual execution trace run directly from the Python test harness:
[CodingAgent] Received task: "Update math helper function to return float"
[WorkspaceReader] Indexed 14 files in workspace root.
[PatchEngine] Running DRY-RUN diff on 'math_utils.py'...
--- a/math_utils.py
+++ b/math_utils.py
@@ -10,3 +10,3 @@
def compute_ratio(a: int, b: int) -> float:
- return int(a / b)
+ return float(a / b)
[ApprovalGate] Reviewing patch -> Decision: APPROVED (auto_approval_policy)
[PatchEngine] Applying atomic patch to disk -> math_utils.py updated.
[CodeVerifier] Running AST syntax parser on 'math_utils.py' -> AST syntax valid!
[CodingAgent] Task completed successfully: 1 modification applied and verified.
Micro Coding Agent includes 12 automated unit tests covering all core engine components:
============================= test session starts =============================
tests/test_approval_gate.py::test_approval_gate_auto_approve PASSED [ 8%]
tests/test_approval_gate.py::test_approval_gate_rejects_empty_diff PASSED [ 16%]
tests/test_approval_gate.py::test_approval_gate_custom_callback PASSED [ 25%]
tests/test_coding_agent.py::test_micro_coding_agent_end_to_end_flow PASSED [ 33%]
tests/test_coding_agent.py::test_micro_coding_agent_handles_syntax_failure PASSED [ 41%]
tests/test_patch_engine.py::test_patch_engine_dry_run_and_apply PASSED [ 50%]
tests/test_patch_engine.py::test_patch_engine_create_new_file PASSED [ 58%]
tests/test_patch_engine.py::test_patch_engine_mismatch_fails PASSED [ 66%]
tests/test_verifier.py::test_code_verifier_valid_syntax PASSED [ 75%]
tests/test_verifier.py::test_code_verifier_syntax_error PASSED [ 83%]
tests/test_workspace_reader.py::test_workspace_reader_listing PASSED [ 91%]
tests/test_workspace_reader.py::test_workspace_reader_read_file PASSED [100%]
============================= 12 passed in 0.10s ==============================
- Passed:
12 / 12(100%) - Test Command:
pytest -v
- Milestone development plan: ROADMAP.md
- Release notes and version history: CHANGELOG.md
- Contribution guidelines: CONTRIBUTING.md
- Security reporting policy: SECURITY.md
Micro Coding Agent provides the Code Intelligence & Verification Tools for the series:
- 🧠 nexus-agent — Intelligence & Local Agent Core
- 💻 micro-coding-agent — Deterministic Code AST & Patch Engine
- 🖥️ desktop-action-agent — Safe Sandboxed Desktop Automation
Distributed under the MIT License. See LICENSE for details.