DEV Community: Serhii Zhabskyi

I Tried to Keep My AI Coding Assistants in Sync. It Turned Into a Configuration Problem.

Serhii Zhabskyi — Tue, 12 May 2026 08:45:52 +0000

Most discussions around AI coding assistants focus on models, prompts, benchmarks, or editor UX.

My problem was much more boring: files.

At some point I had several AI coding assistants in the same development workflow. Not because I wanted to collect tools, but because each one was useful in a slightly different context. One was better inside the IDE. Another was useful from the terminal. Another worked better for larger refactors. Another was convenient for quick repository-level questions.

That part was fine.

The painful part was that every assistant wanted its own configuration.

One tool wanted a root instruction file. Another wanted rules in a dedicated directory. Another had its own format for MCP servers. Another supported commands. Another supported agents. Some tools had ignore files. Some had hooks. Some had permissions. Some had overlapping concepts, but not exactly the same concepts.

So the same project slowly started to contain copies of the same intent in different places.

CLAUDE.md
AGENTS.md
.cursor/rules/*.mdc
.github/copilot-instructions.md
.gemini/settings.json
.codex/config.toml
.windsurf/rules/*.md

At first this looked manageable. It was just configuration. A few markdown files. A few JSON or TOML files.

Then it became a real source of drift.

A TypeScript rule changed in one assistant but not in another. A command was updated in one place but the old version stayed somewhere else. An MCP server definition had slightly different names depending on the target. One assistant had a more recent description of the project architecture than the others.

The result was strange: I was asking different AI assistants to work on the same codebase, but they were not really working with the same understanding of the codebase.

The issue is not “which AI assistant is best”

I do not think this problem should be framed as Claude vs Cursor vs Copilot vs Codex vs Gemini vs anything else.

In practice, developers increasingly use more than one AI tool:

one inside the IDE;
one in the terminal;
one for code review;
one for large refactors;
one for documentation or migration work;
one used personally, another standardized by the team.

That is not unusual anymore.

The real problem is that every tool has its own configuration surface.

And these surfaces are not just “prompt files”. They can include:

project rules;
scoped rules;
agent definitions;
reusable commands;
skills or playbooks;
MCP servers;
hooks;
permissions;
ignore files;
global user-level configuration;
project-level team configuration.

A single shared markdown file can help, but it does not cover the whole surface.

For small projects, duplicating a few instructions manually is probably fine. For a serious project, a monorepo, or a team setup, it becomes the same class of problem we already solved many times in software engineering: one source of truth, many generated outputs.

I looked for an existing solution first

Before building anything, I tried the obvious path: use an existing sync/generation tool.

The idea was correct: keep a canonical configuration and generate assistant-specific files from it.

That worked for simple rules.

But once I tried to model the actual configuration I used every day, I kept hitting edge cases.

The first issue was cross-references.

If an agent references a skill, or a rule references a command, the relative path is different in every generated target. A link that works from .agentsmesh/skills/refactor/SKILL.md will not necessarily work from .claude/agents/code-reviewer.md or .cursor/rules/typescript.mdc.

So generation cannot be only “copy this file there”. It needs to understand references and rebase links per target.

The second issue was unsupported features.

Some tools have native agents. Some do not. Some have commands. Some do not. Some have hooks. Some have permissions. Some only have a general instruction file.

If a target does not support a feature natively, there are a few possible choices:

drop the feature;
flatten everything into a generic prompt;
embed the feature with metadata so it can be reconstructed later.

Dropping data was not acceptable. Flattening everything made import/generate cycles lossy. I wanted round-trip behavior: import existing configs, normalize them, generate them again, and not silently lose structure.

The third issue was tool velocity.

New AI coding tools appear constantly. Existing ones change their config formats. Waiting for a central maintainer to add support for every new assistant is not a great model if the ecosystem keeps moving this fast.

That is where I decided to build my own solution.

The mental model I wanted

The model I wanted was not unusual.

We already use it everywhere:

TypeScript source  -> JavaScript output
.proto files       -> generated SDKs
OpenAPI schema     -> generated clients
Dockerfile         -> image
source config      -> target artifacts

I wanted the same pattern for AI assistant configuration.

There should be one canonical directory that describes the intent:

.agentsmesh/
  rules/
  commands/
  agents/
  skills/
  mcp.json
  hooks.yaml
  permissions.yaml
  ignore

Then a generator should project that intent into the native layout of each assistant.

Generated files should be treated as artifacts. You can inspect them, commit them if needed, and let tools consume them in their native format. But humans should primarily edit the canonical source.

That is the important distinction.

I did not want to force every tool into one lowest-common-denominator format. I wanted to preserve native output where possible, while keeping a canonical source that is easier to reason about.

Why this is harder than it looks

At first this sounds like a file converter.

It is not.

The hard parts are mostly about preserving semantics.

1. Native vs embedded capabilities

A target may support a feature natively, partially, or not at all.

For example:

one assistant may have a native commands directory;
another may only support commands as embedded sections in a root instruction file;
another may not have a useful equivalent at all.

The generator needs to know that difference.

More importantly, the importer also needs to know that difference. Otherwise you can generate an embedded command, import it again, and lose the original command boundary.

That is why metadata matters. Not because metadata is elegant, but because lossless round trips are impossible without some way to preserve structure where the target format does not have a native slot.

2. Link rebasing

This was one of the first problems that made the project feel necessary.

Developers naturally split configuration into multiple files:

See ../skills/refactor/SKILL.md before changing this module.

But after generation, that file may live somewhere completely different.

So links must be rewritten depending on the target layout.

This sounds small until you realize that agents can reference skills, skills can reference supporting files, commands can reference rules, and project/global modes have different path assumptions.

If this is not handled, the generated configuration looks correct but slowly rots because internal links stop working.

3. Drift detection

If generated files are committed, somebody will eventually edit them directly.

That is not a moral failure. It is normal developer behavior.

But then the repository needs a way to detect whether the generated files still match the canonical source.

So the workflow needs a check step:

agentsmesh check

The point is not to be strict for the sake of being strict. The point is to make drift visible before different assistants start reading different versions of the project rules.

4. Import matters as much as generate

A tool like this is not useful if adoption requires a clean rewrite.

Most real projects already have some assistant configuration:

.cursor/rules/
CLAUDE.md
.github/copilot-instructions.md
AGENTS.md

So import needs to exist:

agentsmesh import --from cursor
agentsmesh generate

That gives a realistic migration path: start from what already exists, normalize it, then generate from the canonical structure.

5. Plugins are necessary

The AI tooling ecosystem changes too quickly for every target to be hardcoded forever.

So target support has to be data-driven and extensible.

A target should describe:

where its files live;
which features it supports;
whether each feature is native, embedded, partial, or unsupported;
how to generate its output;
how to import existing files back.

That makes it possible to ship new target support as a plugin instead of changing core every time a new assistant appears.

What I ended up building

I built AgentsMesh around that model.

The basic workflow is intentionally boring:

npx agentsmesh init
npx agentsmesh generate

For an existing project:

npx agentsmesh import --from cursor
npx agentsmesh generate

For CI:

npx agentsmesh check

For reviewing output before writing:

npx agentsmesh diff

For personal global config:

npx agentsmesh init --global
npx agentsmesh generate --global

The goal is not to replace any assistant.

The goal is to stop treating assistant configuration as scattered hand-written state.

This is useful outside Node.js projects

The CLI is distributed through npm, but the problem is not Node-specific.

A Rust team can have the same issue. A Python backend can have the same issue. A Java monolith can have the same issue. A Go service, Unity project, mobile app, infrastructure repo, or documentation-heavy project can all hit the same problem once several AI tools are involved.

The configuration being synchronized is not about Node.js. It is about how AI assistants understand a repository.

That includes things like:

coding conventions;
architecture rules;
domain vocabulary;
testing strategy;
forbidden files or directories;
review checklists;
migration playbooks;
commands for repetitive workflows;
MCP server definitions;
permissions and safety boundaries.

Every codebase has some version of this knowledge.

The question is whether it lives in one place or slowly diverges across tools.

Where I think this category is going

I do not think AI coding configuration will become simpler.

I expect the opposite.

Assistants will get more capabilities:

deeper repo indexing;
more tool execution;
more agent-like workflows;
more project memory;
more MCP usage;
more fine-grained permissions;
more team-level policies.

That means configuration will matter more, not less.

A single prompt file may be enough for now in many projects. But as soon as teams start using several assistants with different capabilities, the config layer becomes infrastructure.

And infrastructure usually needs:

a source of truth;
reproducible generation;
validation;
drift detection;
reviewable diffs;
import/export paths;
extension points.

That is the direction I wanted AgentsMesh to take.

When I would not use it

There are cases where this is overkill.

If you use one assistant, one project, and one instruction file, you probably do not need a canonical sync layer.

If your rules are tiny and rarely change, manual duplication might be cheaper than introducing tooling.

If your team does not commit assistant config at all, the value is lower.

But if you maintain several assistants, or you care that every assistant reads the same project rules, then the problem becomes real very quickly.

For me, the breaking point was realizing that my AI tools were not disagreeing because the models were different.

They were disagreeing because I had taught them different versions of the same project.

That is the bug I wanted to remove.

Links

AgentsMesh repository:

https://github.com/sampleXbro/agentsmesh

Documentation:

https://samplexbro.github.io/agentsmesh/

I had four AI coding assistants and the same config in five places. Here's what I built.

Serhii Zhabskyi — Tue, 28 Apr 2026 08:31:01 +0000

A while back my repo looked like this:

CLAUDE.md                                        # rules for Claude Code
.claude/agents/code-reviewer.md                  # agent definitions
.claude/skills/refactor/SKILL.md                 # skill packs
.claude/commands/deploy.md                       # slash commands
.claude.json                                     # MCP servers
.cursor/rules/typescript.mdc                     # rules for Cursor
.cursor/mcp.json                                 # MCP servers (different schema)
.github/copilot-instructions.md                  # rules for Copilot
.github/agents/code-reviewer.md                  # agents (different format)
.continue/rules/typescript.md                    # rules for Continue
.continue/mcpServers/                            # MCP servers (yet another schema)

Same rule - "no any, prefer unknown with narrowing" - in four places. Same MCP server configured three times in three JSON schemas. Same code-reviewer agent described twice with different frontmatter. Same deployment command in two directories.

Then someone updated unknown to never for a specific case in CLAUDE.md only. Cursor still suggested unknown. Copilot agreed with neither. We spent a standup figuring out which AI was "right."

The problem wasn't rules alone. It was the entire config surface: rules, agents, skills, commands, MCP servers, hooks, permissions, and ignore files - all duplicated per tool, all drifting independently.

What I tried first

I looked for existing tools that solve this. The most popular one in this space has the right model: one canonical source, generate per-tool configs. I used it for a few months.

But I kept hitting gaps. Cross-references between files didn't get rewritten on generate, so an agent linking to a skill produced broken paths in every target. Activation semantics got inverted across tool dialects - a manual-only rule became always-on after translation. Hook configs got generated but the scripts they referenced didn't follow. Permissions weren't modeled as a feature at all. And every new AI coding tool that shipped needed a PR to the maintainer's repo — some requests sat open for over a year.

These aren't bugs. They're architectural limits that compound once you grow past flat rule syncing into the full config surface: agents, skills with supporting files, hooks with scripts, permissions, MCP servers with tool-specific schemas.

The pattern

You already use this pattern elsewhere:

package.json → package-lock.json
Dockerfile → image
*.proto → client SDKs

Apply it to AI configs:

One canonical directory describes rules, commands, agents, skills, MCP, hooks, ignore, and permissions in a tool-agnostic way.
A generator projects them into each tool's native format.
An importer does the reverse, so you can adopt without rewriting existing configs.
A lock file detects drift in CI.

The interesting work is in the link rewriting, the round-trip story, and getting the full feature surface (not just rules) to project correctly across 12 tools.

What I built

agentsmesh implements this pattern. Here's the canonical directory and what it generates:

.agentsmesh/                           Generated output (Claude Code):
├── rules/                             ├── CLAUDE.md
│   ├── _root.md                       ├── .claude/
│   └── typescript.md                  │   ├── rules/typescript.md
├── agents/                            │   ├── agents/code-reviewer.md
│   └── code-reviewer.md              │   ├── skills/refactor/
├── skills/                            │   │   ├── SKILL.md
│   └── refactor/                      │   │   └── references/patterns.md
│       ├── SKILL.md                   │   ├── commands/deploy.md
│       └── references/                │   └── settings.json  (hooks, perms)
│           └── patterns.md            ├── .claude.json        (MCP)
├── commands/                          
│   └── deploy.md                      Generated output (Cursor):
├── mcp.json                           ├── .cursor/
├── hooks.yaml                         │   ├── rules/
├── permissions.yaml                   │   │   ├── _root.mdc
└── ignore                             │   │   └── typescript.mdc
                                       │   ├── skills/refactor/
                                       │   │   ├── SKILL.md
                                       │   │   └── references/patterns.md
                                       │   └── mcp.json
                                       ├── AGENTS.md (agents + commands embedded)
                                       └── .cursorignore

One canonical source. Two different generated trees with different directory layouts, different file formats, different frontmatter conventions — all from the same .agentsmesh/ input.

Adopt in an existing project:

npx agentsmesh import --from cursor   # or claude-code, copilot, codex-cli, ...
npx agentsmesh generate

import walks your existing tool config, normalizes it into the canonical shape. generate projects it back out to every enabled tool.

Cross-references get rewritten per-target

This is the part I underestimated.

When the code-reviewer agent file says "see the refactor skill for the full playbook", that link has to resolve differently in every generated output:

Target	The agent's skill link resolves to
Claude Code	`.claude/skills/refactor/SKILL.md`
Cursor	`.cursor/skills/refactor/SKILL.md`
Codex CLI	`.codex/skills/refactor/SKILL.md`
Claude Code (global)	`~/.claude/skills/refactor/SKILL.md`

The rebaser at src/core/reference/link-rebaser.ts rewrites every link per target. The rules are explicit:

Inside .agentsmesh/ → relative paths.
Outside .agentsmesh/ in project mode → repo-root absolute paths.
Outside .agentsmesh/ in global mode → no rewrite. Your home directory isn't mine to touch.
Markdown link URLs stay relative for portability.

Without this you can't have agents referencing skills, skills referencing other skills, rules pointing at commands. You're forced to keep everything in one flat file with no cross-references.

Lossless round-trip across the full feature surface

When a target doesn't natively support a feature (Cursor has no native skills directory, Copilot has no native hooks), the generator embeds them with metadata so re-importing reconstructs the original shape.

This matters for more than just rules:

Skills with supporting files (references, templates, scripts) survive projection to tools that don't have a skills directory — they get embedded in the root instructions with metadata markers.
Agents defined in .agentsmesh/agents/code-reviewer.md become .claude/agents/code-reviewer.md for Claude (native), or get embedded in AGENTS.md for Cursor and Codex (which read that file).
Commands become .claude/commands/deploy.md for Claude, .gemini/commands/deploy.toml for Gemini (different format entirely), or get embedded in the root instructions for tools that don't have a commands directory.
Activation semantics survive too — Cursor's alwaysApply: false round-trips through Claude generation and back into canonical form without getting inverted.

Hooks and permissions are first-class

hooks.yaml and permissions.yaml are canonical types alongside rules and skills. Hooks generate in each target's native format — JSON config in settings for Claude, wrapper scripts for Copilot, per-file .kiro.hook for Kiro. Permissions project to native settings where the target supports it (currently Claude Code has full native support; others embed or partially support).

Targets are data, not classes

A target is a TargetDescriptor value declared in src/targets/<id>/index.ts. The engine reads the descriptor and dispatches generically — it never branches on target name. Capability levels (native | embedded | partial | none) are declared per feature in the descriptor:

capabilities: {
  rules: 'native',
  commands: 'native',
  agents: 'embedded',    // no native agent dir → embed in root instructions
  skills: 'native',
  mcp: 'native',
  hooks: 'partial',      // limited event support
  permissions: 'none',
  ignore: 'native',
}

The builtin catalog is auto-discovered at build time by scanning src/targets/*/index.ts. agentsmesh target scaffold foo-ide generates the full structure — descriptor, generators, importer, linter, constants, tests — so you start from a working base. No enum to update, no shared code to edit.

