⚡ High-performance job queue for Bun. SQLite persistence, DLQ, cron jobs, S3 backups. Built for AI agents and automation
$ npx -y skills add egeominotti/bunqueue --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Repo: egeominotti/bunqueue
What's inside
bun add bunqueue
import { Bunqueue } from 'bunqueue/client';
const app = new Bunqueue('emails', {
embedded: true,
dataPath: './data/emails.db', // omit to run in-memory (lost on restart)
processor: async (job) => {
console.log(`Sending to ${job.data.to}`);
return { sent: true };
},
});
await app.add('send', { to: 'alice@example.com' });
That's it. Queue + Worker in one object, persisted to a single SQLite file.
No Redis, no config, no setup. The install is 5.5 MB, 7 packages, 2 runtime
dependencies (croner + msgpackr) — SQLite, S3, HTTP and WebSocket are Bun
built-ins.
The queue also runs as a standalone server — one command, nothing else to operate:
# in-memory without --data-path; pass it to persist jobs to SQLite
bunx bunqueue start --data-path ./data/bunq.db # TCP :6789, HTTP :6790
# or, with no runtime at all (the volume persists /app/data):
docker run -d -p 6789:6789 -p 6790:6790 \
-v bunqueue-data:/app/data \
ghcr.io/egeominotti/bunqueue:latest
Release images also carry the exact package version. For reproducible
deployments, pin ghcr.io/egeominotti/bunqueue:2.8.59; latest points to the
same multi-arch image at release time.
Then produce and process from the language you already use:
npm install bunqueue-client # Node.js ≥ 20, Deno ≥ 2, Bun, Cloudflare Workers
import { Queue, Worker } from 'bunqueue-client';
const queue = new Queue('emails'); // localhost:6789 by default
await queue.add('welcome', { to: 'user@example.com' });
new Worker('emails', async (job) => ({ sent: true }), { concurrency: 10 });
Python, PHP, Go, Rust and Elixir clients speak the same protocol — see One Queue, Any Language.
Only the server and embedded mode are Bun-only (
bun >= 1.3.9, bun.sh); producers and workers can run anywhere.
| Library | Requires | AI-native |
|---|---|---|
| BullMQ | Redis | No |
| Agenda | MongoDB | No |
| pg-boss | PostgreSQL | No |
| bunqueue | Nothing | Yes |
cp to back upQueue, Worker, QueueEvents; migrating takes minutesaddBulk, and
159K jobs/sec TCP PUSHB; methodology and distributionsGreat for: single-server deployments, AI agents that need a scheduler, prototypes and MVPs, embedded use cases (CLI tools, edge, serverless), teams that don't want to operate Redis.
Not ideal for: multi-region distributed systems requiring HA or automatic failover today. If you already run Redis and BullMQ works for you, keep it.
| Embedded | Server (TCP) | |
|---|---|---|
| How it works | Queue runs inside your process | Standalone server, clients connect via TCP |
| Setup | bun add bunqueue | docker run or bunqueue start |
| Performance | 186K jobs/sec on-disk addBulk; 729K internal in-memory batch | 159K jobs/sec TCP PUSHB; 17K jobs/sec worker drain |
| Best for | Single-process apps, CLIs, serverless | Multiple workers, separate producer/consumer |
| Scaling | Same process only | Multiple clients across machines |
Everything in your process. Without a data path the queue is in-memory: pass
dataPath (or set BUNQUEUE_DATA_PATH) to persist jobs.
import { Queue, Worker } from 'bunqueue/client';
const queue = new Queue('emails', { embedded: true, dataPath: './data/app.db' });
const worker = new Worker(
'emails',
async (job) => {
return { sent: true };
},
{ embedded: true }
);
await queue.add('welcome', { to: 'user@example.com' });
docker run -d -p 6789:6789 -p 6790:6790 \
-v bunqueue-data:/app/data \
ghcr.io/egeominotti/bunqueue:latest
import { Queue, Worker } from 'bunqueue/client';
const queue = new Queue('tasks', { connection: { host: 'localhost', port: 6789 } });
const worker = new Worker(
'tasks',
async (job) => {
return { done: true };
},
{ connection: { host: 'localhost', port: 6789 } }
);
await queue.add('process', { data: 'hello' });
Running the server → · Deployment guide →
The server does all the heavy lifting. Official client SDKs speak the native TCP protocol with full feature parity, so producers and workers can live anywhere in your stack — add a job from TypeScript, process it from Python:
| Where your code runs | Install |
|---|---|
| Node.js ≥ 20, Deno ≥ 2, Bun, Cloudflare Workers | npm install bunqueue-client |
| Python ≥ 3.9 | pip install bunqueue-client |
| PHP ≥ 8.1 | composer require bunqueue/client |
| Go ≥ 1.26.5 | go get github.com/egeominotti/bunqueue/sdk/go |
| Rust ≥ 1.85 | cargo add bunqueue-client |
| Elixir ≥ 1.15 | Hex coming soon — today: use sdk/elixir as a path dependency |
// Node.js / Deno / Cloudflare Workers
import { Queue, Worker } from 'bunqueue-client';
const queue = new Queue('emails', { host: 'localhost', port: 6789 });
await queue.add('welcome', { to: 'user@example.com' });
new Worker('emails', async (job) => ({ sent: true }), { concurrency: 10 });
# Python
from bunqueue import Queue, Worker
queue = Queue("emails", host="localhost", port=6789)
queue.add("welcome", {"to": "user@example.com"})
Worker("emails", lambda job: {"sent": True}, concurrency=10).run()
Every SDK is certified against the same public wire protocol and conformance suite.
Every official FlowProducer resolves all job IDs and reciprocal dependency
edges locally, then sends one PUSHF command. The broker validates the complete
graph and commits it atomically, so a worker cannot observe a leaf from a
partially-created flow.
import { FlowProducer } from 'bunqueue-client';
const flows = new FlowProducer({ host: 'localhost', port: 6789 });
const root = await flows.add({
name: 'publish-release',
queueName: 'release',
data: { version: 'candidate-42' },
children: [
{ name: 'unit-tests', queueName: 'checks', data: { suite: 'unit' } },
{ name: 'sdk-tests', queueName: 'checks', data: { suite: 'sdk' } },
],
});
console.log(root.job.id, root.children?.map(({ job }) => job.id));
await flows.close();
The repository records the contracts and the test strategy beside each implementation:
| SDK | Runtime invariants | Generated tests | Mutation engine |
|---|---|---|---|
| TypeScript | contract | fast-check | none¹ |
| Python | contract | Hypothesis | mutmut |
| PHP | contract | Eris | Infection |
| Go | contract | Rapid | Gremlins |
| Rust | contract | proptest | cargo-mutants |
| Elixir | contract | StreamData | Muex |
¹ The TypeScript SDK has no mutation engine. StrykerJS was removed because its dependency graph produced every advisory the weekly audit had to answer for, none of it reachable from the published client; the planners keep their fast-check coverage.
Property campaigns run in the ordinary SDK gate with deterministic replay
seeds. Mutation campaigns run separately against the pure planners and
snapshot validators. Contributors can reproduce the complete isolated SDK
gate with bun run test:sandbox:sdk; language-specific commands live in each
SDK README and AGENTS.md.
SDK guide (all six languages) →
Bunqueue bundles Queue + Worker + routes + middleware + cron in one object:
import { Bunqueue } from 'bunqueue/client';
const app = new Bunqueue('notifications', {
embedded: true,
routes: {
'send-email': async (job) => ({ sent: true }),
'send-sms': async (job) => ({ sent: true }),
},
concurrency: 10,
retry: { maxAttempts: 5, strategy: 'jitter' },
circuitBreaker: { threshold: 5, resetTimeout: 30000 },
});
// Onion middleware around every job
app.use(async (job, next) => {
const start = Date.now();
const result = await next();
console.log(`${job.name}: ${Date.now() - start}ms`);
return result;
});
await app.cron('daily-report', '0 9 * * *', { type: 'summary' });
await app.add('send-email', { to: 'alice@example.com' });
app.on('completed', (job, result) => console.log(result));
await app.close();
Also included: batch processing, event triggers (job A completes → create job
B), job TTL, priority aging, deduplication, per-group rate limiting, DLQ with
auto-retry, graceful cancellation via AbortController.
Multi-step orchestration with saga compensation, branching, parallel steps and human-in-the-loop signals — built on bunqueue, no new infrastructure:
import { Workflow, Engine } from 'bunqueue/workflow';
const orderFlow = new Workflow('order-pipeline')
.step('reserve-stock', async () => {
await inventory.reserve();
return { reserved: true };
}, {
compensate: async () => await inventory.release(), // auto-rollback on failure
})
.step('charge', async () => {
return { txId: await payments.charge() };
}, {
compensate: async () => await payments.refund(),
})
.waitFor('manager-approval', { timeout: 86_400_000 }) // human-in-the-loop
.step('confirm', async (ctx) => {
return { txId: (ctx.steps['charge'] as { txId: string }).txId };
});
const engine = new Engine({ embedded: true });
engine.register(orderFlow);
const run = await engine.start('order-pipeline', { orderId: 'ORD-1' });
await engine.signal(run.id, 'manager-approval', { approved: true });
| bunqueue | Temporal | Inngest | Trigger.dev | |
|---|---|---|---|---|
| Infrastructure | None (embedded) | PostgreSQL + 7 services | Cloud-only | Redis + PostgreSQL |
| Saga compensation | Built-in | Manual | Manual | Manual |
| Human-in-the-loop | .waitFor() | Signals API | step.waitForEvent() | Waitpoint tokens |
| Self-hosted | Zero-config | Complex | No | Complex |
| Pricing | Free (MIT) | Free / Cloud $$ | Per-execution | Free tier, then $50/mo+ |
Also included: nested workflows, doUntil/doWhile loops, forEach over
dynamic lists, schema validation (Zod, ArkType, Valibot or any .parse()),
step timeouts, typed events, SQLite-persisted execution state.
bunqueue ships a native MCP server: 73 tools, 5 resources, 3 prompts. Agents schedule cron jobs, push and process jobs, retry failures, set rate limits, and read stats — no glue code. HTTP handlers let an agent register a URL and have an embedded worker call it for every job.
bun add bunqueue @modelcontextprotocol/sdk # the MCP SDK is an optional peer
claude mcp add bunqueue -- bunx bunqueue-mcp
// Claude Desktop / Cursor / Windsurf
{
"mcpServers": {
"bunqueue": {
"command": "bunx",
"args": ["--package=bunqueue", "bunqueue-mcp"]
}
}
}
Then just ask: "Schedule a cleanup job every day at 3 AM" · "Show me all failed jobs and retry them" · "Set rate limit to 50/sec on api-calls".
A web dashboard that fully drives your server — queues, jobs, DLQ, cron, webhooks, workers, live activity, SQLite inspector and an AI copilot. Open source, currently in beta:
bunx bunqueue-dashboard
https://github.com/user-attachments/assets/e8a8d38e-b4a6-4dc8-8360-876c0f24d116
Live demo · User guide · GitHub
Native Ryzen 9 9950X3D, Bun 1.3.14; medians from repeated fresh processes:
| Workload | Mode | Median | Persistence |
|---|---|---|---|
| Internal batched push, 1M jobs | Embedded | 729,395 jobs/sec | In-memory, no dataPath |
Public sustained addBulk, 50K cell | Embedded | 186,384 jobs/sec | On-disk buffered SQLite |
PUSHB, fresh 50K sample | TCP | 158,779 jobs/sec | On-disk buffered SQLite |
| No-work worker drain, concurrency 50 | TCP | 17,256 jobs/sec | Full pull/process/ACK |
| Linear Workflow Engine | Embedded / TCP | 2,700 / 3,187 workflows/sec | Workflow SQLite + 3 queue nodes |
These operations do different work; the internal in-memory result is not an
SQLite or public-API claim. Run bun run bench, bun run bench:tcp, or
bun run bench:workflow on your hardware.
Benchmark methodology → ·
full engineering report
MIT
.claude/
.claude-plugin/
plugin.json
agents/
skeptic.md
skills/
bunqueue-dev/
SKILL.md
.codex/
agents/
skeptic.toml
.dockerignore
.env.example
.github/
banner.svg
bunqueue-demo.mp4
icon.png
icon.svg
ISSUE_TEMPLATE/
bug_report.yml
config.yml
feature_request.yml
question.yml
logo.png
logo.svg
mcp-flow.svg
SUPPORT.md
terminal.png
workflows/
ci.yml
sdk-mutation.yml
sdk-release.yml
sdk-security.yml
sdk.yml
x-header.png
x-header.svg
x-profile.svg
.gitignore
.husky/
pre-commit
.mcp.json
.npmignore
agents/
AGENTS.md
bunqueue-assistant.md
bench/
comparison/
bullmq.ts
bunqueue.ts
config.ts
harness.ts
report.ts
run.ts
comprehensive-report.ts
comprehensive.ts
fix-impact/
fix-impact.ts
harness.ts
query.ts
recovery.ts
scheduling-stats.ts
temporal-waiter.ts
types.ts
job-list-perf.ts
local-autobatch.ts
native-benchmark-integrity.ts
pushbulk-delta.ts
tcp-bench.ts
tcp-process-sweep.ts
workflow-engine/
workflow-engine.ts
connection.ts
sample.ts
scale.ts
biome.json
bunfig.toml
CHANGELOG.md
CLAUDE.md
docker-compose.yml
Dockerfile
Dockerfile.sdk-test
Dockerfile.sdk-test.dockerignore
Dockerfile.test
Dockerfile.test.dockerignore
docs/
.gitignore
architecture.md
astro.config.mjs
benchmarks/
fix-impact-2026-07-16.md
native-engineering-2026-07-30.md
native-engineering-2026-08-02.md
native-engineering-2026-08-03.md
CLOUD_CONTRACT.md
CLOUD_PAYLOAD_EXAMPLE.json
data-model.md
features/
background-tasks.md
backup-s3.md
benchmarks.md
cli.md
client-queue-sdk.md
client-transport.md
client-worker-sdk.md
cloud-integration.md
concurrency-and-locking.md
configuration.md
core-public-api-e2e.md
core-queue-engine.md
data-structures.md
dead-letter-queue.md
deduplication-and-unique.md
documentation-tooling.md
documented-feature-verification.md
documented-guide-audit.md
elixir-sdk.md
flow-producer.md
http-api.md
job-lifecycle.md
job-queries-and-control.md
mcp-server.md
model-based-testing.md
persistence.md
polyglot-sdks.md
production-readiness-testing.md
public-api-completeness.md
rate-limiting-and-concurrency.md
rust-sdk.md
scheduler-and-cron.md
security-tls-auth.md
simple-mode.md
stats-and-monitoring.md
store-and-forward.md
tcp-protocol.md
tcp-server-handlers.md
webhooks-and-events.md
workers-management.md
workflow-engine.md
generated-api-reference.md
package.json
protocol.md
public/
338321b685f29b67ae11f935d45ef1e7.txt
apple-touch-icon.png
bq-changelog.js
bq-compat.js
bq-copy.js
bq-inter.js
bq-sim.js
favicon-32x32.png
favicon.svg
llms.txt
manifest.webmanifest
og/
og-image.png
advanced.png
api-reference.png
benchmarks.png
client-sdk.png
elysia.png
getting-started.png
hono.png
integrations.png
production.png
queue.png
server-mode.png
use-cases.png
worker.png
workflow.png
reference/
v2.8/
assets/
custom.css
hierarchy.js
highlight.css
icons.js
icons.svg
main.js
navigation.js
search.js
style.css
classes/
application_queueManager.QueueManager.html
client_events.QueueEvents.html
client_forwarder.Forwarder.html
client_workflow.Engine.html
client_workflow.Workflow.html
client_workflow.WorkflowEmitter.html
client.Bunqueue.html
client.DelayedError.html
client.FlowProducer.html
client.Queue.html
client.QueueGroup.html
client.SandboxedWorker.html
client.TcpConnectionPool.html
client.UnrecoverableError.html
client.Worker.html
domain_types_queue.ConcurrencyLimiter.html
domain_types_queue.RateLimiter.html
enums/
domain_types_dlq.FailureReason.html
domain_types_job.JobState.html
domain_types_queue.EventType.html
domain_types_stall.StallAction.html
functions/
client_types.createPublicJob.html
client_types.toDlqEntry.html
client_types.toPublicJob.html
client.closeAllSharedPools.html
client.closeSharedTcpClient.html
client.getSharedPool.html
client.shutdownManager.html
domain_types_cron.createCronJob.html
domain_types_cron.isAtLimit.html
domain_types_cron.isDue.html
domain_types_dlq.addAttemptRecord.html
domain_types_dlq.canAutoRetry.html
domain_types_dlq.createDlqEntry.html
domain_types_dlq.isDlqEntryExpired.html
domain_types_dlq.scheduleNextRetry.html
domain_types_job.calculateBackoff.html
domain_types_job.canRetry.html
domain_types_job.createJob.html
domain_types_job.createJobLock.html
domain_types_job.generateJobId.html
domain_types_job.generateLockToken.html
domain_types_job.isDelayed.html
domain_types_job.isExpired.html
domain_types_job.isLockExpired.html
domain_types_job.isReady.html
domain_types_job.isTimedOut.html
domain_types_job.jobId.html
domain_types_job.lockToken.html
domain_types_job.normalizeStacktrace.html
domain_types_job.renewLock.html
domain_types_queue.createQueueState.html
domain_types_stall.checkStall.html
domain_types_stall.getStallAction.html
domain_types_stall.incrementStallCount.html
domain_types_stall.resetStallCount.html
domain_types_stall.updateHeartbeat.html
domain_types_worker.createLogEntry.html
domain_types_worker.createWorker.html
main.defineConfig.html
hierarchy.html
index.html
interfaces/
application_queueManager.QueueManagerConfig.html
client_events.ActiveEvent.html
client_events.CompletedEvent.html
client_events.DelayedEvent.html
client_events.DrainedEvent.html
client_events.DuplicatedEvent.html
client_events.FailedEvent.html
client_events.ProgressEvent.html
client_events.RemovedEvent.html
client_events.RetriedEvent.html
client_events.StalledEvent.html
client_events.WaitingChildrenEvent.html
client_events.WaitingEvent.html
client_flowTypes.FlowJob.html
client_flowTypes.FlowOpts.html
client_flowTypes.FlowProducerOptions.html
client_flowTypes.FlowResult.html
client_flowTypes.FlowStep.html
client_flowTypes.GetFlowOpts.html
client_flowTypes.JobNode.html
client_forwarder.ForwardedInfo.html
client_forwarder.ForwardOptions.html
client_forwarder.ForwardSource.html
client_tcp_types.ClientTlsOptions.html
client_tcp_types.ConnectionHealth.html
client_tcp_types.ConnectionOptions.html
client_tcp_types.FrameParser.html
client_tcp_types.PendingCommand.html
client_tcp_types.SocketWrapper.html
client_types.AutoBatchOptions.html
client_types.BackoffOptions.html
client_types.ChangePriorityOpts.html
client_types.ConnectionOptions.html
client_types.CreatePublicJobOptions.html
client_types.DebounceOptions.html
client_types.DeduplicationOptions.html
client_types.DlqConfig.html
client_types.DlqEntry.html
client_types.DlqFilter.html
client_types.DlqStats.html
client_types.FlowJobData.html
client_types.GetDependenciesOpts.html
client_types.Job.html
client_types.JobDependencies.html
client_types.JobDependenciesCount.html
client_types.JobJson.html
client_types.JobJsonRaw.html
client_types.JobOptions.html
client_types.KeepJobs.html
client_types.ParentOpts.html
client_types.QueueOptions.html
client_types.RateLimiterOptions.html
client_types.RepeatOptions.html
client_types.StallConfig.html
client_types.ToPublicJobOptions.html
client_types.WorkerOptions.html
client_worker_types.ExtendedWorkerOptions.html
client_worker_types.PendingAck.html
client_worker_types.TcpConnection.html
client_workflow_types.BranchDefinition.html
client_workflow_types.CleanupOptions.html
client_workflow_types.CompensationOutcome.html
client_workflow_types.EngineOptions.html
client_workflow_types.Execution.html
client_workflow_types.ExecutionListOptions.html
client_workflow_types.ForEachDefinition.html
client_workflow_types.LoopDefinition.html
client_workflow_types.MapDefinition.html
client_workflow_types.ParallelDefinition.html
client_workflow_types.ParkOutcome.html
client_workflow_types.RecoverResult.html
client_workflow_types.RunHandle.html
client_workflow_types.SchemaLike.html
client_workflow_types.SignalEvent.html
client_workflow_types.SignalOutcome.html
client_workflow_types.StepContext.html
client_workflow_types.StepDefinition.html
client_workflow_types.StepEvent.html
client_workflow_types.StepJobData.html
client_workflow_types.StepOptions.html
client_workflow_types.StepRecord.html
client_workflow_types.SubWorkflowOptions.html
client_workflow_types.WorkflowEvent.html
client_workflow_types.WorkflowLifecycleEvent.html
client.BatchConfig.html
client.BunqueueDebounceConfig.html
client.BunqueueDeduplicationConfig.html
client.BunqueueDlqConfig.html
client.BunqueueOptions.html
client.CircuitBreakerConfig.html
client.JobTemplate.html
client.JobTtlConfig.html
client.PriorityAgingConfig.html
client.RepeatOpts.html
client.RetryConfig.html
client.SandboxedWorkerOptions.html
client.SchedulerInfo.html
client.TriggerRule.html
domain_types_cron.CronDedup.html
domain_types_cron.CronJob.html
domain_types_cron.CronJobInput.html
domain_types_cron.CronJobOptions.html
domain_types_dlq.AttemptRecord.html
domain_types_dlq.DlqConfig.html
domain_types_dlq.DlqEntry.html
domain_types_dlq.DlqFilter.html
domain_types_dlq.DlqStats.html
domain_types_job.BackoffConfig.html
domain_types_job.Job.html
domain_types_job.JobInput.html
domain_types_job.JobLock.html
domain_types_job.JobTimelineEntry.html
domain_types_job.RepeatConfig.html
domain_types_queue.JobEvent.html
domain_types_queue.QueueState.html
domain_types_queue.Webhook.html
domain_types_stall.StallCheckResult.html
domain_types_stall.StallConfig.html
domain_types_worker.CreateWorkerOptions.html
domain_types_worker.JobLogEntry.html
domain_types_worker.Worker.html
main.BunqueueConfig.html
modules/
application_queueManager.html
client_events.html
client_flowTypes.html
client_forwarder.html
client_tcp_types.html
client_types.html
client_worker_types.html
client_workflow_types.html
client_workflow.html
client.html
domain_types_cron.html
domain_types_dlq.html
domain_types_job.html
domain_types_queue.html
domain_types_stall.html
domain_types_worker.html
main.html
types/
client_forwarder.RemoteQueueCtor.html
client_types.FailureReason.html
client_types.JobStateType.html
client_types.Processor.html
client_types.QueueEventType.html
client_workflow_types.BranchCondition.html
client_workflow_types.CompensateHandler.html
client_workflow_types.CompensationStatus.html
client_workflow_types.ExecutionState.html
client_workflow_types.ForEachItemsExtractor.html
client_workflow_types.LoopCondition.html
client_workflow_types.MapTransformFn.html
... 1600 moreShowing a partial view of a very large repo.
FAQ
bunqueue is a Claude Code plugin with 2 hand-picked skills for automation work, indexed on Flowy. Install it with the command on its page. It includes bunqueue-dev, bunqueue. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.