How Plip Works: Architecture of an AI Debugging Agent

Everything starts with a label. When you add the plip label to a GitHub issue, GitHub fires a webhook to Plip's server. That webhook is a signed HTTP POST containing the issue metadata—title, body, labels, repository, and author.

The first thing Plip does is validate the webhook signature using HMAC-SHA256. Every GitHub App installation shares a secret with GitHub, and Plip uses that secret to verify the X-Hub-Signature-256 header on every incoming request. If the signature doesn't match, the request is dropped. No exceptions.

After signature verification, Plip checks the installation's plan and quota. Free plans get 10 fixes per month; paid plans get more. If the quota is exhausted, Plip comments on the issue explaining the limit and exits. If everything checks out, the job is enqueued. The webhook handler itself does minimal work—validate, authorize, enqueue—and returns a 202 Accepted within milliseconds. The actual processing happens asynchronously.

Before spinning up an expensive agent, Plip runs a fast triage step. This is a deliberate architectural choice: the models that are good at fixing bugs (Sonnet, Opus) cost significantly more per token than the models that are good at classification. Triage uses Claude Haiku—Anthropic's fastest and cheapest model—to make a binary decision: should we attempt this fix?

The triage prompt is straightforward. Haiku receives the issue title and body and evaluates several criteria. Is this describing a reproducible bug, or is it a feature request? Is there enough context to locate the problem in the codebase? Is the issue specific enough that an automated agent could reasonably attempt a fix, or is it too vague to act on?

If the issue is too vague—something like "the app is broken" with no stack trace, reproduction steps, or file references—Plip comments on the issue asking for more detail. This is significantly cheaper than cloning a repository and running an agent for 8 turns only to produce a bad fix. A single triage call costs roughly $0.001. A failed agent run can cost $0.50 or more. Triage exists to protect both the user's quota and our infrastructure costs.

If the issue passes triage, the system also extracts a structured summary: the likely affected files or modules, the type of bug (runtime error, logic error, missing validation), and any test commands mentioned in the issue body. This structured context is passed to the agent in the next phase to reduce the number of exploratory turns it needs.

Once an issue passes triage, Plip provisions an isolated container—an ephemeral VM that exists for the sole purpose of this one job. The container is created from a clean base image, and the first step is cloning the target repository at its default branch using a scoped GitHub App installation token.

After the clone, Plip runs environment detection. This is a heuristic pass over the repository to identify the language, package manager, and test framework. It looks for package.json, requirements.txt, Cargo.toml, go.mod, pom.xml, and other standard manifest files. Once it identifies the ecosystem, it installs dependencies: npm install, pip install -r requirements.txt, cargo build—whatever the project requires.

Network access inside the container is restricted. Outbound connections are allowed only to two destinations: the GitHub API (for reading additional context like linked PRs or comments) and the AI provider (Anthropic's API). Every other outbound address is blocked at the network level. The container cannot reach arbitrary endpoints, download arbitrary packages from registries beyond the initial install, or exfiltrate data. This is a hard constraint enforced by the infrastructure, not just application-level logic.

This is the core of Plip. The AI agent—Claude Sonnet on standard plans, Claude Opus on Pro and Enterprise—receives the issue description, the triage summary, and access to the codebase through a set of tools. These tools let the agent read files, search the codebase with regex or semantic queries, edit files, and run shell commands (build, lint, test).

The agent operates in a turn-based loop. Each turn consists of the model reasoning about its next action, invoking one or more tools, and receiving the results. A typical fix progresses through a recognizable pattern:

Turns 1–2: Investigation. The agent reads the files most likely to contain the bug. It uses the triage summary as a starting point, then searches for related symbols, imports, and call sites. If the issue includes a stack trace, the agent follows it directly to the relevant lines. If not, it searches more broadly—grepping for error messages, function names, or the specific behavior described in the issue.

Turn 3: Hypothesis. After reading the relevant code, the agent forms a hypothesis about the root cause. This isn't a guess—it's a structured assessment based on what the agent has observed. The hypothesis is recorded in the agent's context so it can be evaluated later and included in the PR description.

Turn 4: The fix. The agent edits the source files to address the root cause. Fixes range from single-line changes (an off-by-one error, a missing null check) to multi-file refactors that touch several modules. The agent writes minimal, targeted changes—it's not rewriting your codebase.

Turn 5: Regression test. The agent writes a test that would have caught the bug. This is a critical step: a fix without a test is a fix that can regress silently. The test targets the specific behavior described in the issue, not just the code path that was modified.

Turn 6: Verification. The agent runs the full test suite. If all tests pass—including the new regression test—the fix is considered verified and the agent exits the loop.

If tests fail, the agent doesn't give up. It reads the test output, identifies what went wrong, and iterates. Maybe the fix introduced a side effect in another test. Maybe the regression test itself has an assertion error. The agent adjusts and reruns. This loop can repeat several times, and most fixes converge within 4–8 turns total.

To prevent runaway costs, the agent has a hard turn limit. If it hasn't converged within the limit, the job is terminated and Plip comments on the issue explaining that it was unable to produce a verified fix. This is a deliberate design choice: it's better to report failure honestly than to open a PR with a broken fix.

Once all tests pass, Plip creates a branch from the default branch, commits the changes, and pushes. The branch naming follows a predictable pattern: plip/fix-<issue-number>. The commit message references the original issue number so GitHub automatically links them.

The pull request body is designed to give reviewers everything they need to evaluate the fix without re-investigating the bug themselves. It includes: the agent's hypothesis about the root cause, a summary of what was changed and why, the full test results (pass/fail counts, any relevant output), and a turn-by-turn log of every action the agent took—which files it read, what it searched for, what commands it ran, and in what order.

This transparency is intentional. Plip produces PRs that are meant to be reviewed by humans, not rubber-stamped. The turn log lets you audit the agent's reasoning. If the agent made an incorrect assumption in turn 3, you can see exactly where and why. If it searched for the wrong symbol and went down a dead end before correcting course, that's visible too. No black boxes.

The PR is linked back to the original issue with a Fixes #<issue-number> reference, so merging the PR automatically closes the issue. From the developer's perspective, the workflow is: label the issue, review the PR, merge. That's it.

Security in an AI coding agent isn't a feature—it's the foundation. Plip handles your source code, and the architecture is built around the assumption that any component could be compromised.

Ephemeral containers. Every job runs in a fresh container that is destroyed after the job completes. There is no persistent state between jobs. The container's filesystem, memory, and network connections are torn down completely. Your code is never stored on disk after the job finishes.

Network isolation. As described in the sandbox section, outbound network access is restricted to the GitHub API and Anthropic's API. The container cannot make requests to any other endpoint. This prevents a class of attacks where a malicious repository could cause the agent to exfiltrate code or credentials to an external server.

Webhook verification. Every incoming webhook is verified using HMAC-SHA256 before any processing occurs. Unsigned or incorrectly signed requests are rejected at the edge. This prevents spoofed webhooks from triggering jobs.

No training on user code. Your code is used only to generate the fix for the current issue. It is not stored, logged, or used to train any model. Anthropic's API usage policies apply to the model calls, and Plip does not retain prompts or completions after the job completes.

Human review required. Plip never pushes directly to main or any protected branch. Every change is a pull request that requires human review before merging. This is a deliberate architectural constraint, not a configuration option. Even if the fix is perfect, a human must approve it. The agent is a tool, not an authority.

Running large language models against full codebases is expensive if you're not careful about architecture. Plip is designed to minimize cost at every stage without sacrificing fix quality.

Triage filters bad inputs early. The Haiku-based triage step costs approximately $0.001 per issue. By filtering out vague, unfixable, or out-of-scope issues before the agent runs, triage prevents the system from spending $0.50+ on agent runs that would fail anyway. Across a high volume of issues, this saves an order of magnitude in compute costs.

Prompt caching reduces token costs. In the agentic loop, each turn includes the full conversation history—the issue description, all previous tool calls and results, and the codebase context. Without caching, this means re-processing the same tokens on every turn. Plip uses Anthropic's prompt caching to avoid this: cached tokens are served at a fraction of the cost of fresh tokens. On a typical 6-turn fix, caching reduces total token costs by 60–80% compared to naive sequential calls.

Model tiering matches cost to complexity. Not every bug needs the most capable (and most expensive) model. The triage step uses Haiku. The agent step uses Sonnet or Opus depending on the user's plan and the complexity signal from triage. This tiered approach means simple fixes don't incur Opus-level costs, while complex multi-file bugs get the reasoning power they need.

The result: a typical fix costs between $0.05 and $0.50 in API costs, depending on the size of the codebase and the number of turns required. Compared to the engineering time saved—even at conservative estimates, a human debugging a bug takes 30 minutes to several hours—the cost per fix is negligible.

The architecture described here—webhook to triage to sandbox to agent loop to PR—is the result of optimizing for three goals simultaneously: fix quality, cost efficiency, and security. Each phase exists because removing it would degrade one of those properties. Triage without an agent loop produces no fixes. An agent loop without triage wastes compute. Any of it without sandboxing is a security liability.

If you want to see it in action, install Plip on a repository, label an issue, and watch the PR appear. The turn-by-turn log in the PR body is the best way to understand how the agent reasons about your specific codebase.