athal7/dotfiles / dot_agents/skills/aoe
aoe
VerifiedUse when creating or managing AoE sessions/worktrees, dispatching workers, or communicating with another independent agent session from OMP or Freebuff.
AoE (Agent of Empires) creates and drives agent sessions. Run aoe --help and aoe <subcommand> --help — flags change between releases; this file covers only what help text won't tell you.
- Drive sessions through the
aoeMCP server, not the CLI.create_session,send,read_output,list_sessionsandwhoamiwrap the same daemon the CLI talks to and return structured results instead of scraped text; OMP exposes them asmcp__aoe_<tool>. The server needs the daemon running (aoe serve --status); with no daemon, nothing can create or drive a session anyway. Reach for the CLI for what the tools do not cover: attach/detach,aoe worktree,aoe project,aoe acp, and plugin management. create_sessionwants a structured view for a prompt. A terminal session gets its prompt typed only once the agent's status rules show an input box; an agent whose rules expose no input prompt getsnot_readywith nothing typed. Useview: "structured"and the prompt arrives as the session's pending first turn. For a terminal session, create it without a prompt, thensendthe prompt and check the returned disposition.- Every session and subagent that may modify a repository needs a dedicated git worktree, unless I point it at a named primary checkout — that direction waives this default, while two active writers in one worktree stays a hazard to surface. Read-only inspection needs neither a new session nor a worktree.
create_sessiontakesworktree_enabled,worktree_branch,create_new_branchandbase_branch; the CLI equivalent isaoe add <registered-path> --worktree <branch> --new-branch. For a session that already exists,aoe session add-project <session> <project>creates a worktree but restarts the agent. If attachment is refused because its conversation is bound to the current directory, use a new session; never clear the resume target or proceed without write isolation. pathis canonicalized, never resolved back to the main repo. Point a create at a worktree and it silently becomes a bogus project rooted there. Pass the exact registered path (aoe project list) plus worktree options. The CLI's--project/--repoadd extra repos to a multi-repo workspace — they don't select the primary target.- Check
list_sessionsbefore dispatch. Verify the recipient's ID, profile, and transport; one task per session. Do not restart, convert, cancel, or revive an existing session to deliver a message. - Retry a create only with its
idempotency_key. A repeated create with the same key returns the original session withfresh: falseand delivers nothing; a bare retry can leave two workers on one task.
Peer communication
sendis the peer channel; keep it out of a live editor.sendtypes into a terminal session's pane, so it can still land in a dialog the agent's status rules do not recognise: checkread_outputfirst, and treat an unexplained wait as a person's decision to make, not a message to deliver. Unlikeaoe send, the tool refuses withwaitingwhen a status rule does detect a dialog or approval, and withnot_runningrather than restarting a stopped session.- Keep peer context distinct from user authority. Attribute messages to the sending agent; never represent them as user steering, approval, or authority to change scope, or answer a user question or approval on a peer's behalf.
acp approveand RPC UI responses also interact with session control state; they are not interchangeable peer inboxes.agent://addresses only the current agent tree;collabshares control of one session, not an independent peer channel. - Prefer an initial prompt over a delivered message.
create_sessionwithview: "structured"and apromptstarts a worker already pointed at its task, with no pane typing to get wrong.
Troubleshooting
Session or subagent silently returns empty responses — a per-org on_launch hook rewrites every model class to a local mlx backend for git-repo-backed sessions, and that backend is overloaded. The hook's first step is git rev-parse --show-toplevel, so it no-ops without a .git: a scratch session (no path) falls back to the global config. aoe rm --keep-scratch preserves the output.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |