AI Coding & Repository Agent

01Problem

One-shot code completion misses the wider codebase, skips compile/test checks, and can break linked files without noticing.

Approach. I built a planner–executor loop: index the repo, pull the right files, plan steps, apply scoped diffs, then run lint/tests before anything is offered for review.

02Requirements

• Parse and index multi-file codebases without exceeding model context limits.
• Restrict file writes and command execution to an explicit workspace allowlist.
• Validate generated edits with linters and test runners before finalizing output.
• Provide transparent diff previews so a human engineer approves every change.

03Architecture

The system separates read-only context gathering from mutating tool execution. A background indexer chunks source files by AST boundaries and stores vector embeddings alongside symbol metadata. When a task arrives, the retrieval layer ranks relevant snippets, the planner produces a structured JSON step list, and the executor invokes sandboxed file and test tools with strict timeout and path guards.

1. Codebase Index
2. Context Retrieval
3. Planning
4. Tool Execution
5. Diff Review
6. Test Validation

04Technology choices

Python & AST Parsers

Enables language-aware chunking so functions and classes stay intact during retrieval.

Embeddings + Vector Search

Combines semantic search with exact keyword/symbol lookup for hybrid context ranking.

Structured Tool Schemas

Enforces typed parameters for file reads, unified diffs, and test execution.

05Implementation

• Built hybrid lexical + vector retrieval to locate symbol definitions and usages.
• Implemented a state machine that caps retry loops when a test or linter check fails.
• Added unified diff generation and dry-run patching prior to writing to disk.

06Security considerations

• Path traversal prevention ensuring the agent cannot read or write outside the repository root.
• Command allowlisting and execution timeouts for test and linter subprocesses.
• Secret-pattern scanning to prevent `.env` or credential files from entering prompt context.

07Challenges

• Balancing context window budget between broad file trees and deep implementation details.
• Handling ambiguous edit locations when files contain similar code blocks.

08Results and lessons learned

Still an active personal prototype — useful for testing retrieval, tool reliability, and validation loops. No inflated success rates claimed.

This project is an experimental engineering prototype; formal benchmark percentages are not claimed. Key lesson: deterministic validation tools (typecheckers, linters, unit tests) are far more effective at improving agent reliability than prompt tuning alone.