Plugins ship as standalone npm packages

npx agentsmesh plugin add agentsmesh-target-foo-ide
npx agentsmesh generate

Plugins get full built-in parity — same descriptor schema, same capability levels, same lint hooks and global-mode support as built-ins. New tool support doesn't wait for me.

CI/dev workflow

- run: npx agentsmesh check    # exits 1 on drift

The rest of the surface:

agentsmesh diff — preview what generate would change, without writing.
agentsmesh lint — validate canonical config against per-target constraints.
agentsmesh watch — regenerate target files on save during local editing.
agentsmesh merge — resolve three-way .lock conflicts after git merge.
agentsmesh matrix — print the full support matrix for all targets and features.

Global mode for personal config

npx agentsmesh init --global
npx agentsmesh import --global --from claude-code
npx agentsmesh generate --global   # writes ~/.claude/, ~/.cursor/, ~/.codex/, ...

~/.agentsmesh/ is for personal setup across every repo you touch. Every CLI command accepts --global.

Native Windows

Path-format detection (/proj vs C:\proj) decoupled from host platform. chokidar polling on Windows for ReadDirectoryChangesW edge cases. basename() everywhere instead of split('/'). CI matrix runs Linux + macOS + Windows.

Typed programmatic API

Same surface as the CLI, exported with full .d.ts under strict TS:

