agencycli

Category: Tools & Productivity | Uploader: chenhg5 | Downloads: 0 | Version: v1.0（Latest）

Manage AI agent teams with agencycli — a CLI tool for organising AI agents (Claude Code, Codex, Gemini, Cursor, etc.) into hierarchical teams (Agency → Team → Role → Project → Agent). Key capabilities: create agencies and teams, hire agents with merged context layers, assign and run tasks with priority queues, manage autonomous playbooks (wakeup.md), send async inbox messages between human and agents, configure heartbeat schedules and cron jobs, run agents inside Docker sandboxes, forward/confirm tasks via inbox, manage templates, and more. Use this skill whenever you need to: create or manage an agencycli workspace, hire/fire/sync agents, add/run/cancel tasks, check inbox confirmations, send messages, configure heartbeats or crons, start the scheduler, or work with agency templates.

Changelog: Source: GitHub https://github.com/chenhg5/agencycli

Directory Structure

Current level: Root

📁 cmd/
- 📁 agencycli/
  - 📄 create.go 13.7 KB
  - 📄 hire.go 10.4 KB
  - 📄 inbox.go 30.6 KB
  - 📄 list.go 3.6 KB
  - 📄 root.go 2.3 KB
  - 📄 run.go 6.7 KB
  - 📄 session.go 3.7 KB
  - 📄 show.go 5.3 KB
  - 📄 sync.go 4.0 KB
  - 📄 task.go 31.5 KB
📁 docker/
- 📁 sandbox-claudecode/
  - 📄 Dockerfile 6.4 KB
- 📁 sandbox-codex/
  - 📄 Dockerfile 3.8 KB
- 📁 sandbox-gemini/
  - 📄 Dockerfile 3.7 KB
- 📁 sandbox-generic/
  - 📄 Dockerfile 1.5 KB
- 📄 README.md 4.7 KB
📁 docs/
- 📄 banner.svg 7.0 KB
- 📄 commands.md 9.2 KB
- 📄 roadmap.md 8.4 KB
- 📄 sandbox-design.md 13.0 KB
- 📄 workflow-design.md 29.9 KB
- 📄 workspace-layout.md 4.0 KB
📁 internal/
- 📁 ctxbuild/
  - 📄 builder.go 5.3 KB
  - 📄 chain.go 757 B
  - 📄 types.go 2.0 KB
- 📁 entity/
  - 📄 types.go 22.1 KB
- 📁 formatter/
  - 📄 claudecode.go 3.9 KB
  - 📄 codex.go 2.4 KB
  - 📄 cursor.go 3.2 KB
  - 📄 formatter.go 1.6 KB
  - 📄 gemini.go 2.5 KB
  - 📄 generic.go 1.7 KB
  - 📄 singlefile.go 2.1 KB
  - 📄 skillfiles.go 2.1 KB
- 📁 runner/
  - 📄 model.go 8.2 KB
  - 📄 runner.go 16.3 KB
- 📁 sandbox/
  - 📄 docker.go 13.3 KB
- 📁 scaffold/
  - 📄 scaffold.go 4.6 KB
  - 📄 templates.go 3.0 KB
- 📁 store/
  - 📄 fs.go 14.5 KB
  - 📄 store.go 4.6 KB
- 📁 taskstore/
  - 📄 fs.go 17.6 KB
  - 📄 store.go 6.7 KB
- 📁 template/
  - 📄 template.go 9.4 KB
- 📁 workspace/
  - 📄 workspace.go 1.5 KB
📁 npm/
- 📄 install.js 6.5 KB
- 📄 package.json 836 B
- 📄 run.js 2.1 KB
📁 skills/
- 📁 agency-messaging/
  - 📄 SKILL.md 5.2 KB
- 📁 agencycli-usage/
  - 📄 SKILL.md 7.7 KB
📄 .gitignore 752 B
📄 CHANGELOG.md 3.7 KB
📄 go.mod 274 B
📄 go.sum 1.3 KB
📄 INSTALL.md 19.7 KB
📄 Makefile 2.9 KB
📄 README.md 9.4 KB
📄 README.zh-CN.md 9.4 KB
📄 SKILL.md 14.4 KB

SKILL.md

---
name: agencycli
description: "Manage AI agent teams with agencycli — a CLI tool for organising AI agents (Claude Code, Codex, Gemini, Cursor, etc.) into hierarchical teams (Agency → Team → Role → Project → Agent). Key capabilities: create agencies and teams, hire agents with merged context layers, assign and run tasks with priority queues, manage autonomous playbooks (wakeup.md), send async inbox messages between human and agents, configure heartbeat schedules and cron jobs, run agents inside Docker sandboxes, forward/confirm tasks via inbox, manage templates, and more. Use this skill whenever you need to: create or manage an agencycli workspace, hire/fire/sync agents, add/run/cancel tasks, check inbox confirmations, send messages, configure heartbeats or crons, start the scheduler, or work with agency templates."
---

