antigravity-workspace-template

A lightweight command-line tool (ag init) that scaffolds cognitive architecture files (.cursorrules, CLAUDE.md, .antigravity/rules.md, AGENTS.md) into any project directory without modifying existing code. This approach encodes agent behavior as declarative files rather than IDE plugins, enabling universal compatibility across Cursor, Claude Code, Windsurf, VS Code + Copilot, and other AI development environments. The CLI generates a standardized project structure with zero configuration required.

Automatically discovers Python functions in src/tools/ directory and registers them as callable tools without explicit configuration. The runtime introspects function signatures, docstrings, and type hints to generate tool schemas compatible with Claude, Codex, and other LLM function-calling APIs. Tools are executed in isolated sandbox environments with automatic input validation and error handling. This eliminates boilerplate tool registration code and enables rapid tool development.

Provides a centralized configuration system that supports environment variable substitution, type validation, and schema-based configuration validation. Configuration can be defined in .antigravity/config.json, environment variables, or Python code. The system validates configuration against a schema to catch errors early and provides helpful error messages. Environment variables are substituted at runtime, enabling configuration to vary across environments (development, staging, production) without code changes. Configuration is loaded at agent startup and can be accessed by all components.

Enables definition of reusable skills (in SKILLS.md or skill modules) that encapsulate common agent capabilities (e.g., 'code-review', 'test-generation', 'documentation-writing'). Skills are composed of tool sets, prompts, and execution patterns that can be combined to create specialized agents. Skills can be enabled or disabled per agent, allowing the same agent framework to be customized for different use cases. This enables rapid agent specialization without code duplication.

Provides Docker configuration and deployment scripts that containerize the agent runtime, enabling deployment to cloud platforms (AWS, GCP, Azure) or on-premises infrastructure. The Docker image includes the Python runtime, agent framework, tools, and dependencies. Deployment scripts handle environment variable injection, volume mounting for persistent storage, and networking configuration. This enables agents to be deployed as microservices or serverless functions without manual infrastructure setup.

Provides a local development environment with hot-reload capability that automatically restarts the agent when code changes are detected. Includes debugging support with breakpoints, step-through execution, and variable inspection. The development workflow supports running agents locally with full access to filesystem and tools, enabling rapid iteration and testing. Development mode includes verbose logging and error traces to aid debugging.

Implements a core cognitive cycle (Think → Act → Reflect) in agent.py that decomposes tasks into planning phases, tool execution phases, and reflection phases. The agent maintains conversation history with recursive summarization via memory.py to handle long-running sessions without token overflow. The Think phase uses chain-of-thought reasoning to decompose tasks; the Act phase executes tools and observes results; the Reflect phase evaluates outcomes and adjusts strategy. This cycle repeats until task completion or max iterations.

Enables definition and coordination of multiple specialized agents (defined in AGENTS.md) that can delegate tasks to each other based on role and capability. The framework provides a multi-agent pipeline that routes tasks to appropriate agents, manages inter-agent communication, and aggregates results. Each agent maintains its own memory and tool set while sharing a common knowledge hub. This architecture supports hierarchical task decomposition where complex problems are broken into sub-tasks assigned to specialized agents.

Manages long-running conversation history using recursive summarization (implemented in memory.py) that compresses old messages into progressively higher-level summaries while preserving recent context in full detail. The system maintains a conversation tree where leaf nodes are recent messages and parent nodes are summaries of their children. When conversation length exceeds a token budget threshold, the oldest messages are recursively summarized and replaced with their summaries. This enables agents to maintain coherent context across conversations spanning thousands of messages without token overflow.

Provides a unified interface for integrating tools from multiple sources: local Python functions (via zero-config discovery), Model Context Protocol (MCP) servers, and external APIs. The framework translates between different tool schema formats (Python type hints, MCP schemas, OpenAI function calling) and provides a common execution interface. MCP servers are configured in .antigravity/mcp.json and automatically discovered and registered. This enables agents to use tools from Claude's ecosystem, custom MCP servers, and local Python functions through a single unified API.

Executes tools in isolated sandbox environments (using containerization or process isolation) to prevent untrusted or experimental tools from compromising the host system. The sandbox provides a restricted filesystem, limited network access, and resource quotas (CPU, memory, disk). Tool execution is monitored for policy violations (e.g., attempts to access /etc/passwd) and can be terminated if limits are exceeded. This enables agents to safely execute user-provided tools or experimental code without risk to the host system.

Implements a multi-agent pipeline (ag-refresh command) that scans project codebases to automatically generate conventions.md and structure.md files. The pipeline uses specialized agents to analyze code patterns, extract architectural conventions, identify project structure, and generate documentation. The knowledge hub serves as a shared context store for all agents in the system, enabling them to understand project conventions without explicit configuration. Generated files are stored in .context/ directory and automatically loaded as context for all agent interactions.

Provides IDE-specific integration points (.cursorrules for Cursor, CLAUDE.md for Claude Code) that inject agent configuration and system prompts into IDE-native agent interfaces. The .cursorrules file contains Cursor-specific rules and context that guide Cursor's native agents. The CLAUDE.md file serves as the entry point for Claude Code, containing system prompt, task description, and links to available tools and context. These files are generated by the CLI and can be manually edited to customize agent behavior. This approach enables the same agent configuration to work across different IDEs without modification.

Automatically discovers and loads context files (Markdown files in .context/ directory) that provide background information, conventions, and project knowledge to agents. Context files are prioritized by relevance to the current task using semantic matching or explicit priority declarations. The system maintains a context budget (token limit) and selects the most relevant context files to include in agent prompts. Context files can include project conventions, architecture documentation, API references, code examples, and other background knowledge. This enables agents to make informed decisions without requiring explicit context injection in every prompt.