import { loadProjectContext, generate, lint, diff, check } from 'agentsmesh';

const project = await loadProjectContext(process.cwd());
await generate(project);
const drift = await check(project);

Subpath imports for narrower bundles: agentsmesh/engine, agentsmesh/canonical, agentsmesh/targets.

JSON Schema for every config

agentsmesh.yaml, hooks.yaml, permissions.yaml, mcp.json, pack.json — all ship with generated $schema references. VS Code and JetBrains autocomplete + validation work out of the box.

Community packs

npx agentsmesh install github:org/shared-config@v1.0.0
npx agentsmesh install --sync    # restore all packs after clone

Packs live in .agentsmesh/packs/, track in installs.yaml, and merge into canonical config on every generate.

What it doesn't do

No GUI. It's a CLI and a library.
Doesn't manage secrets. MCP server tokens stay in your existing secret store.
Won't help if you only use one tool. The canonical layer is overhead.
Smaller ecosystem. Fewer community packs and fewer eyes on it.

Try it

npm install -D agentsmesh
npx agentsmesh init
# or, in an existing project:
npx agentsmesh import --from cursor
npx agentsmesh generate

Linux, macOS, Windows (native, not WSL). MIT. Node 20+. ESM-only. Strict TypeScript.

Source: github.com/sampleXbro/agentsmesh · Docs: samplexbro.github.io/agentsmesh

