If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Nukesor/pueue shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1w ago
• 5 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 87% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Nukesor/pueue repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Nukesor/pueue.

What it runs against: a local clone of Nukesor/pueue — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Nukesor/pueue | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 39 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Nukesor/pueue. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Nukesor/pueue.git
#   cd pueue
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Nukesor/pueue and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Nukesor/pueue(\\.git)?\\b" \\
  && ok "origin remote is Nukesor/pueue" \\
  || miss "origin remote is not Nukesor/pueue (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "pueue/src/bin/pueued.rs" \\
  && ok "pueue/src/bin/pueued.rs" \\
  || miss "missing critical file: pueue/src/bin/pueued.rs"
test -f "pueue/src/bin/pueue.rs" \\
  && ok "pueue/src/bin/pueue.rs" \\
  || miss "missing critical file: pueue/src/bin/pueue.rs"
test -f "pueue/src/daemon/internal_state/state.rs" \\
  && ok "pueue/src/daemon/internal_state/state.rs" \\
  || miss "missing critical file: pueue/src/daemon/internal_state/state.rs"
test -f "pueue/src/daemon/network/message_handler/mod.rs" \\
  && ok "pueue/src/daemon/network/message_handler/mod.rs" \\
  || miss "missing critical file: pueue/src/daemon/network/message_handler/mod.rs"
test -f "pueue/src/client/cli.rs" \\
  && ok "pueue/src/client/cli.rs" \\
  || miss "missing critical file: pueue/src/client/cli.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 39 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~9d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Nukesor/pueue"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Pueue is a daemon-based command queue manager written in Rust that allows you to schedule, execute, and manage shell commands with sequential or parallel execution. It persists task state to disk, supports task dependencies and groups, and lets you control tasks from any terminal via a client-daemon architecture—solving the problem of running long-lived background tasks without keeping a terminal session open. Workspace with two main crates: pueue/ (client and daemon binary in src/bin/pueue.rs and src/bin/pueued.rs) and pueue_lib/ (shared library). Client code in pueue/src/client/ with command modules (add.rs, clean.rs, edit.rs, follow.rs, etc.), daemon logic separate, state persisted as serialized CBOR and optionally compressed with Snap (pueue/benches/ shows save_compressed_state.rs and save_state.rs).

System administrators, researchers, and developers who run batch jobs, data processing pipelines, or long-running scripts and need a persistent queue that survives ssh disconnections, system crashes, and allows pausing/resuming tasks without losing state.

Production-ready and feature-complete. The README explicitly states 'Pueue is considered feature-complete :tada:' with only bug fixes and maintenance planned going forward. Strong CI/CD pipeline (.github/workflows/ has clippy, coverage, lint, test, and package-binary workflows), comprehensive test suite (test.yml and test_lib.yml workflows), and consistent maintenance suggest active stability rather than active feature development.

Standard open source risks apply.

Project is in maintenance mode—feature-complete with focus on stability. .github/workflows show active CI (test.yml runs on push), codecov integration for coverage tracking, and dependabot for dependency updates (.github/dependabot.yml). No active feature development visible; contributions are likely focused on bug fixes and documentation improvements per CONTRIBUTING.md.

git clone https://github.com/Nukesor/pueue.git
cd pueue
cargo build --release
./target/release/pueued &  # Start daemon
./target/release/pueue add 'your command here'  # Add task
./target/release/pueue status  # Check queue

Daily commands: Development: just test (Justfile present) or cargo test --workspace. Start daemon: cargo run --bin pueued -- --daemon. Start client: cargo run --bin pueue -- status. CI/CD uses nextest (config/.config/nextest.toml for parallel test execution).

