How to Debug Issues with ag-kit: A Step-by-Step Troubleshooting Guide

You can debug issues with ag-kit by executing the built-in debug workflow, regenerating the manifest with npm run generate:agents, and running the validation suite to identify schema violations or dependency graph mismatches.

ag-kit is an Antigravity-first AI-agent engineering kit maintained by vudovn that enforces strict safety hooks and generated dependency graphs across three logical layers. When you encounter failures—whether during local development or in CI—knowing how to debug issues with ag-kit requires understanding the interplay between the .agents/ toolkit, the Node-based CLI, and the validation scripts. This guide covers the exact commands, source files, and diagnostic workflows you need to resolve errors quickly.

Run the Built-In Debug Workflow

The fastest way to start debugging is to execute the diagnostic workflow defined in the repository. This workflow runs a sequence of checks and prints a concise report of potential issues.

Run the debug workflow using the CLI:

npx ag-kit workflow run debug

If the command fails or you need to inspect the exact steps manually, open the workflow definition at .agents/workflows/debug.md. This file lists the specific validation commands and sequence that the Antigravity runtime expects.

Regenerate and Verify the Manifest

Most ag-kit failures stem from an out-of-sync manifest. Any change to agents, skills, workflows, rules, or schemas requires manifest regeneration to update the runtime's view of the toolkit.

Regenerate the manifest files:

npm run generate:agents

This executes .agents/scripts/generate_manifest.py, which rebuilds .agents/manifest.json and .agents/manifest.lock.json. After generation, verify that the lock file matches the manifest:

git diff .agents/manifest.json .agents/manifest.lock.json

A mismatch between these files is a common cause of CI failures and runtime errors.

Validate Toolkit Integrity

The check:agents script runs three critical validations that catch schema violations, missing front-matter, and illegal hook definitions.

Execute the full validation suite:

npm run check:agents

This command performs three specific checks:

• Manifest integrity – Ensures .agents/manifest.json matches .agents/manifest.lock.json
• Dependency-graph consistency – Compares the current state against .agents/DEPENDENCY_GRAPH.md
• Python validation – Executes .agents/scripts/validate_kit.py to flag schema violations and malformed component definitions

If you need to run the Python validator directly for detailed output:

python -m .agents.scripts.validate_kit

Test the CLI Implementation

When the toolkit validates successfully but installation or update operations fail, the issue likely resides in the managed-tree logic.

Run the complete CLI test suite:

npm run test:cli

For targeted debugging of specific failures, run a single test file with verbose output:

node --test --watch cli/test/managed-tree.test.js

The core logic for installing and updating the toolkit resides in cli/lib/managed-tree.js. Failing tests in cli/test/ typically point to errors in how this module handles the .agents/ directory structure.

Inspect Antigravity Safety Hooks

ag-kit enforces strict safety rules via hooks that block disallowed filesystem actions. If a command is unexpectedly blocked or fails with permission errors, inspect the hook implementation.

Check the validation hook at .agents/hooks/validate-tool-call.mjs. This file implements the safety gate logic. To see detailed hook output during testing:

node --test .agents/hooks/tests/antigravity.test.mjs -- --verbose

The hook outputs JSON to stdout when it rejects a tool call, helping you identify exactly which filesystem action was blocked and why.

Review Architecture and CI Logs

When debugging complex integration issues, consult the architecture documentation to understand component registration and dependency contracts.

Read the high-level design at .agents/ARCHITECTURE.md. This document explains how the toolkit components interact, which helps pinpoint whether a failure originates from a missing dependency edge or a schema mismatch.

To replicate the exact CI environment locally, check the GitHub Actions workflow files:

• .github/workflows/ci.yml – Runs the validation suite and CLI unit tests
• .github/workflows/antigravity.yml – Executes the Antigravity "doctor" checks and hook tests

Replicating these command sequences locally ensures your fixes will pass in the CI pipeline.

Practical Debugging Examples

Force a full diagnostic cycle

# Pull latest changes

git pull origin main

# Run the debug workflow

npx ag-kit workflow run debug

# Regenerate and validate

npm run generate:agents
npm run check:agents

Debug a specific validation failure

# Run only the Python validator with stack traces

python .agents/scripts/validate_kit.py --verbose

# Check specific manifest entries

cat .agents/manifest.json | grep -A 5 "failed-component"

Test CLI changes iteratively

# Watch mode for rapid iteration

node --test --watch cli/test/managed-tree.test.js

# Test the CLI binary directly

node cli/bin/index.js workflow run debug

Summary

• Start with the debug workflow using npx ag-kit workflow run debug to get a quick diagnostic report
• Regenerate manifests after any toolkit change using npm run generate:agents to prevent lock-file mismatches
• Run npm run check:agents to catch schema violations, dependency graph inconsistencies, and hook errors
• Test CLI logic in cli/lib/managed-tree.js using node --test when installation or update operations fail
• Inspect hooks at .agents/hooks/validate-tool-call.mjs when safety rules block legitimate operations
• Reference .agents/ARCHITECTURE.md to understand component interactions and dependency contracts

Frequently Asked Questions

Why does my CI fail after I edited an agent file?

CI fails because ag-kit requires the generated manifest to stay synchronized with source files. Run npm run generate:agents after editing any file in .agents/ to update .agents/manifest.json and .agents/manifest.lock.json, then commit both files.

What does the "dependency graph mismatch" error mean?

This error indicates that .agents/DEPENDENCY_GRAPH.md is out of sync with the actual dependencies detected in your agents and skills. The validator compares the stored graph against the current component structure. Regenerate the manifest and run npm run check:agents to update the graph.

How do I know if a safety hook is blocking my command?

Check the output of .agents/hooks/validate-tool-call.mjs. When the hook blocks an operation, it logs a JSON object to stdout containing the blocked tool call and the rule that triggered the rejection. Run the hook tests with --verbose to see detailed output.

Where is the source of truth for the debug workflow steps?

The canonical debug workflow is defined in .agents/workflows/debug.md. This Markdown file contains the exact sequence of commands that npx ag-kit workflow run debug executes. Inspect this file manually if the CLI command fails to run.

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