laneq

laneq is a tiny local SQLite priority queue for feeding directives to autonomous agents and orchestrators. It never talks to the network and stores only the queue data you put into its local database.

Part of Patrick Selamy's public agent-systems work: selamy.dev · GitHub profile · agent-skills

Priorities sort as P0 < P1 < P2, with FIFO ordering inside each priority. next atomically takes one pending item so concurrent workers do not receive the same directive.

Install

Run directly from GitHub:

uvx --from git+https://github.com/selamy-labs/[email protected] laneq --help

Or install with pipx:

pipx install git+https://github.com/selamy-labs/[email protected]

The laneq name is already occupied on PyPI by an unrelated lane-line detection package, so releases are GitHub-tag based until the distribution name is resolved.

Directive lifecycle

Each directive moves through a small state machine. next takes the highest-priority pending directive and gives it a lease; the worker either finishes it (done), hands it back (requeue), or lets the lease expire — in which case reap (or the next queue operation) returns it to pending and increments its requeue_count.

stateDiagram-v2
    [*] --> pending: push
    pending --> taken: next (lease + consumer)
    pending --> deferred: defer (not-before / deps)
    deferred --> pending: not-before reached + deps terminal
    taken --> done: done
    taken --> pending: requeue / lease expires + reap
    taken --> deferred: defer (not-before / deps)
    taken --> taken: touch (extend lease)
    pending --> dropped: drop
    taken --> dropped: drop
    deferred --> dropped: drop
    done --> [*]
    dropped --> [*]

peek reads the next actionable pending directive without changing its state. Deferred directives are not leased by next; queue operations promote them back to pending only after their not_before timestamp has passed and every dependency in blocked_by is terminal (done or dropped). Priorities sort P0 < P1 < P2, FIFO within a priority; lanes and parent threads partition work without changing this lifecycle.

TIME Plane Deferral

laneq keeps the queue actionable by separating work that cannot start yet from work that is ready to lease. Use defer when an item has a future not-before time or unmet dependencies:

laneq defer 42 --for 2h
laneq defer 43 --until 2026-06-20T15:00:00Z
laneq defer 44 --blocked-by 42 --blocked-by 43
laneq list --all

This is the first incremental TIME-plane primitive. The broader design is:

• a single writer computes effective priority from static priority, importance, deadline, urgency, and starvation age;
• future work and dependency-blocked work is deferred, not repeatedly leased and requeued;
• workers claim only the next eligible item in their lane;
• later schema can add explicit importance, deadline, and effective_priority fields without changing the worker contract.

Usage

laneq push -p P0 -b "ship the smallest verified fix"
laneq peek
laneq next --id --consumer worker-a
laneq done 1
laneq stats

Read a directive body from a file:

laneq push -p P1 -f directive.txt

Use a specific database path:

LANEQ_DB=/tmp/laneq.db laneq list --all

The default database is ~/.claude/laneq.db.

Coordination

Consumers can identify themselves when taking work:

laneq next --id --consumer worker-a
laneq list --all
laneq stats

Taken directives receive a lease. The default lease is 30 minutes, configurable with LANEQ_LEASE_SECONDS. Use --lease on next or touch to set or extend it:

laneq next --consumer claude --lease 45m
laneq touch 7 --lease 10m
laneq reap --expired-leases

Expired leases are reclaimed lazily on queue operations and increment the directive's requeue_count.

For concurrent workers, use next --json and retain its id and claim_token alongside the directive body. Pass that token to done, requeue, drop, defer, or touch with --claim-token. A token is unique to one claim; a mutation fails if the lease expired or the directive was reclaimed and claimed again, even when the new claim uses the same consumer name. The check and mutation share one SQLite write transaction. Mutations without a token fail. Operators may use --force to override an active claim explicitly; workers must never use that administrative option. MCP and gRPC expose the same token and explicit force fields.

Use lanes to isolate independent work streams inside the same SQLite database:

laneq push --lane release -p P0 -b "verify release candidate"
laneq next --lane release --consumer worker-a
laneq list --lane release

Use parent links to create directive threads:

laneq push -p P0 -b "investigate incident"
laneq push --parent 1 -p P0 -b "collect deployment evidence"
laneq list --thread 1
laneq thread-status 1

Commands