• pueue/src/bin/pueued.rs — Daemon entry point that initializes the background task processor, network server, and state management—every contributor must understand how the daemon lifecycle works.
• pueue/src/bin/pueue.rs — Client CLI entry point that parses commands and communicates with the daemon—essential for understanding the user-facing interface.
• pueue/src/daemon/internal_state/state.rs — Core state machine managing task queues, groups, and execution status—the heart of Pueue's data model that all handlers depend on.
• pueue/src/daemon/network/message_handler/mod.rs — Central dispatcher routing client commands to appropriate handlers—critical for understanding how client requests are processed.
• pueue/src/client/cli.rs — CLI argument parser and command routing—defines the command structure and options users interact with.
• pueue/src/daemon/callbacks.rs — Handles task lifecycle events (completion, failure, restart)—manages the core business logic of task execution.
• pueue/src/aliasing.rs — Command aliasing system for user shortcuts—important for understanding extensibility mechanisms.

• pueue CLI client (Clap CLI, Serde, TLS sockets) — Parses user commands, sends requests to daemon, displays formatted responses
  • Failure mode: Fails gracefully if daemon unavailable; buffers commands for async execution

Add a new daemon command handler

1. Create handler file in daemon message handlers (pueue/src/daemon/network/message_handler/mycommand.rs)
2. Implement handler logic receiving Message and returning Response (pueue/src/daemon/network/message_handler/mycommand.rs)
3. Import and register in main dispatcher with match arm (pueue/src/daemon/network/message_handler/mod.rs)
4. Add corresponding client command parsing in CLI (pueue/src/client/cli.rs)
5. Implement client command handler sending Message to daemon (pueue/src/client/commands/mycommand.rs)

Add a new state query filter or column

1. Define filter logic parsing in PEST grammar (pueue/src/client/commands/state/query/syntax.pest)
2. Implement filter predicate matching tasks (pueue/src/client/commands/state/query/filters.rs)
3. Add column configuration if displaying new field (pueue/src/client/commands/state/query/column_selection.rs)
4. Update table builder to render new column data (pueue/src/client/commands/state/table_builder.rs)

Modify task lifecycle and state transitions

1. Update state machine logic and task status enums (pueue/src/daemon/internal_state/state.rs)
2. Add or modify callbacks for new lifecycle events (pueue/src/daemon/callbacks.rs)
3. Update handlers that transition task states (pueue/src/daemon/network/message_handler/restart.rs)
4. Update display/styling to reflect new states (pueue/src/client/style.rs)

• Rust — Systems language enabling safe concurrent task management with zero-cost abstractions and strong memory safety guarantees required for a daemon managing external processes
• Tokio async runtime — Efficient async I/O for concurrent task monitoring and network handling without threading overhead
• TLS (rustls) — Secure encrypted communication between client and daemon, with local certificate generation for authentication
• PEST parser — Domain-specific language for task state queries with complex filtering and column selection syntax
• Serde + CBOR serialization — Efficient binary serialization for network messages and state persistence with compression support

• Single daemon process rather than worker pool

  • Why: Simplifies state consistency and avoids distributed state synchronization problems
  • Consequence: Daemon becomes a single point of bottleneck for very high task throughput, but acceptable for typical usage patterns

• In-memory state with optional persistence

  • Why: Fast synchronous access to task state without database overhead
  • Consequence: State lost on daemon crash unless explicitly saved; no native multi-machine distribution

• Strict command sequencing per group rather than true parallelism

  • Why: Deterministic execution order prevents race conditions and output interleaving
  • Consequence: Tasks within a group cannot truly overlap; parallel groups require separate group creation

• Local-machine only communication (Unix socket or TCP localhost)

  • Why: Eliminates network authentication complexity and restricts access to local users
  • Consequence: Cannot manage tasks on remote machines directly; requires SSH tunneling for remote access

• Does not handle distributed task execution across multiple machines
• Not a real-time system; task execution timing is best-effort based on system load
• Does not provide built-in task result aggregation or reporting to external systems
• Not designed for interactive command shells; tasks must be non-interactive shell commands

Daemon must be running before client commands work (no auto-start). State is persisted as CBOR (not human-readable)—check ~/.local/share/pueue/ on Linux or use pueue log to view task output. TLS handshake required between client and daemon (certificates auto-generated on first run). Task environment variables are captured at enqueue time (pueue/src/client/commands/add.rs), not at execution—changes to shell environment after enqueue won't affect the task. Task groups are isolated (each has its own parallelism setting) but share the daemon process.