Supercharge Your Axios Requests: axios-retryer for Robust API Communication

Serhii Zhabskyi — Sat, 24 May 2025 15:52:24 +0000

I’ve been working on a React application that needed a robust solution for handling concurrent requests, custom retry logic, and token refresh—without shuffling together multiple scattered packages. I couldn’t find an all-in-one library that combined concurrency management, priorities, token refresh, caching, and circuit breaking in a straightforward API, so I built axios-retryer.

📝 Why I Wrote It

In this TV-based frontend project some data requests were absolutely critical (e.g., user authentication or top-level layout info) and needed to complete before all the nice-to-have background calls. Sure, I could let Axios blasts run wild, but that risked important calls getting stuck behind less urgent tasks. I also hated duplicating retry logic across different request modules. So, I decided to create a single “retryer” layer for concurrency, priority handling, advanced retry strategies, token refreshing, circuit-breaking, caching, and analytics events. Doing so helped me replace multiple incomplete solutions with a single, consistent approach.

🚀 Key Features at a Glance

Priority & Concurrency: Queue requests so critical calls finish before everything else, with fine-grained control over simultaneous requests.
Customizable Retry Strategies: Built-in linear, exponential backoff, static, or provide your own custom retry logic function.
TokenRefreshPlugin: Automatically refresh access tokens upon expiry and seamlessly replay pending requests.
CircuitBreakerPlugin: Intelligently detect repeated errors from an endpoint and temporarily halt requests to avoid further failures, then gracefully recover.
CachingPlugin: Cache responses for common requests to reduce load times and bandwidth usage.
Metrics & Events: Observe request outcomes, success/failure rates, circuit states, and other vital statistics through a rich event system.
Minimal Overhead: Approximately 6.4 kB minified + gzipped (core library with all plugins) means it won’t bloat your bundle.

