Skip to content

15.Async Task Management.md

Latest commit

 

History

History
250 lines (168 loc) · 7.47 KB

15.Async Task Management.md

File metadata and controls

250 lines (168 loc) · 7.47 KB

Snow CLI User Guide - Async Task Management

The async task feature allows you to run time-consuming AI tasks in the background while continuing to use your terminal for other work. Tasks run in independent processes and won't block your operations.

What Are Async Tasks

Async tasks are suitable for the following scenarios:

  • Long-running code analysis and refactoring
  • Batch file processing and conversion
  • Generating detailed project documentation
  • Executing complex multi-step operations

You can create tasks to run in the background, check results later, or approve sensitive operations when needed.

Creating Background Tasks

Use the --task parameter in the terminal to create a background task:

snow --task "Analyze project code and generate architecture documentation"

After execution, task information will be displayed and control returns immediately:

Task created: abc-123-def-456
Title: Analyze project code and generate architecture documentation
Use "snow --task-list" to view task status

The task will run in an independent background process, allowing you to continue using the terminal for other work.

Opening Task Manager

There are two ways to open the task manager to view and manage background tasks:

1. Command Line Launch

snow --task-list

2. Welcome Menu

After launching Snow CLI, select the "Task Manager" option from the main menu.

Viewing Task List

After entering the task manager, you'll see a list of all tasks. Each task displays:

  • Status icon and color
  • Task title (first 50 characters of the prompt)
  • Last update time
  • Message count

Task Status

  • ○ Yellow - Pending: Task created but not yet started
  • ◐ Cyan - Running: Task is executing in the background
  • ⏸ Magenta - Paused: Sensitive command detected, waiting for your approval
  • ● Green - Completed: Task executed successfully
  • ✗ Red - Failed: Task execution error

Operation Shortcuts

In Task List

  • ↑ ↓ - Navigate up/down
  • Space - Mark/unmark task (for batch deletion)
  • Enter - View task details
  • D - Delete task
    • Single delete: Select and press D, press D again to confirm
    • Batch delete: Mark multiple tasks with Space, press D, press D again to confirm
  • R - Refresh task list
  • Esc - Exit task manager

In Task Details

  • C - Convert task to session for continued conversation
    • Press C once to show prompt
    • Press C again to confirm conversion
  • A - Approve sensitive command execution (only available when paused)
  • R - Reject sensitive command (only available when paused)
  • Esc - Return to task list

Approving Sensitive Commands

When a background task needs to execute dangerous operations (like deleting files, resetting code, etc.), it will automatically pause and wait for your approval.

Approval Steps

  1. See the pause icon ⏸ and magenta status in the task list
  2. Press Enter to view task details
  3. Check the specific command shown in the yellow warning box
  4. Choose based on the situation:
    • Press A - Approve execution, task continues running
    • Press R - Reject execution

Rejecting Commands with Reason

  1. Press R on the paused task details page
  2. Enter input mode, cursor displays as █
  3. Enter rejection reason, e.g., "Insufficient permissions, please execute manually"
  4. Press Enter to submit
  5. Press Esc to cancel input

After rejection, the AI will receive your reason and adjust subsequent operations accordingly.

Configuring Sensitive Commands

You can customize which commands require approval. See Sensitive Commands Configuration.

Converting Tasks to Sessions

Completed tasks can be converted to regular sessions, allowing you to continue conversing with the AI, ask for more details, or request modifications.

Conversion Method

  1. Select a task in the task list
  2. Press Enter to view details
  3. Press C key (confirmation prompt appears)
  4. Press C again to confirm
  5. Automatically jump to chat interface

Notes

  • Original task will be deleted after conversion
  • All message history will be preserved in the new session
  • Incomplete tasks can also be converted, but with a warning prompt
  • Conversion operation cannot be undone

Viewing Task Logs

Each task has an independent log file that records detailed execution process.

Log Location

Task creation displays the log path:

Task abc-123-def-456 started in background (PID: 12345)
Logs: /Users/username/.snow/task-logs/abc-123-def-456.log

Viewing Logs

Use any text editor or command-line tool:

# View logs in real-time
tail -f ~/.snow/task-logs/abc-123-def-456.log

# View complete log
cat ~/.snow/task-logs/abc-123-def-456.log

Logs contain:

  • Task start and end times
  • All output information
  • Error information and stack traces
  • Execution process tracking

Usage Scenarios

Scenario 1: Long-Running Code Analysis

# Create background task
snow --task "Comprehensively analyze project code, generate architecture documentation and optimization suggestions"

# Continue other work
cd other-project
git pull

# Check results later
snow --task-list

Scenario 2: Batch File Refactoring

# Execute refactoring in background
snow --task "Refactor all components in src/components, use TS strict mode uniformly"

# Task will pause when detecting file deletion operations
# Open task manager to approve

Scenario 3: Generate Reports and Continue Discussion

# Create analysis task
snow --task "Analyze Git commits from the last week, generate code quality report"

# After task completes
snow --task-list
# Select task → Enter → C → C to convert to session
# Then continue asking: "Which parts should be prioritized for optimization?"

FAQ

Q: Task status stuck at "Running"?

A: The task might be executing time-consuming operations. You can:

  • Check logs to understand current progress
  • Wait longer
  • If confirmed stuck, delete the task and recreate it

Q: What to do if task failed?

A:

  1. Check logs to find the error cause
  2. Verify if the prompt is reasonable
  3. Confirm if system resources are sufficient
  4. Modify and recreate the task

Q: How to delete multiple tasks?

A:

  1. Use Space key to mark tasks to delete (shows marked count)
  2. Press D key
  3. Press D again to confirm batch deletion

Q: Sensitive command not pausing?

A: Check if the command pattern has been added in Sensitive Commands Configuration.

Q: How many tasks can run simultaneously?

A: There's no theoretical limit, but each task consumes system resources. It's recommended to control the number based on machine performance.

Practical Tips

  1. Clear Task Goals - Provide clear and specific prompts when creating tasks, let the AI know what to do
  2. Regular Cleanup - Delete unneeded completed tasks to keep the list clean
  3. Use Marking - Batch mark unwanted tasks for one-time deletion
  4. Check Logs - For long-running tasks, check logs to understand progress
  5. Convert to Session - After important tasks complete, convert to session for easy follow-up queries and modifications

Related Documentation