# Agencycli Usage > Operate the agencycli tool — create agencies, teams, projects, and hire AI agents into working directories. - Skill: `chenhg5/agencycli-usage` (Agent Skill) - Install (CLI): `npx skillmds@latest add chenhg5/agencycli-usage` - Raw SKILL.md: https://api.skillmd.com/api/skills/chenhg5/agencycli-usage/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: chenhg5 (https://skillmd.com/u/chenhg5) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/chenhg5/agencycli-usage --- # 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`: ```bash agencycli --dir $AGENCY_DIR ``` --- ## Discover what exists ```bash 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 ```bash agencycli --dir $AGENCY_DIR task add \ --project --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) ```bash agencycli --dir $AGENCY_DIR task list --project --agent agencycli --dir $AGENCY_DIR task list --project --agent --status pending ``` ### Control tasks ```bash agencycli --dir $AGENCY_DIR task set [--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 agencycli --dir $AGENCY_DIR task retry # Emergency halt — cancel all pending (and optionally running) tasks agencycli --dir $AGENCY_DIR task stop-all \ --project --all-agents agencycli --dir $AGENCY_DIR task stop-all \ --project --agent --include-running ``` ### View token usage and cost ```bash # One agent agencycli --dir $AGENCY_DIR task tokens \ --project --agent # All agents in a project agencycli --dir $AGENCY_DIR task tokens \ --project --all-agents # Specific task agencycli --dir $AGENCY_DIR task tokens \ --project --agent --task ``` ### Task done / confirm-request (called by agents inside their prompt) ```bash # 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 --body 'approve'" \ --action-item "Hold: inbox reply --body 'hold '" ``` 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: `/` — e.g. `cc-connect/pm`, `cc-connect/dev-claude` ### Send a message ```bash # Human → agent agencycli --dir $AGENCY_DIR inbox send \ --to / \ --subject "Subject" \ --body "Body" # Agent → human agencycli --dir $AGENCY_DIR inbox send \ --from / --to human \ --subject "Subject" --body "Body" # Agent → agent agencycli --dir $AGENCY_DIR inbox send \ --from /pm --to /dev \ --subject "Extra context for task " \ --body "Details..." # Group send (repeat --to for multiple recipients) agencycli --dir $AGENCY_DIR inbox send \ --from /pm \ --to /dev --to /qa --to human \ --subject "Sprint kick-off" --body "..." ``` ### Read messages ```bash agencycli --dir $AGENCY_DIR inbox messages # human's unread agencycli --dir $AGENCY_DIR inbox messages --recipient /pm # agent's mailbox agencycli --dir $AGENCY_DIR inbox messages --from /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 ```bash agencycli --dir $AGENCY_DIR inbox reply --from
--body "..." agencycli --dir $AGENCY_DIR inbox fwd --to
--note "..." ``` ### Per-message status ```bash agencycli --dir $AGENCY_DIR inbox read agencycli --dir $AGENCY_DIR inbox archive agencycli --dir $AGENCY_DIR inbox delete agencycli --dir $AGENCY_DIR inbox rm # alias for delete ``` --- ## Heartbeat scheduler ```bash 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 --agent \ --enable --interval 30m \ --active-hours "09:00-20:00" \ --active-days weekdays # Set or update the wakeup routine (runs when task queue is empty) agencycli --dir $AGENCY_DIR scheduler heartbeat \ --project --agent \ --wakeup-prompt-file projects//agents//wakeup.md ``` When the scheduler wakes an agent: 1. If **pending tasks** exist → runs the highest-priority task 2. If queue is **empty** and a wakeup routine is set → runs `wakeup.md` as a synthetic task 3. Any **unread messages** for the agent are auto-prepended to the prompt --- ## Cron jobs ```bash agencycli --dir $AGENCY_DIR cron add \ --project --agent \ --title "Weekly backlog review" \ --schedule "0 9 * * 1" \ --prompt "Review the backlog and reprioritise for the week..." agencycli --dir $AGENCY_DIR cron list --project --agent agencycli --dir $AGENCY_DIR cron disable --project --agent ``` --- ## OKRs (Objectives and Key Results) OKRs support three scope levels: **agency** (global), **project**, and **agent**. Child OKRs can link to a parent via `--parent` for hierarchical alignment. ```bash # List — filter by scope and/or quarter agencycli --dir $AGENCY_DIR okr list agencycli --dir $AGENCY_DIR okr list --quarter 2026-Q2 agencycli --dir $AGENCY_DIR okr list --scope project --scope-ref my-service agencycli --dir $AGENCY_DIR okr list --scope agent --scope-ref my-service/dev # Create — specify scope level agencycli --dir $AGENCY_DIR okr create \ --objective "Ship v2.0" --owner human --quarter 2026-Q2 agencycli --dir $AGENCY_DIR okr create \ --objective "Reduce latency" --scope project --scope-ref my-service agencycli --dir $AGENCY_DIR okr create \ --objective "Improve autonomy" --scope agent --scope-ref my-service/dev \ --parent --description "Detailed description" # Show / Update / Delete agencycli --dir $AGENCY_DIR okr show agencycli --dir $AGENCY_DIR okr update --status at_risk agencycli --dir $AGENCY_DIR okr update --scope project --scope-ref my-service agencycli --dir $AGENCY_DIR okr delete # Key Results agencycli --dir $AGENCY_DIR okr kr add \ --okr --description "Reduce p95 latency" --target 200 --unit ms agencycli --dir $AGENCY_DIR okr kr update \ --okr --kr --current 150 # Review notes agencycli --dir $AGENCY_DIR okr review \ --okr --note "Good progress this week" --author human ``` OKR scope: agency (default), project, agent. Status: on_track, in_progress, at_risk, off_track, achieved. Progress is auto-calculated from Key Results. When completing a task, check if it advances any Key Result and update accordingly. --- ## Milestones ```bash agencycli --dir $AGENCY_DIR milestone list --project agencycli --dir $AGENCY_DIR milestone create --project \ --title "Beta Release" --due-date 2026-05-01 --owner human \ --criteria "All P0 bugs fixed" --criteria "Docs updated" agencycli --dir $AGENCY_DIR milestone show --project agencycli --dir $AGENCY_DIR milestone update --project \ --progress 75 --status in_progress agencycli --dir $AGENCY_DIR milestone delete --project ``` Milestone status: planned, in_progress, completed, cancelled. --- ## Context sync ```bash agencycli --dir $AGENCY_DIR sync # all agents with changed context agencycli --dir $AGENCY_DIR sync --project # one project agencycli --dir $AGENCY_DIR sync --project --name # one agent agencycli --dir $AGENCY_DIR sync --force # force regenerate everything ``` --- ## Context Inheritance Every hired agent automatically receives context in this order: 1. **agency-prompt.md** — global rules, values 2. **teams/\/prompt.md** — team-specific standards 3. **teams/\/roles/\/prompt.md** — role responsibilities 4. **projects/\/prompt.md** — project background and tech stack 5. **skills** — all skills listed in the team's `team.yaml` and role's `role.yaml`