How to Install AG Kit: Complete Setup Guide for the Antigravity Toolkit

Run npx @vudovn/ag-kit init in your project root to scaffold the .agents/ workspace, generate the component registry, and register the Antigravity safety hook.

The vudovn/ag-kit repository provides an Antigravity-first AI-agent engineering toolkit that bundles agents, skills, workflows, and safety constraints into a structured workspace. Installing ag-kit initializes a managed component registry and configures native runtime hooks required for secure AI operations inside the Google Antigravity environment.

Installation Methods

AG Kit supports two primary installation paths: project-local execution via npx (recommended) or a global CLI installation for frequent use.

Project-Local Installation via npx

The fastest way to install ag-kit without cluttering your global npm packages is using npx. This pulls the latest @vudovn/ag-kit package from the registry and executes the initialization command directly in your current working directory.

npx @vudovn/ag-kit init

This approach is documented in the main README.md under the quick-start section.

Global CLI Installation

For teams working across multiple repositories or CI/CD pipelines, install the toolkit globally to gain persistent access to the ag-kit command.

npm install -g @vudovn/ag-kit
ag-kit init

The global workflow and CLI entry point are defined in [cli/bin/index.js](https://github.com/vudovn/ag-kit/blob/main/cli/bin/index.js), which implements the init, update, rollback, and status commands. See the CLI README for additional configuration options.

What the ag-kit init Command Configures

Running the initialization command performs four critical setup tasks that transform a standard repository into an Antigravity-ready environment.

1. Creates the .agents/ Workspace

The command generates a .agents/ directory containing 20 specialist AI personas (e.g., frontend-specialist, backend-specialist), 47 modular skills, 13 workflow slash-commands (/plan, /debug, etc.), and rule definitions. This structure serves as the workspace contract for the Antigravity runtime.

As documented in [.agents/ARCHITECTURE.md](https://github.com/vudovn/ag-kit/blob/main/.agents/ARCHITECTURE.md), the toolkit uses a managed component registry to ensure reproducible installations.

2. Generates the Component Registry

The initialization process writes three key files that lock dependency versions and component states:

• manifest.json – Declares active agents, skills, and workflows
• manifest.lock.json – Locks exact versions for reproducibility
• DEPENDENCY_GRAPH.md – Documents component relationships

These files are referenced by the Antigravity runtime to resolve capabilities and routing constraints.

3. Registers the Native Safety Hook

AG Kit installs a PreToolUse gate that intercepts destructive operations before execution. The hook configuration is written to .agents/hooks.json, which points to the validation logic in validate-tool-call.mjs.

According to the hooks documentation, this safety mechanism blocks unauthorized shell commands and file mutations inside the Antigravity environment while preserving legitimate AI tool use.

4. Configures Version Control Exclusions

By default, the installer leaves .agents/ unignored in your .gitignore, allowing the workspace to be tracked in version control. If you require local-only agent configurations without affecting Antigravity discovery, move the exclusion to .git/info/exclude instead.

Verify Your Installation

After initialization, validate the workspace integrity and Antigravity compatibility using the built-in npm scripts defined in your project's package.json:

npm run check:agents       # Validates manifest.json and manifest.lock.json integrity

npm run check:antigravity  # Executes the Antigravity Doctor (read-only diagnostics)

npm run test:antigravity   # Runs the hook test suite to verify safety gate functionality

Successful execution of these commands confirms that the component registry is healthy and the safety hooks are properly registered.

Update and Rollback Procedures

Once installed, the CLI provides atomic update mechanics that preserve local modifications to agent configurations.

Merge-style update (default, preserves local changes):

ag-kit update

Full replacement (creates a backup before overwriting):

ag-kit update --strategy replace

Restore previous version:

ag-kit rollback

These commands are implemented in [cli/bin/index.js](https://github.com/vudovn/ag-kit/blob/main/cli/bin/index.js) and follow the safe update model described in the CLI README.

Automate Installation with Node.js

For DevOps pipelines or automated onboarding scripts, use the following Node.js pattern to idempotently ensure AG Kit is present. The script detects an existing CLI installation or falls back to npx, then runs the verification suite.

import { execSync } from 'node:child_process';
import path from 'node:path';
import fs from 'node:fs';

const projectRoot = process.cwd();

function run(cmd) {
  console.log(`> ${cmd}`);
  execSync(cmd, { stdio: 'inherit', cwd: projectRoot });
}

// Install if .agents/ is missing
if (!fs.existsSync(path.join(projectRoot, '.agents'))) {
  const cliCmd = (() => {
    try {
      execSync('which ag-kit', { stdio: 'ignore' });
      return 'ag-kit';
    } catch {
      return 'npx @vudovn/ag-kit';
    }
  })();

  run(`${cliCmd} init`);
}

// Verify installation
run('npm run check:agents');
run('npm run check:antigravity');
run('npm run test:antigravity');

This automation mirrors the manual steps documented in the repository without introducing non-standard commands or additional dependencies.

Summary

• Run npx @vudovn/ag-kit init to create the .agents/ workspace without global installation
• The initialization process generates manifest.json, registers safety hooks in hooks.json, and creates the component registry
• Verify setup using npm run check:agents and npm run test:antigravity to ensure the Antigravity runtime can safely execute operations
• Update safely using ag-kit update (merge strategy) or ag-kit update --strategy replace with automatic backups
• Global installation via npm install -g @vudovn/ag-kit provides persistent CLI access for multi-repository workflows

Frequently Asked Questions

Do I need to commit the .agents/ folder to Git?

Yes. By default, ag-kit does not add .agents/ to .gitignore, allowing version control of your agent configurations, skills, and workflow definitions. If you need environment-specific overrides that should not be shared, exclude them using .git/info/exclude rather than the project .gitignore.

Can I use ag-kit across multiple projects without installing it globally?

Yes. The recommended approach is using npx @vudovn/ag-kit init inside each project directory. This ensures each workspace receives the correct component registry version without maintaining a global CLI installation, though installing globally with npm install -g @vudovn/ag-kit is supported for convenience.

What happens if the Antigravity safety hook blocks a legitimate command?

The safety hook defined in .agents/hooks.json and implemented in validate-tool-call.mjs evaluates commands against the rule sets in your .agents/ directory. If a legitimate command is blocked, review the specific rules in the workspace configuration or temporarily disable the hook for that session while consulting the hooks README for whitelist patterns.

How do I update ag-kit without losing custom agent configurations?

Use the merge strategy: ag-kit update. This updates core components from the registry while preserving local modifications to agent definitions and skills. If you need a completely fresh installation, use ag-kit update --strategy replace, which automatically backs up your current .agents/ directory before replacement, allowing rollback via ag-kit rollback if necessary.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}