# Retrieving Traces
Source: https://docs.codegen.com/api-reference/agent-run-logs
The Agent Run Logs API allows you to retrieve detailed execution logs for agent runs, providing insights into the agent's thought process, tool usage, and execution flow.
## Endpoint
```
GET /v1/organizations/{org_id}/agent/run/{agent_run_id}/logs
```
## Authentication
This endpoint requires API token authentication. Include your token in the Authorization header:
```bash
Authorization: Bearer YOUR_API_TOKEN
```
## Parameters
| Parameter | Type | Required | Description |
| -------------- | ------- | -------- | --------------------------------------------------------- |
| `org_id` | integer | Yes | Your organization ID |
| `agent_run_id` | integer | Yes | The ID of the agent run to retrieve logs for |
| `skip` | integer | No | Number of logs to skip for pagination (default: 0) |
| `limit` | integer | No | Maximum number of logs to return (default: 100, max: 100) |
## Response Structure
The endpoint returns an `AgentRunWithLogsResponse` object containing the agent run details and paginated logs:
```json
{
"id": 12345,
"organization_id": 67890,
"status": "completed",
"created_at": "2024-01-15T10:30:00Z",
"web_url": "https://app.codegen.com/agent/trace/12345",
"result": "Task completed successfully",
"logs": [
{
"agent_run_id": 12345,
"created_at": "2024-01-15T10:30:15Z",
"tool_name": "ripgrep_search",
"message_type": "ACTION",
"thought": "I need to search for the user's function in the codebase",
"observation": {
"status": "success",
"results": ["Found 3 matches..."]
},
"tool_input": {
"query": "function getUserData",
"file_extensions": [".js", ".ts"]
},
"tool_output": {
"matches": 3,
"files": ["src/user.js", "src/api.ts"]
}
}
],
"total_logs": 25,
"page": 1,
"size": 100,
"pages": 1
}
```
## Agent Run Log Fields
Each log entry in the `logs` array contains the following fields:
### Core Fields
| Field | Type | Description |
| -------------- | ------- | --------------------------------------------------------- |
| `agent_run_id` | integer | The ID of the agent run this log belongs to |
| `created_at` | string | ISO 8601 timestamp when the log entry was created |
| `message_type` | string | The type of log entry (see [Log Types](#log-types) below) |
### Agent Reasoning Fields
| Field | Type | Description |
| --------- | -------------- | --------------------------------------------------------------- |
| `thought` | string \| null | The agent's internal reasoning or thought process for this step |
### Tool Execution Fields
| Field | Type | Description |
| ------------- | ------------------------ | ------------------------------------------------------------------------------ |
| `tool_name` | string \| null | Name of the tool being executed (e.g., "ripgrep\_search", "file\_write") |
| `tool_input` | object \| null | JSON object containing the parameters passed to the tool |
| `tool_output` | object \| null | JSON object containing the tool's execution results |
| `observation` | object \| string \| null | The agent's observation of the tool execution results or other contextual data |
## Log Types
The `message_type` field indicates the type of log entry. Here are the possible values:
### Plan Agent Types
| Type | Description |
| --------------------------- | ------------------------------------------------------------------- |
| `ACTION` | The agent is executing a tool or taking an action |
| `PLAN_EVALUATION` | The agent is evaluating or updating its plan |
| `FINAL_ANSWER` | The agent is providing its final response or conclusion |
| `ERROR` | An error occurred during execution |
| `USER_MESSAGE` | A message from the user (e.g., interruptions or additional context) |
| `USER_GITHUB_ISSUE_COMMENT` | A comment from a GitHub issue that the agent is processing |
### PR Agent Types
| Type | Description |
| ----------------------- | -------------------------------------------------- |
| `INITIAL_PR_GENERATION` | The agent is generating the initial pull request |
| `DETECT_PR_ERRORS` | The agent is detecting errors in a pull request |
| `FIX_PR_ERRORS` | The agent is fixing errors found in a pull request |
| `PR_CREATION_FAILED` | Pull request creation failed |
| `PR_EVALUATION` | The agent is evaluating a pull request |
### Commit Agent Types
| Type | Description |
| ------------------- | ------------------------------- |
| `COMMIT_EVALUATION` | The agent is evaluating commits |
### Link Types
| Type | Description |
| ---------------- | ----------------------------------- |
| `AGENT_RUN_LINK` | A link to another related agent run |
## Field Population Patterns
Different log types populate different fields:
### ACTION Logs
* Always have: `tool_name`, `tool_input`, `tool_output`
* Often have: `thought`, `observation`
* Example: Tool executions like searching code, editing files, creating PRs
### PLAN\_EVALUATION Logs
* Always have: `thought`
* May have: `observation`
* Rarely have: Tool-related fields
* Example: Agent reasoning about next steps
### ERROR Logs
* Always have: `observation` (containing error details)
* May have: `tool_name` (if error occurred during tool execution)
* Example: Failed tool executions or system errors
### FINAL\_ANSWER Logs
* Always have: `observation` (containing the final response)
* May have: `thought`
* Example: Agent's final response to the user
## Usage Examples
### Basic Log Retrieval
```python
import requests
url = "https://api.codegen.com/v1/organizations/67890/agent/run/12345/logs"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
response = requests.get(url, headers=headers)
data = response.json()
print(f"Agent run status: {data['status']}")
print(f"Total logs: {data['total_logs']}")
for log in data['logs']:
print(f"[{log['created_at']}] {log['message_type']}: {log['thought']}")
```
### Filtering by Log Type
```python
# Get only ACTION logs to see tool executions
action_logs = [log for log in data['logs'] if log['message_type'] == 'ACTION']
for log in action_logs:
print(f"Tool: {log['tool_name']}")
print(f"Input: {log['tool_input']}")
print(f"Output: {log['tool_output']}")
print("---")
```
### Pagination Example
```python
# Get logs in batches of 50
skip = 0
limit = 50
all_logs = []
while True:
url = f"https://api.codegen.com/v1/organizations/67890/agent/run/12345/logs?skip={skip}&limit={limit}"
response = requests.get(url, headers=headers)
data = response.json()
all_logs.extend(data['logs'])
if len(data['logs']) < limit:
break # No more logs
skip += limit
print(f"Retrieved {len(all_logs)} total logs")
```
### Debugging Failed Runs
```python
# Find error logs to debug issues
error_logs = [log for log in data['logs'] if log['message_type'] == 'ERROR']
for error_log in error_logs:
print(f"Error at {error_log['created_at']}: {error_log['observation']}")
if error_log['tool_name']:
print(f"Failed tool: {error_log['tool_name']}")
```
## Common Use Cases
### 1. Building Monitoring Dashboards
Use the logs to create dashboards showing:
* Agent execution progress
* Tool usage patterns
* Error rates and types
* Execution timelines
### 2. Debugging Agent Behavior
Analyze logs to understand:
* Why an agent made certain decisions
* Where errors occurred in the execution flow
* What tools were used and their results
### 3. Audit and Compliance
Track agent actions for:
* Code change auditing
* Compliance reporting
* Security monitoring
### 4. Performance Analysis
Monitor:
* Tool execution times
* Common failure patterns
* Agent reasoning efficiency
## Rate Limits
* **60 requests per 60 seconds** per API token
* Rate limits are shared across all API endpoints
## Error Responses
| Status Code | Description |
| ----------- | ------------------------------------------- |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid or missing API token |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Agent run not found |
| 429 | Too Many Requests - Rate limit exceeded |
## Feedback and Support
Since this endpoint is in ALPHA, we'd love your feedback! Please reach out through:
* [Community Slack](https://join.slack.com/t/codegen-community/shared_invite/zt-2p4xjjzjx-1~3tTbJWZWQUYOLAhvG5rA)
* [GitHub Issues](https://github.com/codegen-sh/codegen-sdk/issues)
* Email: [support@codegen.com](mailto:support@codegen.com)
The structure and fields of this API may change as we gather feedback and
improve the service. We'll provide advance notice of any breaking changes.
# Get Agent Run Logs
Source: https://docs.codegen.com/api-reference/agents-alpha/get-agent-run-logs
api-reference/openapi3.json get /v1/alpha/organizations/{org_id}/agent/run/{agent_run_id}/logs
Retrieve an agent run with its logs using pagination. This endpoint is currently in ALPHA and IS subject to change.
Returns the agent run details along with a paginated list of logs for the specified agent run.
The agent run must belong to the specified organization. Logs are returned in chronological order.
Uses standard pagination parameters (skip and limit) and includes pagination metadata in the response.
Rate limit: 60 requests per 60 seconds.
# Ban All Checks For Agent Run
Source: https://docs.codegen.com/api-reference/agents/ban-all-checks-for-agent-run
api-reference/openapi3.json post /v1/organizations/{org_id}/agent/run/ban
Ban all checks for a PR and stop all related agents.
This endpoint:
1. Flags the PR to prevent future CI/CD check suite events from being processed
2. Stops all current agents for that PR
# Create Agent Run
Source: https://docs.codegen.com/api-reference/agents/create-agent-run
api-reference/openapi3.json post /v1/organizations/{org_id}/agent/run
Create a new agent run.
Creates and initiates a long-running agent process based on the provided prompt.
The process will complete asynchronously, and the response contains the agent run ID
which can be used to check the status later. The requesting user must be a member
of the specified organization.
This endpoint accepts both a text prompt and an optional image file upload.
Rate limit: 10 requests per minute.
# Get Agent Run
Source: https://docs.codegen.com/api-reference/agents/get-agent-run
api-reference/openapi3.json get /v1/organizations/{org_id}/agent/run/{agent_run_id}
Retrieve the status and result of an agent run.
Returns the current status, progress, and any available results for the specified agent run.
The agent run must belong to the specified organization. If the agent run is still in progress,
this endpoint can be polled to check for completion.
Rate limit: 60 requests per 30 seconds.
# List Agent Runs
Source: https://docs.codegen.com/api-reference/agents/list-agent-runs
api-reference/openapi3.json get /v1/organizations/{org_id}/agent/runs
List agent runs for an organization with optional user filtering.
Returns a paginated list of agent runs for the specified organization.
Optionally filter by user_id to get only agent runs initiated by a specific user.
Results are ordered by creation date (newest first).
Rate limit: 60 requests per 30 seconds.
# Remove Codegen From Pr
Source: https://docs.codegen.com/api-reference/agents/remove-codegen-from-pr
api-reference/openapi3.json post /v1/organizations/{org_id}/agent/run/remove-from-pr
Remove Codegen from a PR.
This endpoint performs the same action as banning all checks but with more user-friendly naming.
It:
1. Flags the PR to prevent future CI/CD check suite events from being processed
2. Stops all current agents for that PR
# Resume Agent Run
Source: https://docs.codegen.com/api-reference/agents/resume-agent-run
api-reference/openapi3.json post /v1/organizations/{org_id}/agent/run/resume
Resume a paused agent run.
Resumes a paused agent run, allowing it to continue processing.
Note: Setup commands agents are automatically routed to their dedicated resume function.
# Unban All Checks For Agent Run
Source: https://docs.codegen.com/api-reference/agents/unban-all-checks-for-agent-run
api-reference/openapi3.json post /v1/organizations/{org_id}/agent/run/unban
Unban all checks for a PR.
This endpoint:
1. Removes the ban flag from the PR to allow future CI/CD check suite events to be processed
2. Handles both URL-based bans and parent-agent-run-based bans
# Authentication
Source: https://docs.codegen.com/api-reference/authentication
All Codegen API endpoints require authentication using Bearer tokens. You'll need both an API token and your organization ID to get started.
## Get Your Credentials
Visit the developer settings to generate your API token and find your
organization ID.
## Required Information
### API Token
Your personal API token authenticates all requests to the Codegen API. This token is tied to your user account and inherits your permissions within organizations.
### Organization ID
Most API endpoints require an organization ID to specify which organization's resources you want to access. You can find your organization ID in the developer settings.
## Using Your Credentials
### REST API
Include your API token in the Authorization header for all requests:
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
"https://api.codegen.com/v1/organizations/YOUR_ORG_ID/agent/run"
```
### Python SDK
The Python SDK makes authentication simple:
```python
from codegen import Agent
# Initialize with your credentials
agent = Agent(org_id="YOUR_ORG_ID", token="YOUR_API_TOKEN")
# The SDK handles authentication automatically
task = agent.run(prompt="Fix the bug in user authentication")
```
# Get Cli Rules
Source: https://docs.codegen.com/api-reference/cli-rules/get-cli-rules
api-reference/openapi3.json get /v1/organizations/{org_id}/cli/rules
Get organization and user rules for CLI applications.
This endpoint is designed for CLI applications that need to fetch both organization-specific
rules and user-specific custom prompts that are used in prompts. This includes:
- Organization rules: Same as MCP organization_rules prompt and agent prompt builders
- User custom prompt: Same as MCP user_custom_prompt and agent prompt builders
Returns the rules and prompts that should be followed by AI agents.
Rate limit: 30 requests per minute.
# Get Organization Integrations Endpoint
Source: https://docs.codegen.com/api-reference/integrations/get-organization-integrations-endpoint
api-reference/openapi3.json get /v1/organizations/{org_id}/integrations
Get all integration statuses for the given organization.
Returns a comprehensive overview of all integrations configured for the organization,
including:
- OAuth-based integrations (Slack, Linear, Notion, Figma, ClickUp, Jira, Sentry, Monday.com)
- GitHub app installations
- API key-based integrations (CircleCI)
- Database connections (PostgreSQL)
Each integration includes its current status (active/inactive), associated token/installation IDs,
and relevant metadata such as app names, organization names, etc.
Rate limit: 60 requests per 30 seconds.
# Get Mcp Providers
Source: https://docs.codegen.com/api-reference/organizations/get-mcp-providers
api-reference/openapi3.json get /v1/mcp-providers
Get all MCP providers from oauth_providers table.
Returns only providers with is_mcp=True.
# Get Oauth Token Status
Source: https://docs.codegen.com/api-reference/organizations/get-oauth-token-status
api-reference/openapi3.json get /v1/oauth/tokens/status
Get list of providers that have active OAuth tokens for the current user and organization.
Returns a list of provider names that are connected.
# Get Organizations
Source: https://docs.codegen.com/api-reference/organizations/get-organizations
api-reference/openapi3.json get /v1/organizations
Get organizations for the authenticated user.
Returns a paginated list of all organizations that the authenticated user is a member of.
Results include basic organization details such as name, ID, and membership information.
Use pagination parameters to control the number of results returned.
Rate limit: 60 requests per 30 seconds.
# Revoke Oauth Token
Source: https://docs.codegen.com/api-reference/organizations/revoke-oauth-token
api-reference/openapi3.json post /v1/oauth/tokens/revoke
Revoke/disconnect an OAuth token for a specific provider.
Marks ALL tokens as inactive (is_active=False) for the current user and organization.
# Codegen API
Source: https://docs.codegen.com/api-reference/overview
The Codegen API provides programmatic access to create and manage AI agents, enabling you to integrate Codegen's capabilities into your own applications and workflows.
## What You Can Do
**[Create and manage AI agents](/api-reference/agents/create-agent-run)** that can write code, fix bugs, and handle development tasks across your repositories with full programmatic control over their execution and monitoring. **[Access your organization data](/api-reference/organizations/get-organizations)** including users, repositories, integrations, and **[programmatically retrieve detailed agent traces](/api-reference/agent-run-logs)** for analysis and debugging.
All agents created through the API are fully configurable and viewable in the
Codegen web UI at codegen.com, allowing seamless integration between
programmatic and manual workflows.
Not seeing a capability you want? Get in touch! Join our [community
Slack](https://community.codegen.com) or email us at [support@codegen.com](mailto:support@codegen.com).
## Authentication
All API endpoints require authentication using Bearer tokens and your organization ID.
Get your API token and organization ID to start using the Codegen API.
## Rate Limits
The API includes rate limiting to ensure fair usage:
* **Standard endpoints**: 60 requests per 30 seconds
* **Agent creation**: 10 requests per minute
* **Setup commands**: 5 requests per minute
* **Log analysis**: 5 requests per minute
## Getting Started
### 1. Create Your First Agent Run
```bash
curl -X POST "https://api.codegen.com/v1/organizations/{org_id}/agent/run" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Add error handling to the user authentication function",
"repo_id": 123
}'
```
### 2. Check Agent Status
```bash
curl "https://api.codegen.com/v1/organizations/{org_id}/agent/run/{agent_run_id}" \
-H "Authorization: Bearer YOUR_API_KEY"
```
### 3. Resume with Follow-up
```bash
curl -X POST "https://api.codegen.com/v1/organizations/{org_id}/agent/run/resume" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_run_id": 456,
"prompt": "Also add unit tests for the error handling"
}'
```
## Use Cases
**Automated Workflows**
* Trigger agents from CI/CD pipelines when builds fail
* Create agents in response to issue tracking system events
* Automate code reviews and quality checks
**Custom Integrations**
* Build Codegen into your existing development tools
* Create custom dashboards for agent activity
* Integrate with internal systems and workflows
**Batch Operations**
* Process multiple repositories with consistent changes
* Generate setup commands for new projects
* Analyze logs across multiple sandbox environments
## Explore the API
Explore all available endpoints with detailed schemas and examples.
Learn how to retrieve and analyze detailed agent execution logs.
## SDKs and Tools
For easier integration, we recommend using our Python SDK which provides a simple wrapper around the API:
Use the Codegen Python SDK for a pythonic interface to create and manage
agents programmatically.
**Also available:**
* **[CLI Tool](/introduction/cli)** - Command-line interface for common API operations
The API is RESTful and returns JSON responses. All endpoints support standard
HTTP status codes and include detailed error messages for troubleshooting.
# Edit Pull Request
Source: https://docs.codegen.com/api-reference/pull-requests/edit-pull-request
api-reference/openapi3.json patch /v1/organizations/{org_id}/repos/{repo_id}/prs/{pr_id}
Edit pull request properties (RESTful endpoint).
Update the state of a pull request (open, closed, draft, ready_for_review).
This endpoint requires both repo_id and pr_id for RESTful compliance.
The requesting user must have write permissions to the repository.
Rate limit: 30 requests per minute.
# Edit Pull Request Simple
Source: https://docs.codegen.com/api-reference/pull-requests/edit-pull-request-simple
api-reference/openapi3.json patch /v1/organizations/{org_id}/prs/{pr_id}
Edit pull request properties (simple endpoint).
Update the state of a pull request (open, closed, draft, ready_for_review).
This endpoint only requires the PR ID, not the repo ID.
The requesting user must have write permissions to the repository.
Rate limit: 30 requests per minute.
# Get Check Suite Settings
Source: https://docs.codegen.com/api-reference/repositories/get-check-suite-settings
api-reference/openapi3.json get /v1/organizations/{org_id}/repos/check-suite-settings
Get check suite settings for a repository.
# Get Repositories
Source: https://docs.codegen.com/api-reference/repositories/get-repositories
api-reference/openapi3.json get /v1/organizations/{org_id}/repos
Get repositories for the specified organization.
Returns a paginated list of all repositories that belong to the specified organization.
Results include repository details such as name, ID, description, visibility, and setup status.
Use pagination parameters to control the number of results returned.
Rate limit: 60 requests per 30 seconds.
# Update Check Suite Settings
Source: https://docs.codegen.com/api-reference/repositories/update-check-suite-settings
api-reference/openapi3.json put /v1/organizations/{org_id}/repos/check-suite-settings
Update check suite settings for a repository.
# Analyze Sandbox Logs
Source: https://docs.codegen.com/api-reference/sandbox/analyze-sandbox-logs
api-reference/openapi3.json post /v1/organizations/{org_id}/sandbox/{sandbox_id}/analyze-logs
Analyze sandbox setup logs using an AI agent.
This endpoint creates an AI agent that will analyze the setup logs from a sandbox,
identify any errors, provide insights about what went wrong, and suggest potential
solutions. The analysis runs asynchronously and results can be retrieved using the
returned agent run ID.
Rate limit: 5 requests per minute.
# Generate Setup Commands
Source: https://docs.codegen.com/api-reference/setup-commands/generate-setup-commands
api-reference/openapi3.json post /v1/organizations/{org_id}/setup-commands/generate
Generate setup commands for a repository.
Creates and initiates a setup command generation agent for the specified repository.
The agent will analyze the repository structure and generate appropriate setup commands.
Rate limit: 5 requests per minute.
# Generate Slack Connect Token Endpoint
Source: https://docs.codegen.com/api-reference/slack-connect/generate-slack-connect-token-endpoint
api-reference/openapi3.json post /v1/slack-connect/generate-token
Generate a temporary token for Slack account connection.
This token:
- Expires in 10 minutes
- Can only be used once
- Must be sent to the Codegen bot in a DM with format: "Connect my account: {token}"
# Get Current User Info
Source: https://docs.codegen.com/api-reference/users/get-current-user-info
api-reference/openapi3.json get /v1/users/me
Get current user information from API token.
Returns detailed information about the user associated with the provided API token.
This is useful for applications that need to identify the current user from their API token.
Rate limit: 60 requests per 30 seconds.
# Get User
Source: https://docs.codegen.com/api-reference/users/get-user
api-reference/openapi3.json get /v1/organizations/{org_id}/users/{user_id}
Get details for a specific user in an organization.
Returns detailed information about a user within the specified organization.
The requesting user must be a member of the organization to access this endpoint.
Rate limit: 60 requests per 30 seconds.
# Get Users
Source: https://docs.codegen.com/api-reference/users/get-users
api-reference/openapi3.json get /v1/organizations/{org_id}/users
Get users for the specified organization.
Returns a paginated list of all users that belong to the specified organization.
Results include user details such as name, email, GitHub username, and avatar.
Use pagination parameters to control the number of results returned.
Rate limit: 60 requests per 30 seconds.
# Analytics
Source: https://docs.codegen.com/capabilities/analytics
What impact are code agents having on your codebase (and your finances) today? How can you better deploy them across your org?
Codegen Analytics was built to answer these questions and more.
Access detailed analytics on agent performance, costs, and team productivity.
## Key Metrics
Track the metrics that matter most for your development workflow:
* **Pull Request Analytics** - Monitor code merged, review velocity, and contributor activity
* **Agent Tool Usage** - See which tools agents use most frequently and their success rates
* **Cost Analysis** - Track spending across different models, agents, and time periods
* **Performance Insights** - Analyze agent response times and task completion rates
* **Team Activity** - Understand how different team members interact with agents
## Features
### Pull Request Tracking
* **Merge velocity** - Track how quickly PRs are created and merged
* **Author activity** - See contributor patterns and productivity trends
* **Status monitoring** - Monitor PR states and resolution times
### Detailed Filtering
* **Date range selection** - Analyze data over custom time periods
* **User-specific views** - Filter by individual team members
* **Status filtering** - Focus on specific PR states or outcomes
* **Interactive charts** - Explore data with dynamic visualizations
### Real-time Insights
* **Live dashboards** - Get up-to-date metrics on agent activity
* **Trend analysis** - Identify patterns in agent usage and effectiveness
* **Cost optimization** - Make informed decisions about model selection and usage
## Use Cases
**Performance Optimization**
* Identify which agents and tools provide the best ROI
* Optimize model selection based on cost and performance data
* Track improvement in development velocity over time
**Team Insights**
* Understand how different team members leverage AI assistance
* Identify opportunities for increased agent adoption
* Monitor the impact of agents on overall productivity
**Cost Management**
* Track spending across different LLM providers and models
* Identify high-cost operations and optimize usage patterns
* Budget and forecast AI assistance costs
Use analytics to continuously optimize your agent workflows and demonstrate
the value of AI assistance to your organization.
# How Codegen Agents Work
Source: https://docs.codegen.com/capabilities/capabilities
Codegen agents follow a simple but powerful workflow: they're triggered from your existing tools, work in secure sandboxes to implement changes, create pull requests, and then monitor and fix any issues that arise. This creates a seamless development experience that integrates naturally with your team's existing processes.
## The Agent Happy Path
Here's how Codegen agents work from start to finish:
```mermaid
graph TD
A[Trigger from Integration] --> B[Work in Remote Sandbox]
B --> C[Create Pull Request]
C --> D[Monitor CI Checks]
D --> E[Auto-fix Failed Checks]
E --> D
D --> D1[All checks pass ✓]
D1 --> G[Ready for Review]
G --> F[Respond to Follow-up Questions]
F --> G
A1[Slack @mention] --> A
A2[Linear issue assignment] --> A
A3[GitHub issue comment] --> A
```
### 1. Users Trigger `@codegen` to Perform Tasks
Agents activate seamlessly from the platforms you already use:
* **[Slack](/integrations/slack)** - Tag `@codegen` in any channel or send a direct message
* **[Linear](/integrations/linear)** - Assign an issue to Codegen or mention it in comments
* **[Jira](/integrations/jira)** - Assign an issue to Codegen or mention it in comments
* **[ClickUp](/integrations/clickup)** - Assign a task to Codegen or mention it in comments
* **[Monday.com](/integrations/monday)** - Assign an item to Codegen or mention it in comments
* **[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. `@codegen` Performs Work in Secure Sandboxes
Once triggered, agents work in **[isolated sandbox environments](/sandboxes/overview)** where they can:
* Execute code safely without affecting your systems
* Install dependencies and run tests
* Make changes and validate them before committing
* Access your repository context while maintaining security
### 3. Users Receive Completed Pull-Requests
Agents create **[GitHub pull requests](/integrations/github)** with:
* Detailed descriptions explaining the changes
* Links back to the original request (Linear issue, Slack thread, etc.)
* Clean, tested code ready for review
* Proper commit messages following your conventions
### 4. Agents Monitor and Auto-fix PR Issues
The **[Checks Auto-fixer](/capabilities/checks-autofixer)** ensures quality by:
* Monitoring CI/CD pipeline results in real-time
* Automatically analyzing build failures and test errors
* Pushing targeted fixes to resolve issues
* Retrying up to 3 times before escalating to humans
### 5. Agents Respond to Follow-ups
Agents remain active to handle questions and refinements:
* Respond to PR review comments with additional changes
* Answer questions in the original Slack thread or Linear issue
* Make adjustments based on feedback from team members
* Provide explanations of their implementation decisions
## Configuration & Customization
Codegen agents can be customized to match your team's specific workflows and requirements:
### Model Selection
Choose from leading AI models and configure custom API keys to optimize performance and cost for your organization.
Select LLM providers, configure custom API keys, and optimize performance
settings.
### Agent Behavior
Control how agents interact with users and approach code modifications to ensure they align with your team's preferences.
Configure plan proposals, GitHub mention requirements, and interaction
patterns.
### Security & Permissions
Define what actions agents are allowed to perform across your organization with fine-grained permission controls.
Control PR creation, rules detection, and enforce security policies like
signed commits.
Start with conservative settings and gradually expand agent capabilities as
your team becomes comfortable with AI assistance.
## Learn More
Dive deeper into specific capabilities:
* **[Get started with the overview](/introduction/overview)** - Complete introduction to Codegen
* **[Explore integrations](/integrations/integrations)** - See all available platforms and tools
* **[Understand sandboxes](/sandboxes/overview)** - Learn about the secure execution environment
* **[Configure settings](/settings/settings)** - Customize agent behavior and permissions
* **[View analytics](/capabilities/analytics)** - Monitor agent performance and impact
# Check Suite Auto-fixer
Source: https://docs.codegen.com/capabilities/checks-autofixer
When GitHub checks fail on a Codegen PR, Codegen agents will automatically "wake up", analyze the failure, and push fix commits.
This intelligent system monitors CI status and proactively resolves issues without manual intervention.
Configure globally at the organization level or customize settings per
repository. Enterprise plans can adjust retry limits for optimal performance.
Codegen will try to fix broken checks 3 times before "tapping out" by default.
Enterprise customers can customize the retry count per check or per
repository.
## How Checks Auto-Fixer Works
Codegen continuously monitors your pull requests and automatically responds to check failures:
* **Automatic Detection:** Monitors GitHub check runs and CI status in real-time
* **Intelligent Analysis:** Analyzes build logs, test failures, and error messages to understand root causes
* **Targeted Fixes:** Generates specific code changes to resolve the identified issues
* **Persistent Retry:** Will attempt to fix issues up to 3 times per PR
## What Triggers Auto-Fixing
Check auto-fixing activates when:
* **CI Checks Fail:** Any GitHub check run reports a failure status
* **Build Errors:** Compilation, linting, or build process failures
* **Test Failures:** Unit tests, integration tests, or automated test suites fail
* **Code Quality Issues:** Static analysis tools report violations or warnings
## The Auto-Fix Process
When Codegen auto-fixes a failing PR, it follows this process:
1. **Detect Failure:** Monitor check status and identify when builds break
2. **Analyze Logs:** Grep through CI logs to understand specific failure points
3. **Generate Solution:** Create targeted code changes to resolve identified issues
4. **Apply Fix:** Automatically commit fixes to the same PR branch
5. **Re-validate:** Monitor the new check run to ensure the fix was successful
## Retry Logic
Codegen implements intelligent retry behavior:
* **Default: 3 attempts** per PR to resolve failing checks
* **Enterprise customization** - Enterprise customers can configure retry limits:
* Set global defaults at the organization level
* Override per repository in repository settings
* Customize retry counts per individual check type
* **Progressive analysis** - each retry incorporates learnings from previous attempts
* **Failure escalation** - when retry limit is reached, the issue is flagged for human review
## Configuration Options
The Checks Auto-Fixer can be configured at multiple levels:
### Organization Level
* **Global settings** - Configure default behavior for all repositories
* **Available to all plans** - Enable/disable the feature organization-wide
* **Access via** - Organization Settings → Checks Auto-Fixer
### Repository Level
* **Per-repo overrides** - Customize settings for specific repositories
* **Individual check control** - Enable/disable monitoring per check type
* **Custom instructions** - Provide specific guidance for handling each check
* **Access via** - Repository Settings → Checks Auto-Fixer
### Enterprise Features
* **Custom retry limits** - Set retry counts globally, per repository, or per check type
* **Advanced monitoring** - Granular control over which checks to monitor
* **Priority handling** - Configure high-priority checks for immediate processing
## GitHub Integration
The auto-fix system integrates deeply with GitHub:
* **Check Run Annotations:** Creates detailed feedback with line-specific suggestions
* **PR Comments:** Adds contextual suggestions and explanations
* **Auto-Fix Actions:** Provides one-click fix buttons in the GitHub UI
* **Status Updates:** Real-time updates on fix progress and results
Checks Auto-Fixer only activates for repositories where Codegen has write
access and the feature is enabled. It respects your repository permissions and
team workflows.
# Claude Code Integration
Source: https://docs.codegen.com/capabilities/claude-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.
## 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
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.
## Connect Claude Code to Codegen Tools
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.
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.
## Run Background Agents from your Terminal
Keep your terminal free while Claude handles long-running tasks. Background agents run asynchronously, perfect for automation that doesn't need constant supervision.
## 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.
Enable Claude Code mode to run all agents in secure sandboxes with full
integration support.
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.
To use claude with codegen, ensure you have claude installed and available on your system.
## 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).
Use analytics to identify repetitive tasks that could be automated with
background agents, maximizing your team's productivity gains.
## 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.
# PR Review Agent
Source: https://docs.codegen.com/capabilities/pr-review
Codegen provides AI code review as a first-class supported feature.
Set up PR review at the organization level, then customize per repository.
## How It Works
When PR review is enabled on a repo, a Codegen agent will spin up to leave a detailed review.
This includes:
* **Inline comments** on specific lines with actionable feedback
* **Security scanning** for vulnerabilities and unsafe patterns
* **Code quality** suggestions for maintainability and best practices
* **Architectural feedback** on design patterns and structure
## Configuration
Configure PR reviews at two levels:
### Organization Settings
Set global defaults and organization-wide review rules at [Organization Settings → PR Review](https://codegen.com/settings/review).
### Repository Settings
Override settings and add repository-specific rules at **Repository Settings → Review**.
Repository rules are combined with organization rules for comprehensive coverage. You can:
* Enable/disable PR reviews for the repository
* Add custom review guidelines specific to the codebase
* Define language-specific requirements
* Set repository-specific coding standards
Start with organization-level settings, then customize individual repositories
as needed.
PR reviews require read access to your repository. Enable the feature at both
organization and repository levels to activate reviews.
# Triggering Codegen
Source: https://docs.codegen.com/capabilities/triggering-codegen
Codegen is designed to work where you work. Trigger agents from your existing tools and they'll respond right where the conversation started.
## Trigger Methods
### From Your Tools
* **[Slack](/integrations/slack)** - Mention `@codegen` in any channel or DM
* **[Linear](/integrations/linear)** - Assign issues to Codegen or mention in comments
* **[Jira](/integrations/jira)** - Assign issues to Codegen or `@mention` in comments
* **[ClickUp](/integrations/clickup)** - Assign tasks to Codegen or mention in comments
* **[Monday.com](/integrations/monday)** - Assign items to Codegen or mention in comments
* **[GitHub](/integrations/github)** - Comment on PRs or issues with `@codegen-agent`
### From Codegen
* **[Web UI](https://codegen.com/new)** - Start a new agent run directly from the dashboard
* **[CLI](/introduction/cli)** - Run `codegen agent create "your task"` from your terminal
* **[API](/api-reference/agents/create-agent-run)** - Trigger programmatically for automated workflows
## How Agent Context Works
### One Agent Per Context
Each context gets its own dedicated agent:
* **Slack** - Each thread is a separate agent. Follow-up messages in the same thread route to the same agent
* **Linear/Jira/ClickUp/Monday** - Each ticket is a separate agent. All comments on that ticket go to the same agent
* **GitHub** - Each issue or PR is a separate agent. All comments stay with the same agent
### Shared Context with PRs
When an agent creates a PR:
* The agent **always monitors its own PR** and responds to comments
* Agents triggered from tickets (Linear, Jira, etc.) share context between the ticket and any PRs they create
* Follow-up requests on either the ticket or PR route to the same agent
* **Automatically fixes broken tests** - When CI checks fail, the agent wakes up and pushes fix commits
This means you can start a conversation in Linear, have the agent create a PR,
then continue the discussion on either platform - it's all the same agent with
full context.
Follow-up messages always go to the same agent. Whether you're continuing a
Slack thread, commenting on a ticket, or reviewing a PR - the agent maintains
full conversation history.
Learn more about automatic test fixing in the **[Checks Auto-fixer](/capabilities/checks-autofixer)** documentation.
## All Agents Created Equal
No matter where you trigger from, your request:
1. Routes to a dedicated agent for that context
2. Runs in secure [sandboxes](/sandboxes/overview)
3. Has access to all your [integrations](/integrations/integrations)
4. Creates trackable runs visible at [codegen.com/agents](https://codegen.com/agents)
## Automatic Triggers
Codegen supports certain automated triggers as first-class citizens. These activate without manual intervention to maintain code quality:
* **[Checks Auto-fixer](/capabilities/checks-autofixer)** - Automatically fixes failing CI checks on agent PRs
* **[PR Review](/capabilities/pr-review)** - Provides instant code review feedback on all PRs
These automations work alongside manual triggers. An agent fixing broken tests
can still respond to comments on its PR or the original ticket that triggered
it.
## Learn More
Set up GitHub, Slack, and other tools
Trigger agents from your terminal
Build custom workflows and automations
# CircleCI Integration
Source: https://docs.codegen.com/integrations/circleci
Monitor and automatically fix failing CI checks with CircleCI integration. Codegen views check status, analyzes build logs, and automatically fixes issues when PRs fail. When Codegen creates a PR and checks fail, it will automatically wake up to investigate the logs and push fixes.
CircleCI is currently available for enterprise customers. See
[codegen.com/billing](https://codegen.com/billing) for more
## Capabilities
The CircleCI integration enables intelligent check monitoring and automatic issue resolution:
* **View broken checks and failures** - Monitor CI check status and identify specific failure points
* **Analyze build logs and error messages** - Grep through logs to understand root causes of failures
* **Automatically fix failing PRs** - Push corrective changes when checks fail on Codegen-created PRs
* **Wake up on check failures** - Automatically trigger when CI checks fail to investigate and resolve issues
## Permissions
The Codegen CircleCI integration requires the following permissions:
* **Read project information and settings** - Access pipeline configurations and project details
* **View build history and logs** - Monitor pipeline execution and analyze failure logs
* **Read test results and artifacts** - Access build outputs, test reports, and error details
* **Access check status and details** - Monitor CI check results and failure information
Codegen operates in read-only mode for CircleCI - it monitors and analyzes but
does not trigger builds or modify CI configurations.
## How Agents Use CircleCI
Agents leverage the CircleCI integration to:
* **Monitor Check Status:** Continuously watch for CI check failures on pull requests
* **Analyze Failure Logs:** Grep through build logs to identify specific errors, test failures, or build issues
* **Auto-Fix Issues:** When Codegen creates a PR and checks fail, it automatically investigates and pushes fixes
* **Prevent Broken Merges:** Ensure code quality by resolving CI failures before merge
## Automatic Wake-Up Behavior
When Codegen creates a pull request and CircleCI checks fail, Codegen will automatically:
1. **Detect the failure** - Monitor check status and identify when builds break
2. **Analyze the logs** - Grep through CircleCI logs to understand the specific failure
3. **Generate fixes** - Create targeted code changes to resolve the identified issues
4. **Push updates** - Automatically commit fixes to the same PR branch
This ensures that Codegen-created PRs maintain high quality and don't introduce breaking changes to your codebase.
## Installation
Connect your CircleCI account to Codegen to enable automatic check monitoring and issue resolution.
Authorize Codegen to view your CircleCI check results and build logs.
Ensure the agent has access to the specific CircleCI projects and
organizations you want it to monitor.
{" "}
# ClickUp Integration
Source: https://docs.codegen.com/integrations/clickup
export const COMMUNITY_SLACK_URL = "https://community.codegen.com";
Codegen supports ClickUp as a first-class integration. Assign issues, create issues, perform triage and more.
## Installation
Connect your ClickUp workspace to Codegen to enable agent interactions.
Authorize Codegen to access your ClickUp workspace and project data.
The ClickUp integration is currently in beta. Please reach out in the{" "}
community to have it enabled for your
Codegen account.
## Capabilities
The ClickUp integration provides comprehensive task management capabilities:
* **Create tasks in your workspace** - Generate new tasks automatically based on development needs and project requirements
* **Update existing tasks and status** - Modify task details, progress, and completion status as work advances
* **Read workspace structure and data** - Access project hierarchies, spaces, folders, and lists to understand organization
* **Add comments to tasks and discussions** - Provide updates, ask questions, and facilitate team collaboration
* **Assign tasks to team members** - Route work to appropriate developers and coordinate team workload
* **Access custom fields and properties** - Work with specialized data fields and project-specific information
* **Read and update task dependencies** - Manage task relationships and project workflow dependencies
* **View workspace members and teams** - Access team structure for proper task assignment and collaboration
## Permissions
The Codegen ClickUp integration requires the following permissions:
* **Create tasks in your workspace** - Generate new tasks and to-do items as needed
* **Update existing tasks and status** - Modify task progress, completion status, and details
* **Read workspace structure and data** - Access project organization, spaces, and folder structures
* **Add comments to tasks and discussions** - Provide updates and facilitate collaboration
* **Assign tasks to team members** - Route work to appropriate team members
* **Access custom fields and properties** - Work with specialized project data and configurations
* **Read and update task dependencies** - Manage workflow relationships between tasks
* **View workspace members and teams** - Access team information for proper task management
## How Agents Use ClickUp
Agents leverage the ClickUp integration to:
* **Track Work:** Automatically update the status of tasks they are working on
* **Create Tasks:** Generate new tasks for follow-up work, bugs discovered, or sub-tasks
* **Link Development:** Connect implemented changes and GitHub PRs directly to relevant ClickUp tasks
* **Provide Updates:** Add comments to tasks with progress reports, results, or questions
* **Manage Dependencies:** Update task relationships as development work progresses
* **Coordinate Teams:** Assign and reassign tasks based on workload and expertise
**Data Access Notice:** Workspace content can be surfaced in agent runs by any
of your Codegen account members. Do not connect sensitive workspaces.
The ClickUp integration requires feature flag access. Contact your team
administrator to enable this integration.
# Figma Integration
Source: https://docs.codegen.com/integrations/figma
AI is one of the most valuable collaborators for front-end modifications, UI updates, messaging, and crafting the aesthetic of what you're building. Codegen can now do serious work on both implementation and contributing to your design documentation, bridging the gap between design and code seamlessly.
## Installation
Connect your Figma account to Codegen to enable design-to-code workflows.
Authorize Codegen to access your Figma files and design resources.
## Capabilities
The Figma integration enables seamless design-to-code workflows:
* **Access design specifications** - Read design files, components, and detailed specifications
* **Extract design assets** - Pull images, icons, and visual elements for implementation
* **Convert designs to code** - Transform design mockups into functional frontend code
* **Sync design changes** - Stay updated with design iterations and modifications
## Permissions
The Codegen Figma integration requires the following permissions:
* **Read your profile and user information** - Access basic account details for authentication
* **Access file contents, nodes, and editor data** - Read design files and component structures
* **Read file metadata and version history** - Track design changes and version information
* **View file comments and discussions** - Understand design context and feedback
* **Access design variables and tokens** - Use consistent design system values
* **Read published components and styles** - Access shared design system components
* **Access team library content** - Use shared assets and design resources
* **List projects and project files** - Navigate and organize design files
## How Agents Use Figma
Agents leverage the Figma integration to:
* **Analyze Designs:** Examine design files to understand layout, styling, and component structure
* **Generate Code:** Convert Figma designs into HTML, CSS, React components, or other frontend code
* **Extract Assets:** Pull icons, images, and other visual assets needed for implementation
* **Maintain Design Systems:** Ensure code implementation follows design system guidelines and tokens
The Figma integration requires feature flag access. Contact your team
administrator to enable this integration.
# GitHub Integration
Source: https://docs.codegen.com/integrations/github
GitHub is how Codegen accesses your repository contents and performs all git interactions. Codegen can create PRs from requests or issues, help resolve merge conflicts, conduct code reviews, search through your codebase, and handle the full spectrum of agentic coding workflows—everything flows through GitHub.
## Installation
Authorize Codegen to access your GitHub organizations and repositories.
Click here to install the Codegen GitHub App and grant necessary permissions.
## Capabilities
The GitHub integration provides comprehensive development workflow capabilities:
* **Create and manage pull requests** - Generate, update, and manage PRs with detailed descriptions and context
* **Automated code reviews and feedback** - Provide intelligent code analysis and suggestions
* **Run checks and CI/CD workflows** - Execute automated testing and deployment processes
* **Sync repository changes** - Keep repositories up-to-date and coordinate between branches
## Permissions
The Codegen GitHub integration requires the following permissions to function as a full development team member:
* **Read and write repository contents** - Access code, files, and repository structure
* **Create and manage pull requests** - Generate, update, and merge pull requests
* **Write status checks and CI/CD results** - Report on automated testing and deployment status
* **Read and write issues and comments** - Interact with project issues and provide updates
* **Read repository metadata and settings** - Access repository configuration and settings
* **Read and write GitHub Actions workflows** - Manage automated workflows and CI/CD pipelines
* **Read organization projects and members** - Access team structure and project organization
* **Manage webhooks for real-time updates** - Enable real-time synchronization and notifications
## How Agents Use GitHub
Agents leverage the GitHub integration to:
* **Understand Context:** Read code and related issues/PRs to grasp the task requirements.
* **Implement Changes:** Create branches and commit code directly based on your prompts.
* **Request Reviews:** Open pull requests and automatically request reviews from specified team members.
* **Report Progress:** Comment on related issues or PRs with updates, results, or requests for clarification.
You can manage repository access granularly through the GitHub App settings.
Ensure the agent has access to the specific repositories it needs to work on.
# Integrations
Source: https://docs.codegen.com/integrations/integrations
Codegen agents can work effectively with hundreds of "tools", enabling them to work seamlessly across your existing development stack.
Connect your favorite platforms to enable agents that understand your context and can work across multiple systems.
Give Codegen access to your stack via OAuth or MCP connections
## Core Development
Access repositories, create PRs, conduct code reviews, and manage the full development workflow through GitHub.
Chat with Codegen directly in channels, get real-time notifications, and collaborate seamlessly within your workspace.
## Project Management
Track progress, create issues, and orchestrate teams of humans and agents working together on complex tasks.
{" "}
Manage issues, update project status, and coordinate development workflows
across your team.
{" "}
Create tasks, manage dependencies, and coordinate development workflows with
AI-powered project management.
Automate project management with intelligent task creation, status updates, and team coordination.
## Design & Documentation
Convert designs to code, extract assets, and maintain design systems with seamless design-to-code workflows.
Access your knowledge base, analyze PRDs and specs, and bridge the gap between planning documents and code.
## DevOps & Monitoring
Monitor CI checks, analyze build logs, and automatically fix failing tests and builds.
Analyze errors with automated root cause analysis and intelligent insights for faster issue resolution.
## Data & Search
Query databases, analyze schemas, and generate data-driven reports with secure database access.
Access real-time information from the internet with intelligent search and content analysis capabilities.
## Extensibility
Connect custom tools and services to extend agent capabilities through Model Context Protocol servers.
Access Codegen APIs through a hosted MCP server for seamless AI agent integration.
## Getting Started
Most integrations require authentication and configuration through the [Codegen dashboard](https://codegen.com/integrations). Each integration provides specific capabilities that agents can leverage to assist with your development workflow.
Start with GitHub and Slack for the most comprehensive development experience,
then add project management tools like Linear or Jira based on your team's
workflow.
# Jira Integration
Source: https://docs.codegen.com/integrations/jira
export const COMMUNITY_SLACK_URL = "https://community.codegen.com";
Integrate Codegen with your Jira workspace to allow agents to interact with issues, manage projects, and keep your team updated.
## Installation
Connect your Jira workspace to Codegen to enable agent interactions.
Authorize Codegen to access your Jira workspace and project data.
The Jira integration is currently in beta. Please reach out in the{" "}
community to have it enabled for your
Codegen account.
## Step-by-Step Setup Guide
Follow these steps to successfully connect Codegen to your Jira workspace:
### 1. Enable User-Installed Apps in Jira
* In your Jira workspace, ensure that **user-installed apps** are enabled.
* Make sure the setting to allow user-installed apps is enabled. This is required for the Codegen integration to work properly.
If you don't have admin access to enable user-installed apps, contact your
Jira administrator to enable this setting before proceeding.
### 2. Create a Dedicated Jira User for Codegen
* In your Jira workspace, create a new user account specifically for Codegen.
* **Email:** Use an address with `codegen` in it, like `yourname+codegen@company_domain.com` or `codegen@company_domain.com`.
* **Name:** Set the user's name to **Codegen**. This makes it easy to identify actions performed by Codegen in Jira.
### 3. Authorize Codegen with the New Jira User
* Log in to Jira as the new Codegen user.
* Go to [Codegen's Jira Integration page](https://codegen.com/integrations/jira).
* Click **Connect Jira Workspace** and complete the OAuth flow **using the Codegen Jira user** you just created.
Make sure you are logged in as the Codegen Jira user when authorizing access.
This is to ensure Codegen acts on behalf of the new user and not your personal
account.
### 4. Switch Back to Your Own Jira Account
* After connecting, log out of the Codegen Jira user in Jira.
* Log back in with your personal Jira account.
### 5. Use Codegen in Your Workflow
* On any Jira ticket, `@mention` the Codegen user (e.g., `@Codegen`) to assign or notify Codegen about the issue.
* Codegen will interact with the ticket, update statuses, add comments, and link PRs as needed.
## Capabilities
The Jira integration provides read and write access, enabling agents to manage tasks effectively:
* **Read Access:** Fetch issue details, read comments, view project status, list team members.
* **Write Access:** Update issue status (e.g., to "In Progress", "Done"), add comments, link GitHub PRs to issues, create new issues, assign tasks.
## How Agents Use Jira
Agents use the Jira integration to streamline project management:
* **Track Work:** Automatically update the status of issues they are working on.
* **Link Code:** Connect implemented changes (GitHub PRs) directly to the relevant Jira issue.
* **Provide Updates:** Post comments on issues with progress reports, results, or questions.
* **Create Tasks:** Generate new issues for follow-up work, bugs discovered, or sub-tasks.
# Linear Integration
Source: https://docs.codegen.com/integrations/linear
Linear is designed to orchestrate teams of humans and agents working together. It's the most efficient way to track progress and scale teams of agents to tackle large, complex tasks. Codegen can take a first pass at virtually any issue, breaking down work and making meaningful progress before human review. We recommend letting Codegen handle the initial exploration and implementation of most tasks.
## Installation
Connect your Linear workspace to Codegen to enable agent interactions.
Authorize Codegen to access your Linear workspace via the API settings.
API access allows agents to interact with issues and projects according to
your permissions in Linear.
## Capabilities
The Linear integration provides comprehensive project management capabilities:
* **Create and update issues automatically** - Generate new tasks and update existing ones based on development needs
* **Track development progress** - Monitor and report on the status of ongoing work
* **Link code changes to tickets** - Connect GitHub pull requests and commits directly to Linear issues
* **Sync status updates** - Keep issue statuses current as work progresses through different stages
* **Multi Agent Systems:** Create sub-issues and assign child agents to break down complex tasks into manageable pieces. [Learn more](#multi-agent-systems).
## Permissions
The Codegen Linear integration requires the following permissions:
* **Create issues for your workspace** - Generate new tasks and tickets as needed
* **Create issue comments and discussions** - Provide updates, ask questions, and facilitate collaboration
* **Read access to your workspace data** - Access existing issues, projects, and team information
* **Write access to update issues and projects** - Modify issue status, assignees, and project details
* **Assign issues and projects to teams** - Route work to appropriate team members
* **Mention app in issues and documents** - Enable notifications and cross-references
* **Receive realtime updates about workspace changes** - Stay synchronized with workspace activity
## How Agents Use Linear
Agents use the Linear integration to streamline project management:
* **Track Work:** Automatically update the status of issues they are working on.
* **Link Code:** Connect implemented changes (GitHub PRs) directly to the relevant Linear issue.
* **Provide Updates:** Post comments on issues with progress reports, results, or questions.
* **Create Tasks:** Generate new issues for follow-up work, bugs discovered, or sub-tasks.
## Multi Agent Systems
### Overview
Once you've enabled linear self-assign in the settings [page](https://www.codegen.com/integrations/linear), a codegen agent, that has been assigned to a linear issue (or has been tagged in one), can spawn child agents
by creating sub-issues and assigning itself to those sub-issues. For each sub-issue that codegen assigns to itself a child agent will be spawned and tasked with completing the sub-issue. Once the child agents are
finished with their tasks they will notify their parent by sending it a message. The parent will then incorporate the child's work into its own as appropriate.
### Best Practices
#### Triggering the Child Agents
If you'd like to have codegen break up a linear issue into smaller issues and assign them to child agents you should instruct it to do so in the
description of the original linear issue.
#### Shared Context
Before creating sub-issues and assigning them to child agents the parent agent will produce scaffolding in the form of a git branch and include details
of this branch in the description of the sub-issues. The child agents will then work off of this scaffolding branch. If you have specific scaffolding requirements
or context you'd like the child agents to share, please include them in the description of the parent issue.
#### Availability
This feature is only available on the Team Plan.
# MCP Servers
Source: https://docs.codegen.com/integrations/mcp-servers
Connect external tools and services to enhance your AI agent capabilities through Model Context Protocol (MCP) servers. Codegen allows you to connect arbitrary MCP servers that we will run and manage for your agents.
## Installation
Configure MCP servers to extend your agent capabilities with custom tools and services.
Connect custom MCP servers to enhance your agent workflows.
## Capabilities
The MCP integration provides comprehensive extensibility for your agents:
* **Connect custom tools and services** - Integrate any MCP-compatible server to extend agent functionality
* **Extend agent capabilities** - Add specialized tools, APIs, and data sources to your development workflow
* **Managed execution** - Codegen runs and manages your MCP servers, handling infrastructure and reliability
* **Secure integration** - Connect external services while maintaining security and access controls
* **Repository-specific configuration** - Configure different MCP servers for different repositories and projects
* **Real-time connectivity** - Agents can interact with MCP servers in real-time during task execution
## How It Works
Codegen's MCP server integration allows you to:
1. **Configure MCP Servers** - Add MCP server configurations through the Codegen interface
2. **Repository Integration** - Associate MCP servers with specific repositories for targeted functionality
3. **Agent Access** - Agents automatically discover and use available MCP server tools during execution
4. **Managed Infrastructure** - Codegen handles server deployment, scaling, and maintenance
## Supported MCP Servers
You can connect any MCP-compatible server, including:
* **Database connectors** - Connect to PostgreSQL, MySQL, MongoDB, and other databases
* **API integrations** - Access REST APIs, GraphQL endpoints, and web services
* **Development tools** - Integrate with testing frameworks, deployment tools, and CI/CD systems
* **Custom business logic** - Add company-specific tools and workflows
* **External services** - Connect to cloud services, monitoring tools, and third-party platforms
## Configuration
MCP servers are configured per repository using a JSON configuration file. The configuration includes:
* **Server details** - URL, authentication, and connection parameters
* **Tool mapping** - Define which tools are available to agents
* **Access controls** - Specify permissions and security settings
* **Environment variables** - Configure server-specific settings and secrets
## Permissions
The Codegen MCP integration requires the following permissions:
* **Connect to external MCP servers** - Establish connections to your configured servers
* **Execute custom tool functions** - Run tools and commands provided by MCP servers
* **Access server-provided resources** - Read and write data through MCP server interfaces
* **Manage server configurations** - Update and modify MCP server settings
## How Agents Use MCP Servers
Agents leverage MCP servers to:
* **Extend Functionality:** Access tools and capabilities beyond built-in agent features
* **Connect External Systems:** Interact with databases, APIs, and services specific to your workflow
* **Custom Workflows:** Execute company-specific processes and business logic
* **Data Integration:** Access and manipulate data from various sources and formats
* **Specialized Tools:** Use domain-specific tools for testing, deployment, monitoring, and more
MCP server integration allows for powerful extensibility but requires careful
configuration to ensure security and proper access controls.
# Monday.com Integration
Source: https://docs.codegen.com/integrations/monday
Integrate Codegen with your Monday.com workspace to enable AI-powered project management with intelligent task automation. Codegen can create and update items, manage boards, and keep your team synchronized across development workflows.
## Installation
Connect your Monday.com workspace to Codegen to enable agent interactions.
Authorize Codegen to access your Monday.com workspace and project boards.
## Capabilities
The Monday.com integration provides comprehensive project management capabilities:
* **Create and update items** - Generate new tasks and update existing ones based on development needs
* **Read and update items** - Access and modify task details, status, and progress information
* **Manage boards and columns** - Organize work across different project boards and customize workflows
* **Team coordination** - Assign tasks to team members and manage workload distribution
* **Status synchronization** - Keep project status current as work progresses through different stages
* **Automated reporting** - Generate progress reports and project insights based on development activity
## Permissions
The Codegen Monday.com integration requires the following permissions:
* **Read and update items** - Access and modify task details and progress information
* **Read and update boards** - Manage project boards and organizational structure
* **Read and update columns** - Customize workflows and data fields
* **Read and update groups** - Organize tasks into logical groupings
* **Read and update users** - Access team member information for task assignment
* **Read and update workspaces** - Manage workspace-level settings and permissions
## How Agents Use Monday.com
Agents leverage the Monday.com integration to:
* **Track Work:** Automatically update the status of items they are working on
* **Create Tasks:** Generate new items for follow-up work, bugs discovered, or sub-tasks
* **Provide Updates:** Add updates to items with progress reports, results, or questions
* **Link Development:** Connect implemented changes and code work directly to relevant Monday.com items
* **Manage Workflows:** Update item status as work progresses through different development stages
The Monday.com integration requires feature flag access. Contact your team
administrator to enable this integration.
# Notion Integration
Source: https://docs.codegen.com/integrations/notion
Notion is your team's knowledge base, and now Codegen can tap into it too. Share PRDs, specs, and documentation with Codegen for technical feedback and implementation. A common workflow: pass a PRD to Codegen and it will provide technical insights, comment directly on the document, and then go implement the features described.
## Installation
Connect your Notion workspace to Codegen to enable agent interactions with your knowledge base.
Authorize Codegen to access your Notion workspace and documentation.
## Capabilities
The Notion integration enables seamless access to your team's knowledge base:
* **Access workspace documentation** - Read and analyze existing documentation, specs, and project requirements
* **Update pages and databases** - Modify content, add comments, and keep documentation current
* **Sync development information** - Bridge the gap between planning documents and code implementation
* **Generate knowledge base content** - Create new documentation based on development work and insights
## Permissions
The Codegen Notion integration requires the following permissions:
* **Read workspace content and documents** - Access existing pages, databases, and documentation
* **Update existing pages and documents** - Modify content and add comments for collaboration
* **Create new pages and content** - Generate new documentation and project materials
* **Access user information and emails** - Understand team structure and collaboration context
* **Read database entries and properties** - Access structured data and project information
* **Update database entries and values** - Modify project data and status information
* **Create new databases and structures** - Establish new organizational systems as needed
## How Agents Use Notion
Agents leverage the Notion integration to:
* **Analyze Requirements:** Read PRDs and technical specifications to understand project scope and requirements
* **Provide Technical Feedback:** Comment on documents with implementation insights and technical considerations
* **Update Documentation:** Keep project documentation current as development progresses
* **Bridge Planning and Code:** Connect high-level planning documents with actual code implementation
The Notion integration requires feature flag access. Contact your team
administrator to enable this integration.
# Postgres Integration
Source: https://docs.codegen.com/integrations/postgres
Integrate Codegen with your Postgres (or Postgres-compatible databases) to enable database querying capabilities.
## Installation
Connect your database to Codegen by configuring your database credentials in the settings.
Set up your database connection credentials in the secure settings panel.
For security reasons, it is strongly recommended to configure credentials with READ-ONLY access.
Providing write access to automated agents could potentially lead to unintended data modifications
or other negative consequences.
## Capabilities
The Postgres integration provides secure database access enabling agents to:
* **Query Data:** Execute SELECT queries to fetch information from your database
* **Analyze Schema:** View table structures, relationships, and column definitions
* **Generate Reports:** Create data summaries and analysis based on query results
## How Agents Use Postgres
Agents leverage the Postgres integration to assist with data-related tasks:
* **Data Exploration:** Safely query your database to understand data structures and relationships
* **Report Generation:** Create data-driven reports and analytics
* **Schema Analysis:** Provide insights about database design and optimization
# Sentry Integration
Source: https://docs.codegen.com/integrations/sentry
export const COMMUNITY_SLACK_URL = "https://community.codegen.com";
Integrate Codegen with your Sentry workspace to enable AI-powered error tracking with automated root cause analysis. Codegen can analyze errors, investigate issues, and provide intelligent insights to help resolve production problems faster.
## Installation
Connect your Sentry organization to Codegen to enable agent interactions with error tracking data.
Authorize Codegen to access your Sentry organization and error data.
The Sentry integration is currently in beta. Please reach out in the{" "}
community to have it enabled for your
Codegen account.
## Capabilities
The Sentry integration provides comprehensive error tracking and analysis capabilities:
* **Automated root cause analysis** - Analyze error patterns and stack traces to identify underlying issues
* **Error investigation** - Deep dive into error contexts, user impact, and related code changes
* **Issue prioritization** - Help identify critical errors that need immediate attention
* **Performance monitoring** - Analyze performance issues and bottlenecks in your applications
* **Release tracking** - Connect errors to specific deployments and code changes
* **Team coordination** - Assign issues to appropriate team members based on expertise and ownership
## Permissions
The Codegen Sentry integration requires the following permissions:
* **Read organization information** - Access organization settings and configuration
* **Read/Write project information** - Access project details and modify project settings
* **Read/Write team information** - Access team structure and manage team assignments
* **Read/Write event information** - Analyze error events and update issue status
## How Agents Use Sentry
Agents leverage the Sentry integration to:
* **Analyze Errors:** Examine error patterns, stack traces, and user impact to understand root causes
* **Investigate Issues:** Deep dive into error contexts, related code changes, and deployment history
* **Provide Insights:** Generate intelligent analysis and recommendations for error resolution
* **Track Progress:** Update issue status and resolution progress as fixes are implemented
* **Link Development:** Connect error fixes to GitHub PRs and code changes
* **Prioritize Work:** Help identify critical errors that require immediate attention
The Sentry integration requires feature flag access. Contact your team
administrator to enable this integration.
# Integration for Slack
Source: https://docs.codegen.com/integrations/slack
Connect Codegen to your Slack workspace to enable seamless communication between agents and your team.
Slack is the most fluid way to communicate with Codegen. Simply tag @codegen in any channel to collaborate directly and give it tasks that leverage all your other integrations. As an agent, Codegen can seamlessly work across platforms—from GitHub to Linear to your databases—all initiated from Slack. We recommend Slack as the lowest barrier entry point for all users.
## Installation
To use this integration, follow the installation and configuration steps below.
Create a Codegen account and visit Integrations > Slack to connect your Slack
workspace.
Configure channel access carefully to ensure agents communicate in the
appropriate places.
After installation, proceed to the Configuration Instructions below to finish setup and begin using Codegen in your Slack workspace.
## Capabilities
The Slack integration enables seamless collaboration with Codegen directly within your workspace:
* **Chat with Codegen directly in channels** - Interact naturally through @mentions and direct messages
* **Get real-time notifications** - Stay updated on task progress and completion
* **Share code snippets and updates** - Collaborate on code changes and development tasks
* **Collaborate on development tasks** - Coordinate work across your entire development workflow
All of these capabilities are accessible through natural language interactions in your Slack workspace, allowing your team to leverage Codegen's assistance without context switching between different platforms.
## Configuration Instructions
After installing the integration from the Slack Marketplace, configure the bot by inviting it to relevant channels and setting up triggers so Codegen knows when and how to respond.
### Channel Setup
* **Invite the Codegen bot**: Type `/invite @codegen` in any channel where you want Codegen to participate.
* (Optional) **Create a dedicated channel**: Some Codegen users find creating a channel like `#codegen` helpful for general agent interactions and to encourage experimentation.
## What Triggers Slack Messages from Codegen
These triggers kick off new Codegen requests:
* **Direct mentions**: Type `@codegen` followed by your request in any channel where the bot is present.
* **Thread replies**: Tag `@codegen` in threads to continue the conversation.
* **Direct messages**: Send a DM to the Codegen bot for private conversations.
In addition, Codegen will send messages to Slack when:
* It starts work on a request you made
* It receives an additional message while working on a request
* It completes a task, code change, or research request
## How Codegen Responds to Slack Messages
Codegen only responds when tagged or messaged directly. Use these approaches to ensure your request reaches it:
* **Direct Messages:**
* Responds to any DM sent to the Codegen integration for Slack
* Codegen only sees messages in the direct message conversation where it has been invited
* This provides a more natural conversation experience as many users don't thread messages in DMs
* **Channel Messages:**
* Responds to any message that @mentions Codegen in channels where the integration for Slack is installed
* Codegen only sees messages in threads that it has been invited into
* Only has visibility into the local context of the thread/conversation
* Sending subsequent messages within a thread routes to the same agent (tag `@codegen` to trigger)
* New messages to `@codegen` in an active thread will interrupt the agent if it's currently working
## Permissions and Scopes
The Codegen Slack integration requires the following permissions to function effectively:
### Core Messaging Permissions
* **View messages that mention @codegen** - To respond to direct mentions and requests
* **Read message history in public and private channels** - To understand context and conversation flow
* **Read direct messages and group chats** (`mpim:read`) - To enable private conversations with the agent in group DMs and multi-person direct messages
* **Send messages** - To communicate responses and provide updates
### Enhanced Communication Features
* **View and react with emojis** - To acknowledge messages and provide feedback through reactions
### User and Workspace Access
* **View workspace members and email addresses** (`users:read.email`) - Used to map Slack user accounts to Codegen accounts for proper authentication and permission management. This ensures that when a user interacts with Codegen via Slack, their actions are properly attributed to their Codegen account and repository permissions
* **Access shared files and attachments** - To review and work with shared content like code snippets, images, and documents
* **Access basic channel information** - To operate appropriately within different channel contexts
### Why These Permissions Are Necessary
* **Email mapping** enables secure account linking between Slack and Codegen, ensuring proper access control
* **Group DM access** ensures Codegen can participate in team discussions and collaborative planning sessions
## Data Privacy and Security
**Message Content Handling:**
* **Third-Party LLM APIs:** To provide its core functionality, Codegen shares message content with third-party Large Language Model (LLM) APIs, specifically OpenAI and Anthropic.
* **Data Retention:** Outside of the LLM API interactions, message content is retained by Codegen solely for the purpose of displaying it within the Codegen user interface.
* **Metadata from Private Channels:** When messages from private Slack channels are processed, Codegen does not expose private metadata, such as the original author's name or username, in the Codegen web app. Private channel names are anonymized and displayed as "Private channel" to non-members.
**Data Scope and Context:**
* **Thread Context:** When Codegen is mentioned inside a thread, it will pull context from the entire thread, including the messages sent and media shared within that thread.
* **Single Message Context:** When Codegen is mentioned outside of a thread, it will only be scoped to the specific message in which it is mentioned.
**User Permissions and Access Control:**
Codegen's actions on connected repositories are governed by the permissions of the user who initiated the interaction via Slack. The bot itself does not have independent permissions to repositories. Access to repositories and the ability to trigger actions are determined by the Codegen user's authenticated account and their associated repository permissions. We recommend configuring channel access carefully during installation to ensure the Codegen integration for Slack is only present in channels where its use is appropriate.
**Audit Trail:**
Administrators can access a comprehensive audit trail through the [Recents page](https://codegen.com/recents) in the Codegen web app. This provides detailed logs of when and by whom Codegen was invoked in Slack, with filtering capabilities by integration, user, and other parameters.
**Privacy Policy:**
For complete details on how we collect, use, and protect your data, please review our [Privacy Policy](https://www.codegen.com/privacy-policy).
## AI Components and Usage
**AI-Powered Functionality:**
Codegen uses artificial intelligence to provide intelligent code assistance, automated development tasks, and natural language interactions. Our AI capabilities include:
* **Code Generation and Analysis:** AI models analyze your codebase and generate appropriate code changes, bug fixes, and improvements
* **Natural Language Processing:** AI interprets your requests in Slack and converts them into actionable development tasks
* **Context Understanding:** AI maintains conversation context to provide relevant and coherent responses across interactions
**AI Data Processing:**
* **Message Analysis:** Your Slack messages are processed by AI models to understand intent and generate appropriate responses
* **Code Context:** When working with repositories, AI models analyze relevant code to provide accurate assistance
**AI Limitations:**
* AI-generated code should be reviewed before deployment
* Complex tasks may require human oversight and validation
* AI responses are based on training data and may not always reflect the most current information
## Pricing and Plans
Codegen offers flexible pricing plans to accommodate teams of all sizes. The Slack integration is available across all plan tiers, with usage limits and features varying by plan.
For detailed pricing information and to choose the plan that best fits your team's needs, visit our [Pricing Page](https://www.codegen.com/pricing).
## Tips for Effective Use
* Use direct language when asking Codegen for help (e.g., "Add pagination to the results view").
* Mention Codegen early in the message so it is triggered promptly.
* Use threads for ongoing conversations with Codegen so it has access to previous context.
# Web Search Integration
Source: https://docs.codegen.com/integrations/web-search
Connect Codegen to web search capabilities powered by exa to enable agents to search and retrieve information from the internet.
## Capabilities
Our web search integration, powered by exa, provides agents with the ability to search and understand web content:
* **Real-time Search:** Access up-to-date information from across the internet.
* **Content Analysis:** Parse and extract relevant information from web pages.
* **Source Verification:** Evaluate and cite reliable sources for information.
* **Context Integration:** Incorporate web-sourced information into responses and solutions.
## How Agents Use Web Search
Agents utilize web search capabilities to:
* **Research Solutions:** Find documentation, examples, and best practices for implementing features.
* **Stay Current:** Access the latest information about technologies, APIs, and development trends.
* **Verify Information:** Cross-reference facts and documentation from authoritative sources.
* **Gather Context:** Research domain-specific knowledge needed to better understand and solve problems.
## Implementation
Web search is automatically available to agents when needed, powered by exa's advanced search capabilities.
Discover how exa powers our web search capabilities with state-of-the-art
search technology.
Agents automatically determine when to leverage web search to enhance their
responses and solutions with current, relevant information.
# Codegen, Inc.
Source: https://docs.codegen.com/introduction/about
## Our Mission
Our mission is to build fully-autonomous software engineering.
We believe the most effective path towards this goal is through intelligent AI agents that seamlessly integrate into existing developer workflows.
Our agents connect with tools developers use every day, like GitHub, Slack, and Linear, to automate tasks ranging from fixing bugs and implementing features to writing tests and improving documentation.
By handling routine development tasks, Codegen empowers engineers to focus on higher-level challenges and accelerates the entire software development lifecycle.
## The Team
Based in San Francisco, we're a team of engineers and researchers passionate about:
* Making large-scale code changes more accessible
* Building tools that work the way developers think
* Creating the infrastructure for AI-powered code manipulation
* Advancing the state of the art in program transformation
## Open Source
We believe in the power of open source software. Our core library, [codegen](https://github.com/codegen-sh/codegen-sdk), is freely available and open to contributions from the community.
## Join Us
We're hiring! Join us in building the future of code transformation.
Connect with other developers and share your Codegen experiences.
## Connect with Us
Follow us for updates and announcements
Connect with our team and stay updated on company news
Want to learn more about what we're building? Check out our [getting started
guide](/introduction/getting-started) or join our [community
Slack](https://community.codegen.com).
# Codegen CLI
Source: https://docs.codegen.com/introduction/cli
export const CODEGEN_SDK_GITHUB_URL = "https://github.com/codegen-sh/codegen-sdk";
export const COMMUNITY_SLACK_URL = "https://community.codegen.com";
The `codegen` CLI is your terminal interface to Codegen agents. Use it to view agents, pull their work, create new agents, and run Claude Code with full telemetry and monitoring.
It also wraps your local Claude Code, surfaces traces in the web UI for remote telemetry and analytics, and provides access to your Codegen integrations via MCP injection.
## Installation & Setup
```bash
uv tool install codegen
```
The CLI uses your API token for authentication. Get your token and organization ID from the **[authentication guide](/api-reference/authentication)**.
```bash
codegen login
```
## Key Commands
### `codegen`
Launches the interactive terminal UI (TUI) for browsing agents, viewing runs, and managing your Codegen workflow from the terminal.
### `codegen login`
Store your API token for authentication. Supports both interactive login and direct token input.
```bash
# Interactive login
codegen login
# Direct token login
codegen login --token YOUR_API_TOKEN
```
### `codegen update`
Keep your CLI up to date with the latest features and improvements. The CLI automatically checks for updates daily and notifies you when new versions are available.
```bash
# Update to latest version
codegen update
# Check for updates without installing
codegen update --check
# Update to a specific version
codegen update --version 1.2.3
# Preview changes without updating
codegen update --dry-run
```
## What You Can Do
* **View and manage agents** - List agent runs, check status, and see detailed execution logs
* **Pull agent work** - Download branches and code changes created by agents directly to your local environment
* **Create new agents** - Trigger agent runs from the command line with custom prompts
* **Run Claude Code** - Execute Claude Code with OpenTelemetry monitoring and comprehensive logging
* **Manage organizations** - Switch between organizations and configure repositories
* **Stay up to date** - Built-in self-update system with automatic update notifications
The CLI provides the same capabilities as the web UI and API, optimized for
terminal-based workflows and automation.
## Full Demo
## Get Started
Sign up for a free account and get your API token.
Star us on GitHub and contribute to the project.
# Community & Contributing
Source: https://docs.codegen.com/introduction/community
export const CODEGEN_SDK_GITHUB_URL = "https://github.com/codegen-sh/codegen-sdk";
export const COMMUNITY_SLACK_URL = "https://community.codegen.com";
Join the growing Codegen community! We're excited to have you be part of our journey to make codebase manipulation and transformation more accessible.
Connect with the community, get help, and share your Codegen projects in our
active Slack workspace.
Star us on GitHub, report issues, submit PRs, and contribute to the project.
Follow us for updates, tips, and community highlights.
Learn how to use Codegen effectively with our comprehensive guides.
Please help us improve this library and documentation by submitting a PR!
## Contributing
We welcome contributions of all kinds! Whether you're fixing a typo in documentation, reporting a bug, or implementing a new feature, we appreciate your help in making Codegen better.
Check out our [Contributing Guide](https://github.com/codegen-sh/codegen-sdk/blob/develop/CONTRIBUTING.md) on GitHub to learn how to:
* Set up your development environment
* Submit pull requests
* Report issues
* Contribute to documentation
# Frequently Asked Questions
Source: https://docs.codegen.com/introduction/faq
The Codegen AI agent leverages modern large language models (LLMs) for code
understanding and generation. This means it can generally handle tasks
involving any programming language, configuration format (like JSON, YAML),
documentation (like Markdown), or other text-based files that current LLMs
are proficient with. If you have specific needs or find limitations with a
particular language or format, please let us know!
The Codegen agent uses large language models to understand and modify code.
While powerful, its understanding isn't based on formal static analysis and
may not always be perfectly exact or catch all edge cases like a traditional
compiler or linter might. It aims for practical correctness based on the
provided context and instructions.
Yes! Codegen's agent is designed to work effectively on large, real-world
codebases. You can provide context and specific instructions to help it
navigate complex projects.
For enterprise use cases and support, please reach out to
[team@codegen.com](mailto:team@codegen.com)
Yes. The Codegen SDK is a standard Python package (`pip install codegen`).
You can import and use it in your Python scripts, CI/CD pipelines, or any
other development tool that can execute Python code.
Start by trying out the Codegen agent and SDK, joining our [Slack
community](https://community.codegen.com), and reporting any issues or
feedback on [GitHub](https://github.com/codegen-sh/codegen-sdk). We welcome
contributions to documentation, examples, and SDK improvements.
The best places to get help are: 1. Our community [Slack
channel](https://community.codegen.com) 2. [GitHub
issues](https://github.com/codegen-sh/codegen-sdk) for bug reports or SDK
feature requests 3. Reach out to us on [Twitter](https://x.com/codegen)
# Codegen
Source: https://docs.codegen.com/introduction/overview
[Codegen](https://codegen.com) helps you run frontier code agents at scale. It provides the necessary building blocks (sandboxes, integrations, telemetry) for successful enterprise code agent deployments across thousands of teams today.
Focus on higher-level tasks and leverage Codegen agents to do the low-level
labor of software engineering.
Think of it as an AI coworker that can understand and solve coding challenges, access your codebase instantly, and interact directly with your development tools.
## What Can Codegen Agents Do?
Codegen agents come equipped with a versatile set of tools and capabilities:
Analyze requirements, implement features, fix bugs, write tests, and improve
documentation based on your prompts.
Send notifications, ask for clarification, report progress, and interact
directly with your team in Slack channels.
Update statuses, add comments, link PRs to issues, and create new tasks.
Support for Jira, Linear, Clickup and Monday.com.
Review PRs, suggest changes, comment on issues, create branches, commit
code, and manage repositories.
Safely run code, install dependencies, and test changes in robust isolated
environments
Connect with Slack, Linear, Figma, databases, and extend capabilities with
custom MCP tools.
Connect with Slack, Linear, Figma, databases, and extend capabilities with
custom MCP tools.
Log local Claude Code instances to the cloud and provision MCP servers
across your org.
## Get Started in Minutes
Integrating Codegen into your workflow is designed to be quick and easy:
Install the GitHub App to grant the agent access to your repositories. No
complex setup required.
Add the Codegen Slack App to communicate with the agent directly in your
workspace.
Connect your Linear workspace to enable agent interactions with your issues.
Programmatically interact with agents using the Python SDK for advanced
automation.
## Security & Compliance
Codegen is [SOC 2 Type I & II certified](https://codegen.com/security/soc2) and performs regular pen tests, ensuring your code and data are handled with the highest standards for security, privacy, and compliance.
Learn more about our security practices here.
Details on Codegen's security practices and more
View SOC-2 documents and pen test results
## Install Now
Create an account via Github OAuth and install our [Github application](https://github.com/apps/codegen-sh) to get started.
Codegen's Github app is free to install. Get started in just a few clicks.
## Learn More
Connect with other developers, get help, and share your experiences in our
active Slack workspace.
Learn about our mission to build fully-autonomous software engineering and
meet the team.
# Effective Prompting
Source: https://docs.codegen.com/introduction/prompting
To get the best results from Codegen, treat it like a skilled teammate: provide clear, specific instructions and sufficient context. Vague requests lead to ambiguous outcomes.
Codegen is based on Anthropic's Claude 4 Sonnet. You can prompt it similarly to
ChatGPT or other LLM-based assistants
## The Core Principle: Specificity
Instead of "Fix the user service," try:
> In the `my-web-app` repo (PR #42), refactor the `UserService` class in `src/services/user.ts` to use the `UserRepository` pattern shown in `ProductService`/`ProductRepository`.
If there are specific implementation details you want included, make sure to specify. For example:
> Ensure all tests in `tests/services/user.test.ts` pass and add new tests for the repository with 90%+ coverage. Update the diagram in `docs/architecture/user-service.md`.
## Elements of a Strong Prompt
1. **Scope:** What repository, branch, or files are involved? (e.g., `my-web-app` repo, `PR #42`, `src/services/user.ts`)
2. **Goal:** What is the high-level objective? (e.g., Refactor `UserService`, improve testability)
3. **Tasks:** What specific actions should the agent take? Use a numbered or bulleted list for clarity. (e.g., Extract logic to `UserRepository`, use dependency injection, update tests, update diagram)
4. **Context/Patterns:** Are there existing patterns, examples, or documentation to reference? (e.g., `ProductService`, `ProductRepository`)
5. **Success Criteria:** How will you know the task is done correctly? (e.g., Tests pass, 90%+ coverage, diagram updated)
Clear, detailed prompts empower Codegen agents to deliver accurate results
faster, significantly streamlining your workflow.
# Python SDK
Source: https://docs.codegen.com/introduction/sdk
export const CODEGEN_SDK_GITHUB_URL = "https://github.com/codegen-sh/codegen-sdk";
export const COMMUNITY_SLACK_URL = "https://community.codegen.com";
The [Codegen SDK](https://github.com/codegen-sh/codegen-sdk) is a thin pythonic wrapper around the **[Codegen API](/api-reference/overview)** with all the same capabilities for creating and managing AI agents programmatically.
Go to [developer settings](https://codegen.sh/token) to generate an API token
```python
from codegen import Agent
# Initialize the Agent with your organization ID and API token
agent = Agent(org_id="...", token="...")
# Run an agent with a prompt
task = agent.run(prompt="Leave a review on PR #123")
# Check the initial status
print(task.status)
# Refresh the task to get updated status (tasks can take time)
task.refresh()
if task.status == "completed":
print(task.result) # Result often contains code, summaries, or links
```
## Installation
Install the [codegen](https://pypi.org/project/codegen/) package from PyPI using your preferred package manager:
```bash
# Using pip
pip install codegen
# Using pipx (for CLI usage)
pipx install codegen
# Using uv
uv pip install codegen
# or
uv tool install codegen
```
### Keeping Up to Date
The CLI includes a built-in self-update system that checks for updates daily:
```bash
# Update to latest version
codegen update
# Check for updates
codegen update --check
```
## Get Started
Sign up for a free account and get your API token.
Get help and connect with the Codegen community.
Learn how to use Codegen for common code transformation tasks.
Star us on GitHub and contribute to the project.
# Support
Source: https://docs.codegen.com/introduction/support
Need help with Codegen? We're here to support you every step of the way.
## Get Help
Email us directly at [support@codegen.com](mailto:support@codegen.com) for technical issues and questions.
Join our active community for peer support, tips, and discussions.
## Team Plans & Above
All Team plans and above get a **shared Slack channel with our team** for direct access to Codegen engineers and priority support.
## Enterprise Support
Codegen offers forward deployed engagements for organizations looking for
hands-on implementation support. Get in touch if you need dedicated assistance
with your Codegen deployment.
Response times vary by plan level. Team and Enterprise customers receive
priority support with faster response times.
# Use Cases
Source: https://docs.codegen.com/introduction/use-cases
This page provides an LLM-generated summary of how teams are using Codegen agents, based on analysis of tens of thousands of customer agent runs. The data represents actual requests from users across different organizations and communication channels.
## 🏗️ Code Development & Implementation (35%)
The most common use case for Codegen agents is building new functionality and applications from scratch.
**Full-stack app creation**
* Complete Next.js/React applications with production-ready UI/UX
* End-to-end web applications with authentication, databases, and deployment
* Mobile and desktop applications across different platforms
**Feature implementation**
* Adding new functionality to existing codebases
* Implementing user stories and product requirements
* Building complex business logic and workflows
**API development**
* Creating REST and GraphQL endpoints
* Third-party service integrations
* Microservices architecture and implementation
**Database work**
* Schema design and migrations
* Complex queries and data analysis
* Database optimization and performance tuning
## 🔍 Code Review & Analysis (25%)
Teams heavily rely on Codegen for thorough code analysis and quality assurance.
**PR reviews**
* Deep code analysis with inline suggestions
* Bug detection and security vulnerability identification
* Code quality and best practices validation
**Codebase audits**
* Performance analysis and optimization recommendations
* Security reviews and compliance checks
* Technical debt assessment and prioritization
**Architecture reviews**
* Design pattern validation and improvements
* System architecture recommendations
* Code organization and structure analysis
**Migration analysis**
* Impact assessment for major changes
* Legacy system modernization planning
* Framework and library upgrade guidance
## 🛠️ Bug Fixes & Maintenance (20%)
Codegen agents excel at debugging and maintaining existing systems.
**Issue resolution**
* Debugging complex problems across the stack
* Root cause analysis and systematic fixes
* Error handling and edge case management
**Dependency updates**
* Package management and version conflict resolution
* Security patch application
* Breaking change migration assistance
**Configuration fixes**
* Build system troubleshooting
* Deployment pipeline optimization
* Environment setup and configuration management
**Performance optimization**
* Identifying and resolving bottlenecks
* Memory and CPU usage optimization
* Database query performance improvements
## 📋 Project Management & Documentation (10%)
Teams use Codegen to streamline project workflows and maintain documentation.
**Linear ticket management**
* Creating and organizing development tasks
* Sprint planning and backlog management
* Progress tracking and status updates
**Documentation creation**
* README files and setup instructions
* API documentation and guides
* Technical specifications and architecture docs
**Project scoping**
* Breaking down large features into manageable tasks
* Effort estimation and timeline planning
* Risk assessment and mitigation strategies
**Workflow automation**
* CI/CD pipeline setup and optimization
* Development process standardization
* Quality gates and automated checks
## 🤖 AI/ML & Specialized Tasks (5%)
Advanced use cases involving specialized tools and integrations.
**Feature flag cleanup**
* Statsig and A/B testing tool maintenance
* Experimental feature management
* Configuration cleanup and optimization
**Data analysis**
* SQL queries and business intelligence
* Performance metrics and analytics
* Data pipeline development and maintenance
**Integration work**
* Third-party API connections
* Webhook setup and management
* Service-to-service communication
**Custom tooling**
* Specialized utilities and automation scripts
* Developer productivity tools
* Internal service development
## 💬 Communication Channels
**Linear (35%)**
* Primarily used for ticket management and feature requests
* Project planning and sprint organization
* Task assignment and progress tracking
**Chat/API (30%)**
* Development tasks and quick fixes
* Real-time problem solving
* Interactive debugging sessions
**Slack (20%)**
* Team collaboration and questions
* Code reviews and discussions
* Knowledge sharing and support
**GitHub (15%)**
* Pull request reviews and management
* Repository maintenance and organization
* Release planning and deployment
## 🎯 Key Insights
1. **Most common request**: "Review this PR" - developers want thorough, automated code analysis
2. **Growing trend**: Full-stack application development from scratch with production-ready requirements
3. **High value tasks**: Complex debugging, architecture decisions, and system design
4. **Quick wins**: Documentation updates, simple feature additions, and configuration fixes
5. **Team efficiency**: Agents handle routine tasks, allowing developers to focus on creative problem-solving
## Getting Started
Ready to leverage these use cases for your team? Check out our [overview](/introduction/overview) to get started, or explore specific [capabilities](/capabilities/capabilities) that align with your needs.
# Remote Editor (VSCode)
Source: https://docs.codegen.com/sandboxes/editor
Codegen provides access to a remote VSCode editor instance that is directly connected to your active sandbox environment. This powerful feature allows for real-time interaction with the agent's workspace, offering capabilities for live debugging, manual intervention, and detailed progress monitoring.
## Accessing the Editor
When an agent is active and utilizing a sandbox, a link or button to access the Remote Editor will typically be available on the agent's trace page or within the Codegen UI.
Access to the editor is password-protected. A unique password will be dynamically generated at runtime for each session and provided to you, ensuring secure access to the sandbox environment.
## Capabilities
The Remote Editor offers several key benefits:
* **Run Arbitrary Commands:** Open a terminal directly within VSCode to execute any shell commands in the sandbox. This is useful for:
* Manually running tests.
* Inspecting file contents.
* Trying out different commands or scripts.
* Installing additional temporary tools or dependencies.
* **View Agent's Progress:** See the files the agent is creating or modifying in real-time. This provides a transparent view into the agent's operations and can help in understanding its decision-making process.
* **Live Debugging:** If the agent is running a service or script, you can use VSCode's debugging tools (if applicable to the language/runtime) to step through code, inspect variables, and diagnose issues.
* **Manual Edits:** While generally agents manage the codebase, you can make manual edits to files directly if needed for quick fixes or experiments. Be mindful that agent actions might overwrite manual changes if not coordinated.
## How it Works
The remote editor essentially provides a fully functional VSCode interface tunneled into the agent's sandbox. This means you are working directly within the same environment as the agent, with access to the same file system, installed tools, and [Environment Variables](./environment-variables).
The Remote Editor is an excellent tool for gaining deeper insights into an
agent's operations and for situations where you need to interact more directly
with the sandbox environment than through standard agent commands.
Like other sandbox features, the editor session is tied to the lifecycle of
the sandbox. Changes made might be ephemeral if the sandbox is reset or a new
snapshot is used for subsequent runs, unless those changes are committed back
through the agent or other means.
{" "}
# Environment Variables
Source: https://docs.codegen.com/sandboxes/environment-variables
Codegen sandboxes come pre-configured with a set of environment variables to facilitate common development tasks and ensure smooth operation of tools and package managers. Understanding these variables can be helpful when debugging or customizing setup scripts.
## Standard Environment Variables
The following environment variables are typically available within Codegen sandboxes:
| Variable | Default Value | Description |
| --------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `NVM_DIR` | *Dynamic* | Specifies the directory where Node Version Manager (NVM) is installed. The exact path is set during sandbox initialization. |
| `PATH` | *Dynamic (includes NVM Node version)* | The system's execution search path. It's augmented to include the `bin` directory of the currently active Node.js version (managed by NVM). |
| `NVM_BIN` | *Dynamic (points to active Node version bin)* | Points to the `bin` directory of the currently active Node.js version. This is also set dynamically by NVM. |
| `NODE_VERSION` | *Dynamic (current NVM Node version)* | Indicates the version of Node.js that is currently active in the sandbox, as managed by NVM. |
| `NODE_OPTIONS` | `"--max-old-space-size=8192"` | Configures V8 to allow a max old space size of 8192MB. Useful for memory-intensive Node.js apps. |
| `DEBIAN_FRONTEND` | `"noninteractive"` | Instructs Debian-based package managers (like `apt`) to run without interactive prompts. |
| `PYTHONUNBUFFERED` | `"1"` | Forces `stdout` and `stderr` for Python to be unbuffered, meaning output is written immediately. |
| `COREPACK_ENABLE_DOWNLOAD_PROMPT` | `"0"` | Disables the Corepack prompt when it needs to download a package manager (like Yarn or pnpm). |
| `PYTHONPATH` | `"/usr/local/lib/python3.13/site-packages"` | Adds the specified directory to Python's module search path. (Python version may vary). |
| `IS_SANDBOX` | `"true"` | A boolean flag indicating the environment is a Codegen sandbox. |
| `NPM_CONFIG_YES` | `"true"` | Configures npm to automatically answer "yes" to prompts. |
| `PIP_NO_INPUT` | `"1"` | Instructs pip (Python's package installer) to operate in non-interactive mode. |
| `YARN_ENABLE_IMMUTABLE_INSTALLS` | `"false"` | Disables Yarn's "immutable installs" feature, allowing `yarn install` to modify the lockfile. |
| `CG_PREVIEW_URL` | *Dynamic (preview URL)* | Contains the URL where the web preview will be served. This is automatically set when Web Preview is configured. |
The values for variables like `NVM_DIR`, `PATH`, `NVM_BIN`, and `NODE_VERSION`
are typically set dynamically during the sandbox setup process, depending on
the specific NVM and Node.js versions being used. The `PYTHONPATH` may also
vary based on the Python installation within the sandbox.
# Code Execution Sandboxes
Source: https://docs.codegen.com/sandboxes/overview
Codegen agents operate within secure, isolated sandbox environments where they can safely execute code and run commands without affecting your local machine or production systems.
Codegen's sandbox environments are highly configurable and built for
enterprise workloads
Select VM resources, install dependencies, securely upload secrets and more.
## Capabilities
Each sandbox provides a controlled environment with:
* **File System Access:** Read, write, and modify files within the sandbox's temporary file system.
* **Terminal Access:** Execute shell commands (`bash`, `sh`, etc.) to run scripts, linters, formatters, build tools, and other necessary commands.
* **Process Execution:** Run code in various languages (Python, Node.js, etc., depending on the sandbox image).
* **Networking:** Controlled network access for tasks like installing packages or fetching data (can be restricted).
## How Agents Use Sandboxes
Agents utilize sandboxes for a variety of tasks:
* **Testing Code:** Running unit tests, integration tests, or linters against the code they've written or modified.
* **Verifying Changes:** Executing the code to ensure it runs correctly before committing.
* **Installing Dependencies:** Using package managers (`pip`, `npm`, `yarn`) to install necessary libraries.
* **Running Tools:** Executing build scripts, code formatters, or other development utilities.
## Configuration
Sandboxes are typically configured per-agent run or defined within your Codegen settings. You often don't need to manage them directly, but advanced configurations might allow specifying Docker images or environment variables.
Sandboxes maintain file system persistence between agent interactions within
the same context. For example, when continuing a conversation across different
Slack messages or Linear comments, the sandbox state is preserved, allowing
agents to seamlessly continue their work without losing context or having to
reinstall dependencies.
## Sandbox Configuration
Configure custom setup commands that run when initializing your sandbox
environment.
Manage environment variables and secrets securely injected into your
sandbox.
Learn how Codegen creates filesystem snapshots for faster initialization.
Start development servers and view your running applications through
Codegen.
Explore the comprehensive Docker image that powers Codegen sandboxes.
Access a VSCode editor connected directly to your sandbox environment.
# Repository Secrets
Source: https://docs.codegen.com/sandboxes/secrets
Manage environment variables and secrets for your repository. These are securely injected into the agent's sandbox environment during code execution.
Only use staging credentials and non-production secrets. Never store
production API keys, database passwords, or sensitive credentials.
## How Secrets Work
Repository secrets are environment variables that get automatically injected into the sandbox when agents execute code:
* **Secure Storage:** Secrets are encrypted and stored securely per repository
* **Sandbox Injection:** Automatically available as environment variables during agent execution
* **Development Support:** Enable agents to run dev servers, connect to staging databases, and test integrations
## Common Use Cases
* **Development Server Credentials:** API keys for staging services and development APIs
* **Database Connections:** Connection strings for staging/test databases
* **Third-Party Integrations:** Non-production tokens for services like Stripe test mode, staging analytics
* **Build Configuration:** Environment-specific build variables and feature flags
## Managing Secrets
Add secrets through your repository settings:
1. Navigate to your repository settings
2. Go to the Secrets tab
3. Add key-value pairs for your environment variables
4. Secrets are immediately available to agents in the sandbox
Agents can access these secrets when running code, starting development
servers, or executing tests that require environment configuration.
{" "}
# Setup Commands
Source: https://docs.codegen.com/sandboxes/setup-commands
Codegen lets you configure custom setup commands that run once when initializing a repository's sandbox environment. The resulting file system snapshot serves as the starting point for all future agent runs, ensuring consistency.
The most common use cases for setup commands is installing dependencies, e.g.
`npm install`
## Base Image
Codegen sandboxes are built on a custom Docker image that provides a comprehensive development environment. For detailed information about the base image, including the complete Dockerfile and available tools, see the [Base Image](/sandboxes/base-image) documentation.
## Accessing Setup Commands
To configure setup commands for a repository:
1. Navigate to [codegen.com/repos](https://codegen.com/repos).
2. Click on the desired repository from the list.
3. You will be taken to the repository's settings page. The setup commands can be found at a URL similar to `https://www.codegen.com/repos/{arepo_name}/setup-commands`
## How it Works
Enter your desired setup commands in the provided text area, with one command per line. These commands will be executed in sequence within the sandbox environment.
For example, you might want to:
* Switch to a specific Node.js version.
* Install project dependencies.
* Run any necessary build steps or pre-compilation tasks.
After the commands are executed successfully, Codegen takes a snapshot of the sandbox's file system. This snapshot then serves as the base environment for future agent interactions with this repository, meaning your setup commands don't need to be re-run every time, saving time and ensuring consistency.
## Common Examples
Here are a few common use cases for setup commands:
```bash
# Switch to Node.js version 20
nvm use 20
# Install npm dependencies
npm install
```
```bash
# Setup with specific Python version for compatibility
pyenv install 3.12.0
pyenv local 3.12.0
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
```bash
# Or a combination of commands
nvm use 18
npm ci
npm run build
```
### Working with Different Python Versions
The sandbox comes with Python 3.13 by default, but some packages may not yet be compatible with this version. Here are strategies for handling different Python versions:
#### Using pyenv for Multiple Python Versions
If you need to work with a different Python version, you can install and use `pyenv`:
```bash
# Install pyenv
curl https://pyenv.run | bash
# Add pyenv to PATH (for current session)
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
# Install Python 3.12 (or your desired version)
pyenv install 3.12.0
# Set Python 3.12 as the local version for your project
pyenv local 3.12.0
# Create a virtual environment with Python 3.12
python -m venv venv
source venv/bin/activate
# Install your dependencies
pip install -r requirements.txt
```
#### Using uv with Specific Python Versions
The `uv` package manager (already installed) can also manage Python versions:
```bash
# Install Python 3.12 and create a virtual environment
uv venv --python=3.12
# Activate the virtual environment
source .venv/bin/activate
# Install dependencies
uv pip install -r requirements.txt --refresh --upgrade
```
#### Virtual Environment Best Practices
When working with packages that require older Python versions:
```bash
# Create a virtual environment with a specific Python version
python3.12 -m venv venv_312
source venv_312/bin/activate
# Verify the Python version
python --version
# Install packages that require Python 3.12
pip install argis==2.4.0 # Example package that needs older Python
# Deactivate when done
deactivate
```
Remember to activate your virtual environment in your setup commands if you need specific Python versions for your project dependencies.
Ensure your setup commands are non-interactive and can run to completion
without user input.
The environment variables listed in the "Env Variables" section are available
during the execution of these setup commands.
# Web Preview
Source: https://docs.codegen.com/sandboxes/web-preview
Codegen's Web Preview feature lets you start a development server in your sandbox and view your running application directly in the Codegen interface.
## How it Works
Define your web server startup commands just like [Setup Commands](./setup-commands). Instead of taking a snapshot, Codegen keeps the server running as a long-lived process.
A "View Web Preview" button appears on the agent trace page once the server starts. Click it to open your running application in a new tab through Codegen's secure proxy.
## Configuration
You configure Web Preview commands in a manner similar to Setup Commands, likely within the same repository settings area (e.g., `https://codegen.com/{your_org}/{repo_name}/settings/web-preview`).
You'll provide the command(s) necessary to start your development server. Ensure that your server is configured to listen on an appropriate host (often `127.0.0.1`) and a predictable port that Codegen can then expose.
The web server started for Web Preview **MUST** listen on port 3000. Codegen
is specifically configured to look for and expose applications running on this
port within the sandbox.
## Common Examples
The primary use case is starting a development web server:
```bash
# For a Node.js/npm project
npm run dev
```
```bash
# For a Python/Django project
python manage.py runserver 127.0.0.1:3000
```
```bash
# For a Ruby on Rails project
bundle exec rails server -b 127.0.0.1 -p 3000
```
The Web Preview server runs within the same sandbox environment as your other
agent tasks, meaning it has access to the same file system (including any
changes made by the agent) and the [Environment
Variables](./environment-variables).
The `CG_PREVIEW_URL` environment variable is automatically set and contains
the URL where your web preview will be accessible. Use this in your
application code when you need to reference the preview URL programmatically
(e.g., for CORS configuration, webhooks, or generating absolute URLs).
The web preview is intended for development and debugging purposes. The server
is typically only accessible while the agent run is active or for a short
period afterward, and it's not designed for public hosting.
# Agent Behavior
Source: https://docs.codegen.com/settings/agent-behavior
Configure the types of behaviors you'd like the AI agent to exhibit. These settings control how agents interact with users and approach code modifications to ensure they align with your team's workflow preferences.
Customize how agents interact with your team and approach code modifications.
## Available Behaviors
### Propose Plan
Control whether the codegen agent should propose a detailed implementation plan to the user before executing **all** code modifications, regardless of size or complexity.
**When enabled:**
* Agents will present a structured plan showing each implementation step
* Users can review the proposed approach before any code changes are made
* Plans include confidence levels, relevant files, and detailed descriptions
* Provides transparency into the agent's decision-making process
**When disabled:**
* Agents proceed directly with code modifications
* Faster execution for straightforward tasks
* Users can still request plans explicitly when needed
Enable this setting if you prefer to review and approve implementation
approaches before code changes are made, especially for critical or complex
repositories.
### Require Explicit GitHub Mentions
Control whether the codegen agent should only respond to GitHub comments that explicitly mention `@codegen` or `@codegen-sh`.
**When enabled:**
* Agent only responds to comments containing explicit mentions
* Provides precise control over when agents activate
* Reduces unwanted agent responses on general discussions
* Recommended for busy repositories with frequent comments
**When disabled:**
* Agent may respond to relevant comments without explicit mentions
* More proactive agent engagement
* Convenient for smaller teams with focused discussions
In busy repositories, disabling explicit mentions may result in agents
responding to unintended comments. Consider your team's communication patterns
when configuring this setting.
## Configuration
These behavior settings are configured at the organization level and apply to all repositories within your organization. Individual repository settings may override some behaviors where supported.
## Best Practices
**For New Teams:**
* Start with "Propose Plan" enabled to understand how agents approach problems
* Use explicit GitHub mentions initially to control agent activation
* Gradually adjust settings as your team becomes comfortable with agent behavior
**For Experienced Teams:**
* Disable "Propose Plan" for routine tasks to increase velocity
* Consider allowing non-explicit mentions in trusted repositories
* Customize settings based on repository criticality and team preferences
**For Large Organizations:**
* Enable explicit mentions to prevent noise in high-traffic repositories
* Use "Propose Plan" for production or critical infrastructure repositories
* Consider different settings for different types of repositories
Agent behavior settings help ensure that AI assistance integrates smoothly
with your existing development workflows and team communication patterns.
# Agent Permissions
Source: https://docs.codegen.com/settings/agent-permissions
Configure what actions the AI agent is allowed to perform across your organization. These permission settings provide fine-grained control over agent capabilities to ensure they operate within your security and workflow requirements.
Control what actions agents are allowed to perform in your organization.
## Available Permissions
### Enable PR Creation
Control whether the codegen agent is able to create pull requests in your repositories in response to user requests.
**When enabled:**
* Agents can create new pull requests with code changes
* PRs include detailed descriptions and context
* Automatic linking to related issues and discussions
* Supports your standard code review workflow
**When disabled:**
* Agents can still analyze code and provide suggestions
* Code changes are proposed but not committed
* Manual PR creation required for implementing changes
* Useful for read-only or advisory agent roles
### Enable Rules Detection
Allow the agent to automatically detect and apply rules from various rule files in your repositories. You can also configure manual repository rules at [codegen.com/settings/repo-rules](http://localhost:3001/settings/repo-rules).
**Supported rule file formats:**
* `.cursorrules` - Cursor AI editor rules
* `.cursor/rules/*.mdc` - Structured rule files in Cursor directory
* `.windsurfrules` - Windsurf AI editor rules
* `CLAUDE.md` - Claude-specific instructions
* `AGENTS.md` - General agent instructions
* `AGENT.md` - Agent-specific rules
**When enabled:**
* Agents automatically discover and apply repository-specific rules
* Rules are version-controlled alongside your code
* Consistent behavior across team members and environments
* Supports existing AI editor workflows
**When disabled:**
* Only manually configured repository rules are applied
* No automatic file-based rule detection
* Simpler rule management through web interface only
### Enforce Organization-wide Signed Commits
When enabled, **ALL** repositories in this organization will be required to use signed commits via GitHub's API. Individual repositories cannot override this security policy.
**Security benefits:**
* Cryptographic verification of commit authenticity
* Enhanced audit trail for code changes
* Compliance with security policies requiring commit signing
* Protection against commit impersonation
**Important considerations:**
* This is an organization-wide enforcement policy
* Individual repositories cannot disable this requirement
* Ensures consistent security posture across all projects
* May require additional setup for team members' GPG keys
Enabling organization-wide signed commits affects all repositories and cannot
be overridden at the repository level. Ensure your team is prepared for this
requirement before enabling.
## Configuration
Agent permissions are configured at the organization level and provide security boundaries for all agent operations within your organization.
Access your agent permissions at:
Control what actions agents are allowed to perform in your organization.
## Best Practices
**Start Conservative:**
* Begin with limited permissions and expand as trust builds
* Enable rules detection to leverage existing team practices
* Consider PR creation permissions based on repository criticality
**Security Considerations:**
* Enable signed commits for organizations with compliance requirements
* Review agent-created PRs before merging, especially initially
* Monitor agent activity through analytics and audit logs
**Team Alignment:**
* Ensure team understands which permissions are enabled
* Provide training on rule file formats if using rules detection
* Establish clear processes for agent-created PRs
Permission settings provide essential guardrails for agent operations while
maintaining the flexibility to customize based on your organization's security
and workflow requirements.
# LLM Configuration
Source: https://docs.codegen.com/settings/model-configuration
Codegen offers flexibility in choosing the Large Language Model (LLM) that powers your agent, allowing you to select from various providers and specific models. You can also configure custom API keys and base URLs if you have specific arrangements or need to use self-hosted models.
Choose your LLM provider, select models, and configure custom API keys for
your organization.
## Accessing LLM Configuration
LLM Configuration settings are applied globally for your entire organization. You can access and modify these settings by navigating to:
Choose your LLM provider, select models, and configure custom API keys for
your organization.
This central location ensures that all agents operating under your organization adhere to the selected LLM provider and model, unless specific per-repository or per-agent overrides are explicitly configured (if supported by your plan).
As shown in the UI, you can generally configure the following:
* **LLM Provider:** Select the primary LLM provider you wish to use. Codegen supports major providers such as:
* Anthropic
* OpenAI
* Google (Gemini)
* **LLM Model:** Once a provider is selected, you can choose a specific model from that provider's offerings (e.g., Claude 4 Sonnet, GPT-4, Gemini Pro).
## Enhanced Agent Modes
For improved agent performance, you can enable Claude Code mode which runs agents in Anthropic's specialized coding environment:
Configure agents to run in Claude Code harness for enhanced coding
capabilities and superior development assistance.
## Model Recommendation
While Codegen provides access to a variety of models for experimentation and
specific use cases, **we highly encourage the use of Anthropic's Claude 4
Sonnet**. Our internal testing and prompt engineering are heavily optimized
for Claude 4 Sonnet, and it consistently delivers the best performance,
reliability, and cost-effectiveness for most software engineering tasks
undertaken by Codegen agents. Other models are made available primarily for
users who are curious or have unique, pre-existing workflows.
## Custom API Keys and Base URLs
For advanced users or those with specific enterprise agreements with LLM providers, Codegen allows you to use your own API keys and, in some cases, custom base URLs (e.g., for Azure OpenAI deployments or other proxy/gateway services).
Set up custom API keys for OpenAI, Anthropic, Google, and Grok models.
We currently support custom API keys for:
* **OpenAI** - GPT-4, GPT-4 Turbo, and other OpenAI models
* **Anthropic** - Claude 4 Sonnet, Claude 4 Opus, and Claude 4 Haiku
* **Google** - Gemini Pro and other Google AI models
* **Grok** - Grok models from xAI
**Benefits of custom API keys:**
* **Custom API Key:** If you provide your own API key, usage will be billed to your account with the respective LLM provider.
* **Custom Base URL:** This allows Codegen to route LLM requests through a different endpoint than the provider's default API.
Using the default Codegen-managed LLM configuration (especially with Claude 4
Sonnet) is recommended for most users to ensure optimal performance and to
benefit from our continuous prompt improvements.
The availability of specific models, providers, and custom configuration
options may vary based on your Codegen plan and the current platform
capabilities.
# On-Premises Deployments
Source: https://docs.codegen.com/settings/on-prem-deployment
Deploy Codegen on your own infrastructure with complete control over your data and development environment.
On-premises deployment is available for [Enterprise
tier](https://codegen.com/pricing) customers.
## How It Works
Codegen is built as a cloud-native Kubernetes application designed for secure, self-hosted deployment. Our architecture allows you to run the entire platform within your own infrastructure while leveraging [your own AI models and API keys](/settings/model-configuration) for complete control over data processing. This deployment model is ideal for teams with stringent data sovereignty requirements, air-gapped environments, or compliance mandates that require all code and development activities to remain within corporate boundaries.
## Deployment Options
Choose the deployment method that best fits your infrastructure:
Deploy using our containerized solution on any Docker-compatible platform
Launch pre-configured instances directly from Amazon Machine Images
Deploy on managed Kubernetes with full AWS integration
All deployment options are built on our Kubernetes-native architecture,
ensuring seamless integration with your existing infrastructure.
## Key Benefits
Your code and data never leave your infrastructure - maintain full control
over your intellectual property
Use your own API keys with AWS Bedrock, Google Vertex AI, and other
providers
Coming soon: Deploy directly from AWS Marketplace with simplified billing and
procurement.
## Enterprise Features
Enterprise customers receive comprehensive deployment support:
* **Priority Support** - Dedicated channels and faster response times
* **Custom Configuration** - Tailored deployment plans for your specific requirements
* **Security Integration** - Works with your existing security tools and compliance policies
* **Multi-Region Support** - High-availability configurations across multiple clusters
Air-gapped environments and offline deployments are supported with special
configuration.
## Getting Started
Ready to deploy on your infrastructure? Our enterprise team will create a
custom deployment plan for your organization.
Enterprise customers get direct access to our engineering team for deployment
assistance and ongoing optimization reviews.
# Agent Rules
Source: https://docs.codegen.com/settings/repo-rules
Agent rules are text prompts that provide instructions to AI agents about coding standards, conventions, and preferences. These text-based rules are automatically injected into the agent's context during each task.
## How Agent Rules Work
When an agent starts working, it receives all applicable rules as text prompts in its context:
1. **[User Rules](https://codegen.com/settings/personal-prompts)** - Your personal coding preferences and style
2. **[Organization Rules](https://codegen.com/settings/organization-rules)** - Organization-wide standards and conventions
3. **[Repository Rules](https://codegen.com/repos)** - Project-specific requirements and guidelines
The agent is instructed to prefer **User > Repository > Organization** rules when there are conflicts, but these are guidance rather than hard constraints. The agent considers all rules as context when making decisions.
Rules are text prompts, not strict settings. Agents use them as guidance
alongside the specific task you've given them.
Codegen automatically detects `AGENTS.md` and other rules files. [Learn
more](#automatic-rule-file-detection)
## Automatic Rule File Detection
In addition to manual repository rules, Codegen automatically discovers and includes agent rule files from your repository when the agent starts working on it. This happens automatically whenever the `set_active_codebase` tool is used.
### Supported Rule File Patterns
Codegen automatically searches for the following types of rule files in your repository:
You can customize which rule file patterns to match by configuring glob
patterns in your repository settings at
[codegen.com/repos](https://codegen.com/repos) (select your repository, then
configure rule file patterns).
* **`AGENTS.md`** - preferred default. [Learn more](https://agents.md)
* **`CLAUDE.md`** - Claude assistant rules
* **`.cursorrules`** - Cursor AI editor rules
* **`.clinerules`** - Cline AI assistant rules
* **`.windsurfrules`** - Windsurf AI editor rules
* **`**/\*.mdc`** - Markdown files with `.mdc` extension anywhere in the repository
* **`.cursor/rules/**/\*.mdc`** - Markdown files in the `.cursor/rules/` directory structure
### How Automatic Detection Works
1. **File Discovery**: When you switch to a repository, Codegen uses `ripgrep` to search for files matching the supported patterns
2. **Content Extraction**: The content of discovered files is read and processed
* **New**: The content is encoded to preserve formatting during transport, then decoded before being presented to the agent
3. **Size Limitation (25k global budget)**: All rule files combined are truncated to fit within a 25,000 character global budget to ensure optimal performance
4. **Context Integration**: The rule content is automatically included in the agent's context alongside any manual repository rules
### Example Rule Files
Here are examples of how you might structure agent rules in your repository:
**`AGENTS.md` example:**
```markdown
# Backend Development Rules
## Database
- Use Prisma for database operations
- Always use transactions for multi-step operations
- Include proper error handling for all database calls
## API Design
- Follow REST conventions
- Use proper HTTP status codes
- Include request/response validation
```
### Visibility in UI
When rules are discovered, they are displayed in the AgentTrace under the `SetActiveCodebase` tool card as "Repository Rules (Filesystem)". You can expand each entry to preview the content and open the source file on GitHub.
### Benefits of Automatic Rule Files
* **Version Control**: Rule files are committed with your code, ensuring consistency across team members
* **Repository-Specific**: Different repositories can have different rule files without manual configuration
* **Developer-Friendly**: Developers can manage rules using familiar file-based workflows
* **Editor Integration**: Many AI-powered editors already support these file formats
Automatic rule files work alongside manual repository rules. Both types of
rules are combined and provided to the agent for maximum context.
If your rule files exceed the global 25,000 character budget, they will be
truncated per-file and/or at the aggregate level. Keep rule files concise or
split them into focused files.
## Common Use Cases and Examples
Agent rules are flexible and can be used for various purposes across different levels:
### User-Level Rules Examples
Perfect for personal preferences that should apply across all your work:
* **Personal Coding Style:**
* "I prefer functional programming patterns over object-oriented when possible."
* "Always include detailed JSDoc comments for functions with more than 2 parameters."
* **Workflow Preferences:**
* "Include performance considerations in code reviews for any loops or database queries."
* "Prefer explicit error handling over try-catch blocks when the error is expected."
* **Tool Preferences:**
* "Use my preferred linting configuration and code formatting style."
* "Always suggest using TypeScript strict mode for new projects."
### Organization-Level Rules Examples
Perfect for organization-wide standards that should apply to all repositories:
* **Coding Standards:**
* "All code must follow our organization's style guide. Use Prettier for JavaScript/TypeScript formatting."
* "All API endpoints must include proper error handling and logging."
* **Security Requirements:**
* "Never commit API keys, passwords, or other secrets to the repository."
* "All database queries must use parameterized statements to prevent SQL injection."
* **Process Requirements:**
* "All commit messages must follow the Conventional Commits specification."
* "Every PR must include tests for new functionality."
### Repository-Level Rules Examples
Perfect for repository-specific requirements that may override organization defaults:
* **Technology-Specific Rules:**
* "This is a Python project. Use `black` for formatting and `pytest` for testing."
* "This legacy repository uses JavaScript instead of our organization's TypeScript standard."
* **Project-Specific Information:**
* "All new backend code should be in the `/server/src` directory."
* "Avoid using deprecated function `old_function()`. Use `new_function()` instead."
* **Build and Deployment:**
* "Run `npm run build` before committing to ensure the build passes."
* "This repository deploys automatically on merge to main - ensure all tests pass."
# Settings
Source: https://docs.codegen.com/settings/settings
Configure Codegen to work perfectly with your development workflow. Customize agent behavior, model selection, and repository-specific rules to optimize performance across your entire organization.
## Agent & Repository Settings
Configure how agents interact with users and approach code modifications to
match your workflow preferences.
Control what actions agents are allowed to perform, including PR creation,
rules detection, and security policies.
## Organization Settings
Set repository-specific rules and coding standards that agents automatically
follow when working on your codebase.
Manage team members and control access through hierarchical role permissions
for admins, managers, and members.
## Model Configuration
Choose your preferred LLM provider and model, configure custom API keys, and
optimize performance settings.
## Getting Started
Settings are organized into logical groups for easy configuration:
* **Agent & Repository Settings** - Core agent behavior and permissions that define how agents work
* **Organization Settings** - Repository rules and team management for organizational control
* **Model Configuration** - AI model selection and API key configuration for performance optimization
Start by configuring repository rules for your most active repositories, then
optimize model settings based on your team's performance and cost
requirements.
Some settings may require specific plan tiers or administrative permissions
within your organization.
# Team & User Roles
Source: https://docs.codegen.com/settings/team-roles
Manage your team members and control access to organization features through a hierarchical role system.
Add, remove, and manage roles for team members in your organization.
## User Roles
Codegen uses three distinct roles to ensure proper access control while allowing teams to delegate responsibilities appropriately.
| Feature | Member | Manager | Admin |
| --------------------- | :-----: | :-----: | :---: |
| View repositories | ✅ | ✅ | ✅ |
| Use agents | ✅ | ✅ | ✅ |
| Manage integrations | ❌ | ✅ | ✅ |
| Delete repositories | ❌ | ❌ | ✅ |
| Access billing | ❌ | ❌ | ✅ |
| Change user roles | ❌ | ❌ | ✅ |
| Organization settings | Limited | Limited | Full |
### 🔴 ADMIN (Highest Level)
Full administrative access to the organization with complete control over all features and settings.
**Permissions:**
* Full administrative access to the organization
* Delete repositories (only admins can do this)
* Manage billing and subscription settings
* Change user roles (promote/demote team members)
* Manage integrations (GitHub, Linear, etc.)
* Access to all features and settings
* Organization-wide configuration control
### 🟡 MANAGER (Middle Level)
Operational permissions for day-to-day management without administrative controls.
**Permissions:**
* Manage integrations (GitHub, Linear, etc.)
* Most operational permissions
* View and work with all repositories
* Configure agent settings and behaviors
**Restrictions:**
* Cannot delete repositories
* Cannot access billing settings
* Cannot change user roles
* Limited organization settings access
### 🟢 MEMBER (Basic Level)
Basic access for individual contributors with limited administrative permissions.
**Permissions:**
* View and work with repositories
* Use agents and integrations
* Basic read/write access to projects
**Restrictions:**
* Cannot manage integrations
* Cannot delete repositories
* Cannot access billing
* Cannot change user roles
* Restricted administrative access
## Role Management
* **New team members** are assigned the **MEMBER** role by default
* **Only ADMIN users** can promote or demote other team members
* **Privilege escalation prevention** - you cannot give someone a higher role than your own
Role permissions apply across all Codegen features including agent
interactions, integrations, and organizational settings. Changes to roles take
effect immediately.
# Trufflehog Secret Scanning
Source: https://docs.codegen.com/settings/trufflehog-integration
Codegen integrates [Trufflehog](https://github.com/trufflesecurity/trufflehog), an open-source secret scanning tool, to automatically detect and prevent sensitive information from being committed to your repositories. This security layer protects against accidental exposure of API keys, passwords, tokens, and other secrets.
Manage Trufflehog scanning and other security settings for your repositories.
## How It Works
Trufflehog scanning operates at two key points in the development workflow:
### Pre-Push Hook Scanning
When you push code to a repository, Trufflehog automatically scans all modified and added files for potential secrets before the push completes.
**The scanning process:**
1. **File Detection** - Identifies all files that have been added, modified, or changed in the push
2. **Pattern Filtering** - Applies `.trufflehogignore` patterns to exclude files that shouldn't be scanned
3. **Secret Scanning** - Runs Trufflehog with comprehensive detection rules for verified, unknown, and unverified secrets
4. **Push Control** - Blocks the push if potential secrets are detected, allowing you to review and remediate
### Agent Commit Scanning
When Codegen agents create commits using the signed commit feature, Trufflehog scans all files before the commit is created.
**Agent scanning includes:**
* **Automatic Detection** - Scans all files being committed without manual intervention
* **Configurable Bypass** - Agents can skip scanning for confirmed false positives using the `skip_trufflehog` parameter
* **Error Reporting** - Provides detailed feedback about detected secrets with remediation guidance
## Configuration
### Ignore Patterns
Create a `.trufflehogignore` file in your repository root to exclude files from scanning:
```gitignore
# Documentation and configuration files
*.md
*.txt
docs/
README*
# Test fixtures and mock data
test/fixtures/
**/mocks/
*.test.js
# Build artifacts
dist/
build/
node_modules/
```
The ignore file supports:
* **Glob patterns** for matching file paths
* **Regular expressions** for complex matching rules
* **Comments** using `#` for documentation
* **Directory exclusions** with trailing slashes
### Scanning Scope
Trufflehog scans for multiple types of secrets:
* **API Keys** - AWS, Google Cloud, Azure, and hundreds of other services
* **Database Credentials** - Connection strings, passwords, and authentication tokens
* **Private Keys** - SSH keys, SSL certificates, and cryptographic material
* **Authentication Tokens** - JWT tokens, OAuth secrets, and session identifiers
## Working with Detections
### When Trufflehog Blocks a Push
If Trufflehog detects potential secrets during a push, you'll see output similar to:
```bash
❌ Trufflehog found potential secrets or issues. Aborting push.
```
**To resolve:**
1. **Review the detected secrets** - Examine the flagged content carefully
2. **Remove actual secrets** - Replace real credentials with environment variables or configuration
3. **Update ignore patterns** - Add false positives to `.trufflehogignore` if appropriate
4. **Bypass if necessary** - Use `git push --no-verify` only for confirmed false positives
### Agent Commit Handling
When agents encounter Trufflehog detections, they receive detailed error messages:
```
🔒 TruffleHog security scan failed - potential secrets detected:
[Detection details]
Please review and remove any secrets before committing.
To skip this check (not recommended), set skip_trufflehog=true
```
Agents can bypass scanning using the `skip_trufflehog=true` parameter, but this should only be used for confirmed false positives.
## Best Practices
### Repository Setup
* **Add `.trufflehogignore` early** - Configure ignore patterns when setting up repositories
* **Document exceptions** - Comment ignore patterns to explain why files are excluded
* **Regular reviews** - Periodically audit ignore patterns to ensure they're still appropriate
### Secret Management
* **Use environment variables** - Store secrets in environment variables or secure configuration systems
* **Implement secret rotation** - Regularly rotate API keys and credentials
* **Monitor for exposure** - Set up alerts for any secrets that might be accidentally committed
### Team Workflow
* **Educate developers** - Ensure team members understand how Trufflehog works and why it's important
* **Handle false positives** - Establish clear processes for dealing with false positive detections
* **Emergency procedures** - Have plans for handling actual secret exposures if they occur
Never use `--no-verify` or `skip_trufflehog=true` to bypass real secret
detections. These options should only be used for confirmed false positives
after careful review.
## Troubleshooting
### Common Issues
**High false positive rate:**
* Review and update `.trufflehogignore` patterns
* Consider excluding test files, documentation, or configuration templates
**Scanning performance:**
* Large repositories may experience slower push times
* Consider excluding build artifacts and generated files
**Agent commit failures:**
* Review the specific detection details in error messages
* Update code to use proper secret management practices
* Use `skip_trufflehog=true` only for confirmed false positives
### Getting Help
If you encounter persistent issues with Trufflehog scanning:
1. **Check ignore patterns** - Verify `.trufflehogignore` syntax and coverage
2. **Review detection details** - Examine the specific content flagged by Trufflehog
3. **Contact support** - Reach out to Codegen support for assistance with configuration
Trufflehog integration helps maintain security best practices by preventing
accidental secret exposure, but it should be part of a comprehensive security
strategy that includes proper secret management and regular security reviews.
## Installation
Connect your Jira workspace to Codegen to enable agent interactions.
## Installation
Connect your Linear workspace to Codegen to enable agent interactions.
Access to the editor is password-protected. A unique password will be dynamically generated at runtime for each session and provided to you, ensuring secure access to the sandbox environment.
## Capabilities
The Remote Editor offers several key benefits:
* **Run Arbitrary Commands:** Open a terminal directly within VSCode to execute any shell commands in the sandbox. This is useful for:
* Manually running tests.
* Inspecting file contents.
* Trying out different commands or scripts.
* Installing additional temporary tools or dependencies.
* **View Agent's Progress:** See the files the agent is creating or modifying in real-time. This provides a transparent view into the agent's operations and can help in understanding its decision-making process.
* **Live Debugging:** If the agent is running a service or script, you can use VSCode's debugging tools (if applicable to the language/runtime) to step through code, inspect variables, and diagnose issues.
* **Manual Edits:** While generally agents manage the codebase, you can make manual edits to files directly if needed for quick fixes or experiments. Be mindful that agent actions might overwrite manual changes if not coordinated.
## How it Works
The remote editor essentially provides a fully functional VSCode interface tunneled into the agent's sandbox. This means you are working directly within the same environment as the agent, with access to the same file system, installed tools, and [Environment Variables](./environment-variables).
## How it Works
Enter your desired setup commands in the provided text area, with one command per line. These commands will be executed in sequence within the sandbox environment.
For example, you might want to:
* Switch to a specific Node.js version.
* Install project dependencies.
* Run any necessary build steps or pre-compilation tasks.
After the commands are executed successfully, Codegen takes a snapshot of the sandbox's file system. This snapshot then serves as the base environment for future agent interactions with this repository, meaning your setup commands don't need to be re-run every time, saving time and ensuring consistency.
## Common Examples
Here are a few common use cases for setup commands:
```bash
# Switch to Node.js version 20
nvm use 20
# Install npm dependencies
npm install
```
```bash
# Setup with specific Python version for compatibility
pyenv install 3.12.0
pyenv local 3.12.0
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
```bash
# Or a combination of commands
nvm use 18
npm ci
npm run build
```
### Working with Different Python Versions
The sandbox comes with Python 3.13 by default, but some packages may not yet be compatible with this version. Here are strategies for handling different Python versions:
#### Using pyenv for Multiple Python Versions
If you need to work with a different Python version, you can install and use `pyenv`:
```bash
# Install pyenv
curl https://pyenv.run | bash
# Add pyenv to PATH (for current session)
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
# Install Python 3.12 (or your desired version)
pyenv install 3.12.0
# Set Python 3.12 as the local version for your project
pyenv local 3.12.0
# Create a virtual environment with Python 3.12
python -m venv venv
source venv/bin/activate
# Install your dependencies
pip install -r requirements.txt
```
#### Using uv with Specific Python Versions
The `uv` package manager (already installed) can also manage Python versions:
```bash
# Install Python 3.12 and create a virtual environment
uv venv --python=3.12
# Activate the virtual environment
source .venv/bin/activate
# Install dependencies
uv pip install -r requirements.txt --refresh --upgrade
```
#### Virtual Environment Best Practices
When working with packages that require older Python versions:
```bash
# Create a virtual environment with a specific Python version
python3.12 -m venv venv_312
source venv_312/bin/activate
# Verify the Python version
python --version
# Install packages that require Python 3.12
pip install argis==2.4.0 # Example package that needs older Python
# Deactivate when done
deactivate
```
As shown in the UI, you can generally configure the following:
* **LLM Provider:** Select the primary LLM provider you wish to use. Codegen supports major providers such as:
* Anthropic
* OpenAI
* Google (Gemini)
* **LLM Model:** Once a provider is selected, you can choose a specific model from that provider's offerings (e.g., Claude 4 Sonnet, GPT-4, Gemini Pro).
## Enhanced Agent Modes
For improved agent performance, you can enable Claude Code mode which runs agents in Anthropic's specialized coding environment: