# How to Use the Build-Error-Resolver Agent for Build Failures in Claude Code

> Fix TypeScript build failures in Claude Code with the build-error-resolver agent. Automatically diagnose and repair errors using the /build-fix command for minimal, safe changes.

- Repository: [Affaan Mustafa/everything-claude-code](https://github.com/affaan-m/everything-claude-code)
- Tags: how-to-guide
- Published: 2026-03-20

---

**The build-error-resolver agent in Claude Code automatically diagnoses and repairs TypeScript compilation errors through the `/build-fix` command, applying minimal code changes while preserving existing functionality.**

The **build-error-resolver** agent is a specialized "debug-first" tool in the `affaan-m/everything-claude-code` repository that resolves build failures with surgical precision. According to the agent definition in [`agents/build-error-resolver.md`](https://github.com/affaan-m/everything-claude-code/blob/main/agents/build-error-resolver.md), it focuses exclusively on fixing errors rather than introducing new features or refactoring unrelated code. This agent integrates directly into Claude Code's workflow to provide rapid recovery from broken builds.

## How the Build-Error-Resolver Agent Works

The agent follows a disciplined five-step workflow defined in [`agents/build-error-resolver.md`](https://github.com/affaan-m/everything-claude-code/blob/main/agents/build-error-resolver.md) to ensure safe, minimal interventions.

### Error Collection and Prioritization

First, the agent executes `npx tsc --noEmit` (or the full build command) to capture every TypeScript error, missing import, configuration problem, or dependency mismatch. It then categorizes these errors by severity, addressing critical build-breakers before type warnings to maximize immediate impact.

### Minimal Fix Generation

For each identified error, the agent applies the smallest possible corrective edit. Common fixes include adding type annotations, inserting missing `import` statements, or applying optional chaining operators. The agent's **DO / DON'T** checklist guarantees that only non-architectural changes are made, preventing scope creep into refactoring territory.

### Iterative Verification Process

After each edit, the agent re-executes the type-checker to ensure the fix did not introduce regressions. Once `npx tsc` reports zero errors, the agent runs `npm run build` followed by `npm test` to confirm the entire project compiles and existing tests still pass. This validation ensures that fixes satisfy both the TypeScript compiler and the project's runtime requirements.

## Invoking the Agent in Claude Code

You can trigger the build-error-resolver through Claude Code's command interface or direct agent invocation.

### Using the /build-fix Command

The primary entry point is the `/build-fix` command defined in [`.opencode/commands/build-fix.md`](https://github.com/affaan-m/everything-claude-code/blob/main/.opencode/commands/build-fix.md). This command automatically routes requests to the build-error-resolver agent with the correct execution context.

```bash
/build-fix

```

You can narrow the diagnostic scope by providing a path or pattern:

```bash
/build-fix src/utils

```

When you specify a path, the agent focuses its diagnostics exclusively on the supplied files or directories, making it ideal for large monorepos where you want to isolate fixes to specific modules.

### Manual Invocation Methods

For advanced usage or scripting scenarios, invoke the agent directly by name:

```bash
/build-fix --agent build-error-resolver

```

Claude Code's internal dispatcher maps the `build-error-resolver` identifier to the logic described in the agent definition file, ensuring consistent behavior regardless of invocation method.

### Practical Workflow Example

Here is a complete workflow demonstrating the agent's operation:

```bash

# 1. Build fails with module resolution error

npm run build

# → error: Cannot find module '@/lib/redis'

# 2. Invoke the resolver

/build-fix

# 3. Agent executes:

#    • npx tsc --noEmit

#    • Detects "Cannot find module" error

#    • Checks tsconfig.json paths and package.json

#    • Installs missing package or corrects import path

#    • Re-runs tsc until clean

# 4. Final verification

npm run build   # succeeds

npm test        # all tests pass

```

After completion, the agent outputs a summary including file paths and line numbers, allowing you to review the minimal diff before committing.

## What to Expect from Agent Fixes

The build-error-resolver produces diffs that modify exactly one line per error. For example, if TypeScript reports *"Object is possibly 'undefined'"* on line 42 of [`src/components/UserCard.tsx`](https://github.com/affaan-m/everything-claude-code/blob/main/src/components/UserCard.tsx), the agent applies:

```diff
- const avatar = user.profile.avatarUrl;
+ const avatar = user.profile?.avatarUrl;

```

This surgical approach preserves original logic while satisfying the type checker, ensuring your codebase remains maintainable and reviewable.

## When to Use the Build-Error-Resolver Agent

| Situation | Recommended Action |
|-----------|-------------------|
| `npm run build` exits with compilation errors | Run `/build-fix` immediately |
| TypeScript type checker reports failures | Use `/build-fix` to auto-apply annotations or import fixes |
| Dependency or configuration mismatches appear during compilation | Let the agent adjust [`tsconfig.json`](https://github.com/affaan-m/everything-claude-code/blob/main/tsconfig.json) paths or suggest `npm install` fixes |
| You need a "green build" before writing tests or new features | Invoke as the first step after any build failure |

Avoid using this agent for **refactoring**, **feature addition**, or **performance optimization**. Those tasks belong to other agents in the `affaan-m/everything-claude-code` toolkit, such as `refactor-cleaner` or `architect`, as documented in [`AGENTS.md`](https://github.com/affaan-m/everything-claude-code/blob/main/AGENTS.md).

## Summary

- **The build-error-resolver agent** fixes TypeScript and general build failures through the `/build-fix` command in Claude Code.
- **File locations**: Agent logic resides in [`agents/build-error-resolver.md`](https://github.com/affaan-m/everything-claude-code/blob/main/agents/build-error-resolver.md), the command wrapper is in [`.opencode/commands/build-fix.md`](https://github.com/affaan-m/everything-claude-code/blob/main/.opencode/commands/build-fix.md), and the agent catalog is in [`AGENTS.md`](https://github.com/affaan-m/everything-claude-code/blob/main/AGENTS.md).
- **Workflow**: The agent runs `npx tsc --noEmit`, prioritizes errors, applies minimal fixes (single-line edits), and verifies with `npm run build` and `npm test`.
- **Scope limitation**: The agent only repairs compilation errors—it never adds features or refactors unrelated code per its strict DO/DON'T constraints.
- **Usage**: Invoke via `/build-fix` optionally with path arguments to narrow scope, or manually via `--agent build-error-resolver`.

## Frequently Asked Questions

### How do I trigger the build-error-resolver agent?

Run the `/build-fix` command in Claude Code to automatically invoke the agent. You can optionally specify a file path or directory (e.g., `/build-fix src/components`) to limit the diagnostic scope to specific parts of your codebase.

### What types of build errors can the agent fix?

The agent handles TypeScript compilation errors, missing module imports, configuration mismatches in [`tsconfig.json`](https://github.com/affaan-m/everything-claude-code/blob/main/tsconfig.json), and dependency resolution issues. It applies fixes such as adding type annotations, inserting import statements, or applying optional chaining to resolve *"possibly undefined"* errors.

### Will the build-error-resolver agent refactor my code?

No. According to [`agents/build-error-resolver.md`](https://github.com/affaan-m/everything-claude-code/blob/main/agents/build-error-resolver.md), the agent is strictly constrained to error correction. It will not refactor unrelated code, introduce new features, or optimize performance. For refactoring tasks, use the `refactor-cleaner` or `architect` agents listed in [`AGENTS.md`](https://github.com/affaan-m/everything-claude-code/blob/main/AGENTS.md).

### Where is the build-error-resolver agent defined in the codebase?

The agent's core responsibilities, workflow steps, and success metrics are defined in [`agents/build-error-resolver.md`](https://github.com/affaan-m/everything-claude-code/blob/main/agents/build-error-resolver.md). The user-facing command interface is implemented in [`.opencode/commands/build-fix.md`](https://github.com/affaan-m/everything-claude-code/blob/main/.opencode/commands/build-fix.md), and the agent's relationship to other Claude Code tools is cataloged in [`AGENTS.md`](https://github.com/affaan-m/everything-claude-code/blob/main/AGENTS.md) within the `affaan-m/everything-claude-code` repository.