v0.3.0

What's New

JSON Output for CLI (tq)

Added --json flag to CLI commands for programmatic queue inspection:

# Get queue state as JSON
tq list --json
# {"tasks": [...], "summary": {"total": 1, "running": 1, "waiting": 0}}

# Get logs as JSON
tq logs --json
# {"entries": [...]}

# Clear queue without confirmation
tq clear --json
# {"cleared": 5, "success": true}

Command Tracking

Tasks now store and display the command being executed, so you can see what's actually running:

{
  "id": 1,
  "status": "running",
  "command": "./gradlew :app:assembleDebug",
  ...
}

Schema Contract Tests

Added comprehensive tests to ensure JSON output structure remains stable for programmatic consumers.

Full Changelog

v0.2.0...v0.3.0

v0.2.0

Changelog (0.1.4 → 0.2.0)

Fixed

• Orphaned task cleanup with PID reuse detection - Tasks from cancelled sub-agents no longer block subsequent tasks (#7)

  • Added is_task_queue_process() to detect if a PID is actually running task_queue vs being reused by an unrelated process
  • Added SERVER_INSTANCE_ID and _active_task_ids tracking in MCP server to detect orphaned tasks from disconnected clients
  • Added CLI_INSTANCE_ID tracking in tq.py for same protection
  • Handle asyncio.CancelledError to properly clean up when sub-agents are cancelled

• Ctrl+C leaving orphaned waiting tasks - Split registration from wait to ensure cleanup

Changed

• Refactored shared infrastructure - Extracted queue_core.py with shared database, logging, and cleanup logic
• Memory efficiency - Stream output directly to file with bounded deque
• Wait time calculation - Use POLL_INTERVAL_WAITING instead of hardcoded value

Added

• server_id column to queue table with migration for existing databases
• Signal handling integration tests for tq CLI

Security

• Pin pypa/gh-action-pypi-publish to commit SHA
• Add nosec B602 comments explaining intentional shell=True usage for CLI tool

v0.2.0b1 - Beta

Beta Release

This beta includes significant improvements to orphaned task cleanup:

New Features

• PID reuse detection: Detects when a PID has been reused by an unrelated process (Chrome, etc.) vs our actual task_queue process
• Instance tracking: Each server/CLI instance gets a unique ID to detect orphaned tasks from crashed/restarted processes
• Cancellation handling: Properly cleans up queue entries when MCP clients disconnect (e.g., sub-agents cancelled)

Infrastructure

• Extracted shared queue logic into queue_core.py for code reuse between MCP server and CLI

Installation

# Via uvx (recommended)
uvx [email protected]

# Via pip
pip install agent-task-queue==0.2.0b1

Note: This is a pre-release. Use @latest or no version specifier to stay on stable (0.1.4).

v0.1.4

Breaking Changes

• CLI renamed from atq to tq - The atq command conflicted with the Unix at(1) job scheduler. Update any scripts or aliases that used atq to use tq instead.

New Features

• tq run command - Execute commands through the same FIFO queue that AI agents use. This prevents resource contention when humans and agents run builds simultaneously.

  tq ./gradlew assembleDebug          # Run a build through the queue
  tq -q android ./gradlew test        # Use a specific queue
  tq -t 600 npm test                  # Custom timeout (seconds)
  tq -C /path/to/project make         # Set working directory

• Implicit run - tq echo hello works the same as tq run echo hello

• Rich terminal output - Passthrough mode preserves progress bars, colors, and interactive output from build tools

Improvements

• Database recovery - Automatically detects and recovers from corrupted SQLite databases
• Log rotation - Metrics log file rotates when exceeding 5MB to prevent unbounded disk growth
• Zombie cleanup metrics - Logs zombie_cleared events when cleaning up dead or stale tasks
• Graceful Ctrl+C handling - Clean process group termination without tracebacks

Testing

• Added comprehensive test suite for tq CLI (25 new tests)

v0.1.3

What's New

New Features

• atq CLI - Inspect the task queue from the command line
  • atq list - Show current queue status
  • atq logs - View recent task activity
  • atq clear - Clear stuck tasks

Documentation

• Improved agent configuration docs with compatibility table
• Added setup guides for Claude Code in examples/
• Clarified Bash allowed rules warning for Claude Code users

Install

uv tool install agent-task-queue

Or run one-off:

uvx --from agent-task-queue atq list

v0.1.2

---

Documentation improvements for timeout behavior.

Changes

• Clarify that timeout_seconds applies to execution time only, queue wait time does not count against the timeout
• Update tool docstring so agents understand this behavior

---

v0.1.1

---

Fixes uvx agent-task-queue installation.

Changes

• Add CLI entry point so uvx agent-task-queue works correctly
• Add author and license metadata to package

Installation

uvx agent-task-queue

---

v0.1.0

---

Initial Release

Agent Task Queue is an MCP server that prevents multiple AI agents from running expensive build operations concurrently.

Features

• FIFO task queuing - Serializes builds across all connected agents
• Multiple queue support - Isolate workloads with named queues
• No timeouts - MCP keeps connections alive indefinitely
• Zombie protection - Detects dead processes and clears stale locks
• Environment variables - Pass build-specific config via env_vars
• Configurable - CLI options for data directory, log rotation, timeouts

Installation

uvx agent-task-queue

Supported Agents

Works with any MCP-compatible tool: Claude Code, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Amp, Cline, Firebender, and others.

---