⚙️ Quick Install & Hello World

Installation is straightforward using npm, yarn, or pnpm. Here’s the minimal setup to get you started:

# Using npm
npm install axios-retryer

# Using yarn
yarn add axios-retryer

// Import the library
import { createRetryer } from 'axios-retryer';

async function main() {
  // Create a retryer instance with sensible defaults
  const retryer = createRetryer({
    retries: 3, // Attempt requests up to 3 times on failure
    debug: false // Set to true for development logging
  });

  // Use the axiosInstance provided by the retryer
  try {
    const response = await retryer.axiosInstance.get('https://api.example.com/data');
    console.log('Data:', response.data);
  } catch (error) {
    console.error('All retries failed:', error);
  }
}

main();

That’s the essence: createRetryer() returns a manager object, and you use its axiosInstance property, which is a specially configured Axios instance with concurrency, retry logic, and plugin support baked in.

Priority & Concurrency

Priority and concurrency control were the main motivators for this library. In many applications, you can’t just fire off 20 requests simultaneously and hope they resolve in the right order. Instead, you often need to limit how many calls happen at once (maxConcurrentRequests), while also ensuring critical requests jump the queue (__priority).

Concurrency: If you set maxConcurrentRequests to, say, 2, axios-retryer will ensure that no more than two requests are in-flight at any given time. This can mitigate server load and prevent the UI from becoming unresponsive under heavy network traffic.
Priority: By passing a __priority option (numeric, typically using predefined constants) in your request config, you can dictate which requests get processed first from the queue. Lower numeric priority values in the constants (e.g., CRITICAL) mean higher actual priority.

Here’s a TypeScript snippet demonstrating this:

import { createRetryer, AXIOS_RETRYER_REQUEST_PRIORITIES } from 'axios-retryer';

const retryer = createRetryer({
  maxConcurrentRequests: 2, // Max two concurrent requests
  // Requests with priority >= HIGH will block lower priority ones
  blockingQueueThreshold: AXIOS_RETRYER_REQUEST_PRIORITIES.HIGH
});

async function exampleRequests() {
  // Critical request - gets processed sooner, potentially blocking others
  retryer.axiosInstance.get('/critical-endpoint', {
    __priority: AXIOS_RETRYER_REQUEST_PRIORITIES.CRITICAL
  }).then(response => console.log('Critical data received:', response.data));

  // Standard important request
  retryer.axiosInstance.get('/user-profile', {
    __priority: AXIOS_RETRYER_REQUEST_PRIORITIES.HIGH
  }).then(response => console.log('User profile received:', response.data));

  // Lower priority request - waits if concurrency is at capacity or blocked
  retryer.axiosInstance.get('/background-sync', {
    __priority: AXIOS_RETRYER_REQUEST_PRIORITIES.LOW
  }).then(response => console.log('Background sync complete:', response.data));
}

exampleRequests();

Behind the scenes, axios-retryer manages an internal priority queue. When maxConcurrentRequests is reached, new requests are enqueued. Within that queue, items are sorted by their __priority. The blockingQueueThreshold adds another layer, ensuring that no requests with a priority lower than the threshold are processed if higher-priority requests are pending.

Retry Strategies (Linear, Exponential, Static, Custom)

We’ve all implemented the typical "retry a request 3 times if it fails," but sometimes a more sophisticated approach is needed. axios-retryer supports various backoff strategies:

Linear: Increments wait times consistently (e.g., 1s, 2s, 3s).
Exponential: Doubles the backoff period with each attempt (e.g., 1s, 2s, 4s, 8s). This is the default.
Static: Static backoff period (e.g. 2s, 2s, 2s, 2s).
Custom: Pass your own function to calculate delays.

You configure the retry behavior within the createRetryer options:

import { createRetryer, AXIOS_RETRYER_BACKOFF_TYPES } from 'axios-retryer';

const retryer = createRetryer({
  retries: 3, // Total retry attempts
  backoffType: AXIOS_RETRYER_BACKOFF_TYPES.EXPONENTIAL, // 'linear', 'exponential', 'static'
  // You can also specify retryable HTTP methods and status codes
  retryableMethods: ['get', 'head', 'options', 'put'],
  retryableStatuses: [408, 429, [500, 599]] // Retries on 408, 429, or 5xx
});

// This request will use the exponential backoff strategy defined above
retryer.axiosInstance.get('/some-flaky-endpoint')
  .catch(err => console.error('Failed after exponential backoff retries:', err));

For a completely custom strategy, you can provide a retryStrategy object with isRetryable, shouldRetry, and getDelay functions:

import { createRetryer, createRetryStrategy } from 'axios-retryer';

const customStrategy = createRetryStrategy({
  isRetryable: (error) => !error.response || (error.response.status >= 500 && error.response.status < 600),
  shouldRetry: (error, attempt, maxRetries) => {
    if (error.config?.method?.toLowerCase() === 'post' && attempt >= 1) {
      return false; // Don't retry POST requests more than once
    }
    return attempt < maxRetries; // Note: attempt is 0-indexed for calculation
  },
  getDelay: (attempt) => (attempt + 1) * 1000 + (Math.random() * 500) // Linear backoff with jitter
});

const customRetryer = createRetryer({
  retries: 4,
  retryStrategy: customStrategy
});

customRetryer.axiosInstance.post('/another-endpoint', { data: 'payload' })
  .catch(err => console.error('Failed with custom strategy:', err));

The library automatically handles the asynchronous timeouts for you.

TokenRefreshPlugin (Single Refresh + Replay)

Dealing with expired authentication tokens is a common pain point, especially if multiple requests are made around the token's expiration time. The TokenRefreshPlugin simplifies this by detecting token-related errors (typically 401 Unauthorized), automatically fetching a new token (once per expiration cycle), and then replaying the requests that failed due to the expired token.

Here’s how you set it up:

import { createRetryer } from 'axios-retryer';
import { createTokenRefreshPlugin } from 'axios-retryer/plugins/TokenRefreshPlugin';
import axios from 'axios'; // Import base axios for the refresh function if needed

const retryer = createRetryer({
  maxConcurrentRequests: 3
  // other configurations...
});

const tokenRefreshPlugin = createTokenRefreshPlugin(
  async (axiosInstanceForRefresh) => {
    // This function is called to get a new token
    // It receives an Axios instance specifically for the refresh call
    // to avoid circular dependencies with the retryer's interceptors.
    console.log('Attempting to refresh token...');
    const refreshToken = localStorage.getItem('refreshToken');
    // Use a clean axios instance for the refresh call
    const { data } = await axios.post('/auth/refresh', { refreshToken });
    localStorage.setItem('accessToken', data.accessToken);
    console.log('Token refreshed successfully.');
    return { token: data.accessToken }; // Must return the new token
  },
  {
    // Optional configuration for the plugin
    authHeaderName: 'Authorization',    // Default: 'Authorization'
    tokenPrefix: 'Bearer ',             // Default: 'Bearer '
    refreshStatusCodes: [401],          // Default: [401]
    maxRefreshAttempts: 2,              // Default: 3
    // Custom detector for APIs that don't use 401 (e.g., GraphQL)
    customErrorDetector: (response) => {
      return response?.data?.errors?.some(
        (err: any) => err.extensions?.code === 'UNAUTHENTICATED' || err.message?.includes('token expired')
      );
    }
  }
);

// Add the plugin to the retryer instance
retryer.use(tokenRefreshPlugin);

// Now, requests made with retryer.axiosInstance will benefit from auto token refresh
retryer.axiosInstance.get('/secure-data')
  .then(response => console.log('Secure data:', response.data))
  .catch(error => console.error('Failed to get secure data:', error));

When a request returns a status code matching refreshStatusCodes (or if customErrorDetector returns true), the plugin pauses outgoing requests, executes your fetchNewToken function, updates the default headers of the retryer.axiosInstance with the new token, and then replays the original failed request and any other requests that were queued while the token was being refreshed.

CircuitBreakerPlugin

To prevent an application from repeatedly trying to connect to a service that is known to be failing, you can use the CircuitBreakerPlugin. Once a configured error threshold is met (e.g., 5 failed requests in a row), the circuit "opens," and subsequent requests to that service fail immediately (short-circuit) without hitting the network. After a cooldown period, the circuit transitions to a "half-open" state, allowing a limited number of test requests. If these succeed, the circuit "closes" and normal operation resumes. If they fail, it re-opens.

import { createRetryer } from 'axios-retryer';
import { createCircuitBreaker } from 'axios-retryer/plugins/CircuitBreakerPlugin'; // Corrected import name

const retryer = createRetryer({
  // other configurations...
});

const circuitBreakerPlugin = createCircuitBreaker({
  failureThreshold: 5,     // Trip after 5 consecutive failures
  openTimeout: 30000,      // Stay open for 30 seconds
  halfOpenMax: 2,          // Allow 2 test requests in half-open state
  successThreshold: 2,     // Need 2 successes in half-open to close
  useSlidingWindow: false  // Set to true for time-based failure counting
});

retryer.use(circuitBreakerPlugin);

// Requests to a consistently failing service will eventually be short-circuited
function fetchDataRepeatedly() {
  retryer.axiosInstance.get('/unreliable-service')
    .then(response => console.log('Service responded:', response.data))
    .catch(error => {
      console.error('Service call failed:', error.message);
      if (error.isAxiosError && error.message.includes('Circuit is open')) {
        console.log('Circuit breaker is open, not attempting network request.');
      }
    });
}

// Simulate multiple calls
// setInterval(fetchDataRepeatedly, 2000);

This pattern is crucial for building resilient applications that can gracefully handle temporary outages of downstream services.

CachingPlugin

The CachingPlugin (using createCachePlugin) helps you cache responses from specific endpoints, reducing unnecessary network calls and improving perceived performance. You can configure cache lifetime, which HTTP methods to cache, and more.

import { createRetryer } from 'axios-retryer';
import { createCachePlugin } from 'axios-retryer/plugins/CachingPlugin'; // Corrected import name

const retryer = createRetryer({
  // other configurations...
});

const cachePlugin = createCachePlugin({
  timeToRevalidate: 60 * 1000, // Cache entries for 1 minute (in ms)
  cacheMethods: ['GET'],       // Only cache GET requests (default)
  cleanupInterval: 5 * 60 * 1000, // Check for stale entries every 5 minutes
  maxItems: 100,               // Store up to 100 cached items
  compareHeaders: false,       // Set to true to include headers in cache key
  cacheOnlyRetriedRequests: false // Set to true to only cache successful retried requests
});

retryer.use(cachePlugin);

async function fetchCachedData() {
  console.log('Fetching /static-data...');
  const response1 = await retryer.axiosInstance.get('/static-data');
  console.log('Data 1:', response1.data, '(from network or cache)');

  console.log('Fetching /static-data again...');
  const response2 = await retryer.axiosInstance.get('/static-data');
  console.log('Data 2:', response2.data, '(likely from cache if within TTR)');
}

fetchCachedData();

// You can also control caching on a per-request basis
retryer.axiosInstance.get('/api/realtime-updates', {
  __cachingOptions: {
    cache: false // Disable caching for this specific request
  }
});

retryer.axiosInstance.post('/api/submit-form', { data: 'content' }, {
  __cachingOptions: {
    cache: true, // Force caching for this POST request (if method allowed globally)
    ttr: 30000   // Custom Time To Revalidate: 30 seconds
  }
});

The plugin automatically generates cache keys based on the request URL, method, and optionally headers. It provides methods to invalidate or clear the cache programmatically.

Metrics/Events

Monitoring real-time performance and understanding request behavior can help you catch bottlenecks or diagnose issues. axios-retryer emits a variety of events throughout the request lifecycle, allowing you to wire up custom analytics or logging.

