.

Author: jayhack

docs/capabilities/capabilities.mdx

@@ -1,6 +1,6 @@
 ---
-title: "Agent Capabilities"
-sidebarTitle: "Overview"
+title: "How Codegen Agents Work"
+sidebarTitle: "How it Works"
 icon: "gear"
 iconType: "solid"
 ---
@@ -28,7 +28,7 @@ graph TD
     A3[GitHub issue comment] --> A
 ```
 
-### 1. Trigger `@codegen` from Your Tools
+### 1. Users Trigger `@codegen` to Perform Tasks
 
 Agents activate seamlessly from the platforms you already use:
 
@@ -40,7 +40,7 @@ Agents activate seamlessly from the platforms you already use:
 - **[GitHub](/integrations/github)** - Comment on issues or PRs to request changes
 - **[API](http://localhost:3001/api-reference/agents/create-agent-run)** - Programmatically trigger agents for automated workflows
 
-### 2. Work in Secure Sandboxes
+### 2. `@codegen` Performs Work in Secure Sandboxes
 
 Once triggered, agents work in **[isolated sandbox environments](/sandboxes/overview)** where they can:
 
@@ -49,7 +49,7 @@ Once triggered, agents work in **[isolated sandbox environments](/sandboxes/over
 - Make changes and validate them before committing
 - Access your repository context while maintaining security
 
-### 3. Create and Manage Pull Requests
+### 3. Users Receive Completed Pull-Requests
 
 Agents create **[GitHub pull requests](/integrations/github)** with:
 
@@ -58,7 +58,7 @@ Agents create **[GitHub pull requests](/integrations/github)** with:
 - Clean, tested code ready for review
 - Proper commit messages following your conventions
 
-### 4. Monitor and Auto-fix Issues
+### 4. Agents Monitor and Auto-fix PR Issues
 
 The **[Checks Auto-fixer](/capabilities/checks-autofixer)** ensures quality by:
 
@@ -67,7 +67,7 @@ The **[Checks Auto-fixer](/capabilities/checks-autofixer)** ensures quality by:
 - Pushing targeted fixes to resolve issues
 - Retrying up to 3 times before escalating to humans
 
-### 5. Respond to Follow-ups
+### 5. Agents Respond to Follow-ups
 
 Agents remain active to handle questions and refinements:
 

docs/capabilities/claude-code.mdx

@@ -0,0 +1,304 @@
+---
+title: "Claude Code Integration"
+sidebarTitle: "Claude Code"
+icon: "code"
+---
+
+Claude Code brings the power of Anthropic's coding assistant directly into your development workflow through Codegen. Whether you're running Claude locally or in the cloud, Codegen provides the infrastructure to enhance your AI coding experience with telemetry, integrations, and seamless deployment options.
+
+<Frame>
+  <video
+    controls
+    src="https://res.cloudinary.com/dbikr6pew/video/upload/v1757996504/Claude_Code_Integration_coe5sm.mp4"
+    className="aspect-[3340/2160]"
+  />
+</Frame>
+
+## Cloud Logging for Local Sessions
+
+Every local Claude Code session is automatically logged to the cloud through the Codegen CLI. This seamless integration means your local development gains enterprise-grade observability without any extra configuration.
+
+When you run Claude through `codegen`, you get:
+
+- **Persistent history** across all your local Claude sessions
+- **Searchable conversations** accessible from any device
+- **Team visibility** into AI-assisted development patterns
+- **Audit trails** for compliance and debugging
+
+<Note>
+  Sessions appear instantly at [codegen.com/agents](https://codegen.com/agents),
+  making it easy to share context with teammates or continue work from another
+  machine.
+</Note>
+
+## MCP Server Integration
+
+Claude Code running through Codegen automatically gains access to all your connected integrations via MCP (Model Context Protocol). This transforms Claude from a coding assistant into a full development platform orchestrator.
+
+Your existing Codegen integrations work seamlessly:
+
+- **Slack** - Send updates and coordinate with your team
+- **Linear/Jira** - Update tickets and track progress
+- **GitHub** - Create PRs and manage repositories
+- **Databases** - Query and modify data safely
+- **Custom tools** - Any MCP server you've configured
+
+No additional setup required - if it's connected to Codegen, Claude can use it.
+
+<Tip>
+  MCP integration means Claude can perform complex workflows like "When tests
+  fail, create a Linear ticket and notify the team on Slack" - all in a single
+  command.
+</Tip>
+
+## Background Terminal Agents
+
+Keep your terminal free while Claude handles long-running tasks. Background agents run asynchronously, perfect for automation that doesn't need constant supervision.
+
+```bash
+# Start a background agent to handle PR reviews
+codegen agent create --background "Review all open PRs and suggest improvements"
+
+# Continue working while the agent runs
+# Check status anytime at codegen.com/agents
+```
+
+Common use cases for background agents:
+
+- Automated code reviews on new PRs
+- Continuous monitoring of test suites
+- Documentation generation from code changes
+- Dependency updates and security patches
+
+<Note>
+  Background agents support scheduling with flags like `--repeat-daily` or
+  `--repeat-weekly`, turning one-off tasks into automated workflows.
+</Note>
+
+## Remote Sandbox Execution
+
+Configure Claude Code as your default agent to run in Codegen's secure cloud sandboxes. This provides consistent, scalable environments for all your AI-assisted development.
+
+<Card
+  title="Set Claude Code as Default"
+  icon="toggle-on"
+  href="https://codegen.com/settings/model"
+>
+  Enable Claude Code mode to run all agents in secure sandboxes with full
+  integration support.
+</Card>
+
+Remote execution benefits:
+
+- **Consistent environments** across your team
+- **Pre-configured tools** and dependencies
+- **Scalable compute** for resource-intensive tasks
+- **Security isolation** from your local machine
+
+## Getting Started
+
+### Local Claude with Cloud Benefits
+
+Get up and running in three simple steps:
+
+1. Install the Codegen CLI:
+
+   ```bash
+   uv tool install codegen
+   ```
+
+2. Authenticate with your account:
+
+   ```bash
+   codegen login
+   ```
+
+3. Run Claude with full telemetry:
+   ```bash
+   codegen claude "Help me refactor this authentication module"
+   ```
+
+Your session immediately appears in the cloud with full integration access.
+
+<Tip>
+  The first time you run `codegen claude`, it will download the Claude Code
+  binary. Subsequent runs start instantly.
+</Tip>
+
+### Enable Organization-Wide
+
+For teams ready to standardize on Claude Code:
+
+1. Navigate to [Model Settings](https://codegen.com/settings/model)
+2. Enable "Claude Code Mode"
+3. Select Claude 4 Sonnet (recommended)
+4. All agents now run with Claude Code capabilities
+
+## Real-World Workflows
+
+### Continuous PR Monitoring
+
+Set up automated review cycles that run in the background:
+
+```bash
+# Daily PR reviews with actionable feedback
+codegen agent create --background --repeat-daily \
+  "Review new PRs in myrepo and suggest improvements"
+```
+
+The agent runs daily, reviewing PRs and posting suggestions directly to GitHub.
+
+### Local Development with Team Visibility
+
+Perfect for pair programming or mentoring sessions:
+
+```bash
+# Start a traced Claude session
+codegen claude
+
+# Your team can follow along at codegen.com/agents
+# All integrations available through MCP
+```
+
+Team members can observe your AI interactions in real-time, learning from your prompting patterns and problem-solving approaches.
+
+### Hybrid Workflow
+
+Start locally, deploy to cloud when ready:
+
+```bash
+# Prototype locally with Claude
+codegen claude "Build a new API endpoint for user profiles"
+
+# Happy with the approach? Deploy to sandbox
+codegen agent create "Implement the user profile API we discussed"
+```
+
+<Note>
+  Context from your local Claude sessions carries over to cloud agents,
+  maintaining continuity across environments.
+</Note>
+
+## Advanced Configuration
+
+### Custom MCP Servers
+
+Extend Claude's capabilities with your own tools:
+
+```bash
+# Configure custom MCP server
+codegen mcp add my-tool https://my-mcp-server.com
+
+# Now available in all Claude sessions
+codegen claude "Use my-tool to generate test data"
+```
+
+### Session Management
+
+Powerful commands for working with Claude sessions:
+
+```bash
+# List recent sessions
+codegen sessions list
+
+# Resume a previous session
+codegen sessions resume <session-id>
+
+# Export session for sharing
+codegen sessions export <session-id> > session.md
+```
+
+## Best Practices
+
+### When to Run Locally vs Remote
+
+**Run locally when:**
+
+- Prototyping and experimenting
+- Working with sensitive code
+- Need immediate feedback
+- Debugging specific issues
+
+**Run in sandboxes when:**
+
+- Executing long-running tasks
+- Need consistent environments
+- Collaborating with team
+- Running automated workflows
+
+### Effective Background Agents
+
+Keep background agents focused:
+
+- Single responsibility per agent
+- Clear success criteria
+- Reasonable time bounds
+- Proper error handling
+
+<Tip>
+  Use descriptive names for background agents - they appear in your dashboard
+  and help teammates understand what's running.
+</Tip>
+
+### Integration Patterns
+
+Leverage MCP for complex workflows:
+
+```bash
+# Agent that coordinates across tools
+codegen agent create "When tests fail on PR #123, \
+  create a Linear ticket and notify #eng-team on Slack"
+```
+
+## Monitoring and Debugging
+
+All Claude Code sessions include comprehensive telemetry:
+
+- **Execution traces** showing every tool invocation
+- **Token usage** per request and response
+- **Error logs** with full stack traces
+- **Performance metrics** for optimization
+
+Access logs at [codegen.com/agents](https://codegen.com/agents) or via CLI:
+
+```bash
+# View recent agent runs
+codegen agents list
+
+# Stream logs for active agent
+codegen agents logs <agent-id> --follow
+```
+
+<Note>
+  Logs are retained for 30 days and can be exported for compliance or analysis
+  purposes.
+</Note>
+
+## Analytics and Insights
+
+Transform your Claude Code usage into actionable intelligence. The analytics dashboard provides deep insights into how AI is transforming your development workflow.
+
+Track key metrics:
+
+- **Token usage** to understand costs and optimize prompts
+- **Task completion rates** and success patterns
+- **Integration usage** showing which tools Claude uses most
+- **Team adoption** identifying power users and best practices
+
+Access detailed analytics at [codegen.com/analytics](https://codegen.com/analytics).
+
+<Tip>
+  Use analytics to identify repetitive tasks that could be automated with
+  background agents, maximizing your team's productivity gains.
+</Tip>
+
+## What's Next
+
+Claude Code integration is just the beginning. We're actively working on:
+
+- OpenAI Codex support for GPT-4 workflows
+- Gemini CLI integration for Google's models
+- Enhanced MCP protocol features
+- Custom model deployment options
+
+Join our [community Slack](https://community.codegen.com) to stay updated and share your Claude Code workflows with other developers.