An autonomous software debugging engine that diagnoses failing test suites, inspects codebases, proposes surgical file edits, and verifies fixes in an isolated environment with Human-In-The-Loop (HITL) approval.
CodePilot executes tests inside an isolated container, navigates source trees safely, and generates targeted unified diffs instead of rewriting entire files. Destructive file operations pause execution, returning the exact proposed change over HTTP for human confirmation. Approved edits are written to disk, verified with another test run, and permanently recorded in an immutable PostgreSQL audit ledger.
Autonomous code generation often fails in production because models rewrite full files, introduce silent regressions, or hallucinate changes without test feedback. A practical debugging agent needs guardrails, deterministic file operations, human oversight, and verifiable test feedback.
- Surgical modifications over full rewrites: The agent targets exact code snippets with character-for-character whitespace checks, preventing accidental deletions and broad rewrites.
- Stateless HTTP with stateful HITL: Pausing and resuming runs is handled over standard REST endpoints without keeping sockets open or blocking the server event loop.
- Decoupled audit logging: File modifications are logged as standard Git unified diffs directly into PostgreSQL, keeping audit history separate from the model's active reasoning scratchpad.
The result is a controlled debugging engine that fixes bugs safely, verifies every change with pytest, and ensures no code touches the disk without explicit human authorization.
Tests run inside a dedicated container sandbox. Test execution outputs and failure traces are captured headlessly and returned to the agent as the primary source of truth.
All file operations pass through a directory boundary validator
(safe_path), preventing the agent from reading or writing files outside
the designated project workspace.
The replace_code tool requires exact string matches and verifies that
target snippets appear only once in the file. This blocks ambiguous edits
and preserves file formatting.
Modifying tools (replace_code, append_code, create_file) trigger
an execution pause. The server saves the paused coroutine state and
returns a paused status with the proposed arguments for human review.
Every disk modification generates a unified diff using difflib. The
change, file name, timestamp, and technical reason are committed
directly to the public.register_logs database table.
A standalone Python CLI built with rich provides an interactive terminal
flow with animated status spinners, syntax-highlighted diff panels, and
inline confirmation prompts.
flowchart TD
A[Start Run: POST /agent/run] --> B[Run Pytest Sandbox]
B --> C{Tests Passing?}
C -- Yes --> D[Completed: Return Summary]
C -- No --> E[Read Code & Propose Edit]
E --> F[Trigger HITL: Return Status Paused]
F --> G[CLI Displays Unified Diff]
G --> H{User Approval}
H -- Rejected --> I[acontinue_run with Rejection]
H -- Approved --> J[Apply Edit to Disk]
J --> K[Log Unified Diff to PostgreSQL]
K --> L[Resume Run: Re-run Pytest]
L --> C
The workflow connects the user-facing CLI to the FastAPI backend, isolates test execution within Docker, and preserves all verified diffs inside PostgreSQL.
demo.mp4
View the 1-minute demo video showing failure detection, interactive diff confirmation, and automated test resolution.
The service runs through Docker Compose, maintaining database migrations with Alembic and persisting structured audit logs for every file change.
docpilot/
├── app/
│ ├── agent/
│ │ ├── instance.py # Initializing the agent
│ │ └── state.py # Track runs
│ ├── routers/
│ │ └── router.py # Main api router
│ ├── core/
│ │ ├── config.py # Environment settings
│ │ └── database.py # Database initialization
│ ├── models/
│ │ └── logs.py # Audit logs table
│ ├── schemas/
│ │ └── agent.py # Pydantic Schema
│ ├── tools/
│ │ ├── file_tools.py # File tools for agent to use
│ │ ├── logs_services.py # Audit logs service
│ │ └── test_runner.py # Isolated Test case runner
│ └── main.py # FastAPI entrypoint
├── projects/
│ ├── calculator/ # Example project 1
│ └── wallet # Example project 2
├── docker-compose.yml
├── Dockerfile
└── requirements.txt
git clone https://github.com/imLeo007/codepilot.git
cd codepilotCreate a .env file in the project root:
DATABASE_URL=postgresql+asyncpg://postgres:password@db:5432/codepilot_db
AGNO_DATABASE_URL=postgresql+psycopg_async://postgres:password@db:5432/codepilot_db
OPENAI_API_KEY=your_api_key_heredocker compose up -d --buildThis starts the FastAPI server, the isolated test environment, and PostgreSQL.
docker compose exec codepilot alembic upgrade headRun the interactive CLI on your host machine:
python cli.py- Select your target project (e.g.,
calculatororwallet). - Optionally inspect the recent PostgreSQL audit history.
- Enter your debugging instruction (e.g.,
"Fix all failing tests"). - Review the syntax-highlighted diffs and approve or reject edits interactively.
CodePilot is built around verifiable actions rather than open-ended code generation. By restricting the agent to surgical edits, validating every step through automated tests, and requiring human approval before writing to disk, it provides an autonomous debugging workflow that remains safe, predictable, and fully auditable.

