agy

Files (7)

• SKILL.md
• agy-proxy-implementation.md · references/
• argument-ordering-pitfall.md · references/
• deepseek-openrouter-quirks.md · references/
• deepseek-openrouter-reasoning.md · references/
• litellm-routing.md · references/
• session_resume_token_caching.md · references/

SKILL.md (first lines)

# Agy — Local Orchestrator Agent

[Agy](https://github.com/nousresearch/hermes) is Matt's primary worker-bee orchestration agent. It runs locally via LiteLLM proxy on `localhost:8082` (inside tmux session `litellm`). Use it for cheap delegation — research, investigation, one-shot tasks, anything you'd rather not eat tokens for in your main thread.

## When to Use

- **Research tasks** — "find out why X is happening", "check system state", "investigate error Y"
- **Cheap parallel work** — agy uses tiered LiteLLM workers (cheaper models)
- **Fire-and-forget investigations** — start a background agy task and get results back
- **Anything the user explicitly asks you to delegate to agy** — don't over-engineer it, just call it
- **Triage mode: when running on a cheap/fast model** — check AGENTS.md triage rules. If the task is complex (multi-file analysis, cross-referencing repos, protocol research, reading large codebases) and you're on a cheap model, hand off to agy immediately instead of doing it yourself. Do NOT default to reading files yourself when you could delegate.

### CRITICAL: "Pass this to agy" means LITERAL delegation

When the user says "pass this to agy", "hand this off to agy", "give this to agy", or shares a URL/link saying "pass this off":

- **Do NOT research the link yourself first.** Do NOT open the URL. Do NOT form any opinion about the content.
- **Do NOT editorialize.** Do NOT add commentary, context, or your own observations. Do NOT explain what you're doing.
- **Do NOT do any prep work.** Do NOT read files, check state, or gather context before delegating.
- **Just pass the user's exact words to agy via `mcp__agymcp__agy`.** Include the URL/reference verbatim. Let agy do the reading.
- **If the user asks for a raw prompt** (not MCP delegation — they want text to paste themselves), just give them the prompt they described. No extra sections, no explanations, no "here's what this does". Just the prompt text.

**Why:** The user has explicitly designed agy as the research worker. When they route something there, they already know what they want. Any work you do first is wasted tokens and frustrates them.

## Mandatory MCP Routing

`mcp__agymcp__agy` is the default handoff path for every agent that has access to MCP tools. It provides structured results, explicit working-directory handling, resumable `SESSION_ID` conversations, and safe tracked background work.

1. Before claiming `agymcp` is unavailable, search the complete tool registry for `agymcp` or `agy`; it may be exposed as a deferred tool rather than listed in the initial tool declaration.
2. For normal one-shot handoffs, call `mcp__agymcp__agy` with the original request, `cd` set to the active project, `include_hermes_prompt=false`, and the smallest appropriate mode. Use `no_tmux=true` unless the caller explicitly needs an attached interactive tmux session.
3. For long-running work, use `mcp__agymcp__agy_start`, then `agy_status`, `agy_read`, and `agy_result`. For a cached/resumable Antigravity conversation, retain its `SESSION_ID` and call `mcp__agymcp__agy_continue`.
4. Use the terminal CLI only if the MCP tool is genuinely absent after discovery, or the bridge returns a structured invocation failure. State that fallback reason in the result.
5. Never substitute a generic model alias such as `claude`; use the exact supported model identifier returned by the bridge or quota/model inventory.

## Prerequisites

- agy installed at `~/.local/bin/agy` (confirm with `which agy`)
- LiteLLM proxy running: `tmux has-session -t litellm 2>/dev/null` (agy connects automatically)
- AGENTS.md/CLAUDE.md in the cwd — agy loads these for project context

## Critical: Argument Order

**`-p` takes the NEXT ARGUMENT as the prompt text.** This is the #1 pitfall.

```
# WRONG — --dangerously-skip-permissions gets consumed as the prompt text
agy -p --dangerously-skip-permissions "do X"

# RIGHT — prompt text immediately after -p, flags after the prompt
agy -p "do X" --dangerously-skip-permissions
```

In the wrong order, agy reads `--dangerously-skip-permissions` as your prompt and responds about its permission configuration instead of doing the task.

## Print Mode (One-Shot Tasks)

Print mode runs a single prompt non-interactively, returns the result, and exits. It is the CLI fallback path, not the default agent handoff path:

```bash
agy -p "Your task description here" --dangerously-skip-permissions --print-timeout 5m
```

### When to use print mode:
- One-shot investigations and diagnostics
- Scripted automation
- Any task where you don't need multi-turn conversation

### Timeout notes:
- `--print-timeout` defaults to `5m0s` (5 minutes)
- Must use Go duration format: `5m`, `10m`, `30s` — bare numbers fail with `invalid value`
- Set a high timeout for complex investigations; the command returns instantly when done, timeout is only a cap

### Quoting Guide for Shell Invocation

| Prompt contains | Use | Example |
|---|---|---|
| Any text (short or long) | Single quotes (bash multiline) | `agy -p 'your whole prompt here'` — single quotes prevent ALL bash interpretation of backticks, $, and other special chars |
| Single quotes inside prompt | Double-quote the outer string | `agy -p "it's a permissions issue"` |

**Rule of thumb:** ALWAYS use a single-quoted string directly in the terminal command. Single quotes pass everything through verbatim — backticks, $ signs, newlines, all of it. If the prompt is very long, bash single-quoted strings can span multiple lines naturally.

**NEVER do any of these:**
- ❌ Write prompt to a file and read with `$(cat file)` — backticks and $ signs in the file get interpreted by bash
- ❌ Use Python subprocess wrappers — triggers permission prompts, wastes CPU and time
- ❌ Pipe stdin into agy (`cat prompt | agy -p`) — agy doesn't read stdin for the prompt
- ❌ Create temp scripts, heredocs, or intermediate layers

If the quoting is awkward, fix the quoting — don't escalate the infrastructure. The user notices and is frustrated by extra processes, permission dialogs, and fan noise from needless overhead.

**Long prompts:** Bash single-quoted strings span multiple lines naturally. This works fine:
```bash
agy -p 'First paragraph of instructions.

Second paragraph with more detail.

Third paragraph with even more context.
Final line.' --dangerously-skip-permissions --print-timeout 5m
```

## Interactive Mode (Multi-Turn)

Not typically needed for agy (it's a worker, not a conversational agent), but available if the task needs follow-up:

```bash
agy -i "initial prompt" --dangerously-skip-permissions
```

## Key Flags

| Flag | Effect |
|------|--------|
| `-p, --print` | Non-interactive one-shot mode (takes NEXT ARG as prompt text) |
| `-i, --prompt-interactive` | Start interactive session with initial prompt |
| `-c, --continue` | Resume the most recent conversation |
| `--dangerously-skip-permissions` | Auto-approve all tool permission requests without prompting |
| `--print-timeout <duration>` | Max wait in Go duration format (e.g., `5m`, `30s`) |
| `--model <name>` | Override model for the session |
| `--agent <name>` | Choose a specific agent profile |
| `--mode <mode>` | Set execution mode: `accept-edits`, `plan` |

From mattdanielmurphy/ai-os, MIT.

More from mattdanielmurphy/ai-os