You subscribe to these events using the on method of the retryer instance:

import { createRetryer } from 'axios-retryer';

const retryer = createRetryer({ debug: true }); // Enable debug for more event logs

retryer
  .on('onRetryProcessStarted', (requestConfig) => {
    console.log(`[Event] Retry process started for: ${requestConfig.url}`);
  })
  .on('beforeRetry', (requestConfig, attemptInfo) => {
    console.log(`[Event] Before retry attempt ${attemptInfo.attemptNumber} for: ${requestConfig.url}`);
  })
  .on('afterRetry', (requestConfig, attemptInfo, wasSuccessful) => {
    console.log(`[Event] After retry attempt ${attemptInfo.attemptNumber} for: ${requestConfig.url}. Success: ${wasSuccessful}`);
  })
  .on('onRetryProcessFinished', (requestConfig, metrics) => {
    console.log(`[Event] Retry process finished for: ${requestConfig.url}. Metrics:`, metrics);
    // metrics include totalAttempts, wasSuccessful, etc.
  })
  .on('onMetricsUpdated', (globalMetrics) => {
    // These are overall metrics for the retryer instance
    // console.log('[Event] Global metrics updated:', globalMetrics);
    // updateDashboard(globalMetrics);
  })
  .on('onTokenRefreshed', (newToken) => {
    console.log('[Event] Token was successfully refreshed.');
  });

// Example request to trigger events
retryer.axiosInstance.get('https://api.example.com/flaky')
  .catch(() => console.log('Request to flaky endpoint eventually failed or succeeded.'));

The globalMetrics object provided by onMetricsUpdated includes counts for total requests, successful retries, failed retries, and new timer health statistics to help monitor event loop congestion.

💡 Less-Obvious Use Cases

Beyond the standard retry or concurrency scenarios, here are some other ways axios-retryer can be beneficial:

Offline-First PWAs: In Progressive Web Apps, use mode: 'manual' to store failed requests when offline. When the connection is re-established, call retryer.retryFailedRequests() to sync critical data, respecting priorities.
Serverless Edge Functions: When calling external APIs from environments with strict concurrency limits (like some edge function providers), maxConcurrentRequests helps stay within quotas.
React Query/SWR Adapter: While libraries like React Query or SWR handle their own caching and some retries, axios-retryer can manage the underlying Axios instance to provide global concurrency limits, priority queuing, and standardized token refresh logic for all data fetches.
Robust Microservice Communication (Node.js): If your Node.js backend acts as an API gateway or communicates with multiple microservices, axios-retryer (with plugins like Circuit Breaker) can make these interactions more resilient.
Batch Data Uploads/Processing: For scenarios where you need to upload many items or process a batch of API calls, concurrency control ensures you don't overwhelm the server, and retries handle intermittent failures gracefully.
Web Scraping Responsibly: When scraping data, use maxConcurrentRequests and appropriate backoff strategies with queueDelay to avoid overwhelming the target server and to respect its rate limits.

📈 Performance & Bundle Size

axios-retryer is designed to be efficient. The core library, including all plugins, comes in at approximately 6.4 kB minified and gzipped. The plugin system is modular, so if you don't use a plugin, its code won't be included in your bundle when using tree-shaking.

Performance considerations:

The priority queue uses efficient data structures (like a binary heap) for O(log n) operations.
Retry strategies add minimal overhead, primarily driven by JavaScript timers.
The new timer management system actively monitors and helps prevent event loop congestion from excessive timers.

It should integrate smoothly into typical front-end or Node.js projects without significantly impacting bundle size or runtime performance.

🛣️ Roadmap & Contribution Call

I have several features and improvements planned for future releases:

WebSocket Reconnection Plugin: A dedicated plugin to manage robust WebSocket connections, including automatic reconnection with backoff strategies.
DevTools Panel: A browser extension (e.g., for Chrome/Firefox DevTools) to visualize the request queue, circuit breaker states, cache contents, and active timers.
More Granular Cache Control: Advanced cache invalidation strategies and tagging.

Contributions are highly welcome! Whether it's tackling one of these features, suggesting new ones, improving documentation, or reporting bugs, your input is valuable. Please check out the CONTRIBUTING.md file on GitHub, open an issue to discuss your ideas, or submit a pull request.

🏁 Conclusion / CTA

If you're tired of cobbling together solutions for API request concurrency, complex retries, token refreshing, circuit breaking, and caching, axios-retryer offers a unified and powerful approach.

Install: npm install axios-retryer

Explore the documentation, examples, and source code on GitHub. If you find it useful, please consider giving it a star! I’d love to hear your feedback, learn about your use cases, and see how axios-retryer can be improved to better serve the developer community.