scorpiox-tasks Core

Persistent task management for agentic loops. Create, track, and complete multi-step tasks across AI agent sessions. Tasks survive context window resets, enabling long-running workflows that span multiple interactions.

Supported Platforms

Linux x64 Linux ARM64 macOS ARM64 Windows x64

Actions

create

Create a new task with a name. Returns a unique task ID used to reference it in all subsequent operations.

add

Add a step to an existing task by task ID. Each step is automatically assigned a step ID for tracking completion.

complete

Mark a specific step as complete by task ID and step ID. Tracks progress through multi-step workflows.

list

List all tasks with their steps and completion status. Provides a full overview of all tracked work.

pending

Show only incomplete steps across all tasks. Quickly identify what work remains to be done.

switch

Switch to a different task context by task ID. Clears the context window for a fresh start while preserving task state.

Flags & Options

Flag	Short	Description	Takes Value
--session	—	Scope task storage to the current session only	No

Usage Examples

Create a new task

# Create a task and receive its ID
scorpiox-tasks create --query "Deploy v2.1 release"

Task created: id=1 name="Deploy v2.1 release"

Add steps to a task

# Add sequential steps to task 1
scorpiox-tasks add --task-id 1 --text "Run test suite"
scorpiox-tasks add --task-id 1 --text "Build release binaries"
scorpiox-tasks add --task-id 1 --text "Push to production"

Step 1 added to task 1
Step 2 added to task 1
Step 3 added to task 1

Complete steps and check progress

# Mark first step as done
scorpiox-tasks complete --task-id 1 --step-id 1

# View all pending work
scorpiox-tasks pending

Task 1: "Deploy v2.1 release" (1/3 complete)
  [ ] Step 2: Build release binaries
  [ ] Step 3: Push to production

List all tasks

# Full overview of all tasks and steps
scorpiox-tasks list

Task 1: "Deploy v2.1 release" (1/3 complete)
  [✓] Step 1: Run test suite
  [ ] Step 2: Build release binaries
  [ ] Step 3: Push to production

Task 2: "Refactor auth module" (0/2 complete)
  [ ] Step 1: Extract OAuth logic
  [ ] Step 2: Write unit tests

Switch context to a task

# Switch agent focus to a specific task
# Clears context window, reloads task state
scorpiox-tasks switch --task-id 2

Switched to task 2: "Refactor auth module"
Context cleared. 2 pending steps loaded.

Session-scoped tasks

# Create a task that only lives in the current session
scorpiox-tasks --session create --query "Quick debug investigation"

# Tasks created with --session are automatically cleaned
# up when the session ends

Source & Build Info

Source File

scorpiox/scorpiox-tasks.c

Lines of Code

636

Dependencies

libsxutil