Delegator CLI: Running Multi-Agent Delegation from the Terminal

We packaged the Worksona delegation engine as a global npm command. Type worksona delegate followed by a query and a pattern flag, and a coordinated team of AI agents runs the task and returns the output — to the terminal, to a file, or as JSON for piping into another tool.

What is it?

The Worksona CLI is a Node.js command-line tool, distributed as the npm package @worksona/cli. It exposes the full delegation system — all six patterns, all agent templates, task management, and configuration — through a structured set of subcommands. It does not require a running browser or an MCP client. It runs wherever Node.js 18+ runs.

Why a CLI?

Three reasons. First, scripting. A browser-based UI cannot be invoked from a Makefile, a GitHub Actions workflow, or a shell script. A CLI can. Analysis tasks, report generation, and research steps that would otherwise be manual can become automated pipeline steps.

Second, output handling. The CLI supports --format json and --output <file>. That means delegation results can be written directly to a markdown file for inclusion in a project, captured as JSON for downstream processing, or piped into another command. The report from a multi-agent run becomes a build artifact.

Third, focus. Running in a terminal keeps the developer in the terminal. There is no context switch to a browser and back.

How does it work?

Configuration is stored at ~/.worksona/config.json. First-time setup runs an interactive wizard:

worksona config setup

The wizard prompts for API keys (Anthropic, OpenAI, or Google), a default model, and default delegation preferences. After that, delegation is one command.

# Research with hierarchical delegation, saved as markdown
worksona delegate "analyze the electric vehicle market in Europe" \
  --pattern hierarchical \
  --agents 4 \
  --focus "market size" "key players" "growth trends" \
  --format markdown \
  --output ev-analysis.md

The --watch flag streams progress to the terminal as agents complete their subtasks. Without it, the command blocks until synthesis is complete and then prints the result. The --interactive flag replaces the --pattern flag with a guided selection prompt that asks questions about the task before recommending a pattern.

Task management is a first-class concern. Every delegation run is assigned a task ID. That ID can be used to check status, retrieve results again, or cancel a running task:

worksona tasks list --status completed
worksona tasks results task_1234567890_abc123 --format markdown
worksona tasks history --limit 10

The pattern subcommands let you explore and compare options before committing:

worksona patterns recommend "analyze customer feedback"
worksona patterns compare hierarchical competitive peer-to-peer

The CLI can also be used as a Node.js library directly if you need delegation inside an existing script:

import { delegationEngine } from '@worksona/cli/src/core/delegation-engine.js';

const task = await delegationEngine.createTask(
  "review architecture for scalability bottlenecks",
  "hierarchical"
);
const result = await delegationEngine.executeTask(task.taskId);
console.log(result.synthesis);

Where and how it applies

The most direct use is one-off research and analysis during development work: asking a multi-agent team to produce a competitive analysis, review a design, or draft a structured report, without opening a browser. The output file flag makes the results immediately usable — write to docs/analysis.md and commit it.

The more structured use is in CI pipelines. A GitHub Actions step can install @worksona/cli, run a delegation task against a codebase or dataset, and write the result as an artifact or comment:

- name: Install Worksona CLI
  run: npm install -g @worksona/cli

- name: Run architecture analysis
  run: worksona delegate "review this codebase for scalability issues" \
    --pattern hierarchical \
    --output architecture-review.md \
    --format markdown
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

The package is 93.9 kB compressed, has no bundled credentials, and installs cleanly on any Node 18+ environment. Distribution is via npm, GitHub releases, a Docker image, and a direct install script.