Agent skill

Agent of Empires Session Manager

by agent-of-empires in agent-of-empires/agent-of-empires

Starts, monitors and organizes coding agent sessions that run in tmux through the aoe command, including groups, profiles and worktree-based parallel work.

MITAuto-check passedAgent Workflows

Install Agent of Empires Session Manager

skills CLI
$ npx skills add agent-of-empires/agent-of-empires --skill aoe -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install agent-of-empires/agent-of-empires aoe --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/agent-of-empires/agent-of-empires.git skills-src && mkdir -p .claude/skills && cp -r skills-src/contrib/openclaw-skill .claude/skills/aoe && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
aoe
GitHub stars
3.3k
Token cost
~2.1k tokens
SKILL.md length
666 words
Files
1
Skills in repo
2
Repo updated
First seen
Licence
MIT

At a glance

Starts, monitors and organizes coding agent sessions that run in tmux through the aoe command, including groups, profiles and worktree-based parallel work.

  • Launching several coding agents on different project directories
  • SKILL.md covers When to use this skill, Core concepts, Command reference and Workflow patterns
  • Calls jq
  • Checking which agent sessions are running, waiting or idle

What it does

The skill teaches the agent to use the aoe CLI, rather than raw tmux commands, to run coding agents such as Claude Code, Codex and OpenCode. Each session has an ID, title, tool and project path; sessions can be placed in nested groups like backend/api, kept in separate profiles, and reported with a status such as running, waiting, idle, stopped, error, starting or unknown.

Commands covered include adding a session for a directory with a title, listing sessions as text or JSON, checking status, capturing a session's output for review, and sending input to a session. The JSON listing documents session states (live, archived, trashed) and warns that it carries no live status, so status or capture commands are needed for that. It is not meant for tmux window or pane management that has nothing to do with coding agents.

When your agent uses it

  • Launching several coding agents on different project directories
  • Checking which agent sessions are running, waiting or idle
  • Capturing a session's output to review what an agent did
  • Setting up parallel worktree-based development with separate agents

Example prompts

  • “Start an agent session for the api folder titled payments refactor, then list all sessions.”
  • “Which of my agent sessions are waiting for input right now?”
  • “Put my frontend sessions into a group called web/ui and show their status.”

Requirements

  • The aoe (Agent of Empires) CLI
  • tmux

What it can do on your machine

Read from SKILL.md and the folder at commit 8e70782. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • jq

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Agent of Empires Session Manager loads about 2.1k tokens when it runs. Until then it costs about 16 tokens; SKILL.md has 666 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~16
When it runs · the whole SKILL.md, loaded when a task matches
~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from agent-of-empires/agent-of-empires at commit 8e70782, republished under its MIT licence (© agent-of-empires). 666 words, ~2,085 tokens.

