skills.rest
catalystctl
catalystctlOFFICIAL
Explore all skills by this author →
WebsiteGitHub

add-core-background-task

Implements periodic background tasks in the Rust core using tokio spawn loops.

10|1|Updated Jul 7, 2026
Search Tags:#concurrency#rust#async#polling#tokio#heartbeat#background task
One-click install
npx skills add https://github.com/catalystctl/catcode --skill add-core-background-task-catalystctl
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: add-core-background-task
Source: https://github.com/catalystctl/catcode/tree/main/.catalyst-code/skills/add-core-background-task
Command: npx skills add https://github.com/catalystctl/catcode --skill add-core-background-task-catalystctl

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Adding ambient, timer-driven behavior to the Catalyst Code Rust core (like usage polling or presence heartbeats) requires knowing exactly where to spawn tasks, how to share state safely, and how to avoid async pitfalls that stall the turn loop. ## Core Features & Use Cases - Spawn-site guidance: Locates the correct place in core/src/main.rs to launch a tokio::spawn loop, modeled on the existing umans_conc poll block. - State caching pattern: Shows how to add a Mutex<T> field on State so turn-loop consumers read a cached snapshot instead of re-polling. - Crash-safe file writes: Prescribes atomic temp+fsync+rename writes, shutdown cleanup, and stale-file reaping for per-process files. - Use Case: Add a heartbeat task that publishes the session's work state every 8 seconds so peer sessions can detect concurrent activity in the same workspace. ## Quick Start Add a background task to the Rust core that polls an endpoint every 30 seconds and caches the result on State for the turn loop to read.

Frequently Asked Questions about add-core-background-task

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a periodic background task in a Rust tokio application?▼

Spawn a task with tokio::spawn containing a loop that does its work and then awaits tokio::time::sleep for the interval. Clone an Arc<State> into the task, capture read-once values before the move, and perform the first write immediately before entering the loop.

How do I share state between a tokio background task and the main loop?▼

Add a Mutex or RwLock field to the shared State struct wrapped in Arc. The background task refreshes the cached value each tick, and consumers on the hot path read the cache cheaply instead of re-polling or doing I/O.

Why should I avoid std::thread::sleep inside a tokio task?▼

std::thread::sleep blocks an async runtime worker thread, stalling other tasks scheduled on it. Use tokio::time::sleep instead, which yields control back to the runtime while waiting for the interval.

What happens if I hold a MutexGuard across an await in Rust?▼

Holding a MutexGuard across an await serializes the background task against the turn loop, causing contention and stalls. Snapshot the value with clone, drop the guard, then perform any awaited I/O.

How do I make per-process file writes crash-safe in Rust?▼

Write to a temp file, fsync, then atomically rename it into place. Provide a cleanup function called on the clean shutdown path, and tolerate kill -9 by having readers reap stale files based on an mtime threshold.

Related Skills

Explore More Software Engineering Skills→
EliasVahlbergEliasVahlberg

codebase-game-loop

Document main game loop, turn processing, and system call order.

Community
Intermediate
zircotezircote
14

team-management

Create, configure, and shut down autonomous agent teams with permissions and messaging.

Community
Advanced
dsgalkardsgalkar

benchmark-agents

Runs interactive Claude Code eval sessions via WezTerm to verify Vercel plugin skill injection.

Community
Advanced
udecodeudecode
434

convex-scheduling

Schedule runtime cron-like tasks with configurable timeouts and retries.

Official
Advanced