# agencycli

`agencycli` is a CLI tool for organising AI agents into hierarchical teams (Agency → Team → Role → Project → Agent). Each agent = Model + Context + Skills. The binary is at `/usr/local/bin/agencycli` or in `$PATH`.

## Installation

```bash
# via npm (recommended)
npm install -g @agencycli/agentctl

# via install script
curl -fsSL https://raw.githubusercontent.com/chenhg5/agencycli/main/scripts/install.sh | sh

# verify
agencycli version
```

## Core concepts

| Concept | What it is |
|---------|-----------|
| **Agency** | The root workspace (`agency-prompt.md`, `.agencycli/agency.yaml`) |
| **Team** | A group with a shared prompt (`teams/<team>/prompt.md`) |
| **Role** | A position within a team — has its own prompt + bound skills + workspace setup |
| **Project** | A work unit with its own prompt, linked to a code repo |
| **Agent** | A hired instance: model + merged context from all layers |
| **Skill** | Reusable instructions copied into agent workspace on hire |
| **Task** | A unit of work with status, priority (0=critical…3=low), prompt, and optional heartbeat/cron |
| **Playbook** | `wakeup.md` — the autonomous routine an agent runs when its task queue is empty |
| **Message** | Async non-blocking communication between any two participants (human or agent) |

Context is merged in this order (later layers override): **Agency → Team → Role → Project → Agent**

---

## Quick start — blank agency

```bash
# 1. Create agency
agencycli create agency --name "MyAgency" --desc "My first agency"
cd MyAgency

# 2. Create team + role
agencycli create team --name "engineering" --desc "Software engineers"
agencycli create role --team "engineering" --name "developer"

# 3. Create project
agencycli create project --name "my-service" --repo "/path/to/repo"

# 4. Hire an agent
agencycli hire --project my-service --team engineering --role developer \
  --model claudecode --name dev --sandbox docker

# 5. Add and run a task
agencycli task add --project my-service --agent dev \
  --title "Implement feature X" --prompt "..."
agencycli run --project my-service --agent dev
```

## Quick start — from a template (recommended)

```bash
# 1. Create agency from template
agencycli create agency --name "MyAgency" \
  --template https://example.com/tech-agency.tar.gz
cd MyAgency

# 2. List available project blueprints
agencycli project blueprints

# 3. Create a project from a blueprint
agencycli create project --name "my-service" --blueprint default

# 4. Review and apply (hires agents, configures heartbeats, installs wakeup.md playbooks)
agencycli project show  --project my-service
agencycli project apply --project my-service

# 5. Start the scheduler — agents wake up on schedule and run their playbooks when idle
agencycli scheduler start

# 6. Monitor
agencycli inbox list          # task confirmations awaiting your decision
agencycli inbox messages      # async messages from agents
agencycli task list --project my-service --agent pm
```

---

## Global flag

All commands support `--dir <workspace>` to point to the agency root when not running from inside it:

```bash
agencycli --dir /root/code/MyAgency task list --project my-service --agent dev
```

---

## Command reference

### Workspace setup

```bash
agencycli create agency  --name "Name" [--desc "..."] [--template file.tar.gz|dir|URL]
agencycli create team    --name "engineering" [--desc "..."]
agencycli create role    --team "engineering" --name "developer" [--desc "..."]
agencycli create project --name "my-service"  --repo "/path/to/repo" [--desc "..."]
agencycli create project --name "my-service"  --blueprint default   # from blueprint
```

### Hiring agents

```bash
agencycli hire --project <proj> --team <team> [--role <role>] \
               --model <model> --name <name> [--sandbox docker]
# Supported models: claudecode  codex  gemini  cursor  generic-cli

agencycli sync --project <proj> --agent <name>   # re-sync after editing prompts/skills
agencycli sync --project <proj>                  # sync all agents in project
agencycli fire --project <proj> --agent <name>          # soft delete → .fired/
agencycli fire --project <proj> --agent <name> --force  # hard delete
```

### Project lifecycle

```bash
agencycli project blueprints
agencycli project show  --project P
agencycli project apply --project P             # hire agents + configure heartbeats + install playbooks
agencycli project apply --project P --dry-run
agencycli project apply --project P --force
```

