Skip to main content
By default, Claudeye runs evals only when you open a session in the dashboard. The background queue scans your projects directory on an interval and processes sessions automatically - so all your sessions get graded without you having to open each one.

​
Enable background processing

Pass --queue-interval with the number of seconds between scans: 
claudeye --evals ./my-evals.js --queue-interval 60
This scans for new or changed sessions every 60 seconds and enqueues any that have uncached results.

​
Queue options

FlagDescriptionDefault
--queue-interval <secs>Seconds between background scansdisabled
--queue-concurrency <num>Max items processed in parallel2
--queue-history-ttl <secs>How long to keep completed items in history3600
--max-queue-items <num>Max items to enqueue per scan (0 = unlimited)500
# Higher concurrency, shorter history window
claudeye --evals ./my-evals.js --queue-interval 30 --queue-concurrency 5 --queue-history-ttl 1800

​
Filter which sessions get processed

Use app.queueCondition() to skip sessions during background scanning. This only affects the background scanner - UI-triggered runs are unaffected. 
// Only process sessions with more than 3 turns
app.queueCondition(({ stats }) => stats.turnCount >= 3, { cacheable: true });

// Only process sessions from production projects
app.queueCondition(
  ({ projectName }) => projectName.startsWith('production'),
  { cacheable: true }
);

// Only process during business hours (time-dependent - do not cache)
app.queueCondition(() => {
  const hour = new Date().getHours();
  return hour >= 9 && hour < 17;
});

​
cacheable option

ValueBehavior
false (default)Re-evaluated every scan cycle. Use for time or external-state dependent logic.
trueResult cached per session. Auto-invalidates when the session file or condition function changes.
app.queueCondition() and app.condition() can both be set. queueCondition filters sessions before they enter the queue; app.condition() runs again when each item executes. See Conditions for details.

​
How priority works

Every eval and enrichment - whether triggered from the UI or the background scanner - goes through the same unified queue:
  • HIGH priority: UI requests (opening a session, clicking Re-run)
  • LOW priority: background scanner items
  • HIGH items always process before LOW items
  • If the same item is enqueued twice, it’s upgraded to the higher priority

​
Alerts after bulk processing

Alerts fire after all evals and enrichments complete for a session - this works the same way during background processing. Use them to get notified when a session finishes grading. 
# Process all sessions in the background, send Slack alerts on failure
claudeye --evals ./my-evals.js --queue-interval 60

​
Monitor the queue

View live queue status, processing history, and errors in the dashboard. See Queue Monitoring.