Download SKILL.mdSave it as .claude/skills/aoe/SKILL.md (or your agent's skills folder).
name
aoe
description
Manage AI coding agent sessions via Agent of Empires (aoe)

Agent of Empires (aoe) Skill

Use aoe to create, manage, and monitor AI coding agent sessions (Claude Code, Codex, OpenCode, etc.) in tmux. Prefer aoe over raw tmux commands for agent management.

When to use this skill

  • Launching one or more AI coding agents on project directories
  • Monitoring agent progress (waiting vs running vs idle)
  • Capturing agent output for review
  • Organizing agents into groups or profiles
  • Setting up parallel worktree-based development

Do NOT use this skill for general tmux window/pane management unrelated to coding agents.

Core concepts

  • Session: An agent process running in a tmux session. Each session has an ID, title, tool (e.g. claude), and project path.
  • Group: A named folder for organizing sessions (supports nesting with /, e.g. backend/api).
  • Profile: A separate workspace with its own sessions and config. Use -p <name> globally or set AGENT_OF_EMPIRES_PROFILE.
  • Status: One of running, waiting, idle, stopped, error, starting, unknown.

Command reference

Adding sessions
bash
# Add a session for the current directory
aoe add . -t "my feature"

# Add with group, launch immediately
aoe add /path/to/repo -t "API work" -g backend -l

# Add with specific tool
aoe add . -t "codex session" -c codex

# Add in a git worktree (parallel branch)
aoe add . -t "fix-123" -w fix/issue-123 -l

# Add in Docker sandbox
aoe add . -t "sandboxed" -s -l

# Add as sub-session of another
aoe add . -t "sub task" -P <parent-id>

# Enable YOLO mode (skip permission prompts)
aoe add . -t "yolo" -y -l
Listing sessions
bash
# Human-readable list
aoe list

# JSON output for parsing
aoe list --json

# List across all profiles
aoe list --all

# Skip trashed and archived rows (default is every persisted session)
aoe list --json --state=live

JSON output shape (aoe list --json):

json
[
  {
    "id": "a1b2c3d4-...",
    "title": "my feature",
    "path": "/home/user/project",
    "group": "backend",
    "tool": "claude",
    "command": "claude",
    "profile": "default",
    "state": "live",
    "created_at": "2025-01-01T00:00:00Z",
    "workspace_repos": []
  }
]

command is omitted when empty; worktree appears only for worktree-backed sessions. state is live, archived, or trashed; trashed_at and archived_at are set independently, and trashing leaves archived_at alone, so a session archived and then trashed carries both keys and reports trashed. Neither timestamp is durable, but they do not clear alike: archived_at is cleared by aoe session unarchive, by aoe session favorite, and by anything that wakes the session (aoe send, and aoe session restart when it sends its wake message), while trashed_at is cleared only by aoe session restore. Key off state rather than caching a timestamp. A trashed session stays in the listing and keeps its title, so check state before treating a row as a live session. list --json does not include live status; use aoe status --json or aoe session capture --json for that.

snoozed_until and pinned_at round out the four state timestamps the REST API exposes: pinned_at appears whenever the session is pinned for the web sidebar, while snoozed_until appears only while the snooze is still active (the API's own gate), so an expired deadline omits the key instead of advertising a snooze that already ended. Both are independent of state, and neither key appears on a row carrying neither marker. snoozed_until also clears readily, more often than its siblings: waking the session (aoe send), archiving, favoriting, unsnoozing, or pinning all remove it on the next read, so treat a missing key as no active snooze rather than a listing gap.

Show full SKILL.md (261 more words)Show less
Session lifecycle
bash
aoe session start <id-or-title>
aoe session stop <id-or-title>
aoe session restart <id-or-title>
aoe session attach <id-or-title>   # interactive attach
Inspecting sessions
bash
# Show session metadata
aoe session show <id-or-title> --json

# Capture tmux pane content (key for monitoring)
aoe session capture <id-or-title> --json
aoe session capture <id-or-title> -n 100 --strip-ansi
aoe session capture <id-or-title>   # plain text, good for piping

# Quick status summary
aoe status --json
aoe status -q   # just the waiting count (for scripting)

JSON output shape (aoe session capture --json):

json
{
  "id": "a1b2c3d4-...",
  "title": "my feature",
  "status": "waiting",
  "tool": "claude",
  "content": "... pane text ...",
  "lines": 50
}

JSON output shape (aoe session show --json):

json
{
  "id": "a1b2c3d4-...",
  "title": "my feature",
  "path": "/home/user/project",
  "group": "backend",
  "tool": "claude",
  "command": "claude",
  "status": "running",
  "state": "live",
  "profile": "default"
}

state is live, archived, or trashed, the same vocabulary aoe list --json uses; trashed_at and archived_at are set independently, and trashing deliberately leaves archived_at alone, so a session archived and then trashed carries both keys and reports trashed. Neither timestamp is durable, and they do not clear alike: archived_at is cleared by aoe session unarchive, by aoe session favorite, and by anything that wakes the session, which means aoe send and aoe session restart when it sends its wake message (with session.restart_wake_message set to the empty string it does not send one, and the archive survives the restart). trashed_at is cleared only by aoe session restore. Read the current state rather than caching a timestamp; status is the pane's live status and does not carry it, since an archived session can still be running.

The same two keys apply here as in aoe list --json: pinned_at whenever the session is pinned for the web sidebar, snoozed_until only while the snooze is still active.

JSON output shape (aoe status --json):

json
{
  "waiting": 1,
  "running": 2,
  "idle": 1,
  "stopped": 1,
  "error": 0,
  "total": 5
}
Auto-detection (inside a tmux pane)

When called from within an aoe-managed tmux session, identifier can be omitted:

bash
aoe session show          # auto-detects current session
aoe session capture       # auto-detects current session
aoe session current --json
Renaming and organizing
bash
aoe session rename <id> -t "new title"
aoe session rename <id> -g "new/group"

aoe group create mygroup
aoe group move <id-or-title> mygroup
aoe group list --json
aoe group delete mygroup --force
Profiles
bash
aoe profile list
aoe profile create staging
aoe profile delete staging
aoe profile default staging   # set default
aoe -p staging list            # use inline
Worktrees
bash
aoe worktree list
aoe worktree info <id-or-title>
aoe worktree cleanup -f
Removing sessions
bash
aoe remove <id-or-title>
aoe remove <id-or-title> --delete-worktree --force

Workflow patterns

Single agent
bash
aoe add /path/to/repo -t "feature X" -l
# ... wait ...
aoe session capture "feature X" --json
Parallel worktree agents
bash
aoe add . -t "issue-100" -w fix/issue-100 -l
aoe add . -t "issue-101" -w fix/issue-101 -l
aoe add . -t "issue-102" -w fix/issue-102 -l
aoe status --json   # check all at once
Monitoring loop

Poll all sessions until none are running:

bash
while true; do
  status=$(aoe status --json)
  waiting=$(echo "$status" | jq '.waiting')
  running=$(echo "$status" | jq '.running')
  if [ "$running" -eq 0 ] && [ "$waiting" -eq 0 ]; then
    echo "All agents finished"
    break
  fi
  echo "Running: $running, Waiting: $waiting"
  sleep 30
done
Capture and review
bash
for id in $(aoe list --json | jq -r '.[].id'); do
  echo "=== $id ==="
  aoe session capture "$id" -n 100 --strip-ansi
  echo
done
Group operations via TUI

Groups are primarily managed through the aoe TUI (run aoe with no arguments). The TUI supports bulk start/stop/restart on groups. Use CLI commands above for scripted workflows.

© agent-of-empires, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in contrib/openclaw-skill of agent-of-empires/agent-of-empires.

Open the folder on GitHubat commit 8e70782

Compare with similar skills

Agent of Empires Session Manager next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Agent of Empires Session Manager compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Agent of Empires Session Manager this skillagent-of-empires/agent-of-empires3.3k—~2.1kAutomated safety check: PassMIT
Agent Manager Fleet TUIYoanWai/agent-manager582—~1kAutomated safety check: PassApache-2.0
Agtx Task Sweepfynnfluegge/agtx1.7k—~1.7kAutomated safety check: PassApache-2.0
Clawteamwin4r/ClawTeam-OpenClaw1.5k—~3.1kAutomated safety check: PassMIT
Huashu Agent Swarmalchaincyf/huashu-skills1.7k—~576Automated safety check: PassMIT
Multi Agent Orchestrationcat-xierluo/legal-skills720—~6.6kAutomated safety check: PassMIT

Similar skills

  • Agent Manager Fleet TUI

    YoanWai/agent-manager

    Runs several coding-agent CLIs as real tmux sessions in one terminal UI, color-coded by whether each is working, waiting, idle or blocked.

    582 GitHub stars~1k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Agtx Task Sweep

    fynnfluegge/agtx

    Breaks a conversation's results into feature-level tasks and pushes them to the agtx kanban board, where each task gets its own worktree and agent session.

    1.7k GitHub stars~1.7k tokensUpdated 8 days ago
    Agent WorkflowsAuto-check passed
  • Clawteam

    win4r/ClawTeam-OpenClaw

    Multi-agent swarm orchestration. An agent skill from win4r/ClawTeam-OpenClaw.

    1.5k GitHub stars~3.1k tokensUpdated 3 mo ago
    Agent WorkflowsAuto-check passed
  • Huashu Agent Swarm

    alchaincyf/huashu-skills

    多Agent蜂群并行协作,纯git自组织,适合大型项目开发。当用户提到"蜂群模式"、"多agent"、"并行开发"、"agent swarm"时使用。

    1.7k GitHub stars~576 tokensUpdated 18 days ago
    Agent WorkflowsAuto-check passed
  • Multi Agent Orchestration

    cat-xierluo/legal-skills

    编排两个以上边界独立的本地 worker,使用 Orca Run/Task/Dispatch、独立 worktree/session 或 tmux 回退,由 PM 负责拆解、派发、巡检、429 停滞恢复、独立验收、PR 收口与临时资源清理;也用于用户明确要求“并行推进”“多个 worker”“PM 总控”“Wave Autopilot”或防止 PM…

    720 GitHub stars~6.6k tokensUpdated yesterday
    DevelopmentAuto-check passed
  • Orca CLI

    stablyai/orca

    Operate Orca-managed worktrees, folder contexts, terminals, repos, automations, artifacts, skill sharing, worktree comments, and Orca's embedded browser…

    89k GitHub starsUsed in 2 repos~593 tokens
    Agent WorkflowsAuto-check passed

More from agent-of-empires/agent-of-empires

  • Agent of Empires Session Manager

    agent-of-empires/agent-of-empires

    Launches, monitors and organizes AI coding agent sessions such as Claude Code or Codex inside tmux, tracking status, capturing output and managing git worktrees for parallel branches.

    3.3k GitHub stars~2.5k tokensUpdated today
    Auto-check passed

Works with

Questions about Agent of Empires Session Manager

What does Agent of Empires Session Manager do?

Starts, monitors and organizes coding agent sessions that run in tmux through the aoe command, including groups, profiles and worktree-based parallel work. The skill teaches the agent to use the aoe CLI, rather than raw tmux commands, to run coding agents such as Claude Code, Codex and OpenCode. Each session has an ID, title, tool and project path; sessions can be placed in nested groups like backend/api, kept in separate profiles, and reported with a status such as running, waiting, idle, stopped, error, starting or unknown.

When should I use Agent of Empires Session Manager?

Agent of Empires Session Manager fits situations like: launching several coding agents on different project directories; checking which agent sessions are running, waiting or idle; capturing a session's output to review what an agent did; setting up parallel worktree-based development with separate agents.

How do I install Agent of Empires Session Manager in Claude Code?

Run `npx skills add agent-of-empires/agent-of-empires --skill aoe -a claude-code`. Or copy the skill folder (contrib/openclaw-skill in agent-of-empires/agent-of-empires) into .claude/skills/aoe in your project. Claude Code loads it when a task matches its description.

How do I install Agent of Empires Session Manager in Codex?

Run `npx skills add agent-of-empires/agent-of-empires --skill aoe -a codex`. Or copy the skill folder (contrib/openclaw-skill in agent-of-empires/agent-of-empires) into .agents/skills/aoe in your project. Codex loads it when a task matches its description.

Can I use Agent of Empires Session Manager in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add agent-of-empires/agent-of-empires --skill aoe -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/aoe, .gemini/skills/aoe, .github/skills/aoe and .opencode/skills/aoe in your project.

What does Agent of Empires Session Manager need to run?

Going by SKILL.md and its folder, Agent of Empires Session Manager needs the command-line tools its instructions call (jq). Our summary lists: The aoe (Agent of Empires) CLI; tmux.

Does Agent of Empires Session Manager access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Agent of Empires Session Manager safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Agent of Empires Session Manager use?

Agent of Empires Session Manager is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Agent of Empires Session Manager use?

About 2.1k tokens (SKILL.md is roughly 8.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Agent of Empires Session Manager?

Skills that share tags, products or a category with Agent of Empires Session Manager: Agent Manager Fleet TUI (YoanWai/agent-manager, 582 stars), Agtx Task Sweep (fynnfluegge/agtx, 1.7k stars), Clawteam (win4r/ClawTeam-OpenClaw, 1.5k stars) and Huashu Agent Swarm (alchaincyf/huashu-skills, 1.7k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Agent of Empires Session Manager?

agent-of-empires (a GitHub organization) maintains it in agent-of-empires/agent-of-empires, which has 3,332 GitHub stars. The repository holds 2 skills in this directory. The repository was last updated on October 10, 2026.

Source: agent-of-empires/agent-of-empires on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.