**project-blueprints/default.yaml** example:
```yaml
name: "{{PROJECT_NAME}}"
description: "..."
agents:
  - name: dev
    role: developer
    team: engineering
    model: claudecode
    sandbox: true
    playbook: dev.md        # installed as wakeup.md by project apply
    heartbeat:
      enabled: true
      interval: 30m
      active_hours: "09:00-20:00"
      active_days: weekdays

  - name: pm
    role: product-manager
    team: product
    model: claudecode
    playbook: pm.md
    heartbeat:
      enabled: true
      interval: 30m
```

### Tasks

```bash
agencycli task add    --project P --agent A --title "T" --prompt "..." \
                      [--type feature|bug|chore] [--priority 0-3]
agencycli task list   --project P --agent A [--status pending] [--archived]
agencycli task show   <task-id>
agencycli task cancel <task-id>
agencycli task retry  <task-id>

# Emergency halt — cancel pending (and optionally running) tasks
agencycli task stop-all --project P --all-agents
agencycli task stop-all --project P --agent A --include-running

# View token usage and cost
agencycli task tokens --project P --agent A
agencycli task tokens --project P --all-agents
agencycli task tokens --project P --agent A --task <task-id>

# Called by agent inside its prompt:
agencycli task done --id <task-id> --status success --summary "brief description"
agencycli task done --id <task-id> --status failed  --error "reason"

# Pause and wait for human confirmation (blocks until human responds):
agencycli task confirm-request --id <task-id> \
  --summary "PR #42 ready for review" \
  --action-item "Open the PR and check the diff" \
  --action-item "Reply: merge / hold <reason>"
```

Task priority: 0=critical, 1=high, 2=normal (default), 3=low. The scheduler always picks the highest-priority pending task first. After `confirm-request`, the human's reply is available as `$CONFIRMATION_REPLY`.

### Running agents

```bash
agencycli run  --project P --agent A              # pick next pending task
agencycli run  --project P --agent A --task <id>  # run specific task
agencycli exec --project P --agent A --prompt "..." # one-off prompt (no task queue)
```

### Inbox — task confirmations (blocking)

Agents call `task confirm-request` to pause a task and wait for the human's decision.

```bash
agencycli inbox list
agencycli inbox show    <task-id>
agencycli inbox confirm <task-id> --message "approved, go ahead"
agencycli inbox reject  <task-id> --reason "needs rework"
agencycli inbox comment <task-id> --message "check the auth module first"
agencycli inbox forward <task-id> --to <project>/<agent> --note "please re-check"
```

### Inbox — async messages (non-blocking)

Any participant (human or agent) can send messages to any other. Recipients read them on their next wakeup — the scheduler auto-injects unread messages at the top of the wakeup prompt.

**Address format:** `human` or `project/agent` (e.g. `cc-connect/pm`, `cc-connect/dev-claude`)

```bash
# Send
agencycli inbox send --to cc-connect/pm --subject "Prioritise #55" --body "..."
agencycli inbox send --from cc-connect/pm --to human --subject "Update" --body "..."
agencycli inbox send --from cc-connect/pm --to cc-connect/dev-claude \
  --subject "Extra context" --body "..."

# Read (human's mailbox by default)
agencycli inbox messages
agencycli inbox messages --recipient cc-connect/pm
agencycli inbox messages --recipient cc-connect/pm --from human      # filter by sender
agencycli inbox messages --from cc-connect/pm                        # human inbox, only from pm
agencycli inbox messages --all          # include already-read
agencycli inbox messages --mark-read    # mark as read after listing

# Reply
agencycli inbox reply <msg-id> --from cc-connect/pm --body "Acknowledged."
```

### Daemon (heartbeat + wakeup routines)

```bash
# Configure heartbeat
agencycli scheduler heartbeat --project P --agent A \
  --enable --interval 30m \
  --active-hours "09:00-18:00" \
  --active-days  "weekdays"

# Set wakeup routine (runs as synthetic task when queue is empty)
agencycli scheduler heartbeat --project P --agent A \
  --wakeup-prompt-file /path/to/wakeup.md

# Start scheduler (aliases: sched, s)
agencycli scheduler start
agencycli scheduler stop
agencycli scheduler status

# Cron jobs
agencycli cron add     --project P --agent A \
  --title "Daily standup" --schedule "0 9 * * 1-5" --prompt "..."
agencycli cron list    --project P --agent A
agencycli cron delete  <cron-id>  --project P --agent A
agencycli cron enable  <cron-id>  --project P --agent A
agencycli cron disable <cron-id>  --project P --agent A
```

Each heartbeat cycle: if pending tasks exist → run highest-priority task; if queue is empty and `wakeup.md` is set → run wakeup routine. Unread messages are always prepended automatically.