• Daemon-Client Architecture (IPC via TLS) — Pueue's core design—the daemon (pueued) persists state and spawns processes while the client (pueue CLI) sends commands over encrypted sockets; understanding this separation is essential to navigating the codebase
• CBOR Serialization with Snap Compression — Task state is persisted to disk as CBOR (Concise Binary Object Representation) and optionally compressed with Snap; benchmarks in pueue/benches/ measure this performance-critical path
• Task Dependency Graph — Pueue supports task dependencies (specifying that task B waits for task A); the scheduler must respect this graph when deciding which tasks to run, visible in state management code
• Process Group Management and Signal Handling — The daemon spawns tasks in process groups (via process-wrap crate) to handle pause/resume/kill operations atomically; critical for reliable task control without orphaned processes
• Async Rust with Tokio — Pueue's entire runtime is built on Tokio (1.49+), managing concurrent task execution, network I/O, and background state persistence without blocking; essential to understanding performance and scalability
• State Machine (Task Lifecycle) — Tasks transition through states (Queued → Running → Done/Failed/Paused); docs/Pueue-State-Diagram.svg visualizes this; understanding valid transitions is crucial for command handler logic
• Structured Logging (tracing ecosystem) — All logging uses tracing with spans and events; enables debug-level visibility into daemon operations and helps diagnose state inconsistencies

• BurntSushi/ripgrep — Similar Rust CLI tool architecture with daemon-optional design; good reference for CLI parsing patterns
• starship/starship — Rust cross-platform tool with strong CI/CD and packaging; reference for GitHub Actions workflow structure and binary distribution
• orhun/git-cliff — Rust changelog generator in same ecosystem; demonstrates use of serde, tracing, and structured logging patterns
• alacritty/alacritty — Large Rust project using tokio + TLS communication; reference for async architecture and process spawning
• torrust/torrust-tracker — Rust daemon with persistent state management; demonstrates CBOR serialization and background process patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for log command output formats (JSON, local, remote)

The repo has three distinct log implementations (pueue/src/client/commands/log/json.rs, local.rs, remote.rs) but there's no visible integration test suite validating their output consistency. Given that log output is critical for users relying on JSON parsing or remote command monitoring, integration tests would ensure each format handles edge cases (empty logs, special characters, timestamps) correctly and prevent regressions.

• [ ] Create pueue/tests/integration_log_formats.rs
• [ ] Add test cases for JSON output parsing with various task states
• [ ] Add test cases for local log retrieval with missing/truncated logs
• [ ] Add test cases for remote log commands with network failures
• [ ] Verify output consistency across all three log implementations

Add GitHub Actions workflow for cross-compilation testing (ARM64, AARCH64)

The repo has Cross.toml for cross-compilation support and package-binary.yml for releases, but no dedicated CI workflow testing cross-compilation on PRs. This means contributors could merge changes that break ARM64 builds without catching it early. Adding a cross-compilation test workflow would catch platform-specific issues (e.g., in libc, process-wrap, or tokio usage) before release.

• [ ] Create .github/workflows/cross-compile-test.yml
• [ ] Add matrix strategy for targets: aarch64-unknown-linux-gnu, armv7-unknown-linux-gnueabihf
• [ ] Use cross-rs/cross action to run cargo build and cargo test
• [ ] Trigger on pull_request and push to main
• [ ] Reference Cross.toml configuration in the workflow

Add missing documentation for state query command in docs/

The file structure shows pueue/src/client/commands/state/query exists but there's no corresponding documentation in docs/. The main README mentions Pueue is a task management tool but doesn't explain how to query system state. Given that state management appears central to the architecture (evidenced by Pueue-State-Diagram.svg), users need clear docs on state query capabilities, filters, and output formats.

• [ ] Create docs/StateQueries.md documenting query syntax and capabilities
• [ ] Add examples for common queries (e.g., get running tasks, list failed tasks)
• [ ] Document the relationship between state queries and the state diagram in docs/Pueue-State-Diagram.svg
• [ ] Add cross-reference to docs/StateQueries.md from main README.md
• [ ] Include JSON output format examples for scripting use cases