• push: enqueue a directive from --body, --file, or stdin; add --lane and --parent to route and thread it.
• next: atomically take the highest-priority pending directive and print its body; add --consumer, --lease, and --lane for multi-worker coordination. --json returns the body, id, and fencing token for safe worker completion.
• peek: print the next pending directive without taking it; add --lane to inspect a specific lane.
• show: print any directive by id, including lane, thread, consumer, lease, and requeue details.
• list: list pending directives; add --all to include non-pending items, --lane to filter a lane, or --thread to render a thread.
• reprioritize: change a directive priority.
• done, requeue, drop: update directive status with the token from next --json, or use --force for an administrative override.
• defer: mark a directive deferred until a time, duration, or dependency ids; requires a claim token or explicit --force.
• touch: extend the lease for a taken directive with --claim-token, or use --force for an administrative override.
• thread-status: summarize whether a directive thread still has open work.
• reap: requeue stale taken directives or expired leases.
• stats: print counts by priority/status and taken counts by consumer.

next and peek exit with status code 3 when the queue is empty.

Existing v0.1 databases migrate in place on first open. New columns are added for consumers, leases, lane names, parent links, deferral metadata, and requeue counts while preserving existing directive ids and statuses.

Before any migration touches an existing database, laneq takes a SQLite write lock, checks the current schema, makes an online backup (including WAL pages) at laneq.db.backup-<UTC>, and requires PRAGMA integrity_check to return ok. The migration then runs under that lock; on failure, SQLite rolls the original database back and the verified backup remains. Backup retention defaults to the last 5 copies and can be changed with LANEQ_BACKUP_RETENTION or laneq migrate --keep-backups N.

Use laneq migrate --dry-run to inspect planned schema/data changes without modifying the database. A successful explicit migration prints the changed steps and backup path.

The claim-token change requires a coordinated cutover for a shared database. Before the first new next, stop every old CLI, MCP, and gRPC consumer and producer that can access that database, including scheduled jobs. Verify no old process can restart, install the new version for every account using the database, and restart only those versions. An old executable ignores claim tokens and can still update a new worker's claim by id. Keep multiworker dispatch paused until all clients are upgraded and a private stale-claim and crash/restart check has passed against the exact database route.

codex-q remains as a compatibility command alias for existing local automation. Prefer laneq for new docs, scripts, and integrations.

MCP server

laneq ships an optional Model Context Protocol server so agents can drive the queue as typed tools instead of shelling out to the CLI. The core package stays dependency-free; the server is an extra:

pipx install "git+https://github.com/selamy-labs/[email protected]#egg=laneq[mcp]"
laneq-mcp   # serves over stdio

Or run it directly with uvx:

uvx --from "git+https://github.com/selamy-labs/[email protected]" --with mcp laneq-mcp

Register it with an MCP client (the server reads the same LANEQ_DB, so it shares one queue with the CLI):

{
  "mcpServers": {
    "laneq": {
      "command": "laneq-mcp",
      "env": { "LANEQ_DB": "/home/you/.claude/laneq.db" }
    }
  }
}

The server exposes one tool per queue operation, each with structured JSON input and output:

• laneq_push, laneq_next, laneq_peek, laneq_show, laneq_list
• laneq_reprioritize, laneq_done, laneq_requeue, laneq_drop
• laneq_defer, laneq_touch, laneq_reap, laneq_stats, laneq_thread_status

laneq_next and laneq_peek return {"empty": true} when a lane has no pending work. Every tool wraps the same queue logic the CLI uses, so the two interfaces never diverge.

Observability (OpenTelemetry)

The server runs unmodified under OpenTelemetry zero-code auto-instrumentation. Install the otel extra and launch via opentelemetry-instrument:

pipx install "git+https://github.com/selamy-labs/[email protected]#egg=laneq[mcp,otel]"
OTEL_SERVICE_NAME=laneq-mcp \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 \
OTEL_TRACES_EXPORTER=otlp \
  opentelemetry-instrument laneq-mcp

Config is vendor-neutral — point OTEL_EXPORTER_OTLP_ENDPOINT at any OTLP collector; the collector (not this server) owns any Cloud Trace / vendor coupling.

stdio safety (required): this server speaks MCP over stdin/stdout, so its stdout carries the JSON-RPC protocol. Export traces/logs via OTLP only — never set OTEL_TRACES_EXPORTER=console (or any stdout exporter), which would interleave span output into the protocol stream and break the client.

Development

python -m pip install -e ".[test]"
coverage run -m pytest
coverage report --fail-under=95

The runtime package intentionally has zero third-party dependencies.

Architecture

The system context documents laneq's runtime clients, shared queue boundary, local SQLite persistence, and optional telemetry export.