# How to Use ag-kit in a Project: Complete Setup and Integration Guide

> Learn how to use ag-kit in your project with our complete setup and integration guide. Quickly initialize your workspace and validate the installation.

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

---

**To use ag-kit in a project, run `npx @vudovn/ag-kit init` to scaffold the `.agents/` workspace, validate the installation with `npm run check:agents`, and open the directory as a trusted Antigravity workspace.**

ag-kit is a full-stack agent engineering kit designed for Google Antigravity. According to the vudovn/ag-kit source code, it provides a managed component registry, a Node-based CLI, and safety hooks that create a reproducible, auditable agent toolkit. The following guide covers bootstrapping, validation, and maintenance workflows.

## What Is ag-kit?

ag-kit consists of three logical layers that work together to manage AI agents safely.

**Toolkit** – The `.agents/` directory contains the workspace contract defined in [`.agents/antigravity.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/antigravity.json). This registry stores agents, skills, workflows, and rules as Markdown files with YAML front-matter, plus generated manifests ([`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json), [`manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.lock.json)) that ensure reproducibility.

**CLI** – Located in [`cli/bin/index.js`](https://github.com/vudovn/ag-kit/blob/main/cli/bin/index.js), the command-line interface handles installation, updates, and rollbacks. It merges upstream changes while preserving local modifications in `.ag-kit-backups/`.

**Safety Hooks** – The `.agents/hooks/validate-tool-call.mjs` file implements the native `PreToolUse` hook that blocks destructive commands before execution.

## Bootstrapping the Workspace

### Initial Installation

Run the initializer to clone the `.agents/` directory into your project root. The installer automatically backs up existing toolkit files to `.ag-kit-backups/` and merges with any current configuration.

```bash

# One-off installation via npx

npx @vudovn/ag-kit init

```

Alternatively, install the CLI globally for repeated use:

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

```

The command creates the managed component structure where agents and skills live as versioned Markdown files.

### Global CLI Setup

For teams managing multiple projects, global installation provides the `ag-kit` binary referenced in [`cli/README.md`](https://github.com/vudovn/ag-kit/blob/main/cli/README.md). This exposes commands like `init`, `update`, and `rollback` across your system.

## Validating the Contract

After installation, verify that generated manifests match source files and that the Antigravity safety hook is correctly configured.

Run the validation suite:

```bash

# Verify manifest consistency against generation step

npm run check:agents

# Run Antigravity-specific static checks

npm run check:antigravity

# Execute the hook test suite

npm run test:antigravity

```

These scripts validate that `npm run generate:agents` produced correct immutable manifests and that the dependency graph in [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/DEPENDENCY_GRAPH.md) reflects current components.

## Running Antigravity

Open the repository as a trusted Antigravity workspace. The runtime automatically discovers agents, skills, and workflows defined in `.agents/` according to the contract in [`.agents/antigravity.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/antigravity.json).

The native `PreToolUse` hook registered in [`.agents/hooks.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/hooks.json) executes `.agents/hooks/validate-tool-call.mjs` before any tool invocation. This blocks dangerous patterns such as `rm -rf /`.

Test the safety hook manually:

```bash
printf '%s' '{"tool_args":{"CommandLine":"rm -rf /"}}' |
  node .agents/hooks/validate-tool-call.mjs

# Expected output: "BLOCKED by AG Kit" (non-zero exit)

```

## Updating and Rolling Back

### Safe Updates

Use `ag-kit update` to merge upstream changes while preserving local modifications. Conflicts are reported and stored under `.agents/.ag-kit/conflicts/`.

Preview changes before applying:

```bash
ag-kit update --dry-run

```

Apply the update:

```bash

# Default merge strategy

ag-kit update

# Or replace entirely

ag-kit update --strategy replace

```

### Rollback Procedures

If an update causes issues, restore the previous state:

```bash

# Restore newest backup

ag-kit rollback

# Restore specific backup by timestamp

ag-kit rollback --backup 20260712-090000-000

```

## Summary

- **Bootstrap** with `npx @vudovn/ag-kit init` to scaffold the `.agents/` workspace and create backups automatically.
- **Validate** installations using `npm run check:agents` to ensure manifest consistency and safety hook configuration.
- **Operate** by opening the folder as a trusted Antigravity workspace; the `PreToolUse` hook in `.agents/hooks/validate-tool-call.mjs` blocks destructive commands.
- **Maintain** with `ag-kit update` (supports `--dry-run` and `--strategy replace`) and `ag-kit rollback` for safe version management.

## Frequently Asked Questions

### How do I install ag-kit without losing my existing project files?

The `ag-kit init` command automatically creates backups in `.ag-kit-backups/` before merging. It preserves user edits while scaffolding the `.agents/` directory, ensuring no data loss during installation.

### What is the purpose of the [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json) file in the `.agents/` directory?

The [`.agents/manifest.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/manifest.json) file is a generated immutable manifest that catalogs all managed components (agents, skills, workflows). It is produced by `npm run generate:agents` and validated by `npm run check:agents` to guarantee reproducibility and track dependencies.

### How does ag-kit protect against dangerous command execution?

The repository registers a native `PreToolUse` hook via [`.agents/hooks.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/hooks.json) that executes `.agents/hooks/validate-tool-call.mjs` before any tool invocation. This script pattern-matches command lines to block destructive operations and exits with a non-zero status to prevent execution.

### Can I update ag-kit without losing my custom agent configurations?

Yes. The `ag-kit update` command uses a merge strategy by default that preserves local modifications. Conflicts are stored in `.agents/.ag-kit/conflicts/` for manual review, and you can preview changes with `--dry-run` before applying them.