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

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. This registry stores agents, skills, workflows, and rules as Markdown files with YAML front-matter, plus generated manifests (manifest.json, manifest.lock.json) that ensure reproducibility.

CLI – Located in 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.

# One-off installation via npx

npx @vudovn/ag-kit init

Alternatively, install the CLI globally for repeated use:

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

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

The native PreToolUse hook registered in .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:

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:

ag-kit update --dry-run

Apply the update:

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

# 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 file in the .agents/ directory?

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

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