Auto-intercepts and translates errors from live Bash tool execution in Cowork
Detects errors in tool output, classifies severity, translates them to plain-language explanations, and suggests executable fix commands.
Cowork Error Interceptor
Tags: Introduced in Beta, Error, Intercept, Bash, Git, Python, Permission, Fix, Bridge, Cowork
TL;DR
What It Does
Auto-intercepts and translates errors from live Bash tool execution in Cowork. Detects errors in tool output, classifies severity, translates them to plain-language explanations, and suggests executable fix commands.
How It Works
When a Bash command returns a non-zero exit code or matches a known error pattern, the recipe activates automatically via COM. It matches against a built-in library of 10 common Cowork error types: git authentication, merge conflicts, missing repos, lock files, permissions, Python tracebacks, file-not-found, missing commands, network errors, and npm failures. Each pattern includes severity, translation, and fix commands.
What To Expect
Instant error diagnosis and actionable fix suggestions. Critical errors ask for confirmation before attempting a fix. Warnings explain what happened and offer a fix. Info-level errors are silently auto-fixed.
Best Results When You
Let auto-intercept run in the background. Read the translation and suggested fix before confirming. For recurring errors not in the pattern library, ask the AI to add the pattern for future auto-detection.
Typical Time
Under 1 minute. Auto-triggered immediately when an error is detected.
Difficulty
Beginner — the recipe does almost everything automatically. You confirm fixes for critical errors and optionally review warnings. No technical knowledge required to understand the translations.
How To Start
The error interceptor is designed to run automatically. You can also invoke it manually with specific error output.
STEP 1Let It Run or Provide Error Output
In auto-intercept mode, COM triggers this recipe whenever a Bash tool returns an error. You can also invoke it manually.
Available parameters
-
auto_intercept
· boolean · optional · default: true
When true, COM auto-triggers on Bash errors. Set false for manual-only mode. -
error_output
· string · required
The raw error output from the Bash tool. -
command_executed
· string · optional
The Bash command that produced the error. Improves diagnosis accuracy. -
log_errors
· boolean · optional · default: false
Append error details to a session error log file.
Invocations
Auto-Intercept (COM-Triggered)
#H->AI::Directive: (Intercept and translate Bash tool error)
Manual with Error Output
#H->AI::Directive: (Intercept and translate Bash tool error with error_output=“fatal: unable to access…”)
With Error Logging
#H->AI::Directive: (Intercept and translate Bash tool error with log_errors=true)
Usage Examples
Three scenarios — a git authentication failure (critical), a missing Python module (warning), and a missing command (info, auto-fixed).
Example 1 · Git authentication failure (critical)
AI:
Git Authentication — CRITICAL. Command: git push origin main. Git cannot authenticate with the remote repository. This is expected in Cowork — the VM resets each session. Suggested fix: Set PAT for this session, retry, then scrub PAT.
AI:
This error blocks the current operation. Should I attempt the suggested fix, or would you like to handle it differently?
Example 2 · Missing Python module (warning)
AI:
Python Error — WARNING. Command: python analyze.py. ModuleNotFoundError encountered. Suggested fix: pip install –break-system-packages pandas.
AI:
Want me to try the suggested fix?
Example 3 · Missing command (info, auto-fixed)
AI:
Missing Command — jq is not installed in this Cowork VM. Installing via apt-get. [auto-installs and retries]
How AI Reads This Recipe
When this recipe is triggered, the AI runs a 5-step error interception pipeline. The AI should:
- DETECT errors by parsing Bash tool output for indicators: non-zero exit code, “error:” or “fatal:” strings, “Traceback,” “EACCES” or “EPERM,” “command not found,” “No such file or directory,” “CONFLICT,” “npm ERR!,” “SyntaxError,” and “Connection refused.” If no indicators are found, do not activate.
- MATCH the error against the built-in pattern library: git authentication, git conflicts, git not initialized, git lock files, permission errors, Python tracebacks, file not found, missing commands, network errors, and npm errors. If no pattern matches, classify as “Unknown Error.”
- CLASSIFY severity: CRITICAL (task cannot proceed), WARNING (impacted, workarounds exist), or INFO (minor, minimal impact). For cascading errors, focus on the first error — later errors are often caused by the first failure.
- TRANSLATE the error to plain language and present fix commands. For CRITICAL: show full diagnosis, require user confirmation. For WARNING: show diagnosis, offer to try the fix. For INFO: show brief note and auto-attempt the fix.
- LOG the error if logging is enabled: timestamp, command, truncated error output, matched pattern, severity, and fix status. Session-scoped file, does not persist across sessions.
Auto-intercept is the default — errors are caught without user invocation. For unrecognized patterns, provide raw output with general guidance and suggest adding the pattern if it recurs. Prefer specific fix commands from the pattern library over generic advice.
When to Use This Recipe
Use this recipe when you:
- Encounter any error from Bash tool execution and want instant, plain-language explanation with a fix.
- Are new to command-line tools and need errors translated to actionable guidance.
- Want automatic error detection and resolution without diagnosing issues yourself.
- Need a session error log for debugging recurring issues.
Do not use this recipe when:
You are deliberately testing error handling and want to see raw error output without interception. Disable auto_intercept in this case. Also unnecessary for errors from non-Bash tools (Read, Write, Edit) — those have user-friendly error messages already.
Recipe FAQ
Q.What error types are in the pattern library?
Ten types: git authentication failures, git merge conflicts, git not initialized, git lock files, permission errors, Python tracebacks, file not found, missing commands, network errors, and npm errors. Each includes detection patterns, severity, translation, and fix commands.
Q.What are the severity levels?
Three levels: CRITICAL (task cannot proceed — asks for confirmation), WARNING (impacted but workarounds exist — offers a fix), and INFO (minor impact — auto-applies the fix).
Q.What happens with unrecognized error patterns?
The recipe classifies them as “Unknown Error” with WARNING severity, provides raw output, and suggests general guidance. If the same pattern recurs, the AI suggests adding it to the library.
Q.How does cascading error handling work?
When multiple errors appear in one output, the recipe focuses on the first error. Later errors are often downstream effects of the first failure. Fixing the root cause typically resolves the cascade.
Q.Does the error log persist across sessions?
No. The error log is session-scoped and resets with the VM. It is useful for intra-session debugging and pattern detection.
Q.Can I add custom patterns to the library?
Yes. Tell the AI to add a new pattern with detection strings, severity, translation, and fix commands. The pattern is available for the rest of the session. For permanent additions, request a framework change via CWK-026 transfer packet.
Version History
Changes to this recipe over time. Most recent first.
v1.00a
2026-02-28
Initial release. Extends Core Error Translator with reactive auto-interception: 5-step pipeline, 10 built-in error patterns, 3 severity levels, COM auto-trigger, severity-based confirmation flow, session error logging, cascading error handling, unknown pattern fallback. Audit trail per R-12.
Get this recipe with CRAFT for Claude Cowork
Cowork recipes ship bundled with CRAFT for Claude Cowork — there’s no separate download. Clone the framework once, and your AI runs every recipe automatically when invoked.
Pull anytime to stay on the latest version — free to clone, no login or email required.
Then start your session
Once CRAFT is in your project folder, open a new Cowork session and ask Claude to initialize. For example:
You
Please initialize my CRAFT session.
Claude
CRAFT session ready. Your project is loaded, your persona is active, and your recipes are available. What would you like to work on?
Not familiar with Git? Download as a ZIP
No command line needed. Just download, move, and unzip:
- Open the CRAFT framework repo on GitHub.
- Click the green Code button, then choose Download ZIP.
- Move the downloaded ZIP into your Claude Cowork project folder.
- Unzip it: double-click on Mac, or right-click → Extract All on Windows.
