coder · blink-so · Aug 25, 2025 · Aug 25, 2025 · Aug 25, 2025 · Aug 25, 2025
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,314 @@
+# AI Agent Modules
+
+The Coder Registry provides Terraform modules for integrating various AI coding agents into your development workspaces. These modules enable seamless AI-powered development experiences with web interfaces, task reporting, and automated setup.
+
+## Available AI Agent Modules
+
+### Core AI Agents (`coder` namespace)
+
+#### Aider
+
+- **Module**: `registry.coder.com/coder/aider/coder`
+- **Description**: AI pair programming tool for editing code in your local git repository
+- **Features**: Git-aware code editing, multiple AI provider support, automatic commits
+- **Supported Providers**: OpenAI, Anthropic, Google, Azure, Ollama
+- **AgentAPI**: ✅ Supported
+- **Documentation**: [View Module](https://registry.coder.com/modules/aider/coder)
+
+#### Claude Code
+
+- **Module**: `registry.coder.com/coder/claude-code/coder`
+- **Description**: Anthropic's Claude AI assistant with subagent support
+- **Features**: Code generation, debugging, specialized subagents for different tasks
+- **Subagents**: 46+ specialized agents for various development tasks
+- **AgentAPI**: ✅ Supported
+- **Documentation**: [View Module](https://registry.coder.com/modules/claude-code/coder)
+
+#### Goose
+
+- **Module**: `registry.coder.com/coder/goose/coder`
+- **Description**: AI-powered development assistant with toolkit integration
+- **Features**: Code analysis, generation, development workflow automation
+- **Toolkits**: Extensible toolkit system for custom workflows
+- **AgentAPI**: ✅ Supported
+- **Documentation**: [View Module](https://registry.coder.com/modules/goose/coder)
+
+#### Amazon Q
+
+- **Module**: `registry.coder.com/coder/amazon-q/coder`
+- **Description**: Amazon's AI coding assistant with AWS integration
+- **Features**: AWS-integrated development, MCP support, comprehensive CLI integration
+- **Version**: v2.0.0 (Major rewrite with AgentAPI support)
+- **AgentAPI**: ✅ Supported
+- **Documentation**: [View Module](https://registry.coder.com/modules/amazon-q/coder)
+
+#### Cursor IDE
+
+- **Module**: `registry.coder.com/coder/cursor/coder`
+- **Description**: Launch Cursor IDE with AI-powered development features
+- **Features**: One-click IDE launch, folder support, recent workspace access
+- **Type**: IDE Integration (not CLI agent)
+- **AgentAPI**: ❌ Not applicable (IDE launcher)
+- **Documentation**: [View Module](https://registry.coder.com/modules/cursor/coder)
+
+### Experimental AI Agents (`coder-labs` namespace)
+
+#### Gemini
+
+- **Module**: `registry.coder.com/coder-labs/gemini/coder-labs`
+- **Description**: Google's Gemini AI model for code assistance
+- **Features**: Multi-modal AI assistance, code generation, analysis
+- **Version**: v1.1.0 (Cleaned up and refactored)
+- **AgentAPI**: ✅ Supported
+- **Documentation**: [View Module](https://registry.coder.com/modules/gemini/coder-labs)
+
+#### OpenAI Codex
+
+- **Module**: `registry.coder.com/coder-labs/codex/coder-labs`
+- **Description**: OpenAI's Codex model for code generation and completion
+- **Features**: Code completion, generation, natural language to code translation
+- **Implementation**: Rust-based CLI with comprehensive task reporting
+- **AgentAPI**: ✅ Supported
+- **Documentation**: [View Module](https://registry.coder.com/modules/codex/coder-labs)
+
+#### Sourcegraph Amp
+
+- **Module**: `registry.coder.com/coder-labs/sourcegraph-amp/coder-labs`
+- **Description**: Sourcegraph's AI-powered code search and analysis tool
+- **Features**: Code search, analysis, AI-powered development insights
+- **Integration**: Full task prompt support and system prompt configuration
+- **AgentAPI**: ✅ Supported
+- **Documentation**: [View Module](https://registry.coder.com/modules/sourcegraph-amp/coder-labs)
+
+#### Cursor CLI
+
+- **Module**: `registry.coder.com/coder-labs/cursor-cli/coder-labs`
+- **Description**: Cursor CLI for AI-assisted development
+- **Features**: Command-line interface for Cursor's AI capabilities, MCP settings integration
+- **Installation**: Automatic via npm with Node.js bootstrapping
+- **AgentAPI**: ✅ Supported (cursor-agent)
+- **Documentation**: [View Module](https://registry.coder.com/modules/cursor-cli/coder-labs)
+
+#### Auggie
+
+- **Module**: `registry.coder.com/coder-labs/auggie/coder-labs`
+- **Description**: AI coding assistant with extensive configuration options
+- **Features**: Task automation, MCP server integration, configurable AI models
+- **Configuration**: Supports custom prompts, workspace rules, and model selection
+- **AgentAPI**: ✅ Supported
+- **Documentation**: [View Module](https://registry.coder.com/modules/auggie/coder-labs)
+
+### Community Modules
+
+#### Docker Claude Template
+
+- **Template**: `registry.coder.com/sharkymark/docker-claude/sharkymark`
+- **Description**: Docker-based template with Claude integration
+- **Type**: Complete workspace template
+- **Maintainer**: Community (sharkymark)
+
+## Module Features
+
+### Common Features
+
+All AI agent modules provide:
+
+- **🚀 One-Click Setup**: Automatic installation and configuration
+- **🌐 Web Interface**: AgentAPI integration for browser-based chat
+- **📋 Task Integration**: Seamless Coder Tasks support with status reporting
+- **🔧 Configurable**: Extensive customization options
+- **📝 Documentation**: Comprehensive usage guides and examples
+- **🧪 Tested**: Full test coverage with Terraform and TypeScript tests
+
+### AgentAPI Integration
+
+Modules with AgentAPI support provide:
+
+- **Interactive Chat**: Web-based chat interface
+- **Task Reporting**: Automatic status updates to Coder Tasks UI
+- **Health Checks**: Agent status monitoring
+- **File Context**: Share workspace files with AI agents
+- **Custom Prompts**: System and task prompt configuration
+
+## Usage Patterns
+
+### Basic Usage
+
+```terraform
+module "ai_agent" {
+  count    = data.coder_workspace.me.start_count
+  source   = "registry.coder.com/coder/<agent>/coder"
+  version  = "1.0.0"
+  agent_id = coder_agent.main.id
+}
+```
+
+### With API Key Configuration
+
+```terraform
+variable "ai_api_key" {
+  type        = string
+  description = "API key for AI service"
+  sensitive   = true
+}
+
+module "ai_agent" {
+  count    = data.coder_workspace.me.start_count
+  source   = "registry.coder.com/coder/<agent>/coder"
+  version  = "1.0.0"
+  agent_id = coder_agent.main.id
+  api_key  = var.ai_api_key
+}
+```
+
+### With Task Prompt Support
+
+```terraform
+data "coder_parameter" "ai_prompt" {
+  name        = "AI Prompt"
+  description = "Initial prompt for the AI agent"
+  type        = "string"
+  default     = ""
+  mutable     = true
+}
+
+module "ai_agent" {
+  count       = data.coder_workspace.me.start_count
+  source      = "registry.coder.com/coder/<agent>/coder"
+  version     = "1.0.0"
+  agent_id    = coder_agent.main.id
+  ai_prompt   = data.coder_parameter.ai_prompt.value
+}
+```
+
+## Prerequisites
+
+### Required Modules
+
+Most AI agent modules require:
+
+```terraform
+module "coder_login" {
+  source   = "registry.coder.com/modules/coder-login/coder"
+  agent_id = coder_agent.main.id
+}
+```
+
+### Runtime Dependencies
+
+- **Node.js**: Automatically installed via NVM for npm-based agents
+- **Python**: Required for Python-based agents (aider, goose)
+- **Git**: Required for git-aware agents
+- **Network Access**: Required for API-based agents
+
+## Configuration Best Practices
+
+### Environment Variables
+
+Use `coder_env` resources instead of inline exports:
+
+```terraform
+# ✅ Good
+resource "coder_env" "api_key" {
+  agent_id = coder_agent.main.id
+  name     = "OPENAI_API_KEY"
+  value    = var.openai_api_key
+}
+
+# ❌ Avoid
+resource "coder_agent" "main" {
+  env = {
+    OPENAI_API_KEY = var.openai_api_key
+  }
+}
+```
+
+### System Prompts
+
+Configure system prompts for consistent behavior:
+
+```terraform
+resource "coder_env" "system_prompt" {
+  agent_id = coder_agent.main.id
+  name     = "AI_SYSTEM_PROMPT"
+  value    = <<-EOT
+    You are a helpful coding assistant.
+    Always log task status to Coder.
+    Focus on clean, maintainable code.
+  EOT
+}
+```
+
+### Namespace Guidelines
+
+- **`coder`**: Stable, production-ready modules maintained by Coder
+- **`coder-labs`**: Experimental modules, may have breaking changes
+- **Community**: Third-party modules, varying maintenance levels
+
+## Development Workflow
+
+### Adding New AI Agent Modules
+
+1. **AgentAPI Support**: First add agent support to [coder/agentapi](https://github.com/coder/agentapi)
+2. **Module Creation**: Create module in appropriate namespace
+3. **Testing**: Add comprehensive tests (`.tftest.hcl` and `.test.ts`)
+4. **Documentation**: Include detailed README with examples
+5. **Review**: Follow [contributing guidelines](CONTRIBUTING.md)
+
+### Module Structure
+
+```
+registry/<namespace>/modules/<agent>/
+├── main.tf              # Terraform configuration
+├── README.md            # Documentation
+├── main.test.ts         # TypeScript tests
+├── <agent>.tftest.hcl   # Terraform tests
+├── scripts/
+│   ├── install.sh       # Installation script
+│   └── start.sh         # Startup script
+└── testdata/
+    └── <agent>-mock.sh  # Mock for testing
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Module Not Found**: Check namespace and module name spelling
+2. **Agent Installation Fails**: Verify network access and dependencies
+3. **AgentAPI Connection**: Check port configuration and firewall settings
+4. **Task Reporting**: Ensure proper prompt parameter configuration
+
+### Debug Information
+
+Module logs are typically located at:
+
+```
+/home/coder/.<module-name>-module/
+├── install.log
+├── agentapi-start.log
+└── <agent>-debug.log
+```
+
+### Getting Help
+
+- **Issues**: [GitHub Issues](https://github.com/coder/registry/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/coder/registry/discussions)
+- **Discord**: [Coder Community](https://discord.gg/coder)
+- **Documentation**: [Coder Docs](https://coder.com/docs)
+
+## Contributing
+
+We welcome contributions for new AI agent modules! Please:
+
+1. Review the [contributing guidelines](CONTRIBUTING.md)
+2. Check existing issues for planned agents
+3. Follow the module structure and testing requirements
+4. Ensure AgentAPI support is available
+5. Submit a PR with comprehensive documentation
+
+### Bounty Program
+
+Some AI agent modules are part of our bounty program. Look for issues labeled `🙋 Bounty claim` for opportunities to contribute and earn rewards.
+
+<!-- CI trigger -->