lazybox AGENTS.md

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

What is lazybox?

A reactive PR inbox TUI. Instead of checking GitHub, events flow to you — new comments, CI failures, review requests surface automatically with read/unread tracking. Each task becomes a session with an embedded terminal for running Codex or a shell in a git worktree.

Source-agnostic: GitHub is one provider, but Linear/Jira/etc. plug in the same way.

Build & Run

cargo build                   # build (first build compiles SQLite, takes ~30s)
cargo run -p lazybox-tui-boot # run (uses `gh auth token` automatically)
cargo test --workspace        # tests
cargo clippy --workspace      # lint
make run                      # same as cargo run -p lazybox-tui-boot

Logs go to /tmp/lazybox.log. State persisted in ~/.lazybox/v2/state.db.

Before you compile or test — check shared resources

Lazybox routinely runs many agents on one box. Before cargo build, cargo test, or cargo clippy, check for available resources — sample the system load (uptime vs. nproc) and back off, throttle the job count (CARGO_BUILD_JOBS), or scope to the crate you touched (cargo test -p <crate>) while iterating when the machine is already busy. Blindly grabbing every core when fifteen other agents are doing the same is what drives the box to 100% CPU. Throttling changes how hard you compile, never whether the full gate suite runs before you push — scoped runs miss cross-crate gates. Full guidance: docs/agent-resource-awareness.md.

Staying current (outdated-build guard)

A uniformly-stale build — daemon and client compiled from the same old commit — passes every wire check silently and reproduces already-fixed bugs. At startup crates/tui/src/build_guard.rs checks the channel appropriate to the running build and opens a dismissable update modal when something newer exists:

• Dev/source builds compare the baked LAZYBOX_BUILD_GIT_SHA with the baked checkout's current HEAD and, when it can fast-forward safely, that branch's tracking upstream. This path performs no network request and still runs for dirty builds.
• Cargo-dist release builds compare CARGO_PKG_VERSION with GitHub's latest published release through a bounded, cached API request.