OpenSrcer

Agentic AI for deep codebase exploration. It structurally understands your code to resolve complex issues, pass local tests, and securely open verified PRs.

Comment

Inspiration

As a solo developer, I’ve always wanted to contribute to massive open-source projects, but the sheer cognitive load of navigating undocumented, sprawling codebases always stopped me. The barrier to entry isn't necessarily writing the code; it's understanding the context—finding where a bug originates, understanding how the classes interact, and figuring out the specific testing conventions of that repository.

I built OpenSrcer to completely obliterate that barrier. I wanted a system that doesn't just pass strings into an LLM, but acts as a highly structural, autonomous pair-programmer that can interrogate a codebase, generate a precise patch, verify it against local tests, and open a pull request while I sleep.

How I Built It

OpenSrcer is an intensely deterministic orchestration layer wrapped around non-deterministic AI models. It features a bifurcated architecture with two main execution paths: a deterministic Rust binary (contribai.exe) for fast, well-scoped leaf fixes, and a deeply agentic Next.js/Node.js path for multi-file exploration.

The Code Intelligence Engine (MCP & AST)

The heart of the agentic path is a custom Model Context Protocol (MCP) server that communicates with a headless Claude 3.5 Sonnet process (claude -p) over stdio. Instead of relying on brute-force regex searches, the MCP server provides Claude with a specialized toolbelt for structural codebase exploration:

  • The WASM Tree-Sitter: When Claude uses the find_definition tool, the system utilizes WebAssembly-powered web-tree-sitter to parse the repository into an Abstract Syntax Tree (AST). This allows the agent to structurally locate function declarations, interfaces, and nested classes across Python, JavaScript, TypeScript, TSX, Rust, and Go.
  • Graceful Fallbacks: If the AST misses a symbol or encounters an unsupported language, the tool gracefully falls back to a regex-driven git grep to ensure the agent is never blocked.
  • In-Memory Repo Caching: To prevent race conditions from parallel tool calls, the MCP server manages a shallow clone cache (~/.contribai/repos/) with in-process locks and a strict 24-hour TTL.

Zero-Trust Authentication

Because OpenSrcer directly handles repository access, security is paramount. The platform operates on a zero-trust model:

  • No Stored Credentials: When a user logs in via Auth0, a custom post-login action embeds their scoped GitHub OAuth token directly into the ID token as a custom claim (https://opensrcer.dev/github_token). Anthropic and Gemini API keys are encrypted using AES-256-GCM and stored exclusively in an httpOnly cookie.
  • Process Sanitization: Before the Node.js backend spawns the Claude subprocess, it explicitly executes delete env.GITHUB_TOKEN and delete env.ANTHROPIC_API_KEY from the environment. This mathematically guarantees that the server operator's credentials can never leak into a user-initiated dispatch.

Zero-Database Architecture

To optimize for speed and eliminate migration overhead, I built a completely flat-file, zero-database architecture. Live dispatch logs (.dispatches/<id>.log) serve as the absolute single source of truth. The Next.js 15 App Router utilizes Stale-While-Revalidate (SWR) caching to instantly serve this data to the client, allowing the application shell to bypass edge middleware and render in milliseconds.

Challenges I Ran Into

LLM Hallucinations & The 5-Tier Apply Ladder

The hardest engineering challenge was dealing with the reality of LLM outputs. Even with AST guidance, LLMs notoriously hallucinate exact line numbers, chunk headers, and whitespace when generating diffs. If the system blindly committed these outputs, every build would break.

To combat this, I engineered a highly fault-tolerant auto-PR pipeline featuring a 5-Tier Git Apply Ladder:

  1. Tier 1: Strict git apply --index --recount.
  2. Tier 2: git apply --ignore-whitespace (handles LLM spacing issues).
  3. Tier 3: git apply --3way after a shallow fetch (handles context line drift).
  4. Tier 4: git apply --3way --ignore-whitespace.
  5. Tier 5: A total fallback to GNU patch -p1 --fuzz=3 for when the LLM completely botches the hunk headers.

Preventing Broken Builds (Crucible Sandbox)

I quickly realized that just applying code isn't enough; the code actually has to work. For private organizations, I built the Crucible Test Runner.

Once the diff is applied to the isolated git worktree, the system dynamically analyzes the repository to detect its ecosystem (e.g., finding a Cargo.toml, pyproject.toml, or package.json). It then natively executes the corresponding test suite (cargo test, pytest, npm test) right in the sandbox. If the tests fail, the PR is strictly blocked, and the log is marked as [crucible-tests] status=failed. Additionally, a Gemini 2.0 Flash agent is invoked to self-review the patch for security vulnerabilities before the draft PR is opened.

Smart Branch Resolution

Finally, when opening the PR, blindly targeting main caused issues with repositories utilizing GitFlow. I implemented a resolver that queries the last 30 merged PRs via the GitHub CLI. If $\geq 80\%$ of those PRs target a specific branch (like develop), OpenSrcer dynamically sets that as the base branch, ensuring the PR is routed correctly.

What I Learned

Building OpenSrcer was an intense crash course in distributed process management, AST compiler theory, and secure execution boundaries.

I also had to learn how to mathematically model and enforce real-time API spending limits for the autonomous agents. Because the agentic loops can spiral, I implemented a strict streaming parser that tracks cumulative token usage against a user-defined budget limit $B$. The system continuously calculates the total dispatch cost:

$$C_{total} = \sum_{i=1}^{n} \left( T_{in, i} \cdot P_{in} + T_{out, i} \cdot P_{out} \right)$$

If the 30-minute wall-clock timeout is exceeded or dispatch cost exceeded, the entire process tree is systematically killed (taskkill /F /T /PID <pid>) to protect the user's wallet.

What's Next for OpenSrcer

The immediate next step is expanding the Crucible test runner to utilize fully isolated Docker containers or Firecracker microVMs for maximum security during local testing. I also plan to expand the web-tree-sitter grammars to support C++ and Java, bringing OpenSrcer's structural code intelligence to legacy enterprise systems. I also want to be able to fully scale it, so I will incorporate Edge computing and microservices to preserve throughput.

Built With

Share this project:

Updates