• Add missing integration tests for pueue/src/client/commands/edit.rs and pueue/src/client/commands/env.rs (follow the pattern in test.yml workflow to verify command parsing and state mutations)
• Improve docs/Architecture.md with a sequence diagram showing client→daemon→process lifecycle for a typical task (take inspiration from existing Pueue-State-Diagram.svg)
• Add error handling tests in pueue_lib/src/ for malformed CBOR state files and network disconnections (check codecov.yml to identify coverage gaps)

The Pueue codebase demonstrates reasonable security hygiene with modern dependencies (Tokio async runtime, Rustls for TLS, proper use of Serde). However, several areas require attention: (1) The edition field is misconfigured (2024 does not exist), which is a critical configuration error. (2) Command execution via process-wrap requires strict input validation to prevent command injection. (3) Template engine and serialization library usage need careful validation of untrusted data. (4) No visible input validation patterns suggest potential injection risks in CLI argument handling. (5) Custom query parser may be vulnerable

• Medium · Outdated Rust Edition in Workspace — Cargo.toml (workspace.package edition). The workspace is configured with edition = "2024", which does not exist as of the latest Rust releases. This should be "2021". This may cause compilation issues or unexpected behavior. Fix: Update edition to "2021" which is the latest stable edition.
• Low · TLS Configuration with Ring Dependency — Cargo.toml (workspace.dependencies rustls). The rustls dependency is configured with ring cryptography provider. While ring is well-maintained, ensure the ring crate version is kept up-to-date as cryptographic libraries require frequent updates for security patches. Fix: Regularly update rustls and ring dependencies, and monitor security advisories via cargo-audit.
• Low · Dependency on Handlebars Template Engine — Cargo.toml (workspace.dependencies handlebars). The handlebars dependency (version 6.4) is used for templating. Template engines can be vulnerable to Server-Side Template Injection (SSTI) if user input is directly used in templates without proper escaping. Fix: Ensure handlebars templates are not constructed from untrusted user input. Validate and sanitize all template data, particularly in daemon/client command processing.
• Low · Process Execution via process-wrap — Cargo.toml (workspace.dependencies process-wrap), pueue/src/client/commands/add.rs, pueue/src/daemon/. The process-wrap crate (version 9) is used for wrapping shell command execution. Command injection is possible if user input from CLI commands is not properly validated before execution. Fix: Implement strict input validation for all user-provided command arguments. Avoid shell interpolation where possible; use direct process invocation with argument arrays instead of shell strings.
• Low · Serialization Library (Ciborium) Usage — Cargo.toml (workspace.dependencies ciborium). Ciborium is used for CBOR serialization. Deserialization of untrusted data can lead to denial-of-service or other attacks if not handled carefully. Fix: Validate deserialized data structure and implement size limits on serialized inputs. Ensure daemon properly validates all messages from clients.
• Low · Missing Clippy Configuration for Security Lints — .github/workflows/clippy.yml. While clippy.yml workflow exists, the codebase does not show explicit security-focused lint configurations (e.g., unsafe code restrictions, missing panics in production). Fix: Add security-focused clippy lints to CI/CD configuration, such as cargo +nightly clippy with security-focused deny lists.
• Low · No Visible Input Validation for CLI Arguments — pueue/src/client/commands/. The presence of edit.rs, add.rs, send.rs, and similar commands suggests dynamic command handling. Without visible validation patterns in file structure, there's risk of command injection or argument parsing vulnerabilities. Fix: Implement comprehensive input validation for all CLI arguments, especially in add.rs and edit.rs. Use allowlists for command execution where feasible.
• Low · Query Parser without Visible Sandboxing — pueue/src/client/commands/state/query/syntax.pest. A custom query parser (syntax.pest) is used for state filtering. Parser vulnerabilities or insufficient validation could lead to ReDoS or other parsing-based attacks. Fix: Test the pest parser for ReDoS vulnerabilities. Implement timeouts on query parsing operations and limits on query complexity.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.