async-runner

name	async-runner
description	Run background agents and bash commands asynchronously for CircleTel development. Use when running dev servers, parallel tests, long builds, or multi-agent research tasks without blocking the main workflow.

Async Task Runner

Skill for managing asynchronous background tasks and agents in CircleTel development.

When to Use

This skill activates when you:

• Need to run dev server while coding
• Want parallel test execution
• Run long builds in background
• Spawn research agents for codebase exploration
• Monitor logs while implementing fixes

Keywords: background, parallel, async, spawn, concurrent, dev server, watch, monitor, simultaneously

Quick Reference

Action	Command/Method
Background bash	Ctrl+B or append &
Check running tasks	/tasks
Kill background task	Use task ID from /tasks
Spawn background agent	Task tool with run_in_background: true

Background Bash Commands

Development Server (Always Background)

# Start dev server - never blocks
npm run dev:memory &

Parallel Test Execution

Ask Claude:

"Run these tests in parallel:
1. Type check
2. Unit tests
3. E2E tests

Continue working on the auth fix while they run."

Claude will spawn:

npm run type-check:memory &
npm run test &
npm run test:e2e &

Long-Running Builds

"Start the production build in background while I review code"

Claude runs:

npm run build:memory &

Then continues with your code review.

Log Monitoring

"Tail the Supabase logs in background while I debug"

Background Agents

Parallel Research

"Spawn 3 Explore agents in parallel:
1. Investigate how auth works in /app/dashboard
2. Map the payment flow in /app/checkout
3. Document the coverage API integration"

Claude spawns specialized Explore agents that run concurrently. Results come back asynchronously.

Multi-File Analysis

"Analyze these files in parallel:
1. app/api/payment/route.ts - check error handling
2. lib/payment/netcash.ts - review integration
3. components/checkout/PaymentForm.tsx - check validation"

Codebase Exploration

"Use Explore agents to find:
1. All files that import CustomerAuthProvider
2. All API routes that use service role
3. All components with loading states"

CircleTel-Specific Patterns

Full Development Setup

"Start my development environment:
1. Dev server (background)
2. Supabase logs (background)
3. Then start working on the billing feature"

Spawns:

npm run dev:memory &
npx supabase functions serve &

Then begins coding.

Pre-Commit Workflow

"Run all checks in parallel before I commit:
- Type check
- Lint
- Build
- Tests"

Deployment Verification

"Run pre-deploy checks in background while I write the PR description:
1. Full type check
2. Production build
3. E2E tests"

Task Management

Check Running Tasks

/tasks

Shows all background bash processes and agents.

Monitor Task Output

"Show me the output from the background build"

Claude retrieves output via TaskOutputTool.

Cancel Task

"Kill the dev server"

Or use task ID:

"Kill task abc123"

When to Use Background

Always Background

• npm run dev / npm run dev:memory
• npm run watch
• Log tailing (tail -f, supabase logs)
• Long builds (npm run build:memory)

Run in Parallel

• Independent test suites
• Multiple lint checks
• Codebase exploration
• File analysis tasks

Run Sequentially

• Dependent operations (build → deploy)
• Database migrations
• Git operations
• File modifications to same files

Resource Considerations

Memory Usage (Approximate)

Process	Memory
Dev server	~500MB
Build	~2GB
Type check	~1GB
Tests	~1GB

Recommendation: Limit to 2-3 heavy tasks simultaneously.

When NOT to Background

• Interactive commands (npm init)
• Commands requiring user input
• Quick one-time commands (git status)
• Commands that need immediate results

Integration with Other Skills

With Session Manager

# Name session for async work
/rename dashboard-tests

# Start background tasks
"Run all dashboard E2E tests in background"

# Can resume later
claude --resume dashboard-tests
# Background results available

With Context Manager

# Background tasks don't consume context
# Use for verbose operations
"Run verbose build in background"
# Build output doesn't fill context window

With Stats Tracker

# Background agents still count toward usage
# But more efficient than sequential
/stats  # Check usage after parallel work

Examples

Example 1: Feature Development

You: "Start dev server and begin working on the payment form"

Claude:
- Starts: npm run dev:memory & (background)
- Immediately begins: Reading PaymentForm.tsx
- Dev server running while coding

Example 2: Bug Investigation

You: "Investigate this timeout error from multiple angles in parallel"

Claude spawns 3 Explore agents:
- Agent 1: Checks API route error handling
- Agent 2: Reviews database query performance
- Agent 3: Analyzes frontend retry logic

All run concurrently, results aggregated.

Example 3: Release Preparation

You: "Run full test suite in background while I update the changelog"

Claude:
- Background: npm run type-check:memory &
- Background: npm run build:memory &
- Background: npm run test:e2e &
- Foreground: Opens CHANGELOG.md for editing

Reports results as each completes.

Best Practices

1. Always background dev servers - Never block with npm run dev
2. Parallel for independent tasks - Tests, lints, builds together
3. Sequential for dependencies - Build before deploy
4. Use Explore agents - Faster, uses efficient Haiku model
5. Monitor resource usage - Don't overload system
6. Check task status - Use /tasks to track
7. Clean up finished tasks - Kill completed background processes

Troubleshooting

Background task not starting

# Check if command is valid
npm run dev:memory  # Test without &

# Then add background
npm run dev:memory &

Can't see background output

"Show output from background task [name/id]"

Too many background tasks

# List all
/tasks

# Kill unnecessary ones
"Kill the old dev server"

---

Version: 1.0.0 Last Updated: 2025-12-10 For: Claude Code v2.0.64+