khanhbkqt/spawn-agent

---

The Problem

Antigravity is powerful, but it has no built-in way to delegate work to sub-agents. Every file read, build output, and error trace goes into the same context window — and it fills up fast. Once it does, the agent loses track of earlier instructions and can’t reason about the big picture.

Before spawn-agent:

Main Agent Context:
├── User conversation          ~5%
├── Codebase understanding     ~10%
├── File A contents            ~15%  ← polluting
├── File B contents            ~15%  ← polluting
├── Build output               ~20%  ← polluting
├── Lint errors                ~10%  ← polluting
└── Remaining for reasoning    ~25%  ← squeezed

After spawn-agent:

Main Agent Context (Orchestrator):         Worker Agent Context:
├── User conversation     ~15%             ├── Task prompt          ~10%
├── Codebase overview     ~20%             ├── File A contents      ~25%
├── Delegation plan       ~10%             ├── File B contents      ~25%
├── Worker results        ~15%             ├── Build output         ~20%
└── Remaining reasoning   ~40%  ← clean   └── Implementation       ~20%

How It Works

The main agent acts as an orchestrator — it plans, delegates, and reviews. Worker agents (Gemini or Codex) handle the actual implementation in isolated sessions.

Orchestrator                    Worker (Gemini/Codex)
     │                               │
     ├──── 1. DEFINE task ────────►   │
     ├──── 2. COMPOSE prompt ─────►   │
     ├──── 3. SPAWN ──────────────►   ├── reads codebase
     │                                ├── implements changes
     │                                ├── runs verification
     │     ◄── 4. OUTPUT ────────────┘
     ├──── 5. REVIEW results
     └──── 6. REPORT to user

Installation

Prerequisites

At least one of these CLI tools must be installed:

# Gemini CLI
npm install -g @google/gemini-cli

# Codex CLI
npm install -g @openai/codex

Install the Skill

Clone into your Antigravity skills directory:

# Recommended: into your global skills directory
git clone https://github.com/khanhbkqt/spawn-agent.git ~/.gemini/antigravity/skills/spawn-agent

# Or per-project
git clone https://github.com/khanhbkqt/spawn-agent.git .agent/skills/spawn-agent

# Or symlink from a central location
git clone https://github.com/khanhbkqt/spawn-agent.git ~/spawn-agent
ln -s ~/spawn-agent ~/.gemini/antigravity/skills/spawn-agent

Make the script executable:

chmod +x ~/.gemini/antigravity/skills/spawn-agent/scripts/spawn-agent.sh

Antigravity will automatically discover the skill from SKILL.md and learn the delegation protocol.

Quick Start

1. Simple inline task

./scripts/spawn-agent.sh --gemini --yolo -p "Count all TODO comments in src/ and list them"

2. Complex task with a template

Create a prompt file from a template:

cp templates/implementation-task.md /tmp/spawn-agent-task-auth.md
# Fill in the template sections...

Then spawn:

./scripts/spawn-agent.sh --codex --auto-edit --timeout 300 -f /tmp/spawn-agent-task-auth.md

3. Read-only research

./scripts/spawn-agent.sh --gemini --yolo --timeout 120 \
  -p "Analyze the authentication flow in packages/backend/src/auth/. 
      List all JWT-related functions and their dependencies.
      Output as a markdown summary. DO NOT modify any files."

Choosing an Agent

Tip: Choose the agent based on the task — don’t be loyal to one CLI. Each has its own strengths.

Approval Modes

Templates

Three prompt templates are provided for common task types:

Each template includes sections for goal, scope, constraints, and expected output format. Fill in all sections before delegating — headless workers can’t ask clarifying questions.

Quick inline format (for simple tasks)

# Task: 
## Goal: 
## Files: 
## Constraints: DO NOT modify files outside 
## When done: Summarize changes made and any issues found.

When to Use (and When Not To)

Use spawn-agent when:

• Implementation task has a clear scope (fix bug, add function, refactor file)
• You need to research/query the codebase without polluting the main context
• The task is independent and doesn’t need intermediate human review
• You want to keep the main context clean for high-level reasoning

Don’t use when:

• Task requires interactive discussion with the user
• Scope is too broad (refactoring an entire module)
• Multiple files with complex inter-dependencies need coordination
• Task needs browser interaction or external API calls

Anti-Patterns

Script Reference

Usage: spawn-agent.sh [options]

Agent Selection:
  --gemini                Use Gemini CLI (default)
  --codex                 Use Codex CLI

Prompt:
  -p, --prompt TEXT       Prompt text (inline)
  -f, --file PATH         Prompt file (markdown)

Approval Modes:
  --yolo                  Auto-approve everything
  --auto-edit             Auto-approve edits only (default)
  --safe                  Prompt for every action

Other:
  --timeout SECONDS       Max execution time (default: 300)
  --output PATH           Custom output file path
  -h, --help              Show this help

Compatibility

Built for Antigravity (Google DeepMind), but works with any AI coding assistant that reads SKILL.md files:

• Antigravity — ~/.gemini/antigravity/skills/ (primary target)
• Claude Code (Anthropic) — .agent/skills/
• Gemini CLI (Google) — .gemini/skills/
• Cursor — via rules or skills directories
• Any agent that supports Markdown-based skill definitions

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT