/agencycli-usage

name: agencycli-usage
description: Operate the agencycli tool — create agencies, teams, projects, and hire AI agents into working directories.

Skill: agencycli Usage

`agencycli` is the CLI tool that builds and manages this agency. Use it to manage teams, projects, agents, tasks, and inter-agent communication.

Workspace

The current agency workspace is at: `$AGENCY_DIR`

All commands auto-discover the workspace when run from inside it, or use `--dir`:

agencycli --dir $AGENCY_DIR <command>

---

Discover what exists

agencycli --dir $AGENCY_DIR list teams      # all teams
agencycli --dir $AGENCY_DIR list projects   # all projects
agencycli --dir $AGENCY_DIR list agents     # all agents across all projects
agencycli --dir $AGENCY_DIR list skills     # available skills

agencycli --dir $AGENCY_DIR show team engineering
agencycli --dir $AGENCY_DIR show project cc-connect
agencycli --dir $AGENCY_DIR show agent cc-connect pm
agencycli --dir $AGENCY_DIR show agent cc-connect pm --raw  # full merged context

---

Tasks

Add a task for an agent

agencycli --dir $AGENCY_DIR task add \
  --project <project> --agent <agent> \
  --title "Task title" \
  --prompt "Detailed instructions..." \
  --priority <0-3>   # 0=critical 1=high 2=normal(default) 3=low

View the task queue (sorted by priority)

agencycli --dir $AGENCY_DIR task list --project <project> --agent <agent>
agencycli --dir $AGENCY_DIR task list --project <project> --agent <agent> --status pending

Control tasks

agencycli --dir $AGENCY_DIR task set <task-id> [--title T] [--status S] [--priority N] \
  [--due-date YYYY-MM-DD] [--estimate-duration 30m] [--parent ID] [--label L]...
agencycli --dir $AGENCY_DIR task stats [--since today] [--project P] [--agent A] [--assignee X] \
  [--label L] [--by agent|assignee|label|label:value|label:category] [--detail] [--format json]
agencycli --dir $AGENCY_DIR task cancel <task-id>
agencycli --dir $AGENCY_DIR task retry  <task-id>

# Emergency halt — cancel all pending (and optionally running) tasks
agencycli --dir $AGENCY_DIR task stop-all \
  --project <project> --all-agents
agencycli --dir $AGENCY_DIR task stop-all \
  --project <project> --agent <agent> --include-running

View token usage and cost

# One agent
agencycli --dir $AGENCY_DIR task tokens \
  --project <project> --agent <agent>

# All agents in a project
agencycli --dir $AGENCY_DIR task tokens \
  --project <project> --all-agents

# Specific task
agencycli --dir $AGENCY_DIR task tokens \
  --project <project> --agent <agent> --task <task-id>

Task done / confirm-request (called by agents inside their prompt)

# Report completion
agencycli --dir $AGENCY_DIR task done \
  --id $TASK_ID --status success --summary "Brief description of what was done"

# Report failure
agencycli --dir $AGENCY_DIR task done \
  --id $TASK_ID --status failed --error "reason"

# Request human input before proceeding (non-blocking)
agencycli --dir $AGENCY_DIR task confirm-request \
  --id $TASK_ID \
  --summary "PR #42 ready, awaiting merge approval" \
  --action-item "Review: gh pr view 42 --repo org/repo" \
  --action-item "Approve: inbox reply <msg-id> --body 'approve'" \
  --action-item "Hold: inbox reply <msg-id> --body 'hold <reason>'"

After `confirm-request`, the task is archived (non-blocking). The human replies via `inbox reply` and the agent continues on their next wakeup.

---

Inbox — async messages (non-blocking)

Any participant (human or agent) can send non-blocking messages to any other participant. The recipient reads them on their next wakeup — the scheduler automatically injects unread messages at the top of the wakeup prompt.

Participant address format

• Human: `human`
• Agent: `<project>/<agent>` — e.g. `cc-connect/pm`, `cc-connect/dev-claude`

Send a message

# Human → agent
agencycli --dir $AGENCY_DIR inbox send \
  --to <project>/<agent> \
  --subject "Subject" \
  --body "Body"

# Agent → human
agencycli --dir $AGENCY_DIR inbox send \
  --from <project>/<agent> --to human \
  --subject "Subject" --body "Body"

# Agent → agent
agencycli --dir $AGENCY_DIR inbox send \
  --from <project>/pm --to <project>/dev \
  --subject "Extra context for task <id>" \
  --body "Details..."

# Group send (repeat --to for multiple recipients)
agencycli --dir $AGENCY_DIR inbox send \
  --from <project>/pm \
  --to <project>/dev --to <project>/qa --to human \
  --subject "Sprint kick-off" --body "..."

Read messages

agencycli --dir $AGENCY_DIR inbox messages                          # human's unread
agencycli --dir $AGENCY_DIR inbox messages --recipient <project>/pm # agent's mailbox
agencycli --dir $AGENCY_DIR inbox messages --from <project>/qa      # filter by sender
agencycli --dir $AGENCY_DIR inbox messages --all                    # include read
agencycli --dir $AGENCY_DIR inbox messages --archived               # archived only
agencycli --dir $AGENCY_DIR inbox messages --mark-read              # mark all read

Reply / Forward

agencycli --dir $AGENCY_DIR inbox reply <msg-id> --from <address> --body "..."
agencycli --dir $AGENCY_DIR inbox fwd   <msg-id> --to <address> --note "..."

Per-message status

agencycli --dir $AGENCY_DIR inbox read    <msg-id>
agencycli --dir $AGENCY_DIR inbox archive <msg-id>
agencycli --dir $AGENCY_DIR inbox delete  <msg-id>
agencycli --dir $AGENCY_DIR inbox rm      <msg-id>   # alias for delete

---

Heartbeat scheduler

agencycli --dir $AGENCY_DIR scheduler start
agencycli --dir $AGENCY_DIR scheduler stop
agencycli --dir $AGENCY_DIR scheduler status

# Configure an agent's heartbeat
agencycli --dir $AGENCY_DIR scheduler heartbeat \
  --project <project> --agent <agent> \
  --enable --interval 30m \
  --active-hours "09:00-20:00" \
  --active-days weekdays

# Set or update the wakeup routine (runs when task queue is empt