feat(queue): add queue system with background daemon #140

shoko · 2026-04-05T06:29:14+02:00

shoko commented

2026-04-05 06:29:14 +02:00

Overview

Implements #134 - Queue system with background daemon.

Changes

Configuration

QUEUE_DIR="${QUEUE_DIR:-$KUGETSU_DIR/queue}"
QUEUE_ITEMS_DIR="${QUEUE_ITEMS_DIR:-$QUEUE_DIR/items}"
QUEUE_DAEMON_INTERVAL_MINUTES="${QUEUE_DAEMON_INTERVAL_MINUTES:-5}"
QUEUE_DAEMON_BATCH_SIZE="${QUEUE_DAEMON_BATCH_SIZE:-2}"
QUEUE_CLEANUP_AGE_DAYS="${QUEUE_CLEANUP_AGE_DAYS:-7}"

Queue System

File-based queue at ~/.kugetsu/queue/items/
One JSON file per queue item (no race conditions)
States: pending, notified, completed, error

Queue Item Format

{
  "id": "q_xxx",
  "issue_ref": "github.com/user/repo#123",
  "message": "task description",
  "state": "pending",
  "pending_since": "2026-04-05T10:00:00Z",
  "notified_at": null,
  "completed_at": null,
  "error": null
}

New Commands

kugetsu queue list              # Show queue status
kugetsu queue stats            # Show queue statistics
kugetsu queue clear           # Clean up old completed/error items
kugetsu queue enqueue <issue-ref> <message>  # Manually enqueue a task

kugetsu queue-daemon start     # Start daemon in background
kugetsu queue-daemon stop      # Stop daemon
kugetsu queue-daemon restart   # Restart daemon
kugetsu queue-daemon status    # Check if running
kugetsu queue-daemon logs      # Show daemon logs

Behavior Change

kugetsu delegate now always enqueues (fire-and-forget)
Queue daemon polls queue and invokes PM when slots available
PM decides whether to use start or continue for each task

Daemon Process

Daemon runs at configurable interval (default: 5 minutes)
Checks active sessions < MAX_CONCURRENT_AGENTS
Picks up to BATCH_SIZE pending items
Forks PM session for each picked item
Updates queue item state to notified

Closes #134

## Overview Implements #134 - Queue system with background daemon. ## Changes ### Configuration ```bash QUEUE_DIR="${QUEUE_DIR:-$KUGETSU_DIR/queue}" QUEUE_ITEMS_DIR="${QUEUE_ITEMS_DIR:-$QUEUE_DIR/items}" QUEUE_DAEMON_INTERVAL_MINUTES="${QUEUE_DAEMON_INTERVAL_MINUTES:-5}" QUEUE_DAEMON_BATCH_SIZE="${QUEUE_DAEMON_BATCH_SIZE:-2}" QUEUE_CLEANUP_AGE_DAYS="${QUEUE_CLEANUP_AGE_DAYS:-7}" ``` ### Queue System - File-based queue at `~/.kugetsu/queue/items/` - One JSON file per queue item (no race conditions) - States: `pending`, `notified`, `completed`, `error` ### Queue Item Format ```json { "id": "q_xxx", "issue_ref": "github.com/user/repo#123", "message": "task description", "state": "pending", "pending_since": "2026-04-05T10:00:00Z", "notified_at": null, "completed_at": null, "error": null } ``` ### New Commands ```bash kugetsu queue list # Show queue status kugetsu queue stats # Show queue statistics kugetsu queue clear # Clean up old completed/error items kugetsu queue enqueue <issue-ref> <message> # Manually enqueue a task kugetsu queue-daemon start # Start daemon in background kugetsu queue-daemon stop # Stop daemon kugetsu queue-daemon restart # Restart daemon kugetsu queue-daemon status # Check if running kugetsu queue-daemon logs # Show daemon logs ``` ### Behavior Change - `kugetsu delegate` now **always enqueues** (fire-and-forget) - Queue daemon polls queue and invokes PM when slots available - PM decides whether to use `start` or `continue` for each task ### Daemon Process 1. Daemon runs at configurable interval (default: 5 minutes) 2. Checks active sessions < MAX_CONCURRENT_AGENTS 3. Picks up to BATCH_SIZE pending items 4. Forks PM session for each picked item 5. Updates queue item state to `notified` ## Related Issues Closes #134

shoko added 1 commit 2026-04-05 06:29:14 +02:00

feat(queue): add queue system with background daemon 043542344a

Implements #134 - Queue system with background daemon.

## Changes

### Configuration
- QUEUE_DIR, QUEUE_ITEMS_DIR for queue storage
- QUEUE_DAEMON_PID_FILE, LOCK_FILE, LOG_FILE for daemon management
- QUEUE_DAEMON_INTERVAL_MINUTES (default: 5)
- QUEUE_DAEMON_BATCH_SIZE (default: 2)
- QUEUE_CLEANUP_AGE_DAYS (default: 7)

### Queue System
- File-based queue at ~/.kugetsu/queue/items/
- One JSON file per queue item
- States: pending, notified, completed, error

### New Commands
- kugetsu queue [list|stats|clear] - View queue status
- kugetsu queue enqueue <issue-ref> <message> - Manually enqueue
- kugetsu queue-daemon [start|stop|restart|status|logs] - Daemon management

### Behavior Change
- kugetsu delegate now always enqueues (fire-and-forget)
- Queue daemon polls queue and invokes PM when slots available

### Queue Item Format
```json
{
  "id": "q_xxx",
  "issue_ref": "github.com/user/repo#123",
  "message": "task description",
  "state": "pending",
  "pending_since": "...",
  "notified_at": null,
  "completed_at": null,
  "error": null
}
```

Closes #134

han commented

2026-04-05 06:42:23 +02:00

First-time contributor

I think we should update SKILL.md as well to include about this. so that user or agent use delegate over start/continue directly. by setting up the daemon first as well. and they can check queue list, queue logs, queue-daemon status, and queue-daemon logs for debugging or something

shoko added 1 commit 2026-04-05 06:46:06 +02:00

docs: update SKILL.md with queue system documentation 379d53cedc

- Update kugetsu delegate section to explain queue-based processing
- Add queue-daemon command documentation
- Update queue command with proper list/stats/clear/enqueue
- Add queue-related config options
- Update directory structure to include queue/
- Update workflow example with queue daemon setup

han approved these changes 2026-04-05 06:48:50 +02:00

han left a comment

First-time contributor

lgtm

shoko merged commit 151efadca3 into main

2026-04-05 06:49:13 +02:00

shoko referenced this issue from a commit

2026-04-05 06:49:15 +02:00

Merge pull request 'feat(queue): add queue system with background daemon' (#140) from feat/queue-daemon into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: shoko/kugetsu#140