Skip to content
Background Build Monitor logo

Background Build Monitor

Use this skill when applying home-manager or darwin configurations that require long-running builds. Automatically runs builds in background, monitors progress with appropriate polling intervals, and reports status updates without overwhelming the user. Triggered by "apply changes", "rebuild", "m...

SKILL.md

Full skill instructions

Background Build Monitor

Expert agent for managing long-running Nix builds with efficient background monitoring.

Instructions

Your goal is to run builds in background and provide concise progress updates without excessive polling.

Workflow

  1. Determine Build Type

    • Home-manager: make home (5-10 minutes, background required)
    • Darwin: make darwin (2-5 minutes, can run foreground)
    • Update: make update (variable time, background required)
  2. Pre-flight Check

    • Verify working directory: /​Users/​shavakan/​nix-flakes
    • Note current git status if relevant
    • For home-manager/​darwin: confirm build test passed first
  3. Start Build in Background

    # Home-manager
    make home  # run_in_background: true
    
    # Darwin
    make darwin  # can run foreground or background
    
    # Update
    make update  # run_in_background: true
    
  4. Monitor Progress

    Polling strategy:

    • Initial check: 15 seconds after start
    • Subsequent checks: every 15 seconds
    • Report to user: every 30-45 seconds (combine 2-3 polls)

    What to look for:

    • Build progress: "building...", "copying...", "downloading..."
    • Activation: "setting up...", "activating..."
    • Errors: parse and report immediately
    • Completion: "done", exit code

    Don't report:

    • Every single line of output
    • Repetitive "building" messages
    • Nix hash computations
    • Individual package builds unless user asks
  5. Progress Reporting

    Every 30-45 seconds, concise updates:

    [2m] Building... (42 packages)
    [4m] Building... (ongoing)
    [7m] Activating configuration...
    [8m] Complete ✓
    

    NOT this:

    Checking output...
    Still building...
    No new output...
    Checking again...
    (repeating every 15s)
    
  6. Completion

    On success:

    ✓ Configuration applied successfully
    Total time: [duration]
    
    [If services affected]:
    Check status:
    - rclone: rclone-mount-status
    - logs: ~/​nix-flakes/​logs/
    

    On failure:

    ✗ Build failed at [stage]
    Error: [concise explanation]
    
    [relevant error lines from output]
    
    Check logs: ~/​nix-flakes/​logs/[service].log
    

Monitoring Pattern

Start build in background
↓
Wait 15s
↓
Check output (BashOutput)
↓
Parse state: building | activating | error | complete
↓
If not complete:
  - Wait 15s
  - Check again
  - If 2-3 polls elapsed → report to user
↓
If complete:
  - Report final status
  - Suggest next steps if needed

Error Handling

Build phase errors:

  • Usually Nix evaluation or compilation errors
  • Extract relevant error message
  • Identify file/​module if possible
  • Don't proceed to activation

Activation phase errors:

  • Occur after successful build
  • Often service-related
  • Check ~/​nix-flakes/​logs/ for details
  • Common: rclone hash mismatch, service conflicts

Timeout (>15 minutes for home-manager):

  • Check if process is hung
  • Look for network issues (downloads stuck)
  • Suggest manual intervention

Silent builds:

  • Some builds produce no output for minutes
  • This is normal for large packages
  • Don't report "no output" as a problem
  • Just note "Building... (in progress)"

Special Cases

First-time builds:

  • May take longer (no cache)
  • Warn user this is expected

Service restarts:

  • Some services restart during activation
  • Brief interruptions normal

Hash file updates:

  • rclone activation creates hash files
  • May see "hash changed, recreating"

Multiple builds:

  • If user wants both home-manager and darwin
  • Run sequentially, not parallel
  • Home-manager first, then darwin

Output Discipline

Do report:

  • Major phase transitions (build → activate → complete)
  • Errors immediately
  • Time elapsed at reasonable intervals
  • Final status

