Building a Repository-Aware AI Coding Loop in Rust

Most AI coding examples stop after generating code. The model receives a prompt, returns a proposed implementation, and the application prints the result. That is useful for experimentation, but it is not a complete engineering workflow. Code is only useful after it has been written to the repository, compiled, tested, and reviewed. I built Loop Engine to explore a more practical approach: plan → edit → verify → review → reflect Loop Engine is an open-source Rust CLI that runs this workflow against a local repository. It uses OpenRouter for model access and allows a different model to handle each phase. What the engine does A normal run performs the following steps: Inspects the target repository. Creates an implementation plan. Lets the implementation agent read and modify files. Runs the repository's verification commands. Sends the actual changes and test output to a reviewer. Reflects on the result. Repeats when verification or review fails. The loop only reports completion when: The repository contains real file changes. The implementation agent explicitly finishes. No tool error remains unresolved. Every configured verification command passes. The reviewer approves the implementation. The reflector agrees that the objective is complete. A model cannot complete the workflow merely by returning the word COMPLETE. Why Rust? The engine executes file operations and local verification commands, so predictable behavior matters. Rust gives the project: Strong types for loop state and tool actions. Explicit error handling. Safe path validation. Good support for asynchronous HTTP and subprocess execution. A single installable CLI binary. The engine also uses optimistic concurrency for file updates. An existing file must be read before it can be written. Immediately before writing, the engine confirms that the file still matches the version the agent read. This prevents the agent from silently overwriting a change made by the developer during the run. Installing Loop Engine Clone the repository: git clone https://github.com/anggadb/loop-engine.git cd loop-engine Install the CLI: cargo install --path . --locked Create your local settings: Copy-Item .env.example .env Copy-Item loop-engine.json.example loop-engine.json Add an OpenRouter API key to .env: OPENROUTER_API_KEY=your-openrouter-key OPENROUTER_HTTP_REFERER=your-localhost-url OPENROUTER_X_TITLE=Loop Engine The environment file and local model configuration are excluded from Git. Configuring models by phase Each phase can use a different OpenRouter model: { "models": { "plan": "openai/gpt-4.1-mini", "implement": "openai/gpt-5.1-codex", "review": "openai/gpt-4.1-mini", "reflect": "openai/gpt-4.1-mini" }, "requests": { "timeout_seconds": 600 }, "execution": { "max_tool_calls": 30, "timeout_seconds": 120, "checks": [] } } For free experimentation, the phase models can be replaced with an available free model: { "models": { "plan": "qwen/qwen3-coder:free", "implement": "qwen/qwen3-coder:free", "review": "qwen/qwen3-coder:free", "reflect": "qwen/qwen3-coder:free" }, "execution": { "max_tool_calls": 30, "timeout_seconds": 120, "checks": [] } } Free models have stricter rate limits and may be less reliable. The exact list of available models can also change. Inspecting a repository safely Before sending repository content to a model, inspect the generated snapshot: loop-engine --repo "C:\projects\my-app" --inspect This command does not load the API key or make an OpenRouter request. The snapshot is bounded and excludes hidden entries, common dependency directories, generated output, symlinks, binary files, and credential-like filenames. It still cannot guarantee that source files contain no sensitive values, so reviewing the snapshot remains important. Dynamic verification detection Loop Engine detects common build systems from files in the target directory: Repository marker Verification Cargo.toml cargo test go.mod go test ./... package.json Available test, typecheck, and build scripts Pytest configuration python -m pytest You can preview the selected checks without running them: loop-engine --repo "C:\projects\my-app" --inspect-checks Example output for a Go repository: { "source": "detected", "checks": [ { "program": "go", "args": ["test", "./..."] } ] } Explicit checks override detection: { "execution": { "max_tool_calls": 30, "timeout_seconds": 180, "checks": [ { "program": "go", "args": ["test", "./..."] } ] } } The model cannot invent arbitrary shell commands. It can request verification, but the engine only executes commands resolved from trusted configuration or fixed detection rules. Running an objective To run the engine against a repository: loop-engine ` --repo "C:\projects\my-app" ` --env-file "C:\tools\loop-engine\.env" ` --config "C:\tools\loop-engine\loop-engine.json" ` "Remove the deprecated endpoint and update its tests" ` --iterations 3 During implementation, the coding agent can request these operations: List repository files. Read a text file. Create a text file. Replace an existing text file. Run the configured checks. Finish the implementation. The engine always runs authoritative verification again after the final edit. Exit code 0 means the work passed the completion rules. Exit code 2 means the iteration or tool budget ended before verified completion. Other nonzero codes indicate execution errors. Prompt logs and recovery journals Every run creates a .loop-engine directory inside the target repository: .loop-engine/ run-.jsonl run-/ iteration-001/ 0001-plan.jsonl 0002-implement.jsonl 0003-implement.jsonl 0004-review.jsonl 0005-reflect.jsonl Each prompt log records: The iteration and phase. The selected model. The system and user prompts. The response or error. Request timing. Tool results associated with the prompt. The request is written before the API call starts. If the process is interrupted or the provider times out, the input remains available for diagnosis. The main journal records original and replacement file content before every write. This provides a manual recovery path if a run fails after modifying files. Logs may contain source code and model output, so .loop-engine/ should remain excluded from version control. Handling incomplete runs An incomplete result includes a stop_reason, such as: verification_failed tool_budget_exhausted unresolved_tool_error no_changes invalid_review_response review_requires_changes It also contains: The changed file list. Verification commands and their output. The latest repository snapshot. Every model response. Prompt-log paths. The recovery-journal path. Edits remain in the target repository after an incomplete run. This makes the result inspectable, but it also means the tool should preferably be used in a clean branch or disposable checkout. Current limitations Loop Engine is still experimental. It currently: Replaces complete file contents instead of applying structured patches. Does not delete or rename files. Does not automatically roll back failed runs. Does not resume interrupted prompts. Detects build systems only from the selected repository root. Depends on model compliance with its JSON action protocol. Runs verification commands with the current user's operating-system permissions. The verification process is not an operating-system sandbox. Project build scripts may access the network, environment variables, and files available to the user. What I learned The interesting part of an AI coding agent is not the initial code response. It is the control loop around that response. The model needs constrained tools, real observations, explicit verification, durable logs, and a completion rule that cannot be satisfied by confidence alone. Loop Engine is my attempt to make that loop small enough to understand while still useful against real repositories. The source is available on GitHub: 👉 github.com/anggadb/loop-engine Feedback, issues, and contributions are welcome.