### Agent playbooks

A playbook (`wakeup.md`) defines what an agent does when its task queue is empty. Store in `agent-playbooks/` and reference from `project.yaml` via `playbook:`.

`project apply` copies `agent-playbooks/<playbook>` → `agents/<name>/wakeup.md` and sets `wakeup_prompt: "@wakeup.md"` in `heartbeat.yaml`.

Typical wakeup.md patterns:
- Check injected unread messages (auto-prepended — no `inbox messages` call needed)
- Reply with: `agencycli inbox reply <msg-id> --from project/agent --body "..."`
- Send async update: `agencycli inbox send --from project/agent --to human --subject "..." --body "..."`
- Pause for human decision: `agencycli task confirm-request --id $TASK_ID --summary "..." --action-item "..."`
- Complete: `agencycli task done --id $TASK_ID --status success --summary "..."`

### Skills

```bash
agencycli role skill add    --team <t> --role <r> --skill <s>
agencycli role skill remove --team <t> --role <r> --skill <s>
agencycli role list         --team <t>
agencycli list skills
```

### Templates

A template bundles: `agency-prompt.md`, `teams/`, `skills/`, `agent-playbooks/`, `project-blueprints/`.

```bash
agencycli template pack --output my-agency.tar.gz \
  --name "tech-project" --version "1.0.0" \
  --author "Alice" --email "alice@example.com" \
  --description "Standard software engineering agency" \
  --keywords "engineering,software"

agencycli template info my-agency.tar.gz
agencycli template info my-agency.tar.gz --json

agencycli create agency --name "My Agency" --template my-agency.tar.gz
agencycli create agency --name "My Agency" --template https://example.com/tpl.tar.gz
```

### Sessions & misc

```bash
agencycli session show  --project P --agent A
agencycli session clear --project P --agent A
agencycli list teams | projects | agents | skills
agencycli show team engineering
agencycli show project my-api
agencycli show agent my-api dev [--raw]
agencycli version
```

---

## Agent context file locations

| Model | Context file | Skills dir |
|-------|-------------|------------|
| claudecode | `CLAUDE.md` | `.claude/skills/` |
| codex | `AGENTS.md` | (inlined) |
| gemini | `GEMINI.md` | `.gemini/skills/` |
| cursor | `.cursorrules` | `.cursor/rules/` |
| generic-cli | `context.md` | — |

---

## Agency directory structure

```
<AgencyName>/
  .agencycli/
    agency.yaml            ← workspace marker
    inbox.yaml             ← human task-confirmation inbox
    inbox.md               ← human-readable inbox summary
    messages.yaml          ← async messages for the human
  agency-prompt.md
  teams/
    <team>/
      team.yaml
      prompt.md
      roles/<role>/
        role.yaml
        prompt.md
  skills/
    <skill>/
      skill.yaml
      prompt.md
      [other files, e.g. scripts]
  agent-playbooks/         ← wakeup.md templates, distributed with agency template
    pm.md
    qa-reviewer.md
  project-blueprints/
    default.yaml
  projects/
    <project>/
      project.yaml         ← agents + heartbeats + crons + playbooks (declarative)
      prompt.md
      agents/
        <agent>/
          CLAUDE.md           ← merged context (claudecode)
          .claude/skills/     ← deployed skill files
          wakeup.md           ← autonomous routine (installed by project apply)
          heartbeat.yaml      ← set by project apply or scheduler heartbeat
          crons.yaml          ← set by project apply or cron add
          tasks.yaml          ← active tasks
          tasks_archive.yaml  ← completed tasks
          messages.yaml       ← async messages for this agent
          runs/               ← execution logs
```

---

## Tips for agents

1. Always use `--dir <workspace>` if you are not inside the agency directory.
2. Get your own task ID from `$TASK_ID` (set by the scheduler when running a task).
3. When you need human approval **and must wait**: use `task confirm-request` — do NOT call `task done`. The task resumes when the human confirms; their reply is in `$CONFIRMATION_REPLY`.
4. When you want to notify someone **without blocking**: use `inbox send --from <your-address> --to <recipient> --body "..."`.
5. Unread messages are auto-injected at the top of your wakeup prompt — no need to call `inbox messages` yourself.
6. Use `inbox reply <msg-id> --from <your-address>` to reply to a message.
7. Use `agencycli list agents` to discover all agents and their `project/agent` addresses.
8. Use `agencycli exec --project P --agent A --prompt "..."` for quick one-off tests without adding a task.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

agencycli

Directory Structure

SKILL.md

Report

Notice