Don't report:

  • Every BashOutput check
  • Individual package builds (unless slow)
  • Repetitive "still building" messages
  • Technical Nix internals unless error

Timing:

  • Check every 15s (tool call)
  • Report every 30-45s (user message)
  • Keep user informed without spam

Constraints

  • ALWAYS run make home and make update in background
  • ALWAYS wait minimum 15 seconds between BashOutput checks
  • NEVER poll more frequently than 15s
  • NEVER report every individual check to user
  • AGGREGATE updates into meaningful progress reports
  • PARSE output for actual state changes before reporting

Examples

Typical home-manager run:

Starting home-manager rebuild in background...
[15s] Building...
[45s] Building... (ongoing, 128 packages)
[2m] Activating configuration...
[2m15s] ✓ Complete

Total time: 2m 15s

Build with error:

Starting home-manager rebuild in background...
[15s] Building...
[1m] ✗ Build failed

Error in modules/​vscode/​extensions.nix:42
Attribute 'publisher.extension' not found

[relevant error context]

Update flake:

Updating flake inputs in background...
[15s] Updating...
[45s] Updated: nixpkgs, home-manager, darwin
[1m] ✓ Complete

Run `make home` to apply updates

More DevOps & CI/CD skills

Project scaffolding, deployment configuration, and CI/CD setup for Google ADK agents.

6K 472.6K
View

Set up tracing, logging, and monitoring for deployed ADK agents across Cloud Trace, BigQuery, and third-party platforms.

6K 472.6K
View

Enterprise Azure infrastructure architect generating Bicep or Terraform from workload descriptions.

1.5K 454.3K
View
azure-kubernetes logo
DevOps & CI/CD

azure-kubernetes

Plan and configure production-ready Azure Kubernetes Service clusters with Day-0 and Day-1 best practices.

1.5K 447.1K
View

Raw mechanical interfaces fusing Swiss typographic print with military terminal aesthetics. Rigid grids, extreme type scale contrast, utilitarian color, analog degradation effects. For data-heavy dashboards, portfolios, or editorial sites that need to feel like declassified blueprints.

92.7K 354.9K
View
just-scrape logo
DevOps & CI/CD

just-scrape

Web search, scraping, extraction, crawling, and monitoring via ScrapeGraph AI CLI.

69 245K
View

Skill for working with Firebase Hosting (Classic). Use this when you want to deploy static web apps, Single Page Apps (SPAs), or simple microservices. Do NOT use for Firebase App Hosting.

462 159.7K
View

Deploy and manage web apps with Firebase App Hosting. Use this skill when deploying Next.js/Angular apps with backends.

462 159.1K
View
deploy-to-vercel logo
DevOps & CI/CD

deploy-to-vercel

Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".

31.9K 146.6K
View
programmatic-seo logo
DevOps & CI/CD

programmatic-seo

Build SEO-optimized pages at scale using templates, data, and proven playbook patterns.

53.3K 140.1K
View

Design and build isolated, reusable Convex backend components with clear boundaries and app-facing wrappers.

63 123.5K
View

Deploy and manage projects on Vercel using token-based authentication. Use when working with Vercel CLI using access tokens rather than interactive login — e.g. "deploy to vercel", "set up vercel", "add environment variables to vercel".

31.9K 116.1K
View

Coding & apps AI tools

Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View
Imagica logo
Coding & apps

Imagica

Build a no-code AI app in minutes.

Freemium
View
E
Coding & apps

Emergent.sh

An IDE for code migration from legacy to modern frameworks through coding agents.

Freemium
View
Wonder Dynamics logo
Coding & apps

Wonder Dynamics

Automate CGI animation in live-action scenes

Paid
View
M
Coding & apps

Mixo

Launch a website in seconds with AI.

Paid
View
AI Code Convert logo
Coding & apps

AI Code Convert

Streamline Your Coding Experience with AI Code Helper

Free
View