agent-worker

Run AI agents from the terminal. One agent or many, talking to each other.

npm install -g agent-worker

# Start an agent, send it a task
agent-worker new alice -m anthropic/claude-sonnet-4-5
agent-worker send alice "Refactor the auth module"

# Or define a team in YAML and let them collaborate
agent-worker run review.yaml

Why agent-worker?

Most agent frameworks lock you into a single provider and a single execution model. agent-worker gives you one CLI that works across backends (Claude CLI, Cursor, Codex, or raw SDK) and scales from a single assistant to a team of agents coordinating via @mentions.

• Multi-backend — Same commands whether your agent runs on Claude CLI, Cursor, Codex, or the Vercel AI SDK
• Single & multi-agent — Start one agent interactively, or define a team workflow in YAML
• @mention coordination — Agents talk to each other naturally: @reviewer check this, @coder fix it
• Shared context — Channel (messages), documents (workspace), resources (large content) — all agents see the same state
• Instance isolation — Run the same workflow for different PRs/tasks with --tag, fully isolated
• SDK included — Use programmatically from TypeScript when the CLI isn't enough

Design Philosophy

The central question we're exploring: how do you make a system of short-lived agents accumulate progress over time?

One approach is to give each agent a persistent memory — recall past conversations, learn preferences, build a model of the world. But for engineering work, the value of making an agent more "human-like" is limited. An agent that remembers everything it did last week doesn't necessarily write better code today.

So we start from a different assumption: an agent's lifetime is one tool loop. It starts, it works, it's gone. No memory, no continuity, no identity.

The question then becomes: if each agent is ephemeral, where does the continuity live? Our answer is collective memory — not stored in any individual agent, but in the shared artifacts they produce. Channels capture the conversation. Documents hold the evolving workspace. Event logs record what happened. The next agent reads these artifacts, picks up where the last one left off, and pushes forward.

This has a property we find compelling: it scales with the context window. As models can process more context, agents naturally absorb more of the shared history and make better decisions — without changing a line of code. Contrast this with approaches that program around individual agent limitations (elaborate prompts, rule systems, retrieval hacks). Those techniques solve today's constraints but become dead weight as models improve.

We're not building smarter agents. We're building a better environment for agents to work in.

Quick Start

Single Agent

# Create and interact
agent-worker new alice -m anthropic/claude-sonnet-4-5
agent-worker send alice "Analyze this codebase"
agent-worker peek                    # View conversation

# Try without API keys
agent-worker new -b mock
agent-worker send a0 "Hello"

Multi-Agent Workflow

# review.yaml
agents:
  reviewer:
    model: anthropic/claude-sonnet-4-5
    system_prompt: |
      You are a code reviewer. When you find issues, @coder to fix them.

  coder:
    model: anthropic/claude-sonnet-4-5
    system_prompt: |
      You are a coder. Fix issues found by the reviewer.
      After fixing, @reviewer to verify.

setup:
  - shell: git diff HEAD~1
    as: diff

kickoff: |
  PR diff:
  ${{ diff }}

  @reviewer please review these changes.

agent-worker run review.yaml

That's it. The reviewer reads the diff, finds issues, @mentions the coder. The coder fixes them, @mentions back. They iterate until done.

CLI Reference

Agent Lifecycle

agent-worker new <name> [options]       # Create agent
agent-worker stop <target>              # Stop agent or workflow
agent-worker ls [target]                # List agents (--all for everything)
agent-worker status <target>            # Agent status

Communication

agent-worker send <target> <message>    # Send message
agent-worker send @review "Status?"     # Broadcast to workflow
agent-worker peek [target]              # View messages

Shared Documents

agent-worker doc read <target>
agent-worker doc write <target> --content "..."
agent-worker doc append <target> --file notes.txt

Scheduling

agent-worker schedule <target> set 30s --prompt "Check CI status"
agent-worker schedule <target> get
agent-worker schedule <target> clear

Workflows

agent-worker run <file> [--tag tag]           # Run once, exit when done
agent-worker start <file> [--tag tag]         # Keep alive after kickoff
agent-worker start <file> --background        # Daemon mode

Target Syntax

Agents live in workflows. Standalone agents go into a default global workflow.

alice                → alice@global:main     (standalone agent)
alice@review         → alice@review:main     (agent in "review" workflow)
alice@review:pr-123  → alice@review:pr-123   (specific instance)
@review              → review workflow       (broadcast)
@review:pr-123       → specific instance

Use --tag to run isolated instances of the same workflow:

agent-worker run review.yaml --tag pr-123
agent-worker run review.yaml --tag pr-456    # Completely independent

Backends

agent-worker new alice -m anthropic/claude-sonnet-4-5   # Vercel AI SDK (default)
agent-worker new alice -b claude                         # Claude CLI
agent-worker new alice -b cursor                         # Cursor Agent
agent-worker new alice -b codex                          # OpenAI Codex
agent-worker new alice -b mock                           # No API calls (testing)

| Capability | SDK | Claude CLI | Cursor | Codex | Mock | | -------------- | --- | ---------- | ---------- | ---------- | ---- | | Custom tools | Yes | Via MCP | No | No | Yes | | Streaming | Yes | Yes | Yes | Yes | No | | Token tracking | Yes | Partial | No | No | Yes | | Skills import | Yes | Filesystem | Filesystem | Filesystem | Yes |

Workflow YAML

Full Structure

name: my-workflow # Optional, defaults to filename

agents:
  alice:
    backend: sdk # sdk | claude | cursor | codex | mock
    model: anthropic/claude-sonnet-4-5 # Required for SDK backend
    system_prompt: You are Alice.
    system_prompt_file: ./prompts/alice.txt # Or load from file
    tools: [bash, read, write] # CLI backend tool names
    max_tokens: 8000
    max_steps: 20

context:
  provider: file
  config:
    dir: ./.workflow/${{ workflow.name }}/${{ workflow.tag }}/ # Ephemeral
    bind: ./data/ # Persistent

setup:
  - shell: git diff main...HEAD
    as: changes # Store output as variable
  - shell: echo "$PR_NUMBER"
    as: pr_num

kickoff: |
  ${{ changes }}
  @alice Review this. @bob Stand by.

Variables

• ${{ workflow.name }} — Workflow name
• ${{ workflow.tag }} — Instance tag
• ${{ env.VAR }} — Environment variable
• ${{ task_output }} — Setup task output (via as: field)

Coordination Patterns

Sequential — One agent finishes, @mentions the next:

kickoff: "@alice Start the analysis."
# Alice: "Done! @bob your turn to implement."

Parallel — Multiple agents work simultaneously:

kickoff: "@alice @bob @charlie All review this code."

Document-based — Agents collaborate through shared documents:

context:
  provider: file
  config:
    bind: ./results/ # Persistent across runs

SDK Usage

import { AgentWorker } from "agent-worker";

const agent = new AgentWorker({
  model: "anthropic/claude-sonnet-4-5",
  system: "You are a helpful assistant.",
  tools: [
    /* your tools */
  ],
});

// Request-response
const response = await agent.send("Hello");
console.log(response.content);

// Streaming
for await (const chunk of agent.sendStream("Tell me a story")) {
  process.stdout.write(chunk);
}

With Skills

import { AgentWorker, createSkillTool } from "agent-worker";
import { createBashTool } from "bash-tool";

// Discover skills and collect files for bash sandbox
const { skill, files, instructions } = await createSkillTool({
  skillsDirectory: ".agents/skills",
});

// Create bash tool with skill files available
const { tools } = await createBashTool({ files, extraInstructions: instructions });

const agent = new AgentWorker({
  model: "anthropic/claude-sonnet-4-5",
  system: "You are a helpful assistant.",
  tools: { skill, ...tools },
});

Programmatic Workflows

import { parseWorkflowFile, runWorkflowWithLoops } from "agent-worker";

const workflow = await parseWorkflowFile("review.yaml", { tag: "pr-123" });
const result = await runWorkflowWithLoops({
  workflow,
  workflowName: "review",
  tag: "pr-123",
  mode: "run",
});

console.log(result.success, result.duration);

Model Formats

agent-worker new -m anthropic/claude-sonnet-4-5    # Gateway format (recommended)
agent-worker new -m anthropic                       # Provider shorthand (uses frontier)
agent-worker new -m deepseek:deepseek-chat          # Direct provider format

Requirements

• Node.js 18+ or Bun
• API key for your chosen provider (e.g., ANTHROPIC_API_KEY)

Documentation

• ARCHITECTURE.md — System architecture (module structure, dependency graph)
• docs/architecture/OVERVIEW.md — Design overview (why each layer exists)
• docs/backends.md — Backend comparison
• docs/workflow/ — Workflow system design
• docs/architecture/AGENT-TOP-LEVEL.md — Agent-as-entity proposal
• docs/architecture/GUARD-AGENT.md — Guard agent proposal
• TEST-ARCHITECTURE.md — Testing strategy
• examples/ — Example workflows

License

MIT