Referensi: Ekosistem Plugin¶

Referensi mendalam untuk sistem plugin agy-cli. Perintah-perintah penting dibahas dalam Modul 1 — Bagian 1.7. Halaman ini berisi detail siklus hidup lengkap untuk tim yang membangun dan memelihara plugin kustom.

2.0 — Mengapa Plugin Penting 5 menit¶

Sistem plugin agy-cli melakukan sesuatu yang unik: sistem ini dapat mengimpor plugin yang telah Anda instal di Gemini CLI atau Claude Code — tanpa perlu menginstal ulang atau mengonfigurasi ulang. Investasi Anda yang sudah ada pada ekstensi akan terbawa.

# See what plugins are currently active in agy
agy plugin list

Outputnya adalah JSON yang menunjukkan nama, sumber, tanggal impor, dan komponen dari setiap plugin (skill, perintah, mcpServers, agen).

# More readable
agy plugin list | python3 -m json.tool

📖 Dokumentasi resmi: Plugin · MCP · Skill

2.1 — Mengimpor dari Gemini CLI 10 menit¶

Pola: Cross-Tool Plugin Bridge — tarik seluruh pengaturan plugin Gemini CLI Anda ke dalam agy.

Impor Semua Plugin Gemini CLI¶

agy plugin import gemini

agy memindai instalasi Gemini CLI lokal Anda, menemukan semua plugin yang terinstal, dan menempatkan komponennya (skill, perintah, server MCP, agen) ke dalam konfigurasi agy di ~/.gemini/antigravity/.

Outputnya terlihat seperti:

  [ok]    code-review
          ✔ skills      : 3 processed
          ✔ commands    : 2 processed
          - mcpServers  : skipped (not found)
  [ok]    gemini-deep-research
          ✔ commands    : 1 processed
          ✔ mcpServers  : 1 processed
  [skip]  superpowers (already imported)

agy plugin import gemini --force

What Gets Imported¶

2.2 — Importing from Claude Code 5 min¶

Pattern: Unified Tool Surface — if you use Claude Code alongside agy, import its plugins too.

agy plugin import claude

Same mechanic — agy discovers your Claude Code extension installations and bridges compatible components.

2.3 — Managing Plugins Per-Project 10 min¶

Pattern: Project-Scoped Plugin Config — not every plugin is appropriate for every codebase.

Enable / Disable¶

# Disable a plugin for this session/project
agy plugin disable gemini-deep-research

# Re-enable it
agy plugin enable gemini-deep-research

# Check current state
agy plugin list

Plugin Locations¶

Plugins can be installed at two levels:

Install a Specific Plugin¶

# Install by name (from configured source)
agy plugin install <plugin-name>

# Install a specific version
agy plugin install <plugin-name>@<version>

2.4 — Validating a Plugin 10 min¶

Pattern: Plugin-as-Code — treat plugin definitions like source code. Validate before shipping.

Validate an Existing Plugin Directory¶

# Validate a plugin directory
agy plugin validate ./path/to/my-plugin

# Or validate the current directory
agy plugin validate .

This checks that the plugin's plugin.json manifest is well-formed and all referenced components exist.

Build a Minimal Custom Plugin¶

A valid agy plugin needs a plugin.json manifest. Here's the official structure:

my-plugin/
├── plugin.json          ← manifest (required)
├── mcp_config.json      ← MCP server definitions (optional)
├── hooks.json           ← hook event handlers (optional)
├── skills/              ← SKILL.md files with YAML frontmatter
│   └── my-skill/
│       └── SKILL.md
├── agents/              ← subagent definitions (optional)
└── rules/               ← rules files (optional)
    └── my-rules.md

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom agy plugin",
  "components": ["skills"]
}

# Validate it
agy plugin validate ./my-plugin

# If valid, you'll see: ✔ Plugin manifest is valid

Interacting with Plugin Components¶

Use slash commands to inspect active plugin components in a session:

Exercise: Validate the Workshop Plugin¶

The workshop repo includes a sample plugin at samples/plugins/workshop-helpers/. Validate it:

agy plugin validate samples/plugins/workshop-helpers/

2.5 — Plugin Architecture Overview¶

graph LR
    GC["Gemini CLI\nPlugins"] --> |agy plugin import gemini| S["Plugin Staging\n~/.gemini/antigravity/plugins/"]
    CC["Claude Code\nExtensions"] --> |agy plugin import claude| S
    S --> |agy plugin enable/disable| A[agy session]
    A --> SK[Skills]
    A --> MCP[MCP Servers]
    A --> AG[Agents]
    A --> RU[Rules]
    A --> HK[Hooks]
    A --> SD[Sidecars]

Plugin staging directory structure:

~/.gemini/antigravity/plugins/<name>/
├── plugin.json
├── mcp_config.json
├── hooks.json
├── skills/
├── agents/
├── rules/
└── sidecars/          ← plugin-scoped background processes

2.6 — Sidecars: Persistent Background Processes 15 min¶

Pattern: Always-On Agent — sidecars run alongside AGY CLI, independently of any conversation. Use them for scheduled tasks, event watchers, and persistent background workers.

📖 Source: sidecars

What Sidecars Are¶

A sidecar is a background process that AGY manages for you: it launches automatically when AGY starts, restarts on crash, and runs independently of your active conversation. Unlike hooks (which fire in response to conversation events), sidecars are always running.

Three use cases:

Configuration¶

Sidecars are discovered from two locations:

# Global sidecars (available in all projects)
~/.gemini/config/sidecars/<sidecar-name>/sidecar.json

# Plugin-scoped sidecars (shipped with a plugin)
~/.gemini/config/plugins/<plugin-name>/sidecars/<sidecar-name>/sidecar.json

The directory name becomes the sidecar's ID. Plugin sidecars get the ID <pluginName>/<sidecarName>.

Sidecars are disabled by default. Enable them explicitly in ~/.gemini/config/config.json:

{
  "sidecars": {
    "pr-triage": {
      "enabled": true
    },
    "my-plugin/log-watcher": {
      "enabled": true,
      "projectId": "<conversation-project-id>"
    }
  }
}

sidecar.json Schema¶

Example 1: Background Worker Script¶

{
  "description": "Watches the build queue and notifies on failures",
  "command": "python3",
  "args": ["watch_builds.py"],
  "restart_policy": "on-failure",
  "env": {
    "BUILD_QUEUE_URL": "https://ci.example.com/api/queue"
  }
}

Example 2: Scheduled Recurring Task (the schedule builtin)¶

The schedule builtin takes a cron expression as its first arg, then the command + args to run:

{
  "description": "Hourly PR triage — summarises incoming review requests",
  "builtin": "schedule",
  "args": [
    "0 * * * *",
    "agentapi",
    "new-conversation",
    "Summarise all open PRs waiting for my review. Group by urgency."
  ]
}

agentapi is automatically available to sidecars — it lets them programmatically create or message conversations:

# Start a new conversation from a sidecar
agentapi new-conversation "<prompt>"

# Send a message to an existing conversation
agentapi send-message <conversation_id> "<prompt>"

Runtime Data¶

Sidecar output is stored at:

~/.gemini/antigravity/sidecar_data/<sidecarId>/
├── data/     ← persistent storage (ANTIGRAVITY_EXECUTABLE_DATA_DIR env var)
├── logs/     ← timestamped stdout/stderr logs
└── events/   ← JSON records of agentapi calls

Directory Structure for a Plugin Sidecar¶

~/.gemini/config/plugins/my-plugin/
└── sidecars/
    └── pr-triage/
        ├── sidecar.json   ← config (required)
        └── triage.py      ← helper script (optional, runs in this dir)

Latihan Modul 2¶

Kembali ke Workshop¶

→ Modul 1: Produktivitas SDLC — plugin diperkenalkan pada Bagian 1.7

→ Lembar Contekan — semua perintah plugin dan sidecar di satu tempat