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

> Install AG Kit quickly with our complete setup guide. Run npx @vudovn/ag-kit init to scaffold your workspace, generate the component registry, and register the Antigravity safety hook.

- Repository: [Vũ Đỗ/ag-kit](https://github.com/vudovn/ag-kit)
- Tags: getting-started
- Published: 2026-07-29

---

**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.

```bash
npx @vudovn/ag-kit init

```

*This approach is documented in the [main README.md](https://github.com/vudovn/ag-kit/blob/main/README.md#quick-start) 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.

```bash
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)](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](https://github.com/vudovn/ag-kit/blob/main/cli/README.md#installation) 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)](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`](https://github.com/vudovn/ag-kit/blob/main/manifest.json)** – Declares active agents, skills, and workflows
- **[`manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.lock.json)** – Locks exact versions for reproducibility  
- **[`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/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`](https://github.com/vudovn/ag-kit/blob/main/.agents/hooks.json), which points to the validation logic in `validate-tool-call.mjs`.

According to the [hooks documentation](https://github.com/vudovn/ag-kit/blob/main/.agents/hooks/README.md), 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`](https://github.com/vudovn/ag-kit/blob/main/package.json):

```bash
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):

```bash
ag-kit update

```

**Full replacement** (creates a backup before overwriting):

```bash
ag-kit update --strategy replace

```

**Restore previous version**:

```bash
ag-kit rollback

```

These commands are implemented in [[`cli/bin/index.js`](https://github.com/vudovn/ag-kit/blob/main/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](https://github.com/vudovn/ag-kit/blob/main/cli/README.md#safe-update-model).

## 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.

```javascript
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`](https://github.com/vudovn/ag-kit/blob/main/manifest.json), registers safety hooks in [`hooks.json`](https://github.com/vudovn/ag-kit/blob/main/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`](https://github.com/vudovn/ag-kit/blob/main/.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](https://github.com/vudovn/ag-kit/blob/main/.agents/hooks/README.md) 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.