Inspiration

When software breaks—whether it's an installation failure, an unexpected module regression, or a failing CI/CD pipeline test—developers often copy-paste error traces into a web AI chat window. While foundation models can explain syntax errors, conversational advice cannot prove that a proposed patch works inside an actual repository.

At the same time, existing autonomous agents often swing to the opposite extreme: granting an LLM unbounded filesystem access or arbitrary shell execution privileges (eval, exec, shell=True). This introduces severe security vulnerabilities, including path traversal attacks, credential leakage, and silent hallucinated "fixes" where the model claims a bug is resolved without running tests.

We set out to build an open-source terminal agent that combines the deep reasoning of NVIDIA Nemotron via Nebius Token Factory with the ergonomic flow of Claude Code—anchored by strict, deterministic security boundaries and treating genuine test runner exit codes as the only true evidence of repair.

What it does

RepoMedic CLI is a terminal-first autonomous coding agent designed for repository diagnosis and verified repair:

Interactive Claude Code Interface: Launching repomedic with no arguments starts an interactive terminal session where developers converse naturally (repomedic > find why tests fail in fixtures/broken_sample_project and fix it). Autonomous Toolset: The agent navigates code using safe tools: view_file(path): Reads target source files with token budget protection. list_files(path): Scans folder hierarchies while respecting ignore rules. grep_code(query): Regex-based pattern and symbol search across the codebase. propose_patch(explanation, patch): Formats unified diffs. run_tests(profile): Runs pytest or unittest with process timeouts and captures exit code evidence. Deterministic Security Confinement: All patch targets are strictly checked against repository root boundaries using Path.resolve() and relative_to(). Any attempt to escape via parent traversal (../outside.txt), absolute paths, .git metadata, or symlinks is immediately aborted. Human-in-the-Loop Approval Gate: Before any file is modified, RepoMedic displays a syntax-highlighted, color-coded unified diff preview and pauses for explicit human confirmation (Apply this change? [y/N/e(dit)]:). Evidence-Based Verification: The tool never trusts an LLM declaring "I fixed it". It re-runs the allowlisted test runner and reports the genuine OS return code. Universal Provider Engine: Zero-configuration auto-detection for Nebius Token Factory, NVIDIA NIM, OpenAI, Groq, OpenRouter, or local models (Ollama / vLLM). How we built it

We engineered RepoMedic CLI in Python 3.11+ following a modular architecture:

AI Model & Inference Engine: Powered by NVIDIA Nemotron (nvidia/Nemotron-3_5-Lightning and nvidia/llama-3.1-nemotron-70b-instruct) served over Nebius Token Factory's OpenAI-compatible endpoint, with automated fallbacks to NVIDIA NIM, OpenAI, and Groq. Structured Schemas & Guardrails: Used Pydantic to enforce structured diagnostic responses (summary, evidence, likely_root_cause, patch, verification_steps, limitations). Terminal UI & Interactive Shell: Built with Typer, Rich, and prompt_toolkit to deliver an interactive Claude Code REPL experience with syntax-highlighted diffs, panels, and live spinners. Safe Subprocess Test Runner: Implemented strict argument array execution (shell=False) with timeout guards (avoiding process hangs and command-injection vulnerabilities). Patch Validator & Dual-Mode Applier: Combines Git patch engine (git apply --whitespace=nowarn) with a pure-Python unified diff hunk applier fallback. Testing & Verification: 24 unit and regression tests in pytest covering path traversal defense, secret redaction, and schema parsing, paired with a deterministic failing test fixture (fixtures/broken_sample_project/). Challenges we ran into Deterministic Patch Confinement: LLMs frequently produce git diff headers with varying prefixes (a/, b/, or relative paths without prefixes). Parsing unified diffs reliably while ensuring no path can escape the workspace (or touch .git) required multi-layered validation and canonical resolution. Safe Test Execution Without Shell Injection: Developers frequently run commands through shell string concatenation, opening the door to injection. We constrained execution strictly to allowlisted test profiles (pytest, unittest) executed via argument arrays with shell=False. Cross-Platform Compatibility: Ensuring smooth execution across Windows PowerShell and Linux/macOS terminals required handling Windows-specific console encoding quirks (CP1252 / UTF-8) and making path resolution OS-agnostic with pathlib. Interactive REPL vs. Single-Shot CLI: Blending a single-command CLI (for CI/CD pipelines) with an interactive Claude Code conversational agent required structuring Typer callbacks so running repomedic launches the interactive agent while subcommands (repomedic doctor, repomedic inspect) continue to work seamlessly. Accomplishments that we're proud of True Human-in-the-Loop Safety: Built an AI coding agent where you never have to worry about an AI secretly modifying files or running arbitrary bash scripts behind your back. Claude Code Experience in Open Source: Brought an interactive terminal REPL with natural language prompts, autonomous tool use, and interactive approval prompts to the open-source community. 100% Test Coverage on Security Boundaries: 24 out of 24 unit tests passing, verifying directory traversal rejection, secret masking, and timeout controls. Deterministic 5-Step Demo: Built a self-contained test fixture and demo (python demo/app.py) that showcases baseline failure, diagnosis, approval, and passing verification in under 60 seconds without requiring external API credits. Universal Provider Flexibility: Runs out-of-the-box with Nebius Token Factory, NVIDIA NIM, OpenAI, Groq, or local Ollama instances. What we learned Evidence Beats Confidence: LLMs often speak with high confidence about code fixes that subtly fail syntax or edge-case tests. Coupling AI generation with actual compiler and test feedback loops is essential for real-world software engineering. Small, Bounded Context Works Best: Sending an entire repository introduces noise and dilutes attention. Bounding the context to project manifests, relevant modules, and truncated error logs dramatically improves Nemotron's diagnosis quality. Defense in Depth: Relying on system prompts alone to prevent security escapes is insufficient; deterministic validators at the boundary level are required for robust AI agents. What's next for Opensource AI Agent NVIDIA OpenShell Sandbox Integration: Upgrading the disposable copy system to hardware/OS-level isolation via NVIDIA OpenShell for running untrusted third-party code. Multi-File Complex Refactoring: Expanding patch generation to handle cross-file symbolic refactors and AST-aware transformations. CI/CD GitHub Action: Packaging RepoMedic as an automated GitHub Action that comments on failing PRs with reviewable diffs and test verification evidence. Local Model Fine-Tuning: Evaluating quantized Nemotron models running locally via llama.cpp/Ollama for completely offline, zero-data-leakage repository repair.