AI-powered debugging SDK that turns confusing errors, stack traces, and logs into clear explanations and actionable fixes.
Stop googling. Stop guessing. Just paste your error — and it works now.
Convert cryptic errors into human-readable explanations. Supports stack traces, runtime errors, and API responses.
Get actionable fixes with code snippets, best practices, and step-by-step guidance.
Provide source code, framework, and environment context for more accurate and relevant fixes.
Analyze logs to detect patterns, root causes, and critical issues automatically.
Get suggestions for fallback logic, retry strategies, and resilient error handling.
-
OpenAI (GPT-4, GPT-3.5) - Default
-
Anthropic (Claude)
-
xAI (Grok)
npm install itworksnow
You'll need an API key from one of the supported providers:
import { IWN } from 'itworksnow';
const iwn = new IWN({
provider: 'openai',
apiKey: process.env.OPENAI_API_KEY
});
try {
throw new Error("Cannot read property 'map' of undefined");
} catch (error) {
const result = await iwn.explainError(error, {
code: 'const names = users.map(u => u.name);',
framework: 'Node.js'
});
console.log(result.explanation);
}const iwn = new IWN({
provider: 'openai',
apiKey: process.env.OPENAI_API_KEY,
model: 'gpt-4o-mini',
temperature: 0.3
});const iwn = new IWN({
provider: 'anthropic',
apiKey: process.env.ANTHROPIC_API_KEY,
model: 'claude-3-5-sonnet-20241022',
temperature: 0.3
});const iwn = new IWN({
provider: 'xai',
apiKey: process.env.XAI_API_KEY,
model: 'grok-beta',
temperature: 0.3
});const result = await iwn.explainError(error, {
code: 'your code snippet',
framework: 'Express.js',
description: 'Additional context'
});
console.log(result.explanation);const fix = await iwn.suggestFix(
'ECONNREFUSED: Connection refused at 127.0.0.1:5432',
{
framework: 'PostgreSQL',
description: 'Database connection failing'
}
);
console.log(fix.explanation);const logs = [
'[ERROR] Database connection timeout',
'[WARN] Retrying connection...',
'[ERROR] Max retries exceeded'
];
const analysis = await iwn.analyzeLogs(logs, {
service: 'API Server',
timeRange: '10:00-11:00'
});
console.log(analysis.explanation);const strategy = await iwn.suggestRetry(
'API request failing with 503 Service Unavailable',
{
currentAttempts: 3,
maxRetries: 5,
framework: 'Express.js + Axios'
}
);
console.log(strategy.explanation);const result = await iwn.debug(error, {
includeExplanation: true,
includeFix: true,
context: {
code: 'your code',
framework: 'Node.js',
description: 'What you were trying to do'
}
});
console.log('Explanation:', result.explanation.explanation);
console.log('Fix:', result.fix.explanation);Create a new IWN instance.
Parameters:
-
config.provider(string): AI provider -'openai','anthropic', or'xai'(default:'openai') -
config.apiKey(string): Your API key (required) -
config.model(string): Model to use (optional) -
config.temperature(number): Temperature setting 0-1 (optional, default: 0.3)
Explain what an error means in plain English.
Parameters:
-
error(Error | string | object): The error to analyze -
context(object): Additional context -
code(string): Relevant code snippet -
framework(string): Framework/environment -
description(string): Additional details
Returns: Promise with explanation
Get actionable fix suggestions with code examples.
Parameters: Same as explainError()
Returns: Promise with fix suggestions
Analyze logs to find patterns and issues.
Parameters:
-
logs(string | array): Logs to analyze -
context(object): Additional context -
service(string): Service name -
timeRange(string): Time range -
description(string): Additional details
Returns: Promise with log analysis
Get retry and recovery strategies.
Parameters:
-
failureScenario(string): Description of the failure -
context(object): Additional context -
currentAttempts(number): Current retry count -
maxRetries(number): Max retries allowed -
framework(string): Framework being used
Returns: Promise with retry strategy
Complete debugging session with explanation and fix.
Parameters:
-
error(Error | string | object): The error to debug -
options(object): -
includeExplanation(boolean): Include explanation (default: true) -
includeFix(boolean): Include fix suggestions (default: true) -
context(object): Context object
Returns: Promise with both explanation and fix
Custom analysis for any content.
Parameters:
-
content(string): Content to analyze -
context(object): Additional context -
type(string): Analysis type -'error','log', or'retry'(default:'error')
Returns: Promise with analysis
import { IWN } from 'itworksnow';
const iwn = new IWN({
provider: 'openai',
apiKey: process.env.OPENAI_API_KEY
});
try {
const data = null;
console.log(data.map(x => x));
} catch (error) {
const result = await iwn.explainError(error);
console.log(result.explanation);
}const error = new Error('ECONNREFUSED');
const result = await iwn.debug(error, {
context: {
code: `const client = new Client(config);
await client.connect();`,
framework: 'PostgreSQL + pg',
description: 'Connection fails on startup'
}
});
console.log(result.fix.explanation);const error = {
status: 429,
message: 'Too Many Requests'
};
const strategy = await iwn.suggestRetry(
'API returning 429 Too Many Requests',
{
framework: 'Axios',
currentAttempts: 3,
maxRetries: 5
}
);
console.log(strategy.explanation);const logs = await fetchLogsFromServer();
const analysis = await iwn.analyzeLogs(logs, {
service: 'Payment Service',
timeRange: 'Last 1 hour',
description: 'Users reporting failed payments'
});
console.log(analysis.explanation);Create a .env file:
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
XAI_API_KEY=your_xai_key
{
provider: 'openai',
model: 'gpt-4o-mini',
temperature: 0.3
}{
provider: 'anthropic',
model: 'claude-3-5-sonnet-20241022',
temperature: 0.3,
maxTokens: 4096
}{
provider: 'xai',
model: 'grok-beta',
temperature: 0.3
}Always include code snippets and framework information for better results:
await iwn.explainError(error, {
code: actualCodeSnippet,
framework: 'Express.js + MongoDB',
description: 'What you were trying to accomplish'
});-
explainError()- Understanding the error -
suggestFix()- Getting solutions -
debug()- Complete analysis -
analyzeLogs()- Pattern detection -
suggestRetry()- Resilience strategies
try {
const result = await iwn.explainError(error);
console.log(result.explanation);
} catch (analysisError) {
console.error('Failed to analyze:', analysisError.message);
}-
OpenAI - Fast, cost-effective, great for general errors
-
Anthropic - Excellent for complex analysis and code review
-
xAI - Good alternative with competitive pricing
-
Lower (0.1-0.3): More focused, deterministic responses
-
Higher (0.7-1.0): More creative, varied suggestions
itworksnow/
├── src/
│ ├── core/
│ │ └── IWN.js # Main SDK class (entry logic & orchestration)
│ │
│ ├── providers/
│ │ ├── BaseProvider.js # Abstract provider interface
│ │ ├── OpenAIProvider.js # OpenAI integration
│ │ ├── AnthropicProvider.js# Anthropic (Claude) integration
│ │ └── XAIProvider.js # xAI (Grok) integration
│ │
│ ├── utils/
│ │ ├── errorParser.js # Error parsing & normalization
│ │ └── promptBuilder.js # AI prompt construction logic
│ │
│ └── index.js # Public SDK exports
│
├── examples/
│ ├── basic-usage.js # Simple usage examples
│ ├── advanced-usage.js # Advanced workflows & configs
│ └── error-handling.js # Real-world debugging scenarios
│
├── package.json # Project metadata & dependencies
└── README.md # Documentation
Contributions are welcome! Please feel free to submit issues or pull requests.
MIT
For issues, questions, or feature requests, please open an issue on GitHub.
Stop debugging alone. Let AI help. It Works Now.