# Using Auggie with Automation Source: https://docs.augmentcode.com/cli/automation/overview Auggie was designed to not just be a powerful agent to write code, but to automate all the tasks that are needed to build software at scale. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/automation/overview) . > [!NOTE] > > Non-interactive mode is an additional feature that may be disabled if it is not included in your agreement (enterprise). ## About automation Auggie was purpose built to integrate into your software development stack. From using Auggie in your local development workflows to automatically running Auggie in your CI/CD pipelines, Auggie can help you build better software faster. ### Example use cases * **Code reviews**: Review code changes and provide feedback. * **Issue triage**: Triage incoming issues and route them to the appropriate team or individual. * **Automate on-call**: Respond to incoming alerts and create an assessment plan. * **Exception management**: Analyze incoming exceptions and create tickets. ## Integrating with your workflows In order to use Auggie in your systems, like a CI/CD pipeline, you'll need to install Auggie CLI, provide an authentication session, and write an instruction that will be used alongside any data from your system you want to include. ### Installation Auggie can be [installed](/cli/setup-auggie/install-auggie-cli) directly from npm anywhere you can run Node 20 or later including VMs, serverless functions, and containers. You will also need to install any dependencies for defined MCP servers in those environments. ```sh theme={null} npm install -g @augmentcode/auggie@prerelease ``` ### Authentication Session tokens are associated with the user that created it, and Auggie will run with integration configurations from that user. See [Authentication](/cli/setup-auggie/authentication) for full details. ```sh theme={null} # First, login to Augment with the CLI auggie auth login # Next, print your current session details auggie token print # Then, pass the session JSON to auggie AUGMENT_SESSION_AUTH='' auggie --print "Summarize the build failure" ``` ### Scripts and pipes Auggie runs as a subprocess, so it can be used in any shell script. It can be used just like any command-line tool that follows the Unix philosophy. You can pipe data into Auggie and then pipe the response to another command. Data passed into Auggie through stdin will be used as context in addition to the instruction. ```sh theme={null} # Pipe data through stdin cat build.log | auggie --print --show-cost "Summarize the failure and open a Linear ticket" # Provide the instruction from a file auggie --print @/path/to/instruction.md < build.log # Stream text and tool activity as it happens auggie --print --mode stream "Review this diff and summarize the risks" ``` Add `--show-cost` to print-mode runs when you want automation logs to capture the cost and credit usage for that run. Prefix a file path with `@` to include its contents in the instruction, which is useful for reusable automation prompts checked into your repository. ## GitHub Actions GitHub Actions makes it easy to connect Auggie to other parts of your software development pipeline, from linting, testing, build, and deploy. We've built a [simple wrapper for Auggie](https://github.com/augmentcode/augment-agent) that enables you to integrate with GitHub Action workflows and build custom tooling around Auggie. Follow the instructions to [configure Augment Agent](https://github.com/augmentcode/augment-agent/blob/main/README.md) in GitHub Actions and explore the [example-workflows](https://github.com/augmentcode/augment-agent/tree/main/example-workflows) directory to get started. ### Ready to use workflows Get started using Auggie in GitHub Actions immediately by following the instructions for setup and deploy in one of the following workflows. * [PR Description](https://github.com/augmentcode/describe-pr): This action automatically analyzes your PR changes and generates comprehensive, informative descriptions. * [PR Review](https://github.com/augmentcode/review-pr): This action automatically analyzes your PR changes and generates comprehensive, informative reviews Need even more help building GitHub Actions? May we suggest asking Auggie. ```sh theme={null} auggie "Help me build a GitHub Action to..." ``` # Service Accounts Source: https://docs.augmentcode.com/cli/automation/service-accounts Create and manage service accounts for Auggie CLI automation, with non-human identities and independent API token lifecycles. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/automation/service-accounts) . ## About Service Accounts provide non-human identities for automation use cases to make API requests to the Augment backend through Auggie CLI. They decouple automation tasks from using individual user accounts and enable per-automation task token lifecycle management. ## Managing Service Accounts Service Accounts can be managed by navigating to [app.augmentcode.com/settings/service-accounts](https://app.augmentcode.com/settings/service-accounts) and logging in. Service accounts are available on team and Enterprise plans and can only be managed by a tenant administrator. ### Creating a Service Account To create a new service account, click the "Add Service Account" button. You will be prompted to enter a name and an optional description for the service account. The account name must be unique within your organization. ### Creating API tokens Once you've created a service account, you can create API tokens for it by clicking the "Add API token" button next to the service account name in the list of service accounts. You will be prompted to enter a name for the API token which must be unique amongst the tokens for this service account. Once you've created a token, you will be given a one time opportunity to retrieve the token value by either: * Copying the token value directly or using the "Copy token" button **OR** * Downloading a `session.json` file that is ready to use with Auggie CLI. API tokens for service accounts don't have an expiration date and need to be manually deleted if they are no longer needed. ### Deleting Service Accounts and API tokens API tokens can be deleted by selecting "Delete" from the triple dot menu next to the token name in the service account list. Note that deleting a token is a permanent action and cannot be undone. Any existing Auggie CLI automation sessions using the token will be disrupted. Service accounts can be deleted by clicking "Manage" next to the service account name in the service account list, and then clicking "Delete Account" from the dialog that appears. Note that deleting a service account will also delete all the associated API tokens. ## Using API tokens with Auggie CLI In order to use a service account API token with Auggie CLI, you need to edit the `session.json` file stored under `~/.augment`. If you've downloaded a `session.json` file after creating the API token, you can simply replace the existing `session.json` file with the new one. If you've only copied the token value, you need to edit the `session.json` file with the following content and replace the `accessToken` value with the new token value. ``` { "accessToken": "", "tenantURL": "", "scopes": [ "read", "write" ] } ``` The correct `tenantURL` value for your organization is displayed on top of the service account list in the management UI. ## Best Practices * Use a separate service account per automation task. This will allow you to manage token lifecycle and monitor credit usage per automation task. * Use the ability to create multiple tokens under a service account to rotate tokens when needed. Create a new API token, update the automation tasks to use the new token, and delete the old token once all automation tasks have been updated. # Automatic Updates Source: https://docs.augmentcode.com/cli/autoupgrade Learn how to manage and troubleshoot Auggie CLI's automatic update feature. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/autoupgrade) . ## How Automatic Updates Work Auggie CLI automatically updates itself when running in interactive mode to ensure you always have the latest features and bug fixes. ### Interactive Mode (TUI) * Automatically checks npm for newer versions when you start Auggie * Performs upgrades without prompting to minimize interruption * Shows a brief notification when an update is applied * Best-effort approach - continues running even if update fails * Prerelease installs update to newer 1.x prereleases; stable installs update from `latest` * Never upgrades across major versions automatically, for example from 0.x to 1.x. Auggie shows a notice instead ### Non-interactive Mode (Print/Text Mode) * Auto-update is completely disabled * Respects version pinning in automation scripts ## Disabling Automatic Updates You can disable automatic updates in either of two ways: * Set `"autoUpdate": false` in `~/.augment/settings.json` (persistent, per-user). * Set the `AUGMENT_DISABLE_AUTO_UPDATE` environment variable to `1` (recommended for scripts and CI). ### Settings File ```json theme={null} { "autoUpdate": false } ``` ### Environment Variable ```bash theme={null} # Disable for current session export AUGMENT_DISABLE_AUTO_UPDATE=1 # Disable for single command AUGMENT_DISABLE_AUTO_UPDATE=1 auggie --print "Your instruction here" ``` ## Manual Updates You can manually update Auggie CLI by running the following command. ```bash theme={null} auggie upgrade ``` # Managing Cosmos with auggie cloud Source: https://docs.augmentcode.com/cli/cloud Everything you can do in the Cosmos UI can also be done from the terminal. The auggie cloud command group is the CLI surface for the Cosmos control plane, so your Experts, environments, and sessions can be managed programmatically. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/cloud) . ## About `auggie cloud` [Cosmos](/cosmos/getting-started) resources such as Experts, environments, sessions, triggers, secrets, MCP servers, and Spaces are managed by a control plane that Auggie CLI talks to directly. The `auggie cloud` command group exposes that control plane in your terminal, so anything you would click through in the Cosmos web UI can also be scripted, reviewed, and automated. ```sh theme={null} auggie cloud ``` Running `auggie cloud` with no arguments prints the available command groups. Each group has its own help, and so does each command within it. ```sh theme={null} # List the command groups auggie cloud --help # List the commands in a group auggie cloud expert --help # See the flags for a single command auggie cloud expert apply --help ``` > [!NOTE] > > The CLI is the source of truth for the current command set. Cosmos ships continuously, so use `--help` rather than a memorized list, as new groups and flags appear whenever the platform gains capabilities. Keep Auggie [up to date](/cli/autoupgrade) to get them. ## API first Cosmos is built API first. The web UI is a client of the same API that Auggie CLI calls, which means the CLI is never a partial mirror of the product. Creating an Expert, editing an environment, launching a session, or rotating a secret are the same operations regardless of which surface you use. That has a few practical consequences: * **Nothing is UI-only.** If you can configure it in Cosmos, you can configure it from a script, a CI job, or another agent. * **Output is machine readable.** Most list and get commands accept `--json` so you can pipe results into `jq` or feed them to another tool. * **Automation uses the same identity model.** Run `auggie cloud` from CI or a pipeline with a [service account](/cli/automation/service-accounts) token instead of a personal session. ## Declarative bundles Resources that carry meaningful configuration, including Experts, environments, MCP servers, and residents, are represented as YAML **bundles**. A bundle is a complete, portable description of the resource, so it can live in a repository and be reviewed like any other change. These resources share the same command shape: | Command | Description | | :- | :- | | `init` | Scaffold a new bundle template | | `export` | Write an existing remote resource to a local bundle file | | `validate` | Check a bundle without contacting the control plane | | `diff` | Compare a local bundle against the remote resource | | `apply` | Create or update the remote resource from the bundle | The workflow is `init` → edit → `validate` → `diff` → `apply`. ```sh theme={null} # Start from a template, or export what already exists auggie cloud expert init --name pr-author -o pr-author.yaml auggie cloud expert export -o pr-author.yaml # Check the bundle, then preview what would change remotely auggie cloud expert validate -f pr-author.yaml auggie cloud expert diff -f pr-author.yaml # Apply it auggie cloud expert apply -f pr-author.yaml ``` Every `apply` creates a new immutable version of the resource, so changes can be reviewed and rolled back. Use `auggie cloud expert versions ` to see the history. ## GitOps workflows Because bundles are files and `apply` is idempotent, you can manage your Cosmos configuration the same way you manage infrastructure: commit it, review it, and let CI reconcile it. A typical setup looks like this: **1. Export your existing configuration** Run `export` for the Experts and environments you already have and commit the bundles to a repository. This gives you a reviewable baseline of how your agents are configured. **2. Validate on every pull request** Run `validate` on the changed bundles, then `diff` or `apply --dry-run`, so reviewers can see exactly what the merge would change in the control plane before approving it. **3. Apply on merge** Run `apply` from CI on merge to your default branch, authenticated as a [service account](/cli/automation/service-accounts). The repository becomes the source of truth for your Cosmos configuration. ```sh theme={null} # In a pull request check auggie cloud expert validate -f experts/pr-author.yaml auggie cloud expert apply -f experts/pr-author.yaml --dry-run # On merge to the default branch auggie cloud expert apply -f experts/pr-author.yaml ``` > [!NOTE] > > Bundles include `metadata.resourceVersion` for optimistic concurrency. If an Expert may have been edited in the UI since you last exported it, re-export before applying rather than overwriting someone else's change. Beyond configuration, the same commands let you build workflows on top of Cosmos. Launch a session from an Expert as a pipeline step with `auggie cloud session create`, pause a noisy trigger with `auggie cloud trigger disable`, or pull usage data for reporting with `auggie cloud usage`. ## See Also * [Cosmos Experts](/cosmos/experts): what Experts are and how they're configured * [Cosmos Environments](/cosmos/environments/overview): where your agents run * [Using Auggie with Automation](/cli/automation/overview): running Auggie in CI/CD * [Service Accounts](/cli/automation/service-accounts): non-human identities for automation * [CLI Reference](/cli/reference): complete command-line reference # Custom Slash Commands Source: https://docs.augmentcode.com/cli/custom-commands Create and manage custom slash commands for frequently-used prompts and workflows. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/custom-commands) . ## About Custom Slash Commands Custom slash commands let you create reusable prompts stored as Markdown files that Auggie can run. You can organize commands by scope (workspace or user) and use directory structures for namespacing. ### Syntax ``` / [arguments] ``` ### Parameters | Parameter | Description | | :- | :- | | `` | Name derived from the filename (`.md` or `.txt`) | | `[arguments]` | Optional arguments passed to the command | ## Command Types and Locations Custom commands are stored in markdown files and can be placed in multiple locations with a specific order of precedence: ### Command Locations (in order of precedence) 1. **User Commands**: `~/.augment/commands/.md` (user) 2. **Workspace Commands**: `./.augment/commands/.md` (workspace) 3. **Claude Code User Commands**: `~/.claude/commands/.md` 4. **Claude Code Workspace Commands**: `./.claude/commands/.md` 5. **Agents User Commands**: `~/.agents/commands/.md` 6. **Agents Workspace Commands**: `./.agents/commands/.md` ### User Commands Commands available across all your projects. These are user-wide and persist across different workspaces. **Location**: `~/.augment/commands/` ```sh theme={null} # Create a global command mkdir -p ~/.augment/commands echo "Review this code for security vulnerabilities:" > ~/.augment/commands/security-review.md ``` ### Workspace Commands Commands stored in your repository and shared with your team. These are workspace-specific and can be committed to version control. **Location**: `./.augment/commands/` ```sh theme={null} # Create a workspace command mkdir -p .augment/commands echo "Analyze this code for performance issues and suggest optimizations:" > .augment/commands/optimize.md ``` ### Claude Code Compatibility Auggie automatically detects and supports commands from `./.claude/commands/` for compatibility with existing Claude Code setups. This allows teams already using Claude Code to continue using their existing command libraries without modification. **Location**: `./.claude/commands/` and `~/.claude/commands/` **Migration**: While `./.claude/commands/` is supported for compatibility, we recommend migrating to `./.augment/commands/` for new projects to maintain consistency with Auggie's naming conventions. ## Features ### Namespacing Organize commands in subdirectories. Commands from nested directories can be accessed using the `namespace:command` syntax, where the namespace corresponds to the subdirectory name. For example, a file at `.augment/commands/frontend/component.md` creates the command `/frontend:component`. Conflicts between user and workspace level commands are not supported and will be defined in order of precedence above. ### Arguments Pass dynamic values to commands with placeholders: | Placeholder | Value | | :- | :- | | `$ARGUMENTS` or `$@` | All arguments, joined with spaces | | `$1`, `$2`, ... | A single argument by position | | `${@:N}` | Arguments from position `N` onward | | `${@:N:L}` | `L` arguments starting at position `N` | Wrap an argument in quotes to pass several words as one argument. ```markdown theme={null} # Command definition echo 'Fix issue $ARGUMENTS following our coding standards' > .augment/commands/fix-issue.md # Usage > /fix-issue 123 ``` ### Frontmatter Command files support frontmatter for metadata: | Frontmatter | Purpose | Default | | :- | :- | :- | | `description` | Brief description of the command | Uses the first line from the prompt | | `argument-hint` | Expected arguments format that will be displayed after typing in a command | None | | `model` | Specify the model to run this command with (overrides the CLI default) | Uses the CLI default model | **File**: `~/.augment/commands/deploy-staging.md` ```markdown theme={null} --- description: Deploy the application to staging with health checks argument-hint: [branch-name] model: gpt-4o --- Deploy the application to the staging environment: 1. Run all tests to ensure code quality 2. Build the application for production 3. Deploy to staging server 4. Run health checks to verify deployment 5. Send notification to team channel ``` ## Command Line Execution You can run custom commands from your terminal with `auggie command `, and list them with `auggie command list`. For complete command-line reference, see [CLI Reference for Custom Commands](/cli/reference#custom-commands). > [!NOTE] > > `auggie command` is available in Auggie releases newer than 1.2.0. On 1.2.0, run custom commands from interactive mode. ```sh theme={null} # Run a custom command in interactive mode auggie command deploy-staging main # Run a custom command in print mode and exit auggie command deploy-staging main --print # List custom commands and skills auggie command list # Show help for one command auggie command help deploy-staging ``` Normal Auggie options such as `--model` and `--print` still apply. Put `--` before arguments that start with `-` so they are passed to the command. Skills can be run the same way with `auggie command skill:`. ## Custom commands vs. skills Custom slash commands and [skills](/cli/skills) are separate features: | Feature | Stored in | Purpose | | :- | :- | :- | | **Custom slash commands** | `.augment/commands/.md` (and Claude / Agents equivalents) | Reusable prompts and workflows you trigger with `/` | | **Skills** | `.augment/skills//SKILL.md` (and Claude / Agents equivalents) | Domain-specific knowledge packages following the [agentskills.io](https://agentskills.io) specification, invoked with `/skill:` | Both appear in the slash-command menu in interactive mode. Built-in slash commands take precedence over a custom command with the same name, so pick names that do not collide with the commands listed in [Interactive Mode Slash Commands](/cli/interactive#slash-commands). ## Example Commands For ready-to-use examples of custom slash commands, including code review templates, bug fix guides, and feature implementation plans, see: **[Custom Commands Examples](/cli/custom-commands-examples)** ## Best Practices 1. **Use kebab-case naming** for command names (e.g., `deploy-staging`, `run-tests`) 2. **Keep names descriptive** but concise, avoiding spaces and special characters 3. **Use meaningful prefixes** for related commands (e.g., `deploy-staging`, `deploy-production`) 4. **Include clear descriptions** in frontmatter for better discoverability 5. **Break complex workflows** into numbered steps for clarity 6. **Use user commands** (`~/.augment/commands/`) for personal workflows across all projects 7. **Use workspace commands** (`./.augment/commands/`) for team-shared, project-specific tasks 8. **Organize with subdirectories** for related command groups using namespacing 9. **Document command purpose** and expected outcomes clearly 10. **Version your commands** when making significant changes ## See Also * [Custom Commands Examples](/cli/custom-commands-examples) - Ready-to-use command templates and examples * [Interactive Mode Slash Commands](/cli/interactive#slash-commands) - Learn about Auggie's interactive terminal features * [CLI Reference for Custom Commands](/cli/reference#custom-commands) - Complete reference for command-line flags # Custom Slash Commands Examples Source: https://docs.augmentcode.com/cli/custom-commands-examples Ready-to-use examples of custom slash commands for common development workflows. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/custom-commands-examples) . ## Example Commands Here are some practical examples of custom slash commands you can use in your projects: > **Code Review Command** > > ```markdown theme={null} > --- > description: Perform a comprehensive code review > argument-hint: [file-path] > --- > > Please perform a comprehensive code review of the specified file or current changes, focusing on: > > 1. **Code Quality**: Check for readability, maintainability, and adherence to best practices > 2. **Security**: Look for potential security vulnerabilities > 3. **Performance**: Identify potential performance issues > 4. **Testing**: Suggest areas that need test coverage > 5. **Documentation**: Check if code is properly documented > > $ARGUMENTS > ``` > **Bug Fix Template** > > ```markdown theme={null} > --- > description: Generate a structured bug fix approach > argument-hint: [bug-description] > --- > > Help me fix this bug: $ARGUMENTS > > Please provide: > 1. Root cause analysis > 2. Step-by-step fix approach > 3. Testing strategy > 4. Prevention measures for similar issues > ``` > **Feature Implementation Guide** > > ```markdown theme={null} > --- > description: Create implementation plan for new features > argument-hint: [feature-description] > --- > > Create a detailed implementation plan for: $ARGUMENTS > > Include: > - Technical requirements > - Architecture considerations > - Implementation steps > - Testing approach > - Documentation needs > ``` > **Security Review Command** > > ```markdown theme={null} > --- > description: Perform security analysis on code > argument-hint: [file-path] > --- > > Perform a security review of: $ARGUMENTS > > Focus on: > 1. **Input validation** and sanitization > 2. **Authentication** and authorization checks > 3. **Data exposure** and privacy concerns > 4. **Injection vulnerabilities** (SQL, XSS, etc.) > 5. **Cryptographic** implementations > 6. **Dependencies** with known vulnerabilities > > Provide specific recommendations for any issues found. > ``` > **Performance Optimization** > > ```markdown theme={null} > --- > description: Analyze and optimize code performance > argument-hint: [file-path] > --- > > Analyze the performance of: $ARGUMENTS > > Please examine: > 1. **Algorithm complexity** and efficiency > 2. **Memory usage** patterns > 3. **Database queries** and optimization opportunities > 4. **Caching** strategies > 5. **Network requests** and bundling > 6. **Rendering performance** (for frontend code) > > Suggest specific optimizations with expected impact. > ``` > **Documentation Generator** > > ```markdown theme={null} > --- > description: Generate comprehensive documentation > argument-hint: [file-path] > --- > > Generate documentation for: $ARGUMENTS > > Include: > 1. **Overview** and purpose > 2. **API reference** with parameters and return values > 3. **Usage examples** with code snippets > 4. **Configuration options** if applicable > 5. **Error handling** and troubleshooting > 6. **Dependencies** and requirements > > Format as clear, structured markdown. > ``` > **Test Generation Command** > > ```markdown theme={null} > --- > description: Generate comprehensive test cases > argument-hint: [file-path] > --- > > Generate test cases for: $ARGUMENTS > > Create tests covering: > 1. **Happy path** scenarios > 2. **Edge cases** and boundary conditions > 3. **Error handling** and exceptions > 4. **Integration points** with other components > 5. **Performance** considerations > 6. **Security** edge cases > > Use appropriate testing framework conventions and include setup/teardown as needed. > ``` ## How to Add Commands to Your Project To use these custom slash commands in your project, you need to save them in the `.augment/commands/` directory: ### Step 1: Create the Commands Directory First, create the `.augment/commands/` directory in your project root if it doesn't exist: ```bash theme={null} mkdir -p .augment/commands ``` ### Step 2: Save Command Files Save each command as a separate `.md` file in the `.augment/commands/` directory. For example: ```bash theme={null} # Save the code review command cat > .augment/commands/code-review.md << 'EOF' --- description: Perform a comprehensive code review argument-hint: [file-path] --- Please perform a comprehensive code review of the specified file or current changes, focusing on: 1. **Code Quality**: Check for readability, maintainability, and adherence to best practices 2. **Security**: Look for potential security vulnerabilities 3. **Performance**: Identify potential performance issues 4. **Testing**: Suggest areas that need test coverage 5. **Documentation**: Check if code is properly documented $ARGUMENTS EOF ``` ### Step 3: Use Your Commands Once saved, your custom commands become available as slash commands in Augment: ``` /code-review src/components/Button.tsx /bug-fix "Login form validation not working" /security-review auth/middleware.js ``` ### Directory Structure Your project structure should look like this: ``` your-project/ ├── .augment/ │ └── commands/ │ ├── code-review.md │ ├── bug-fix.md │ ├── security-review.md │ └── performance-optimization.md ├── src/ └── package.json ``` ## Usage Tips * **Save these templates** in your `.augment/commands/` directory * **Customize the prompts** to match your team's coding standards and practices * **Add project-specific context** to make the commands more effective * **Combine commands** by referencing outputs from one command in another * **Use meaningful filenames** like `code-review.md`, `bug-fix.md`, etc. * **Version control your commands** by committing the `.augment/commands/` directory to your repository ## Creating Your Own Examples When creating custom commands, consider these patterns: 1. **Start with a clear description** in the frontmatter 2. **Use argument hints** to guide users on expected inputs 3. **Structure your prompts** with numbered lists or bullet points 4. **Include specific instructions** for the type of analysis or output you want 5. **Reference the `$ARGUMENTS` variable** where user input should be inserted ## See Also * [Custom Slash Commands](/cli/custom-commands) - Learn how to create and manage custom commands * [CLI Reference for Custom Commands](/cli/reference#custom-commands) - Complete command-line reference for custom commands # Hooks Source: https://docs.augmentcode.com/cli/hooks Intercept and control tool execution with custom scripts You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/hooks) . ## Overview Hooks allow you to intercept tool execution at specific lifecycle events and run custom scripts. This enables powerful workflows like: * **Security auditing** - Block dangerous commands or log sensitive file access * **Policy enforcement** - Enforce coding standards or restrict production access * **Logging** - Track tool usage for compliance and analytics * **Integration** - Connect with external systems and workflows Hooks execute automatically when specific events occur during agent operation, giving you fine-grained control over tool execution and session lifecycle. ## Configuration Hooks are configured in `settings.json` files. Augment loads hook configuration from multiple locations, allowing system-wide policies, user preferences, and project-specific hooks to coexist. ### Settings File Locations Auggie reads hooks from all of these files and runs every matching hook. Settings are listed below from **highest to lowest precedence**: | Location | Platform | Supported By | Description | | :- | :- | :- | :- | | `/etc/augment/settings.json` | Linux/macOS | CLI, VSCode, IntelliJ | System-wide settings for enterprise/admin policies (immutable) | | `C:\ProgramData\Augment\settings.json` | Windows | CLI, VSCode, IntelliJ | System-wide settings for enterprise/admin policies (immutable) | | `/.augment/settings.local.json` | All | CLI | Personal project overrides — not committed to source control | | `/.augment/settings.json` | All | CLI | Shared project settings — committed to source control | | `~/.augment/settings.json` | All | CLI, VSCode, IntelliJ | User-level settings (lowest precedence) | > [!NOTE] > > System-level settings (`/etc/augment/settings.json`) take the highest precedence and cannot be overridden by > any other configuration source. Project-scoped settings (`.augment/settings.json` and `.augment/settings.local.json`) > allow repositories to ship hook configurations that apply automatically to all contributors. > [!NOTE] > > In Cosmos, Auggie also reads hooks from settings stored in the VFS. > [!NOTE] > > Enabled [plugins](/cli/plugins) can add hooks from their `hooks/hooks.json`. Plugin hooks use the same format and > can refer to the plugin's folder as `${PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_ROOT}`, or `${AUGMENT_PLUGIN_ROOT}`. > [!TIP] > > Use `/.augment/settings.json` to define hooks that all contributors should use — for example, > security auditing or policy enforcement hooks. Use `/.augment/settings.local.json` for personal > overrides that shouldn't be committed to source control. > [!WARNING] > > `PreToolUse` and `PostToolUse` hooks run **synchronously** - the agent waits for them to > complete before proceeding. Use appropriate timeouts to prevent long delays. Note that only > `PreToolUse` can block tool execution. `Stop`, `SessionStart`, `SessionEnd`, `PromptSubmit`, and > `Notification` hooks run in the background and don't delay the agent. ### Structure Hooks are organized by event type with optional matchers: ```json theme={null} { "hooks": { "PreToolUse": [ { "matcher": "bash", "hooks": [ { "type": "command", "command": "/etc/augment/hooks/validate-command.sh", "timeout": 5000 } ] } ] } } ``` **Configuration fields:** | Field | Description | | :- | :- | | `matcher` | Pattern to match tool names (case-insensitive). Supports regex patterns. Optional for `PreToolUse` and `PostToolUse` (defaults to `".*"` to match all tools). Not used for other events. | | `hooks` | Array of hook handlers to execute when the pattern matches. | | `type` | Hook execution type - currently only `"command"` is supported. | | `command` | Command to run: a script path or any command line (for example `python3 ~/.augment/hooks/check.py`). Run through the system shell. | | `args` | *(Optional)* Argument list. When set, `command` is run directly with these arguments, without a shell. See [Running a program with `args`](#running-a-program-with-args). | | `timeout` | *(Optional)* Timeout in milliseconds (default: 60000ms). | | `metadata` | *(Optional)* Configuration for additional context fields - see [Hook Metadata](#hook-metadata-configuration). | **Matcher pattern examples:** | Pattern | Description | | :- | :- | | `"bash"` | Match a specific tool | | `"edit\|write"` | Match multiple tools using regex OR | | `".*"` | Match all tools | | `"mcp:*"` | Match all MCP tools (special case) | | `"mcp:.*_my-server$"` | Match any tool from a specific MCP server | Only `".*"` (or an omitted matcher) matches MCP tools without the `mcp:` prefix. A pattern such as `"bash"` never matches an MCP tool. For events that don't use matchers (`SessionStart`, `SessionEnd`, `Stop`, `PromptSubmit`, `Notification`): ```json theme={null} { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "/path/to/setup-script.sh" } ] } ] } } ``` ### Script Requirements `command` is run through the system shell (`/bin/sh` on Unix, `cmd.exe` on Windows), so it can be a script path or any command line, such as `python3 ~/.augment/hooks/check.py` or `node ./hooks/audit.js`. There is no required file extension. If `command` points directly to a script on Unix, the script must: 1. **Be executable** - Run `chmod +x your-hook.sh` 2. **Have a valid shebang** - First line must specify the interpreter How common script types are run: | Extension | How it's executed | | :- | :- | | `.sh` | Executed directly on Unix; the shebang line selects the interpreter | | `.bat`, `.cmd` | Dispatched to `cmd.exe /c` on Windows | > [!TIP] > > Shebang-based interpreter selection (Python, Node.js, Ruby, etc.) only applies to scripts run directly on Unix. > `.bat`/`.cmd` files are always run with `cmd.exe` — a shebang inside those files is ignored. > [!NOTE] > > On Windows, `.ps1` and `.sh` scripts are not run automatically. Put the interpreter in the command, > for example `powershell.exe -File C:\hooks\check.ps1` or `bash.exe ./hooks/check.sh`, or use > [`args`](#running-a-program-with-args). ```bash theme={null} #!/usr/bin/env python3 # Python script with .sh extension on Unix - uses Python interpreter via shebang import sys, json event_data = json.load(sys.stdin) # ... your Python code ``` ### Running a program with `args` Set `args` to run `command` directly with a list of arguments, without a shell. Each item is passed as one argument exactly as written, so spaces and quotes need no escaping: ```json theme={null} { "type": "command", "command": "node", "args": ["${HOME}/hooks/check.js", "--strict"] } ``` On Windows, `.sh` files run with `bash.exe`, `.ps1` files with `powershell.exe -File`, and `.bat`/`.cmd` files with `cmd.exe`. ### Environment variables in commands Without `args`, the shell expands variables in `command`. With `args`, Auggie expands `${VAR}` and `${VAR:-default}` in `command` and every `args` item. A variable that isn't set and has no default is left as written. Write `\${` to keep a literal `${`. ## Hook Events > [!NOTE] > > Cursor-style event names are also accepted and mapped to Auggie events: `beforeShellExecution`, `beforeReadFile`, > and `beforeMCPExecution` run as PreToolUse; `afterShellExecution`, `afterFileEdit`, and `afterMCPExecution` run > as PostToolUse; `stop` runs as Stop. ### PreToolUse Runs **before** a tool executes. Can block tool execution. > [!WARNING] > > If a PreToolUse hook times out or crashes, the tool still runs. Only exit code 2 or a `deny` decision blocks it. > Keep security hooks fast and make them fail closed: exit with code 2 when they can't reach a decision. **Common tool names:** | Tool | Description | | :- | :- | | `bash` | Shell commands | | `read` | File reading | | `edit` | File editing | | `write` | File writing | | `grep` | Search file contents | | `find` | Find files by glob | | `web-fetch` | Fetch web content | | `web-search` | Web search | | `codebase-retrieval` | Codebase search | | `github-api` | GitHub integration | | `linear` | Linear integration | > [!NOTE] > > Tool names changed in Auggie 1.x. Matchers that use 0.x names such as `launch-process`, `view`, `str-replace-editor`, or `save-file` still match the new tools for now, and `/hooks` flags them. Update matchers to the new names. Use [PreToolUse output control](#pretooluse-output) to block tools. PreToolUse and PostToolUse hooks also run for tool calls made by [subagents](/cli/subagents). Other events run only for the main agent. ### PostToolUse Runs immediately **after** a tool completes. Can provide feedback to the agent but cannot block execution. Recognizes the same tool names as PreToolUse. Includes `tool_output` and `tool_error` in the event data. ### Stop Runs when the agent stops responding, whether from normal completion or user interrupt. The `agent_stop_cause` field indicates why the agent stopped (e.g., `"end_turn"` or `"interrupted"`). ### SessionStart Runs when Auggie starts a new session. SessionStart hooks run in the background; their output is not added to the agent's context. Useful for: * Installing dependencies * Setting up environment variables ### SessionEnd Runs when an Auggie session ends. Useful for: * Cleanup tasks * Logging session statistics * Saving session state ### PromptSubmit Runs each time you submit a prompt, before the agent starts working on it. The prompt is in the `user_prompt` field. `PromptSubmit` hooks run in the background and cannot block or change the prompt. ### Notification Runs when Auggie shows a notification in interactive mode, or when a cloud agent reports an event. The `notification_type` and `notification_message` fields describe the notification. `Notification` hooks run in the background and cannot block anything. ## Hook Input Hooks receive event data via **stdin** as a JSON object. The structure varies by event type, but all events share common base fields. ### Common Fields (All Events) These fields are present in **every** hook event: | Field | Type | Description | | :- | :- | :- | | `hook_event_name` | string | The type of event: `"PreToolUse"`, `"PostToolUse"`, `"Stop"`, `"SessionStart"`, `"SessionEnd"`, `"PromptSubmit"`, `"Notification"` | | `hook_type` | string | Same value as `hook_event_name` | | `cwd` | string | The session's working directory | | `conversation_id` | string | Unique identifier for the current conversation | | `workspace_roots` | string\[] | List of workspace root directories (usually contains one path) | ### Event-Specific Fields #### PreToolUse / PostToolUse Events Tool events include information about the tool being executed: | Field | Type | Availability | Description | | :- | :- | :- | :- | | `tool_name` | string | Always | Name of the tool (e.g., `"bash"`, `"edit"`). Use to filter which tools your hook applies to. | | `tool_input` | object | Always | Input parameters passed to the tool. **Critical for security hooks** - extract and validate specific parameters. | | `tool_output` | string? | PostToolUse only | Output returned by the tool (if successful). Use for auditing or providing context to the agent. | | `tool_error` | string? | PostToolUse only | Error message if tool execution failed. Use to detect failures and inject troubleshooting tips. | | `tool_result` | array | PostToolUse only | The tool's raw result content blocks. `tool_output` is the text joined from these blocks. | | `tool_is_error` | boolean | PostToolUse only | `true` if the tool failed. | | `file_changes` | object\[]? | PostToolUse only | File changes for `write` and `edit`. Includes `path`, `changeType`, `content`, and `oldContent`. Changes made by `bash` or other tools are not reported; use `git status` or `git diff` instead. | | `is_mcp_tool` | boolean | Always | `true` if the tool is provided by an MCP server, `false` for built-in tools. | **Example: Extracting tool-specific parameters** ```bash Bash - Extract Bash command theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) TOOL_NAME=$(echo "$EVENT_DATA" | jq -r '.tool_name') if [[ "$TOOL_NAME" == "bash" ]]; then # Extract the command being executed COMMAND=$(echo "$EVENT_DATA" | jq -r '.tool_input.command') echo "Command: $COMMAND" >&2 # Check for dangerous patterns if echo "$COMMAND" | grep -qE "rm -rf|sudo|curl.*sh"; then echo "Blocked dangerous command" >&2 exit 2 fi fi exit 0 ``` ```python Python - Extract file path theme={null} #!/usr/bin/env python3 import sys, json event_data = json.load(sys.stdin) if event_data.get('tool_name') == 'edit': path = event_data.get('tool_input', {}).get('path', '') if any(p in path for p in ['.env', 'secrets', 'credentials']): print(f"[AUDIT] Sensitive file: {path}", file=sys.stderr) sys.exit(0) ``` **Example: Using `tool_output` for context (PostToolUse)** ```bash Bash theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) TOOL_NAME=$(echo "$EVENT_DATA" | jq -r '.tool_name') TOOL_OUTPUT=$(echo "$EVENT_DATA" | jq -r '.tool_output // ""') if [[ "$TOOL_NAME" == "bash" ]] && echo "$TOOL_OUTPUT" | grep -q "test.*passed"; then # Tests passed - inject success context cat << EOF { "hookSpecificOutput": { "hookEventName": "PostToolUse", "additionalContext": "All tests passed successfully!" } } EOF fi exit 0 ``` ```python Python theme={null} #!/usr/bin/env python3 import sys import json event_data = json.load(sys.stdin) tool_name = event_data.get('tool_name', '') tool_output = event_data.get('tool_output', '') if tool_name == 'bash' and 'test' in tool_output and 'passed' in tool_output: # Tests passed - inject success context output = { "hookSpecificOutput": { "hookEventName": "PostToolUse", "additionalContext": "All tests passed successfully!" } } print(json.dumps(output)) sys.exit(0) ``` **Example: Using `tool_error` for troubleshooting (PostToolUse)** ```bash Bash theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) TOOL_ERROR=$(echo "$EVENT_DATA" | jq -r '.tool_error // ""') if [[ -n "$TOOL_ERROR" ]] && echo "$TOOL_ERROR" | grep -q "permission denied"; then # Inject troubleshooting tip cat << EOF { "hookSpecificOutput": { "hookEventName": "PostToolUse", "additionalContext": "Permission denied error detected. Try running with appropriate permissions or check file ownership." } } EOF fi exit 0 ``` ```python Python theme={null} #!/usr/bin/env python3 import sys import json event_data = json.load(sys.stdin) tool_error = event_data.get('tool_error', '') if tool_error and 'permission denied' in tool_error.lower(): output = { "hookSpecificOutput": { "hookEventName": "PostToolUse", "additionalContext": "Permission denied error detected. Try with appropriate permissions." } } print(json.dumps(output)) sys.exit(0) ``` **Example: Using `file_changes` for audit logging (PostToolUse)** The `file_changes` field is populated for file-modifying tools and includes the old content for edits: ```json theme={null} { "hook_event_name": "PostToolUse", "conversation_id": "conv-xyz789", "tool_name": "edit", "tool_input": { "path": "src/auth.ts", "edits": [{ "oldText": "...", "newText": "..." }] }, "file_changes": [ { "path": "src/auth.ts", "changeType": "edit", "content": "// New code content here...", "oldContent": "// Old code that was replaced..." } ] } ``` ```bash theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) echo "$EVENT_DATA" | jq -c '.file_changes[]?' | while read -r change; do echo "[AUDIT] $(echo $change | jq -r '.changeType'): $(echo $change | jq -r '.path')" >&2 done exit 0 ``` #### SessionStart / SessionEnd Events Session events have no additional fields beyond the common base fields. **Example SessionStart event:** ```json theme={null} { "hook_event_name": "SessionStart", "conversation_id": "conv-xyz789", "workspace_roots": ["/Users/username/project"] } ``` #### Stop Event Stop events include information about why the agent stopped: | Field | Type | Description | | :-: | :-: | :-: | | `agent_stop_cause` | string | Why the agent stopped: `"end_turn"`, `"interrupted"`, `"empty_completion"`, or `"error"` | **Example Stop event:** ```json theme={null} { "hook_event_name": "Stop", "conversation_id": "conv-xyz789", "workspace_roots": ["/Users/username/project"], "agent_stop_cause": "end_turn" } ``` #### PromptSubmit Event | Field | Type | Description | | :- | :- | :- | | `user_prompt` | string | The prompt you submitted | #### Notification Event | Field | Type | Description | | :- | :- | :- | | `notification_type` | string | Kind of notification, such as `"info"`, `"warning"`, or `"error"` | | `notification_message` | string | The notification text | ### Metadata-Based Fields When hooks declare metadata options in their configuration, additional fields are included in the event data: #### `context` field (when `includeUserContext: true`) Available for: **All event types** ```json theme={null} { "context": { "userEmail": "user@example.com", "modelName": "Claude Opus 4.5", "toolVersion": "1.2.0", "timestamp": "2025-01-15T10:30:00-08:00" } } ``` **How to use:** * **`userEmail`**: Identify which user triggered the hook. Use for user-specific policies or analytics. * **`modelName`**: AI model display name (e.g., "Claude Opus 4.5", "Sonnet-3.7"). Use for model-specific behavior. * **`toolVersion`**: CLI or VSCode extension version (e.g., "1.2.0"). Use for debugging or version-specific behavior. * **`timestamp`**: ISO 8601 timestamp. Use for auditing and analytics. **Example: User-specific permissions** ```bash Bash theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) USER_EMAIL=$(echo "$EVENT_DATA" | jq -r '.context.userEmail // ""') TOOL_NAME=$(echo "$EVENT_DATA" | jq -r '.tool_name') COMMAND=$(echo "$EVENT_DATA" | jq -r '.tool_input.command // ""') # Only allow deployments for specific users if [[ "$TOOL_NAME" == "bash" ]] && echo "$COMMAND" | grep -q "deploy"; then if [[ "$USER_EMAIL" != "admin@example.com" ]]; then echo "Only admins can deploy" >&2 exit 2 fi fi exit 0 ``` ```python Python theme={null} #!/usr/bin/env python3 import sys import json event_data = json.load(sys.stdin) user_email = event_data.get('context', {}).get('userEmail', '') # Only allow deployments for specific users tool_name = event_data.get('tool_name', '') command = event_data.get('tool_input', {}).get('command', '') if tool_name == 'bash' and 'deploy' in command: if user_email != 'admin@example.com': print("Only admins can deploy", file=sys.stderr) sys.exit(2) sys.exit(0) ``` #### `mcp_metadata` field (when `includeMCPMetadata: true`) Available for: **PreToolUse and PostToolUse only** ```json theme={null} { "mcp_metadata": { "timestamp": "2025-01-15T10:30:00-08:00", "mcpDecision": "yes", "mcpTotalToolsCount": 215, "mcpExecutedToolName": "search", "mcpExecutedToolServerName": "my-server", "mcpExecutedTotalToolsCount": 6 } } ``` **How to use:** * **`timestamp`**: ISO 8601 timestamp. Use for auditing and analytics. * **`mcpDecision`**: Whether this is an MCP tool (`"yes"`) or native tool (`"no"`). * **`mcpTotalToolsCount`**: Total MCP tools available across all servers. * **`mcpExecutedToolName`**: MCP tool name as defined by the server (e.g., `"search"`). * **`mcpExecutedToolServerName`**: MCP server name (e.g., `"my-server"`). * **`mcpExecutedTotalToolsCount`**: Tools available from the executed server. **Example: MCP-specific rate limiting** ```bash Bash theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) MCP_DECISION=$(echo "$EVENT_DATA" | jq -r '.mcp_metadata.mcpDecision // "no"') MCP_TOTAL=$(echo "$EVENT_DATA" | jq -r '.mcp_metadata.mcpTotalToolsCount // 0') # Block if too many MCP tools are enabled (security concern) if [[ "$MCP_DECISION" == "yes" ]] && [[ "$MCP_TOTAL" -gt 100 ]]; then echo "Too many MCP tools enabled ($MCP_TOTAL). Contact admin." >&2 exit 2 fi exit 0 ``` ```python Python theme={null} #!/usr/bin/env python3 # /etc/augment/hooks/mcp-limit.sh (Python via shebang) import sys import json event_data = json.load(sys.stdin) mcp_metadata = event_data.get('mcp_metadata', {}) mcp_decision = mcp_metadata.get('mcpDecision', 'no') mcp_total = mcp_metadata.get('mcpTotalToolsCount', 0) # Block if too many MCP tools are enabled (security concern) if mcp_decision == 'yes' and mcp_total > 100: print(f"Too many MCP tools enabled ({mcp_total}). Contact admin.", file=sys.stderr) sys.exit(2) sys.exit(0) ``` #### `conversation` field (when `includeConversationData: true`) Available for: **Stop event only**. On PreToolUse and PostToolUse, the same option adds only a `user_prompt` field with the user's latest prompt. ```json theme={null} { "conversation": { "timestamp": "2025-01-15T10:30:00-08:00", "userPrompt": "Add error handling to the login function", "agentTextResponse": "I'll add comprehensive error handling...", "agentCodeResponse": [ { "path": "src/auth/login.ts", "changeType": "edit", "content": "export function login() { try { ... } catch (e) { ... } }" } ] } } ``` **How to use:** * **`timestamp`**: ISO 8601 timestamp. Use for auditing. * **`userPrompt`**: The user's original request. * **`agentTextResponse`**: Agent's explanation of what it did. * **`agentCodeResponse`**: Array of file changes. Each entry has: * `path`: File path modified * `changeType`: `"edit"`, `"create"`, or `"delete"` * `content`: New content (for edit/create only) ### Reading Hook Input ```bash Bash theme={null} #!/usr/bin/env bash # Read entire JSON from stdin EVENT_DATA=$(cat) # Extract fields using jq HOOK_EVENT=$(echo "$EVENT_DATA" | jq -r '.hook_event_name') TOOL_NAME=$(echo "$EVENT_DATA" | jq -r '.tool_name // ""') CONV_ID=$(echo "$EVENT_DATA" | jq -r '.conversation_id') echo "Event: $HOOK_EVENT, Tool: $TOOL_NAME, Conversation: $CONV_ID" ``` ```python Python theme={null} #!/usr/bin/env python3 import sys import json event_data = json.load(sys.stdin) hook_event = event_data['hook_event_name'] tool_name = event_data.get('tool_name', '') conv_id = event_data['conversation_id'] print(f"Event: {hook_event}, Tool: {tool_name}, Conversation: {conv_id}") ``` ## Hook Output and Communication Hooks communicate results through exit codes and output streams. The behavior depends on the exit code and the hook event type. ### Exit Codes * **Exit code 0**: Success - Hook completed successfully * **Exit code 2**: Blocking error - Prevents tool execution (PreToolUse only) * **Other exit codes**: Non-blocking error - Logged but execution continues ### Output Streams * **stdout**: Standard output from the hook * **stderr**: Error output from the hook ### Communication Matrix The following table shows how hook output is handled based on exit code and event type: | Exit Code | Event Type | Output Stream | Shown To | Behavior | | :-: | - | :-: | - | :-: | | 2 | PreToolUse | stderr | Agent | Blocks tool execution, agent sees why it was blocked | | 2 | SessionStart | stderr | User | Hook failed at startup, user needs to fix configuration | | 0 | PreToolUse | stderr | User | Warning message shown to user | | 0 | PreToolUse | stdout | User | Success message shown to user | | 0 | PostToolUse | stderr | User | Warning message shown to user | | 0 | PostToolUse | stdout | User | Success message shown to user | | 0 | SessionEnd | stdout | User | Show completion message | | Other | Any | stderr | User | Error logged, execution continues | > [!NOTE] > > **Key Principle**: Exit code 2 with PreToolUse blocks the tool and shows stderr to the agent (so > it knows why). Exit code 0 shows output to the user. ### PreToolUse Output **Blocking a tool (exit code 2):** ```bash Bash theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) COMMAND=$(echo "$EVENT_DATA" | jq -r '.tool_input.command // ""') if echo "$COMMAND" | grep -qE "rm -rf|sudo"; then echo "Blocked dangerous command: $COMMAND" >&2 exit 2 # Blocks tool, stderr shown to agent fi exit 0 # Allow tool to proceed ``` ```python Python theme={null} #!/usr/bin/env python3 import sys import json import re event_data = json.load(sys.stdin) command = event_data.get('tool_input', {}).get('command', '') if re.search(r'rm -rf|sudo', command): print(f"Blocked dangerous command: {command}", file=sys.stderr) sys.exit(2) # Blocks tool, stderr shown to agent sys.exit(0) # Allow tool to proceed ``` **Warning message (exit code 0):** ```bash Bash theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) FILE_PATH=$(echo "$EVENT_DATA" | jq -r '.tool_input.path // ""') if echo "$FILE_PATH" | grep -qE "\.env|secrets"; then echo "Warning: Accessing sensitive file: $FILE_PATH" >&2 fi exit 0 # Allow tool but show warning ``` ```python Python theme={null} #!/usr/bin/env python3 import sys import json import re event_data = json.load(sys.stdin) file_path = event_data.get('tool_input', {}).get('path', '') if re.search(r'\.env|secrets', file_path): print(f"Warning: Accessing sensitive file: {file_path}", file=sys.stderr) sys.exit(0) # Allow tool but show warning ``` ## Hook Output Reference Hooks can return structured output to control execution and communicate with the agent or user. Output is provided via **stdout** (as JSON) and **stderr** (for error messages). ### Exit Codes | Exit Code | Meaning | Behavior | | :-: | - | :-: | | `0` | Success | Hook completed successfully. Tool execution continues (unless JSON output blocks it). | | `2` | Blocking Error | **PreToolUse only**: Blocks tool execution. Stderr message is shown to both user and agent. | | Other | Non-blocking Error | Hook failed, but tool execution continues. Stderr shown to the user. | ### JSON Output Format Hooks can return JSON on stdout (exit code 0 only) to provide structured control: ```json theme={null} { "systemMessage": "Message shown to user", "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Security policy violation" } } ``` ### Common JSON Fields (All Events) These fields can be returned by any hook: | Field | Type | Description | Destination | | :-: | - | :-: | :-: | | `systemMessage` | string | Warning or informational message | User | ### Event-Specific JSON Output #### PreToolUse Output PreToolUse hooks can control tool execution: | Field | Type | Description | Destination | | :-: | - | :-: | :-: | | `permissionDecision` | `"deny"` | Block tool execution | - | | `permissionDecisionReason` | string | Reason for blocking the tool | Agent and User | | `updatedInput` | object | Fields to change in the tool input before it runs | Tool | > [!NOTE] > > Currently only `permissionDecision: "deny"` is supported. The `"allow"` and `"ask"` values will be > implemented in a future release. **Example: Block dangerous command** ```json theme={null} { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Command contains 'rm -rf' which is not allowed" } } ``` **Example: Modify tool input** `updatedInput` is merged into the original tool input: fields you return replace the originals, and fields you leave out are kept. If several hooks match, each one's changes are applied in order. ```json theme={null} { "hookSpecificOutput": { "hookEventName": "PreToolUse", "updatedInput": { "command": "rm -rf ./build" } } } ``` #### PostToolUse Output PostToolUse hooks can provide additional context to the agent. `reason` and `additionalContext` are appended to the tool's result, so the agent reads them together with the tool output: | Field | Type | Description | Destination | | :-: | - | :-: | :-: | | `decision` | `"block"` | Sends `reason` to the agent. The tool has already run and is not undone; the agent is not stopped | - | | `reason` | string | Feedback for the agent (used when decision="block") | Agent | | `additionalContext` | string | Additional context for the agent to consider | Agent | **Example: Provide context to agent** ```json theme={null} { "hookSpecificOutput": { "hookEventName": "PostToolUse", "additionalContext": "The command modified 3 files in the authentication module" } } ``` ### Output Routing Different output goes to different destinations: **To Agent (injected into conversation):** * Exit code 2 stderr (PreToolUse, PostToolUse events) * `permissionDecisionReason` (when decision="deny") * `reason` (when decision="block") * `additionalContext` (PostToolUse) **To User (displayed in UI):** * Exit code 2 stderr (SessionStart, SessionEnd events) * `systemMessage` * `permissionDecisionReason` (when decision="allow" or "ask") * Plain (non-JSON) stdout, for non-SessionStart events ### Complete Output Examples ```bash Bash - Block with Exit Code 2 theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) COMMAND=$(echo "$EVENT_DATA" | jq -r '.tool_input.command // ""') if echo "$COMMAND" | grep -qE "rm -rf"; then echo "Blocked dangerous command: $COMMAND" >&2 exit 2 # Blocks tool, stderr shown to agent and user fi exit 0 ``` ```python Python - Block with Exit Code 2 theme={null} #!/usr/bin/env python3 import sys import json import re event_data = json.load(sys.stdin) command = event_data.get('tool_input', {}).get('command', '') if re.search(r'rm -rf', command): print(f"Blocked dangerous command: {command}", file=sys.stderr) sys.exit(2) # Blocks tool, stderr shown to agent and user sys.exit(0) ``` ```bash Bash - Block with JSON theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) COMMAND=$(echo "$EVENT_DATA" | jq -r '.tool_input.command // ""') if echo "$COMMAND" | grep -qE "rm -rf"; then cat << EOF { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Command contains 'rm -rf' which violates security policy" } } EOF exit 0 fi exit 0 ``` ```python Python - Block with JSON theme={null} #!/usr/bin/env python3 import sys import json import re event_data = json.load(sys.stdin) command = event_data.get('tool_input', {}).get('command', '') if re.search(r'rm -rf', command): output = { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Command contains 'rm -rf' which violates security policy" } } print(json.dumps(output)) sys.exit(0) sys.exit(0) ``` ## Hook Metadata (Configuration) Hook metadata options are **configuration-level flags** that control what data is included in the hook input. They provide a privacy-first, opt-in model for accessing conversation data, MCP metadata, and user context. ### Available Metadata Options Metadata options are specified in the hook configuration (not in hook output): ```json theme={null} { "hooks": { "PreToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "/etc/augment/hooks/analytics.sh" } ], "metadata": { "includeConversationData": true, "includeMCPMetadata": true, "includeUserContext": false } } ] } } ``` **Metadata flags:** * **`includeUserContext`**: Include user and environment context in hook input * Adds `context` field to hook event data * Available for: **All event types** (PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd) * Fields included: * `userEmail` - User's email address (e.g., "[user@example.com](mailto:user@example.com)") * `modelName` - Model name being used (e.g., "Claude Opus 4.5") * `timestamp` - ISO 8601 timestamp (e.g., "2025-01-15T10:30:00-08:00") * Default: `false` (user context excluded) * **`includeMCPMetadata`**: Include MCP-specific metadata in hook input * Adds `mcp_metadata` field to hook event data * Available for: **PreToolUse and PostToolUse only** * Fields included: * `mcpDecision` - Whether MCP tools were used ("yes" | "no") * `mcpTotalToolsCount` - Total number of MCP tools available across all servers * `mcpExecutedToolName` - Name of the executed MCP tool (if any) * `mcpExecutedToolServerName` - Server name of the executed MCP tool (if any) * `mcpExecutedTotalToolsCount` - Number of tools from the executed server (if any) * Default: `false` (MCP metadata excluded) * **`includeConversationData`**: Include conversation fields in hook input * **Stop:** adds a `conversation` field with the fields below * **PreToolUse / PostToolUse:** adds a `user_prompt` field with the user's latest prompt * `conversation` fields: * `userPrompt` - The user's prompt/message that triggered the agent response * `agentTextResponse` - Agent's text response (markdown format) * `agentCodeResponse` - Array of file changes made by the agent, each containing: * `path` - File path relative to workspace root * `changeType` - Type of change ("edit" | "create" | "delete") * `content` - File content after the change (undefined for deletions) * Default: `false` (conversation data excluded for privacy) **Metadata availability by event type:** | Metadata Option | PreToolUse | PostToolUse | Stop | SessionStart | SessionEnd | | :-: | :-: | :-: | :-: | :-: | :-: | | `includeUserContext` | ✓ | ✓ | ✓ | ✓ | ✓ | | `includeMCPMetadata` | ✓ | ✓ | - | - | - | | `includeConversationData` | `user_prompt` only | `user_prompt` only | ✓ | - | - | ### When to Use Metadata Options **Use `includeUserContext` when:** * Implementing user-specific rate limiting * Building per-user analytics * Tracking model usage by user * Implementing user-based access controls * Logging user activity for compliance **Use `includeMCPMetadata` when:** * Monitoring MCP tool usage patterns * Debugging MCP integration issues * Building MCP usage analytics * Rate limiting MCP tool calls * Tracking which MCP servers are being used **Use `includeConversationData` when:** * Building analytics dashboards that track user interactions * Implementing compliance logging for audit trails * Analyzing agent response quality * Tracking code changes made by the agent * Capturing complete conversation context for debugging ### Hook Input with Metadata When metadata options are enabled, the hook receives additional fields in the event data. Here's an example showing all three options enabled: **Configuration:** ```json theme={null} { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "/etc/augment/hooks/analytics.sh" } ], "metadata": { "includeUserContext": true, "includeConversationData": true } } ] } } ``` **Hook Input (Stop event with all metadata options):** ```json theme={null} { "hook_event_name": "Stop", "conversation_id": "conv-xyz789", "workspace_roots": ["/Users/username/project"], "agent_stop_cause": "end_turn", "context": { "userEmail": "user@example.com", "modelName": "Claude Opus 4.5", "toolVersion": "1.2.0", "timestamp": "2025-01-15T10:30:00-08:00" }, "conversation": { "timestamp": "2025-01-15T10:30:00-08:00", "userPrompt": "Add error handling to the login function", "agentTextResponse": "I'll add comprehensive error handling...", "agentCodeResponse": [{ "path": "src/auth/login.ts", "changeType": "edit" }] } } ``` **Hook Input (PostToolUse event with metadata - MCP tool):** ```json theme={null} { "hook_event_name": "PostToolUse", "conversation_id": "conv-xyz789", "workspace_roots": ["/Users/username/project"], "tool_name": "search_example-server", "tool_input": { "query": "latest documentation" }, "tool_output": "Found 5 results...", "is_mcp_tool": true, "context": { "userEmail": "user@example.com", "modelName": "Claude Opus 4.5", "toolVersion": "1.2.0", "timestamp": "2025-01-15T10:30:00-08:00" }, "mcp_metadata": { "timestamp": "2025-01-15T10:30:00-08:00", "mcpDecision": "yes", "mcpTotalToolsCount": 15, "mcpExecutedToolName": "search", "mcpExecutedToolServerName": "example-server", "mcpExecutedTotalToolsCount": 5 } } ``` **Hook Input (PostToolUse event with file\_changes - file edit):** ```json theme={null} { "hook_event_name": "PostToolUse", "conversation_id": "conv-xyz789", "workspace_roots": ["/Users/username/project"], "tool_name": "edit", "tool_input": { "path": "src/auth.ts", "edits": [{ "oldText": "...", "newText": "..." }] }, "tool_output": "File edited successfully", "is_mcp_tool": false, "file_changes": [ { "path": "src/auth.ts", "changeType": "edit", "content": "// New content...", "oldContent": "// Old content that was replaced..." } ], "context": { "userEmail": "user@example.com", "modelName": "Claude Opus 4.5", "toolVersion": "1.2.0", "timestamp": "2025-01-15T10:30:00-08:00" } } ``` ### Privacy Considerations Metadata options follow a **privacy-first, opt-in model**: 1. **Default deny**: All sensitive data is excluded by default 2. **Explicit opt-in**: Hooks must explicitly request metadata options 3. **Minimal access**: Request only the options you need 4. **Audit trail**: Metadata usage should be logged for compliance > [!WARNING] > > When using metadata options that include user data (`includeConversationData`, > `includeUserContext`), ensure your hook scripts: - Handle sensitive data securely - Comply with > privacy regulations (GDPR, CCPA, etc.) - Implement appropriate data retention policies - Use > encryption for data at rest and in transit ### Example: Analytics Hook with Metadata **Configuration:** ```json theme={null} { "hooks": { "PostToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "/etc/augment/hooks/analytics.sh" } ], "metadata": { "includeUserContext": true, "includeMCPMetadata": true } } ] } } ``` **Hook script (with metadata options):** ```bash Bash theme={null} #!/usr/bin/env bash # /etc/augment/hooks/analytics.sh EVENT_DATA=$(cat) # Extract user context (available because includeUserContext=true) USER_EMAIL=$(echo "$EVENT_DATA" | jq -r '.context.userEmail // ""') MODEL_NAME=$(echo "$EVENT_DATA" | jq -r '.context.modelName // ""') # Extract MCP metadata (available because includeMCPMetadata=true) MCP_DECISION=$(echo "$EVENT_DATA" | jq -r '.mcp_metadata.mcpDecision // "no"') MCP_SERVER=$(echo "$EVENT_DATA" | jq -r '.mcp_metadata.mcpExecutedToolServerName // ""') # Log analytics echo "User: $USER_EMAIL, Model: $MODEL_NAME, MCP: $MCP_DECISION, Server: $MCP_SERVER" exit 0 ``` ```python Python theme={null} #!/usr/bin/env python3 # /etc/augment/hooks/analytics.sh (Python via shebang) import sys import json event_data = json.load(sys.stdin) # Extract user context context = event_data.get('context', {}) user_email = context.get('userEmail', '') model_name = context.get('modelName', '') # Extract MCP metadata mcp = event_data.get('mcp_metadata', {}) mcp_decision = mcp.get('mcpDecision', 'no') mcp_server = mcp.get('mcpExecutedToolServerName', '') print(f"User: {user_email}, Model: {model_name}, MCP: {mcp_decision}") sys.exit(0) ``` ## Working with MCP Tools Hooks work seamlessly with [Model Context Protocol (MCP)](/setup-augment/mcp) tools. MCP tools have special naming and metadata that you can use in hooks. ### MCP Tool Naming MCP tools follow the naming pattern `{toolName}_{serverName}`. For example: * `search_my-server` - "search" tool from "my-server" * `query_database-server` - "query" tool from "database-server" * `read_filesystem-mcp` - "read" tool from "filesystem-mcp" > [!NOTE] > > Both tool names and server names can contain underscores. The server name is always the suffix after the **last** underscore that matches the known server name. For reliable matching, enable `includeMCPMetadata: true` on the hook configuration and read `mcp_metadata.mcpExecutedToolServerName` from the event JSON rather than parsing the tool name. ### MCP Tool Matchers Use the `mcp:` prefix to match MCP tools. The pattern after `mcp:` is a regex matched against the full tool name (`toolName_serverName`): * `"mcp:*"` - Match ALL MCP tools (special case) * `"mcp:.*_my-server$"` - Match any tool from `my-server` (use `$` anchor) * `"mcp:^search_my-server$"` - Match exact tool `search` from `my-server` * `"mcp:^search_.*"` - Match `search` tool from any server > [!NOTE] > > The `mcp:` prefix ensures only MCP tools are matched. The pattern is a standard regex applied to > the full tool name. Use the `$` anchor when matching server names to avoid partial matches. ### MCP Hook Examples **Log MCP tool usage:** ```bash theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) SERVER=$(echo "$EVENT_DATA" | jq -r '.mcp_metadata.mcpExecutedToolServerName // ""') echo "[MCP] Server: $SERVER, Tool: $(echo "$EVENT_DATA" | jq -r '.tool_name')" >&2 exit 0 ``` **Configuration:** ```json theme={null} { "hooks": { "PreToolUse": [ { "matcher": "mcp:*", "hooks": [ { "type": "command", "command": "/etc/augment/hooks/log-mcp-tools.sh", "timeout": 5000 } ] } ] } } ``` **Block specific MCP server:** ```bash theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) MCP_SERVER=$(echo "$EVENT_DATA" | jq -r '.mcp_metadata.mcpExecutedToolServerName // ""') if [ "$MCP_SERVER" = "blocked-server" ]; then echo "This MCP server is blocked by security policy" >&2 exit 2 fi exit 0 ``` **Configuration:** ```json theme={null} { "hooks": { "PreToolUse": [ { "matcher": "mcp:.*_blocked-server$", "hooks": [ { "type": "command", "command": "/etc/augment/hooks/block-mcp-server.sh", "timeout": 5000 } ] } ] } } ``` ## Examples For ready-to-use hook examples, see [Hooks Examples](/cli/hooks-examples). ## Debugging Hooks ### Environment Variables Hooks have access to these environment variables during execution: | Variable | Description | Example | | :-: | - | :-: | | `AUGMENT_PROJECT_DIR` | First workspace root directory (or `process.cwd()` if empty) | `/Users/username/project` | | `AUGMENT_CONVERSATION_ID` | Current conversation ID | `conv-xyz789` | | `AUGMENT_HOOK_EVENT` | Event type | `PreToolUse` | | `AUGMENT_TOOL_NAME` | Tool name (PreToolUse/PostToolUse only) | `bash` | ```bash theme={null} #!/usr/bin/env bash echo "Project: $AUGMENT_PROJECT_DIR, Event: $AUGMENT_HOOK_EVENT" >&2 exit 0 ``` ### Testing Hooks Locally **1. Create a test event file:** ```bash theme={null} cat > test-event.json << 'EOF' { "hook_event_name": "PreToolUse", "conversation_id": "test-conv", "workspace_roots": ["/Users/username/project"], "tool_name": "bash", "tool_input": { "command": "git status" } } EOF ``` **2. Test your hook script:** ```bash theme={null} # Test your hook script (works for both bash and Python via shebang) cat test-event.json | /etc/augment/hooks/my-hook.sh echo "Exit code: $?" ``` **3. Validate JSON output:** ```bash theme={null} # Test and validate JSON output OUTPUT=$(cat test-event.json | /etc/augment/hooks/my-hook.sh) echo "$OUTPUT" | jq . # Validates JSON syntax ``` ### Viewing Hook Execution Logs Hooks log to the Augment logger. To see hook execution details: **CLI:** ```bash theme={null} # Run with debug-level logging auggie --log-level debug "your prompt here" ``` Use `--log-file ` to choose where the log is written. Hook log lines use the `pi-hooks` prefix. Run `/hooks` in interactive mode to see the configured hooks and any configuration problems. ### Common Debugging Techniques **Log to stderr (won't affect hook output):** ```bash theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) echo "[DEBUG] $(echo "$EVENT_DATA" | jq -r '.hook_event_name')" >&2 exit 0 ``` **Save event data for inspection:** ```bash theme={null} #!/usr/bin/env bash cat > /tmp/hook-debug.json exit 0 ``` #### 3. Validate hook matcher patterns To test if your matcher pattern works: ```bash theme={null} # Test regex pattern in bash TOOL_NAME="search_my-server" PATTERN=".*_my-server$" if [[ "$TOOL_NAME" =~ $PATTERN ]]; then echo "Pattern matches!" else echo "Pattern does not match" fi ``` ```python theme={null} # Test regex pattern in Python import re tool_name = "search_my-server" pattern = r".*_my-server$" if re.match(pattern, tool_name): print("Pattern matches!") else: print("Pattern does not match") ``` ### Performance Tips 1. **Keep hooks fast** - Hooks run synchronously and block tool execution 2. **Cache expensive operations** - Store results in files or environment variables 3. **Use early returns** - Exit as soon as you know the result 4. **Avoid network calls** - Network requests add latency 5. **Minimize JSON parsing** - Parse only the fields you need **Example: Fast hook with early return** ```bash Bash theme={null} #!/usr/bin/env bash EVENT_DATA=$(cat) # Early return if not a bash tool TOOL_NAME=$(echo "$EVENT_DATA" | jq -r '.tool_name') if [[ "$TOOL_NAME" != "bash" ]]; then exit 0 # Not interested, return immediately fi # Only parse command if we got here COMMAND=$(echo "$EVENT_DATA" | jq -r '.tool_input.command') # Check command if echo "$COMMAND" | grep -qE "rm -rf"; then echo "Blocked dangerous command" >&2 exit 2 fi exit 0 ``` ```python Python theme={null} #!/usr/bin/env python3 import sys import json import re event_data = json.load(sys.stdin) # Early return if not a bash tool tool_name = event_data.get('tool_name', '') if tool_name != 'bash': sys.exit(0) # Not interested, return immediately # Only parse command if we got here command = event_data.get('tool_input', {}).get('command', '') # Check command if re.search(r'rm -rf', command): print("Blocked dangerous command", file=sys.stderr) sys.exit(2) sys.exit(0) ``` ## Troubleshooting > **Hook not being triggered** > > **Check:** > > 1. **Matcher pattern** - Verify your regex pattern matches the tool name > 2. **Event type** - Ensure you're listening to the correct event (PreToolUse vs PostToolUse) > 3. **Settings file location** - Verify hooks are in the correct settings file (project vs user vs system) > 4. **Hook path** - Ensure the hook script path is correct and the file exists > 5. **File permissions** - Make sure the hook script is executable (`chmod +x hook.sh`) > > **Debug:** > > ```bash theme={null} > # Check if hook file exists and is executable > ls -la /etc/augment/hooks/my-hook.sh > > # Test matcher pattern > echo "bash" | grep -E "bash|edit" # Should match > echo "read" | grep -E "bash|edit" # Should not match > ``` > **Hook execution timeout** > > Hooks have a **60-second timeout** by default. If your hook takes longer: > > 1. **Optimize the hook** - Make it faster > 2. **Run async operations** - Don't wait for slow operations > 3. **Use background jobs** - Start long-running tasks in the background > > ```bash theme={null} > #!/usr/bin/env bash > EVENT_DATA=$(cat) > > # Start long-running task in background (don't wait) > ( > # Long-running operation here > sleep 300 > ) & > > # Return immediately > exit 0 > ``` > **JSON parsing errors** > > **Common issues:** > > * **Invalid JSON syntax** - Use `jq` to validate > * **Missing quotes** - Ensure all strings are quoted > * **Trailing commas** - JSON doesn't allow trailing commas > * **Special characters** - Escape special characters in strings > > **Validate JSON:** > > ```bash theme={null} > # Test JSON output > cat << 'EOF' | jq . > { > "hookSpecificOutput": { > "hookEventName": "PreToolUse", > "permissionDecision": "deny" > } > } > EOF > ``` > **Hook blocks but shouldn't** > > **Check:** > > * **Exit code** - Make sure you're returning `exit 0` for success > * **JSON output** - Verify `permissionDecision` is not set to `"deny"` > * **stderr output** - Ensure you're not writing errors to stderr with exit code 2 > > **Debug:** > > ```bash theme={null} > #!/usr/bin/env bash > EVENT_DATA=$(cat) > > # Explicitly allow > echo "Allowing tool execution" >&2 # Debug message > exit 0 # Success - don't block > ``` > **Hook errors in logs** > > Check the Auggie logs for hook execution errors: > > ```bash theme={null} > # Write logs to a known file, then watch it from another terminal > auggie --log-level debug --log-file /tmp/auggie.log > tail -f /tmp/auggie.log | grep -i hook > ``` > **Testing hooks locally** > > Test your hook script manually: > > ```bash theme={null} > # Create test event data > echo '{ > "hook_event_name": "PreToolUse", > "tool_name": "bash", > "tool_input": {"command": "ls -la"} > }' | /etc/augment/hooks/your-hook.sh > > # Check exit code > echo $? > ``` ## Security Considerations > [!WARNING] > > **USE AT YOUR OWN RISK**: Hooks execute arbitrary shell commands on your system automatically. By using hooks, you acknowledge that: > > * You are solely responsible for the commands you configure > * Hooks can modify, delete, or access any files your user account can access > * Malicious or poorly written hooks can cause data loss or system damage > * You should thoroughly test hooks in a safe environment before production use > > Always review and understand any hook commands before adding them to your configuration. ### Security Best Practices 1. **Validate and sanitize inputs** - Never trust input data blindly 2. **Always quote shell variables** - Use `"$VAR"` not `$VAR` 3. **Block path traversal** - Check for `..` in file paths 4. **Use absolute paths** - Specify full paths for scripts 5. **Skip sensitive files** - Avoid `.env`, `.git/`, keys, etc. 6. **Set appropriate timeouts** - Prevent hooks from hanging indefinitely 7. **Test thoroughly** - Test hooks with various inputs before deploying ## Best Practices 1. **Keep hooks fast**: Hooks should complete quickly (\< 1 second) to avoid slowing down the agent 2. **Use timeouts**: Always set reasonable timeouts to prevent hanging 3. **Handle errors gracefully**: Use exit code 0 for non-critical errors to avoid blocking the agent 4. **Log appropriately**: Use stderr for user-facing messages, log files for detailed audit trails 5. **Test thoroughly**: Test hooks with various tool inputs before deploying 6. **Version control**: Keep hook scripts in version control with your project 7. **Document behavior**: Add comments explaining what each hook does and why ## Limitations * Hooks currently only support command execution (webhooks planned for future) * PostToolUse hooks cannot modify tool output (read-only) * Hooks cannot access the agent's conversation history directly * PreToolUse and PostToolUse hooks run one at a time, in order; if a hook blocks the tool, later hooks for that call do not run. Other events run their hooks at the same time ## Hook Execution Details * **Timeout**: 60-second execution limit by default, configurable per command * **Execution order**: Hooks execute in the order they are defined * **Environment**: Runs in current directory with Auggie's environment * **Input**: JSON via stdin * **Output**: * PreToolUse/PostToolUse/Stop: Progress shown in logs * SessionStart: not added to the agent's context * SessionEnd: Logged to debug only ## Related Documentation * [Hooks Examples](/cli/hooks-examples) - Ready-to-use hook examples * [MCP (Model Context Protocol)](/setup-augment/mcp) - External tool integration * [Permissions](/cli/permissions) - Tool permission system * [Rules & Guidelines](/cli/rules) - Custom rules and guidelines * [Custom Commands](/cli/custom-commands) - Create custom CLI commands # Hooks Examples Source: https://docs.augmentcode.com/cli/hooks-examples Ready-to-use examples of hooks for common security, automation, and integration workflows. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/hooks-examples) . ## Example Hooks Here are practical examples of hooks you can use in your projects. Each example includes the hook script and the corresponding configuration. > **Block Dangerous Commands** > > Block shell commands that could be destructive: > > **Hook Script** (`/etc/augment/hooks/security-block-dangerous.sh`): > > ```bash Bash theme={null} > #!/usr/bin/env bash > > EVENT_DATA=$(cat) > COMMAND=$(echo "$EVENT_DATA" | jq -r '.tool_input.command // ""') > > # Check for dangerous patterns > if echo "$COMMAND" | grep -qE "rm -rf|sudo|chmod 777"; then > echo "Blocked dangerous command: $COMMAND" >&2 > exit 2 > fi > > exit 0 > ``` > > ```python Python theme={null} > #!/usr/bin/env python3 > import sys > import json > import re > > event_data = json.load(sys.stdin) > command = event_data.get('tool_input', {}).get('command', '') > > # Check for dangerous patterns > if re.search(r'rm -rf|sudo|chmod 777', command): > print(f"Blocked dangerous command: {command}", file=sys.stderr) > sys.exit(2) > > sys.exit(0) > ``` > > **Configuration:** > > ```json theme={null} > { > "hooks": { > "PreToolUse": [ > { > "matcher": "bash", > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/security-block-dangerous.sh", > "timeout": 5000 > } > ] > } > ] > } > } > ``` > **Auto-Format Code Before Editing** > > Automatically format code files using language-specific formatters (Biome, Ruff, gofmt, rustfmt) before the agent edits them. > > **Hook Script** (`/etc/augment/hooks/auto-format.sh`): > > ```bash Bash theme={null} > #!/usr/bin/env bash > > EVENT_DATA=$(cat) > TOOL_NAME=$(echo "$EVENT_DATA" | jq -r '.tool_name') > > # Only run for file editing tools > [[ "$TOOL_NAME" != "edit" ]] && exit 0 > > FILE_PATH=$(echo "$EVENT_DATA" | jq -r '.tool_input.path // ""') > [[ -z "$FILE_PATH" || ! -f "$FILE_PATH" ]] && exit 0 > > EXT="${FILE_PATH##*.}" > > case "$EXT" in > ts|tsx|js|jsx) command -v biome &>/dev/null && biome format --write "$FILE_PATH" ;; > py) command -v ruff &>/dev/null && ruff format "$FILE_PATH" ;; > go) command -v gofmt &>/dev/null && gofmt -w "$FILE_PATH" ;; > rs) command -v rustfmt &>/dev/null && rustfmt "$FILE_PATH" ;; > esac > > exit 0 > ``` > > ```python Python theme={null} > #!/usr/bin/env python3 > import sys, json, subprocess, shutil > from pathlib import Path > > event_data = json.load(sys.stdin) > if event_data.get('tool_name') != 'edit': > sys.exit(0) > > file_path = event_data.get('tool_input', {}).get('path', '') > if not file_path or not Path(file_path).exists(): > sys.exit(0) > > ext = Path(file_path).suffix.lstrip('.') > formatters = { > 'ts': ['biome', 'format', '--write'], > 'tsx': ['biome', 'format', '--write'], > 'js': ['biome', 'format', '--write'], > 'py': ['ruff', 'format'], > 'go': ['gofmt', '-w'], > 'rs': ['rustfmt'], > } > > if ext in formatters and shutil.which(formatters[ext][0]): > subprocess.run(formatters[ext] + [file_path], timeout=30) > > sys.exit(0) > ``` > > **Configuration:** > > ```json theme={null} > { > "hooks": { > "PreToolUse": [ > { > "matcher": "edit", > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/auto-format.sh", > "timeout": 30000 > } > ] > } > ] > } > } > ``` > > **Supported Formatters:** > > | Language | Formatter | Command | > | :-: | :-: | :-: | > | TypeScript/JavaScript | [Biome](https://biomejs.dev/) | `biome format --write` | > | Python | [Ruff](https://docs.astral.sh/ruff/) | `ruff format` | > | Go | [gofmt](https://pkg.go.dev/cmd/gofmt) | `gofmt -w` | > | Rust | [rustfmt](https://rust-lang.github.io/rustfmt/) | `rustfmt` | > **Audit Sensitive File Access** > > Monitor when the agent accesses sensitive files: > > **Hook Script** (`/etc/augment/hooks/audit.sh`): > > ```bash theme={null} > #!/usr/bin/env bash > EVENT_DATA=$(cat) > FILE_PATH=$(echo "$EVENT_DATA" | jq -r '.tool_input.path // ""') > > if echo "$FILE_PATH" | grep -qE "\.env|secrets|credentials"; then > echo "[AUDIT] Sensitive file access: $FILE_PATH" >&2 > fi > > exit 0 # Audit only, don't block > ``` > > **Configuration:** > > ```json theme={null} > { > "hooks": { > "PreToolUse": [ > { > "matcher": "read|edit", > "hooks": [ > { "type": "command", "command": "/etc/augment/hooks/audit.sh" } > ] > } > ] > } > } > ``` > **Block Sudo Commands** > > A simple hook to block sudo commands: > > **Hook Script** (`/etc/augment/hooks/validate-tool.sh`): > > ```bash theme={null} > #!/usr/bin/env bash > EVENT_DATA=$(cat) > COMMAND=$(echo "$EVENT_DATA" | jq -r '.tool_input.command // ""') > > if echo "$COMMAND" | grep -q "sudo"; then > echo "Blocked: sudo not allowed" >&2 > exit 2 # Block execution > fi > > exit 0 > ``` > > **Configuration:** > > ```json theme={null} > { > "hooks": { > "PreToolUse": [ > { > "matcher": "bash", > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/validate-tool.sh", > "timeout": 5000 > } > ] > } > ] > } > } > ``` > **Load Context at Session Start** > > Inject development context when a session starts: > > **Hook Script** (`/etc/augment/hooks/load-context.sh`): > > ```bash Bash theme={null} > #!/usr/bin/env bash > > # Load recent git commits > echo "Recent commits:" > git log --oneline -5 > > # Load current branch info > echo "" > echo "Current branch: $(git branch --show-current)" > > # Load open issues (example) > echo "" > echo "Open issues:" > # curl -s https://api.example.com/issues | jq -r '.[] | "- \(.title)"' > > exit 0 > ``` > > ```python Python theme={null} > #!/usr/bin/env python3 > import sys > import subprocess > > # Load recent git commits > print("Recent commits:") > result = subprocess.run(['git', 'log', '--oneline', '-5'], > capture_output=True, text=True) > print(result.stdout) > > # Load current branch info > print("") > print("Current branch:", end=" ") > result = subprocess.run(['git', 'branch', '--show-current'], > capture_output=True, text=True) > print(result.stdout.strip()) > > sys.exit(0) > ``` > > **Configuration:** > > ```json theme={null} > { > "hooks": { > "SessionStart": [ > { > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/load-context.sh", > "timeout": 10000 > } > ] > } > ] > } > } > ``` > **Session Cleanup** > > Run cleanup when a session ends: > > **Hook Script** (`/etc/augment/hooks/cleanup.sh`): > > ```bash theme={null} > #!/usr/bin/env bash > echo "[$(date)] Session ended" >&2 > exit 0 > ``` > > **Configuration:** > > ```json theme={null} > { > "hooks": { > "SessionEnd": [ > { > "hooks": [ > { "type": "command", "command": "/etc/augment/hooks/cleanup.sh" } > ] > } > ] > } > } > ``` > **Block Production Database Access** > > Prevent agents from accessing production systems or sensitive data: > > **Hook Script** (`/etc/augment/hooks/block-prod.sh`): > > ```bash theme={null} > #!/usr/bin/env bash > EVENT_DATA=$(cat) > TOOL_INPUT=$(echo "$EVENT_DATA" | jq -r '.tool_input | tostring') > > if echo "$TOOL_INPUT" | grep -qE "prod-db|production\.database"; then > echo "Access to production databases is not allowed" >&2 > exit 2 > fi > > exit 0 > ``` > > **Configuration:** > > ```json theme={null} > { > "hooks": { > "PreToolUse": [ > { > "matcher": ".*", > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/block-prod.sh", > "timeout": 5000 > } > ] > } > ] > } > } > ``` > **Compliance Auditing** > > Log all tool executions for compliance: > > **Hook Script** (`/etc/augment/hooks/audit-log.sh`): > > ```bash theme={null} > #!/usr/bin/env bash > EVENT_DATA=$(cat) > TOOL=$(echo "$EVENT_DATA" | jq -r '.tool_name') > echo "[$(date -u +%FT%TZ)] Tool: $TOOL" >&2 > exit 0 > ``` > > **Configuration:** > > ```json theme={null} > { > "hooks": { > "PostToolUse": [ > { > "matcher": ".*", > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/audit-log.sh", > "timeout": 5000 > } > ] > } > ] > } > } > ``` > **Rate Limiting MCP Tools** > > Block excessive API calls to MCP servers: > > **Hook Script** (`/etc/augment/hooks/rate-limit.sh`): > > ```bash theme={null} > #!/usr/bin/env bash > EVENT_DATA=$(cat) > SERVER=$(echo "$EVENT_DATA" | jq -r '.mcp_metadata.mcpExecutedToolServerName // ""') > RATE_FILE="/tmp/rate-$SERVER" > COUNT=$(cat "$RATE_FILE" 2>/dev/null || echo "0") > > if [ "$COUNT" -gt 10 ]; then > echo "Rate limit exceeded" >&2 > exit 2 > fi > > echo $((COUNT + 1)) > "$RATE_FILE" > exit 0 > ``` > > **Configuration:** > > ```json theme={null} > { > "hooks": { > "PreToolUse": [ > { > "matcher": "mcp:*", > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/rate-limit.sh", > "timeout": 5000 > } > ], > "metadata": { > "includeMCPMetadata": true > } > } > ] > } > } > ``` > **Require Tests Before Finishing** > > Block the agent from stopping until tests are modified: > > **Hook Script** (`/etc/augment/hooks/require-tests.sh`): > > ```bash Bash theme={null} > #!/usr/bin/env bash > EVENT_DATA=$(cat) > > # Extract code changes > CODE_RESPONSE=$(echo "$EVENT_DATA" | jq -r '.conversation.agentCodeResponse // []') > > # Check if any test files were modified > TEST_FILES=$(echo "$CODE_RESPONSE" | jq -r '.[] | select(.path | test("test|spec")) | .path') > > if [[ -z "$TEST_FILES" ]]; then > # No test files modified - block stop > cat << EOF > { > "hookSpecificOutput": { > "hookEventName": "Stop", > "decision": "block", > "reason": "Please add or update tests before finishing" > } > } > EOF > exit 0 > fi > > exit 0 > ``` > > ```python Python theme={null} > #!/usr/bin/env python3 > import sys > import json > import re > > event_data = json.load(sys.stdin) > conversation = event_data.get('conversation', {}) > code_response = conversation.get('agentCodeResponse', []) > > # Check if any test files were modified > test_files = [ > change['path'] for change in code_response > if re.search(r'test|spec', change.get('path', '')) > ] > > if not test_files: > output = { > "hookSpecificOutput": { > "hookEventName": "Stop", > "decision": "block", > "reason": "Please add or update tests before finishing" > } > } > print(json.dumps(output)) > sys.exit(0) > > sys.exit(0) > ``` > > **Configuration:** > > ```json theme={null} > { > "hooks": { > "Stop": [ > { > "matcher": ".*", > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/require-tests.sh", > "timeout": 5000 > } > ], > "metadata": { > "includeConversationData": true > } > } > ] > } > } > ``` ## Advanced Configuration Patterns These patterns show how to combine multiple hooks effectively: > **Multiple Hooks on Same Event** > > Execute multiple hooks in order for the same event: > > ```json theme={null} > { > "hooks": { > "PreToolUse": [ > { > "matcher": "bash", > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/log-command.sh", > "timeout": 5000 > }, > { > "type": "command", > "command": "/etc/augment/hooks/security-check.sh", > "timeout": 5000 > } > ] > } > ] > } > } > ``` > > If any hook returns exit code 2, execution is blocked and subsequent hooks are not run. > **Combining Matchers** > > Use multiple matcher configurations for different tools: > > ```json theme={null} > { > "hooks": { > "PreToolUse": [ > { > "matcher": "mcp:*", > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/log-mcp.sh", > "timeout": 5000 > } > ] > }, > { > "matcher": "bash", > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/security-bash.sh", > "timeout": 5000 > } > ] > }, > { > "matcher": ".*", > "hooks": [ > { > "type": "command", > "command": "/etc/augment/hooks/audit-all.sh", > "timeout": 5000 > } > ] > } > ] > } > } > ``` ## See Also * [Hooks](/cli/hooks) - Learn how hooks work and configure them * [Permissions](/cli/permissions) - Tool permission system * [Rules & Guidelines](/cli/rules) - Custom rules and guidelines # Integrations and MCP Source: https://docs.augmentcode.com/cli/integrations Expand Augment's capabilities with external tools and data sources through native integrations and Model Context Protocol (MCP) servers. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/integrations) . > [!NOTE] > > Auggie runs commands and tools automatically. Only use integrations and MCP servers from trusted sources, and be aware of the risks of combining multiple tools with external data sources or production systems. ## About Integrations and MCP Auggie can utilize external integrations through native integrations like GitHub, Linear, and Notion and Model Context Protocol (MCP) to access external systems for information and integrate tools to take actions. MCP is an open protocol that provides a standardized way to connect AI models to different data sources and tools. ## Native Integrations You'll need to configure the integration in Augment for VS Code or JetBrains IDEs. Once configured, the integration will be available for use with Auggie automatically. See a full list and examples for [native agent integrations](/setup-augment/agent-integrations). ### 1. Setup in Augment extension * **Visual Studio Code**: Click the settings icon in the top right of Augment's chat window or press Cmd/Ctrl Shift P and select Show Settings Panel * **JetBrains IDEs**: Click the Augment icon in the bottom right of your JetBrains IDE and select Tool Settings ### 2. Connect the integration Click "Connect" for the integration you want to set up ![Set up integrations in the settings page](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/integration-settings.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=8e1cb7e476ff72baf79853e1a396061a) You'll be redirected to authorize the integration with the appropriate service. After authorization, the integration will be available for use with Augment Agent. ## MCP Integrations In addition to native integrations, Auggie can also access external systems through Model Context Protocol (MCP) servers. MCP servers enable Auggie to interact with external tools and services through a standardized protocol, such as accessing databases, running browser automation, sending messages to Slack, or integrating with APIs. ### Configure MCP via settings.json You can persist MCP servers in the Augment settings file `~/.augment/settings.json`, which will initialize on startup and can be checked with `/mcp`. ```json theme={null} { "mcpServers": { "context7": { "type": "http", "url": "https://mcp.context7.com/mcp", "headers": { "CONTEXT7_API_KEY": "YOUR_API_KEY" } }, "weather": { "type": "sse", "url": "https://weather-mcp.example.com/v1", "headers": { "X-API-Key": "your_weather_api_key", "Content-Type": "application/json" } }, "renderMCP": { "type": "http", "url": "https://mcp.render.com/mcp", "headers": { "Authorization": "Bearer " } }, "local-tool": { "command": "/usr/local/bin/custom-mcp", "args": ["--serve", "--port", "3000"], "env": { "DEBUG": "true" } } } } ``` #### Variable Expansion MCP server configurations support variable expansion for dynamic values: | Syntax | Expands to | | :- | :- | | `${workspaceFolder}` | The current workspace root path | | `${VAR}` | The value of the environment variable `VAR` | | `${VAR:-default}` | The value of `VAR`, or `default` if it isn't set | | `\${VAR}` | The literal text `${VAR}` | | `~` at the start of `command` or `cwd` | Your home directory | **Example: Using `${workspaceFolder}` in args** ```json theme={null} { "mcpServers": { "yaml-lsp": { "command": "mcp-language-server", "args": [ "--workspace", "${workspaceFolder}", "--lsp", "yaml-language-server", "--", "--stdio" ] } } } ``` When running in workspace `/Users/username/my-project`, the args are expanded to: ``` ["--workspace", "/Users/username/my-project", "--lsp", "yaml-language-server", "--", "--stdio"] ``` **Supported locations for variable expansion:** * `command`, `args`, `cwd`, and `env` values (for stdio transport) * `url` and `headers` values (for http and sse transports) **Notes:** * If an environment variable isn't set and has no default, Auggie skips that server and reports an error for it * Variable expansion works with both `settings.json` configurations and `--mcp-config` overrides #### HTTP Transport with Headers MCP servers using HTTP transport can include a `headers` object for authentication or custom headers: ```json theme={null} { "mcpServers": { "renderMCP": { "type": "http", "url": "https://mcp.render.com/mcp", "headers": { "Authorization": "Bearer ", "X-Custom-Header": "custom-value" } } } } ``` The `headers` field accepts any valid HTTP headers as key-value pairs. **Common uses** * **Authentication** - `Authorization` headers with bearer tokens or API keys * **Custom parameters** - Server-specific information that doesn't fit into standard request parameters * **Session management** - `Mcp-Session-Id` header for managing sessions in Streamable HTTP transport **Considerations** * **Transport type** - Headers are relevant for HTTP and SSE transports only. Stdio transport uses standard input/output and does not use HTTP headers * **Server requirements** - Required headers depend on the MCP server implementation * **Security** - Avoid including sensitive information like API keys directly in configuration files. Consider secure credential management methods ### Manage MCP servers with the Auggie CLI You can add and inspect MCP servers with Auggie subcommands. By default, they save the configuration to your `~/.augment/settings.json` file. Pass `--project` to use `.augment/settings.json` or `--local` to use `.augment/settings.local.json` in the current project. #### Usage **Add MCP server:** ```bash theme={null} auggie mcp add [options] ``` Writes the server entry to your settings.json with interactive prompts for overwriting existing configurations. Options: * `-c, --command ` - Executable path (for stdio transport) * `--args ` - Arguments string for command * `-e, --env ` - Environment variable (repeatable) * `-t, --transport ` - stdio|sse|http (default: "stdio") * `-u, --url ` - URL (required for --transport sse or http) * `-H, --header ` - HTTP header (repeatable, for http and sse transports) * `-r, --replace` - Overwrite existing entry without prompt * `--project` - Save to project settings (`.augment/settings.json`) * `--local` - Save to local settings (`.augment/settings.local.json`) **Add MCP server from JSON:** ```bash theme={null} auggie mcp add-json ``` Import an MCP server configuration directly from a JSON string. This is useful when you have a complete server configuration in JSON format and want to add it quickly without specifying individual options. The JSON string should match the structure used in `settings.json` for MCP server configurations. This command uses the same mechanism as `--mcp-config` but provides a convenient way to add servers directly from the command line. **List MCP servers:** ```bash theme={null} auggie mcp list [options] ``` Lists configured MCP servers (from settings and any active overrides). Options: * `--json` - Output JSON format **Remove MCP server:** ```bash theme={null} auggie mcp remove [options] ``` Cleanly removes the named server configuration from settings.json. Pass `--project` or `--local` to remove it from project or local settings. Examples: ```bash theme={null} # Add a stdio-based MCP server (executable with args and environment) auggie mcp add context7 \ --command npx \ --args "-y @upstash/context7-mcp@latest" \ --env CONTEXT7_API_KEY=your_key # Add an SSE-based MCP server (Server-Sent Events with URL) auggie mcp add weather-api \ --transport sse \ --url https://weather-mcp.example.com/sse # Add an HTTP-based MCP server with authentication headers auggie mcp add renderMCP \ --transport http \ --url https://mcp.render.com/mcp \ --header "Authorization:Bearer YOUR_API_TOKEN" # Add HTTP server with multiple headers auggie mcp add api-service \ --transport http \ --url https://api.example.com/mcp \ --header "Authorization:Bearer YOUR_TOKEN" \ --header "X-Custom-Header:custom-value" # List all configured servers (tabular display with status) auggie mcp list # List servers in JSON format for programmatic access auggie mcp list --json # Remove a server configuration auggie mcp remove context7 # Replace existing server without interactive prompt auggie mcp add context7 --command npx --args "..." --replace # Add MCP server from JSON configuration (stdio transport) auggie mcp add-json weather-api '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}' # Add MCP server from JSON configuration (SSE transport) auggie mcp add-json remote-api '{"type":"sse","url":"https://api.example.com/sse"}' # Add MCP server from JSON configuration (HTTP transport with headers) auggie mcp add-json renderMCP '{"type":"http","url":"https://mcp.render.com/mcp","headers":{"Authorization":"Bearer ABC_XYZ_123"}}' ``` ### MCP overrides You can define servers by passing ad‑hoc overrides with `--mcp-config`. The structure is the same as `settings.json`: ```json theme={null} // After npm install gitlab-mr-mcp { "mcpServers": { "gitlab-mr-mcp": { "command": "node", "args": ["/path/to/gitlab-mr-mcp/index.js"], "env": { "MR_MCP_GITLAB_TOKEN": "your_gitlab_token", "MR_MCP_GITLAB_HOST": "your_gitlab_host" } } } } ``` ### MCP Tool Search By default, every tool from every configured MCP server is loaded into Auggie's context up front. When many MCP servers are configured, this can consume a meaningful portion of the agent's context window before your prompt is processed. MCP Tool Search hides individual MCP tools from the agent and exposes two meta-tools — `find-tool` and `execute-tool` — so the agent only loads the full schema for tools it actually uses. MCP Tool Search is disabled by default. Enable it with either: * **Per run** — pass `--enable-tool-search` when invoking Auggie. * **Persistent** — set `"enableToolSearch": true` in your Auggie `settings.json`. When enabled, `find-tool` calls appear as a separate **Tool Search** activity in your usage dashboard. Permissions continue to apply to the underlying MCP tool invocations made through `execute-tool`. For conceptual background, see [MCP Tool Search](/setup-augment/mcp#mcp-tool-search) (VS Code) or [MCP Tool Search](/jetbrains/setup-augment/mcp#mcp-tool-search) (JetBrains). # Interactive mode Source: https://docs.augmentcode.com/cli/interactive Use a rich interactive terminal experience to explore your codebase, build new features, debug issues, and integrate your tools. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/interactive) . ## About interactive mode Auggie is an agentic terminal-based code assistant that has deep codebase knowledge powered by Augment's context engine. Auggie can help you understand a new codebase, fix bugs quickly, and build new features faster. Auggie has access to your connected integrations and MCP servers and can pull in additional context or run tools to get your tasks done. ## Using interactive mode Run `auggie` without any mode flags to get the full-screen terminal user interface with rich interactive features, real-time streaming of responses, and visual progress indicators. This mode shows all tool calls, results, and allows ongoing conversation through an intuitive interface. ```sh theme={null} # Start Auggie in interactive mode auggie # Provide an initial instruction auggie "Look at my open issues and prioritize the highest impact ones for me" ``` ### Multi-line input Press `Shift + Enter` to enter a new line. If `Shift + Enter` does not work in your terminal (for example, macOS Terminal), use `Ctrl + J`. | Terminal application | New line shortcut | | :- | :- | | All terminals | `Ctrl + J` | | Terminals with enhanced keyboard support (Ghostty, Kitty, WezTerm, iTerm2) | `Shift + Enter` | ## Reference ### Shortcuts Run `/hotkeys` to see every shortcut. You can customize shortcuts in `~/.augment/keybindings.json` and apply changes with `/reload`. | Command | Description | | :- | :- | | `Ctrl + P` | Enhance your prompt with codebase context | | `Escape` | Interrupt the active agent | | `Escape` + `Escape` | Open the session tree (configurable with `doubleEscapeAction`) | | `Ctrl + C` | Clear the input box | | `Ctrl + D` | Exit when the input box is empty | | `Shift + Tab` | Cycle the reasoning effort on reasoning models | | `Ctrl + L` | Open the model selector | | `Ctrl + O` | Expand or collapse tool output | | `Ctrl + T` | Show or hide thinking blocks | | `Ctrl + G` | Open current input in external editor, inserts text on exit | | `Alt + Enter` | Queue a follow-up message while the agent is working | | `Alt + Up` | Restore queued messages to the input box | | `Ctrl + V` | Paste an image from the clipboard (`Alt + V` on Windows) | | `Ctrl + Z` | Suspend Auggie to the background | | `Up Arrow` / `Down Arrow` | Cycle through previous messages | All menus and selectors support type-to-filter. Use the arrow keys to move and `Escape` to go back. ### Slash Commands The command menu reflects your available integrations and loaded plugins. Some commands only appear when the relevant feature is enabled. Argument hints appear beside commands as you type. #### Built-in slash commands | Command | Description | | :- | :- | | `/about` | Show version, environment, account, and session info | | `/agents` | Browse and create custom agents | | `/changelog` | Show changelog entries | | `/cloud [on\|off]` | Save the cloud mode startup preference; restart Auggie to apply | | `/compact [instructions]` | Summarize the conversation to free up context | | `/context` | Show context usage | | `/copy` | Copy the last agent message to the clipboard | | `/effort [level]` | Choose how much a reasoning model thinks | | `/enhance` | Enhance the current prompt with codebase context | | `/exit`, `/quit` | Exit Auggie | | `/export [path]` | Export the session to HTML (default) or JSONL | | `/feedback` | Rate the latest response and optionally leave a note | | `/fork` | Create a new fork from a previous message | | `/hooks` | View configured hooks | | `/hotkeys` | Show all keyboard shortcuts | | `/import ` | Import and resume a session from a JSONL file | | `/import-legacy-sessions [ids]` | Import sessions from Auggie 0.x | | `/login`, `/logout` | Log in or out | | `/mcp` | View the status of configured MCP servers | | `/model` | Select the model (press `Tab` to change reasoning effort) | | `/name ` | Set the session display name | | `/new` | Start a new session | | `/permissions` | View and manage tool permission rules | | `/plugins` | Manage plugins and marketplaces | | `/reload` | Reload keybindings, extensions, skills, prompts, and themes | | `/restart-mcp` | Restart MCP servers | | `/resume` | Resume a different session | | `/rules` | View loaded rules | | `/scoped-models` | Choose which models to cycle through | | `/session` | Show session info and stats | | `/settings` | Open the settings menu | | `/tree` | Navigate the session tree and switch branches | | `/worktree` | Select, switch, create, or delete git worktrees | #### Custom and skill slash commands In addition to the built-in commands above, the slash menu also lists: * Your [custom slash commands](/cli/custom-commands). For example, `.augment/commands/deploy-staging.md` becomes `/deploy-staging`. * Your discovered [skills](/cli/skills). For example, a skill at `.augment/skills/my-skill/SKILL.md` becomes `/skill:my-skill`. Built-in slash commands take precedence over custom commands or skills with the same name, so choose names that do not collide with the commands listed above. For more information about slash commands, including how to create custom commands, see [Custom Slash Commands](/cli/custom-commands). # Prompt Enhancer Source: https://docs.augmentcode.com/cli/interactive/prompt-enhancer Use Ctrl+P to enhance your prompts with relevant context, structure, and conventions from your codebase. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/interactive/prompt-enhancer) . ## About the Prompt Enhancer The Auggie CLI prompt enhancer is a powerful feature that helps you craft better prompts by automatically adding relevant context, structure, and conventions from your codebase. Instead of writing detailed prompts from scratch, you can start with a simple idea and let the prompt enhancer transform it into a comprehensive, well-structured prompt. ## Activating the Prompt Enhancer To use the prompt enhancer in Auggie's interactive mode: 1. **Start typing your prompt** in the input box 2. **Press Ctrl + P** to activate the prompt enhancer 3. **Wait for enhancement** - Auggie will process your prompt and replace it with an enhanced version 4. **Review and edit** the enhanced prompt if needed 5. **Submit your enhanced prompt** by pressing Enter You can also run the `/enhance` slash command, or press Ctrl + /. In print mode, pass `--enhance-prompt` to enhance the instruction before it is sent. > [!NOTE] > > The prompt enhancer is only available when you have text entered at the command prompt. The Ctrl + P shortcut will only work in interactive mode. ## How It Works When you press Ctrl + P, the prompt enhancer: 1. **Captures your current input** and saves it to history 2. **Switches to Enhancement mode** - you'll see the mode indicator change and input will be temporarily disabled 3. **Sends your prompt** to the enhancement service using your current workspace context 4. **Processes the response** and extracts the enhanced prompt 5. **Replaces your input** with the enhanced version and returns to Normal mode During enhancement, you'll see: * The mode indicator shows "Enhancing your prompt, press Esc to cancel" * Input is disabled to prevent conflicts * A visual indication that processing is in progress ## Enhancement Process The prompt enhancer uses your workspace context to improve your prompts by: * **Adding relevant file references** from your current project * **Including coding conventions** and patterns from your codebase * **Structuring the prompt** for better clarity and specificity * **Adding context** about your project's architecture and dependencies * **Suggesting specific examples** based on existing code patterns ## Canceling Enhancement You can cancel the prompt enhancement process at any time: * **Press Esc** to cancel enhancement and restore your original input * **Press Ctrl + C** to cancel enhancement and restore your original input When canceled, you'll see a brief notification and your original prompt will be restored. ## Error Handling If the prompt enhancement fails: * Your original input will be restored * An error notification will appear briefly (\~3 seconds) * You can try enhancing again or proceed with your original prompt Common reasons for enhancement failure: * Network connectivity issues * Service temporarily unavailable * Input too short or unclear for enhancement ## Examples ### Before Enhancement ``` fix the login bug ``` ### After Enhancement (Example) ``` Fix the authentication bug in the login flow. Please: 1. Review the current login implementation in `src/auth/login.ts` 2. Check for issues with token validation and session management 3. Examine error handling in the authentication middleware 4. Look at recent changes to the user authentication flow 5. Test the fix with both valid and invalid credentials 6. Ensure the fix follows our existing error handling patterns Context: This appears to be related to the recent changes in the authentication system. Please maintain consistency with our existing auth patterns and ensure proper error messages are returned to the user. ``` ## Integration with Other Features The prompt enhancer works seamlessly with other Auggie CLI features: * **History Navigation**: Enhanced prompts are added to your command history * **Multi-line Input**: Works with both single-line and multi-line prompts * **Conversation Context**: Uses your current conversation history for better enhancement * **Workspace Awareness**: Leverages your current workspace and file context ## Tips for Best Results 1. **Start with clear intent** - Even simple prompts like "add tests" or "refactor this" work well 2. **Be specific about scope** - Mention specific files or components when relevant 3. **Use domain language** - Technical terms related to your project help the enhancer understand context 4. **Review enhanced prompts** - The enhancer provides a starting point; feel free to edit further 5. **Iterate if needed** - You can enhance the same prompt multiple times for different approaches ## Troubleshooting **Ctrl+P doesn't work:** * Ensure you have text in the input box * Make sure you're in Normal mode (not in a menu or other mode) * Check that you're using the correct key combination for your terminal **Enhancement takes too long:** * Press Esc to cancel and try again * Check your network connection * Try with a shorter or simpler prompt **Enhanced prompt isn't helpful:** * Edit the enhanced prompt manually * Try starting with a more specific initial prompt * Consider the context - the enhancer works best with workspace-relevant requests ## Related Features * [Keyboard Shortcuts](/cli/interactive#shortcuts) - Learn other useful CLI shortcuts * [Slash Commands](/cli/interactive#slash-commands) - Discover other interactive commands # Introducing Auggie CLI Source: https://docs.augmentcode.com/cli/overview Auggie in the terminal gives you powerful agentic capabilities to analyze code, make changes, and execute tools in an interactive terminal and in your automated workflows. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/overview) . ## Introduction > **[GitHub Repository](https://github.com/augmentcode/auggie)** > > Report issues, leave feature requests and view custom workflows for Auggie CLI > **[NPM Package](https://www.npmjs.com/package/@augmentcode/auggie)** > > Install Auggie CLI from npm Auggie CLI takes the power of Augment's agent and context engine and puts it in your terminal, allowing you to use Augment anywhere your code goes. You can use Auggie in a standalone interactive terminal session alongside your favorite editor or in any part of your software development stack. * Build features and debug issues with a standalone interactive agent. * Get instant feedback, insight, and suggestions for your PRs and builds. * Triage customer issues and alerts from your observability stack. ## Getting started To use Auggie CLI in interactive mode or in your automations, you'll need: * Node 20 or later installed * A compatible shell like zsh, bash, fish > [!NOTE] > > Auggie 1.x is a prerelease and is published under the `prerelease` tag on npm. Auggie 0.x is published under the `v0-release` tag. See [What's new in Auggie 1.x](/cli/whats-new) for changes from 0.x. **1. Install Auggie with npm** ```sh theme={null} npm install -g @augmentcode/auggie@prerelease ``` You can install Auggie CLI directly from npm anywhere you can run Node 20 or later. **2. Go to your project directory** ```sh theme={null} cd /path/to/your/project ``` Your project will be indexed automatically when you run Auggie in your project directory. Augment's powerful context engine provides the best results when it has access to your project's codebase and any related repositories. **3. Login or sign up to Augment** ```sh theme={null} auggie auth login ``` After installing, you'll have to log in to your Augment account. Run `auggie auth login` and follow the prompts. **4. Start using Auggie** ```sh theme={null} auggie "optional initial prompt" ``` Just run `auggie` to start the interactive terminal. You can also pass a prompt as an argument and use `--print` to print the response to stdout instead of the interactive terminal–perfect for automation workflows. ## Using Auggie in interactive mode Run `auggie` without any mode flags to get the full-screen terminal user interface with rich interactive features, real-time streaming of responses, and visual progress indicators. This mode shows all tool calls, results, and allows ongoing conversation through an intuitive interface. Best for manual development work, exploration, and interactive problem-solving sessions where you want the full visual experience and plan to have back-and-forth conversations with the agent. ## Using Auggie in your automations > [!NOTE] > > Non-interactive mode is an additional feature that may be disabled if it is not included in your agreement (enterprise). **Print Mode**: Add the `--print` flag (e.g., `auggie --print "your instruction"`) to execute the instruction once without the UI. This mode exits immediately without prompting for additional input. Perfect for automation, CI/CD pipelines, and background tasks where you want the agent to act without follow-up from a person. **Output modes**: In print mode, Auggie prints the final response by default, followed by a `Request ID` line (used for support). Use `--mode stream` to see text and tool activity as it happens, or `--mode json` for structured output without the `Request ID` line. # Tool Permissions Source: https://docs.augmentcode.com/cli/permissions Control what tools the agent can execute with granular permission settings for security and compliance. Honored by the Auggie CLI and by Cosmos cloud agents; not enforced in the Augment code extension. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/permissions) . ## About Tool Permissions Auggie CLIs tool permission system provides fine-grained control over what actions the agent can perform in your environment. This security layer ensures that Auggie only executes approved operations, protecting your codebase and system from unintended changes. Tool permissions are especially important when: * Running Auggie in production environments * Working with sensitive codebases * Enforcing organizational security policies * Using Auggie in automated workflows ## Where Permissions Are Enforced `toolPermissions` is honored by the Auggie CLI and by Cosmos cloud agents. Rules are loaded at agent startup from the settings files below and applied to every tool call, so the same configuration behaves identically in either place. ## How Permissions Work When Auggie attempts to use a tool, the permission system: 1. **Checks for matching rules** in your configuration 2. **Applies the first matching rule** based on tool name and optional patterns 3. **Rules are evaluated top-down** - first match wins 4. **Executes or denies** the tool call based on the matched rule ### Permission Flow ``` Tool Request → Check Rules → Apply Permission → Execute/Deny → Log Decision ``` ### Notes on Unmatched Tools * Rules are evaluated in order from top to bottom * The first matching rule determines the permission * If no rules match, the CLI follows its implicit runtime behavior * Configure explicit rules for all tools you want to control ## Permission Types and Precedence There are five permission types: | Type | Effect | | :- | :- | | `allow` | Permit the tool call. | | `deny` | Block the tool call. | | `ask-user` | Ask you to approve the tool call. Without an interactive UI, the call is denied. | | `webhook-policy` | Delegate the decision to an external HTTP endpoint (see [Webhook Validation](#webhook-validation)). | | `script-policy` | Delegate the decision to a local script (see [Script Validation](#script-validation)). | ### Precedence Rules can come from more than one source. Each settings file and the `--permission` CLI flag form a separate **policy**: * **Within a single policy**, the first matching rule wins (top-down). * **Across policies**, the **most restrictive** matching permission wins, in this order (most to least restrictive): `deny` > `webhook-policy` > `script-policy` > `ask-user` > `allow` So if one settings file allows a tool but another file or a `--permission` rule denies it, the tool is denied. This most-restrictive-wins resolution means a stricter policy can never be overridden by a more permissive one. ### The `--permission` CLI Flag The `--permission` flag lets you supply rules on the command line. These rules form a separate policy that is combined with the settings-file rules using the most-restrictive-wins resolution above, so a `--permission` deny always takes effect even if the settings files would allow the tool. ## Configuration Files Tool permissions are configured in `settings.json`. The Auggie CLI and Cosmos cloud agents read these files: | File | Scope | | :- | :- | | `/etc/augment/settings.json` (`C:\ProgramData\augment\settings.json` on Windows) | Managed settings set by an administrator. | | `.augment/settings.local.json` | Personal project settings that are not committed. | | `.augment/settings.json` | Repo-level settings committed to the project, applied to any agent running in that repo. | | `~/.augment/settings.json` | Personal settings that apply to all your projects (user/home). | Run `/permissions` in interactive mode to see the active rules from every source and to add, edit, or remove rules. Cosmos cloud agents read both files at agent startup. Committing a `.augment/settings.json` to your repository is the recommended way to enforce an organizational policy (for example, blocking `git merge`) on every cloud agent that runs there. ## Basic Configuration ### Creating Rules Rules define permissions for specific tools. Each rule can specify: * **Tool name** - The specific tool to control * **Permission type** - `allow` or `deny` * **Optional patterns** - For shell commands, use regex matching ### Basic Rule Structure ```json theme={null} { "toolPermissions": [ { "toolName": "bash", "permission": { "type": "deny" } }, { "toolName": "read", "permission": { "type": "allow" } } ] } ``` > [!WARNING] > > `permission` must be an **object** with a `type` field — `{ "type": "deny" }`, **not** the bare string `"deny"`. A rule with a bare-string permission is malformed and is dropped. As of the latest version, a dropped rule also emits a warning at startup so the misconfiguration is visible instead of failing silently. > > ```json theme={null} > // ✅ Correct > { "toolName": "bash", "permission": { "type": "deny" } } > > // ❌ Wrong — dropped (and warned) at load time > { "toolName": "bash", "permission": "deny" } > ``` ### Allow List Configuration Create an explicit allow list by only allowing specific tools: ```json theme={null} { "toolPermissions": [ { "toolName": "read", "permission": { "type": "allow" } }, { "toolName": "web-search", "permission": { "type": "allow" } }, { "toolName": "web-fetch", "permission": { "type": "allow" } } ] } ``` > [!NOTE] > > This configuration explicitly allows only the listed tools. Tools not in this list will follow the CLI's implicit behavior. ### Block List Configuration Create a block list by explicitly denying specific dangerous tools: ```json theme={null} { "toolPermissions": [ { "toolName": "write", "permission": { "type": "deny" } }, { "toolName": "edit", "permission": { "type": "deny" } }, { "toolName": "bash", "shellInputRegex": "^(rm|sudo|shutdown|reboot)", "permission": { "type": "deny" } } ] } ``` > [!NOTE] > > This configuration blocks specific dangerous operations. Tools not explicitly denied will follow the CLI's implicit behavior. ### Mix and Match Configuration Combine allow and deny rules for fine-grained control: ```json theme={null} { "toolPermissions": [ { "toolName": "read", "permission": { "type": "allow" } }, { "toolName": "edit", "permission": { "type": "allow" } }, { "toolName": "write", "permission": { "type": "deny" } }, { "toolName": "bash", "shellInputRegex": "^(npm test|npm run lint|git status|git diff)", "permission": { "type": "allow" } }, { "toolName": "bash", "shellInputRegex": "^(rm -rf|sudo|chmod 777)", "permission": { "type": "deny" } }, { "toolName": "bash", "permission": { "type": "deny" } } ] } ``` This configuration provides fine-grained control with different permission levels based on tool risk and usage patterns. ## Available Tools ### Shell | Tool | Description | | :- | :- | | `bash` | Execute shell commands. Takes a `command` input and is matched by `shellInputRegex` against that command. | > [!NOTE] > > The shell is exposed as a single tool, **`bash`**. A rule on `bash` gates all shell commands. ### File Operations | Tool | Description | | :- | :- | | `read` | Read file contents | | `edit` | Edit files with find/replace | | `write` | Create or overwrite files | | `grep` | Search file contents with regex patterns | | `find` | Find files matching glob patterns | | `ls` | List directory contents | ### Web | Tool | Description | | :- | :- | | `web-search` | Web search queries | | `web-fetch` | Fetch web page content | ### MCP Server Tools MCP tools follow the pattern `{tool-name}_{server-name}`: * Example: `query_database-mcp` * Truncated to 64 characters if longer * Treated like any other tool for permissions ## Migrating from legacy tool names Older configurations may use legacy tool names. They still work — the legacy names are aliased to their current equivalents — but use the current names below. | Legacy name | Current name | Description | | :- | :- | :- | | `launch-process`, `shell` | `bash` | Execute shell commands | | `view` | `read` | Read file contents | | `str-replace-editor`, `str_replace_editor` | `edit` | Edit files with find/replace | | `save-file`, `save_file` | `write` | Create or overwrite files | | `grep-search` | `grep` | Search file contents | > [!WARNING] > > Only the legacy names in this table are recognized by permission rules. Other legacy names, such as `read_file`, `launch_process`, or `file_search`, are not matched, so a rule using them will not apply. ## Advanced Rules ### Shell Command Filtering Control which shell commands can be executed using regex patterns: ```json theme={null} { "toolPermissions": [ { "toolName": "bash", "shellInputRegex": "^(ls|pwd|echo|cat|grep)\\s", "permission": { "type": "allow" } }, { "toolName": "bash", "permission": { "type": "deny" } } ] } ``` This configuration: 1. Allows only safe commands (ls, pwd, echo, cat, grep) 2. Denies all other shell commands 3. Rules are evaluated in order - first match wins ### Blocking a Specific Command (e.g. `git merge`) To hard-block a single command such as `git merge` — a common enterprise policy for Cosmos cloud agents — deny it on the `bash` tool with a `shellInputRegex`: ```json theme={null} { "toolPermissions": [ { "toolName": "bash", "shellInputRegex": "\\bgit\\s+merge(\\s|$)", "permission": { "type": "deny" } } ] } ``` Commit this to `.augment/settings.json` in the repository to enforce it on every Cosmos cloud agent that runs there. The trailing `(\s|$)` ensures only the `git merge` subcommand is matched and not related subcommands like `git merge-base`: a plain `\bgit\s+merge\b` would still match `git merge-base`, because `-` is a non-word character and `\b` is satisfied at the `merge`/`-` boundary. Requiring whitespace or end-of-input after `merge` blocks `git merge` and `git merge main` while leaving `git merge-base` allowed. ### Event-Based Permissions Control when permission checks occur: ```json theme={null} { "toolPermissions": [ { "toolName": "web-fetch", "eventType": "tool-response", "permission": { "type": "allow" } } ] } ``` **Event types:** * **`tool-call`** (default) - Check before tool execution * **`tool-response`** - Check after execution but before returning results to agent ## Common Configurations ### Read-Only Mode Allow only read operations, perfect for code review and analysis: ```json theme={null} { "toolPermissions": [ { "toolName": "read", "permission": { "type": "allow" } }, { "toolName": "web-search", "permission": { "type": "allow" } }, { "toolName": "web-fetch", "permission": { "type": "allow" } }, { "toolName": "edit", "permission": { "type": "deny" } }, { "toolName": "write", "permission": { "type": "deny" } }, { "toolName": "bash", "permission": { "type": "deny" } } ] } ``` ### Development Mode Deny potentially dangerous operations while allowing the rest: ```json theme={null} { "toolPermissions": [ { "toolName": "bash", "shellInputRegex": "^(rm|sudo|chmod)\\s", "permission": { "type": "deny" } } ] } ``` ### CI/CD Pipeline Restrictive settings for automated workflows: ```json theme={null} { "toolPermissions": [ { "toolName": "read", "permission": { "type": "allow" } }, { "toolName": "edit", "permission": { "type": "allow" } }, { "toolName": "write", "permission": { "type": "allow" } }, { "toolName": "bash", "shellInputRegex": "^(npm test|npm run lint|jest)\\s", "permission": { "type": "allow" } }, { "toolName": "bash", "permission": { "type": "deny" } } ] } ``` ## Custom Policies ### Webhook Validation Use external services to validate tool requests: ```json theme={null} { "toolPermissions": [ { "toolName": "bash", "permission": { "type": "webhook-policy", "webhookUrl": "https://api.company.com/validate-tool" } } ] } ``` The webhook receives a POST request with the following JSON payload: ```json theme={null} { "tool-name": "bash", "event-type": "tool-call", "details": { /* tool-specific data, see below */ }, "timestamp": "2025-01-01T02:41:40.580Z" } ``` **Payload fields:** * **`tool-name`**: The name of the tool being invoked * **`event-type`**: Either `"tool-call"` (before execution) or `"tool-response"` (after execution) * **`details`**: Tool-specific data (for `tool-call`) or response data (for `tool-response`) * **`timestamp`**: ISO 8601 timestamp of the request **Details for `tool-call` event type:** the tool's input arguments. For example: | Tool | Details Fields | | :- | :- | | `bash` | `command`, `timeout` | | `read` | `path`, `offset`, `limit` | | `edit` | `path`, `edits` (a list of `oldText` and `newText` pairs) | | `write` | `path`, `content` | | `web-fetch` | `url` | **Details for `tool-response` event type:** ```json theme={null} { "text": "Tool output text", "isError": false } ``` **Expected response:** ```json theme={null} { "allow": true, "output": "Optional message to include in agent response" } ``` ### Script Validation Use local scripts for complex validation logic: ```json theme={null} { "toolPermissions": [ { "toolName": "bash", "permission": { "type": "script-policy", "script": "/path/to/validate-command.sh" } } ] } ``` The script receives the same JSON payload as webhooks via **stdin**: ```json theme={null} { "tool-name": "bash", "event-type": "tool-call", "details": { "cwd": "/path/to/workspace", "command": "npm install express" }, "timestamp": "2025-01-01T02:41:40.580Z" } ``` **Script behavior:** * **Exit code 0**: Allow the tool execution * **Non-zero exit code**: Deny the tool execution * **stdout/stderr**: Optional message included in the agent response **Example script:** ```bash theme={null} #!/bin/bash # Read JSON payload from stdin payload=$(cat) # Extract command using jq command=$(echo "$payload" | jq -r '.details.command // empty') # Deny dangerous commands if [[ "$command" == *"rm -rf"* ]] || [[ "$command" == *"sudo"* ]]; then echo "Dangerous command blocked: $command" exit 1 fi # Allow all other commands exit 0 ``` ## Best Practices 1. **Be Explicit**: Define clear rules for all tools you want to control 2. **Test Configurations**: Verify permissions work as expected before automation 3. **Log Decisions**: Monitor which tools are being allowed/denied for audit trails 4. **Regular Reviews**: Periodically review and update permission rules 5. **Order Matters**: Remember that rules are evaluated top-down, first match wins ## Troubleshooting **MCP Tools Not Recognized:** * Ensure MCP server name follows `{tool}_{server}` pattern * Check for 64-character truncation on long names * Verify MCP server is properly configured and running ## Security Considerations * **Never commit sensitive webhook URLs** to version control * **Use `.augment/settings.local.json`** for personal security overrides * **Regularly audit** tool usage in production environments * **Implement defense in depth** with multiple permission layers * **Test permission changes** in isolated environments first ## Related Features * [Authentication](/cli/setup-auggie/authentication) - Secure access to Auggie * [Custom Rules](/cli/rules) - Project-specific guidelines * [MCP Integrations](/cli/integrations) - External tool configuration * [Automation](/cli/automation) - Using permissions in CI/CD # Plugins and Marketplaces Source: https://docs.augmentcode.com/cli/plugins Manage and install plugins from marketplaces to extend Auggie's capabilities You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/plugins) . ## About Plugins Auggie supports a plugin system that allows you to extend its functionality with custom commands, subagents, hooks, skills, and MCP server integrations. Plugins are distributed through **marketplaces** - Git repositories that contain collections of plugins. ## Interactive Plugin Browser The easiest way to manage plugins is through the interactive plugin browser in Auggie's TUI (Terminal User Interface). ### Opening the Plugin Browser In interactive mode, use the `/plugins` slash command to open the plugin browser: ```sh theme={null} # Start Auggie in interactive mode auggie # Then type: /plugins ``` ### Plugin Browser Features The plugin browser has three tabs. Press `Tab` or the left and right arrow keys to switch tabs, and type to filter. **Plugins Tab** * View available plugins from your installed marketplaces * Press `Space` to enable or disable a plugin * Press `Enter` to see plugin details, including whether it's enabled and any problems loading it **Marketplace Tab** * View installed plugin marketplaces * Add new marketplaces from GitHub repositories * Browse plugins within each marketplace **Errors Tab** * View problems found while loading marketplaces and plugins ## Plugin Settings Reference ### enabledPlugins Controls which plugins are enabled. This setting is a record mapping plugin IDs to boolean values. * **Type**: `Record` * **Default**: `{}` * **File**: Any settings file (user, project, or local) Example: ```json theme={null} { "enabledPlugins": { "my-plugin@my-marketplace": true, "another-plugin@my-marketplace": false } } ``` ## CLI Commands ```sh theme={null} # Add a marketplace auggie plugin marketplace add owner/repo # Load plugins from a local marketplace directory for one run auggie --plugin-dir /path/to/marketplace ``` Use `/plugins` in interactive mode to enable, disable, and inspect plugins. ## The .augment-plugin Folder The `.augment-plugin` folder is the core configuration directory for Auggie plugins and marketplaces. This folder contains manifest files that define the plugin or marketplace metadata and structure. > [!NOTE] > > `.claude-plugin` is also supported for backwards compatibility with Claude Code plugins. See the [Compatibility with .claude-plugin](#compatibility-with-claude-plugin) section for more details. ### Marketplace Manifest (marketplace.json) The `marketplace.json` file defines your marketplace and lists all available plugins for discovery: ```json theme={null} { "name": "my-marketplace", "description": "A collection of useful Auggie plugins", "version": "1.0.0", "plugins": [ { "name": "hello-commands", "description": "Example slash commands", "version": "1.0.0", "source": "./plugins/hello-commands", "category": "productivity", "tags": ["commands", "example"] }, { "name": "code-guard", "description": "Security-focused hooks", "version": "1.0.0", "source": "./plugins/code-guard", "category": "security", "tags": ["hooks", "security"] } ] } ``` ## Plugin Components Plugins can provide multiple types of components: ### Custom Commands Slash commands are Markdown files in the `commands/` directory. The command name combines the plugin name, marketplace name, and filename. For example, `hello.md` in the `hello-commands` plugin from `my-marketplace` creates `/hello-commands--my-marketplace:hello`: ```markdown theme={null} --- description: Greet the user --- Say hello to the user in a friendly way. Ask them how their day is going. ``` ### Subagents Specialized agents in the `agents/` directory that Auggie can invoke for specific tasks: ```markdown theme={null} --- description: A refactoring specialist color: yellow --- # Refactor Agent You are an expert at code refactoring. When invoked, analyze the code and suggest improvements for readability, maintainability, and performance. ``` ### Hooks Event handlers that respond to Auggie events. Configure in `hooks/hooks.json`: ```json theme={null} { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "${AUGMENT_PLUGIN_ROOT}/hooks/format.sh $FILE" } ] } ] } } ``` ### MCP Servers Model Context Protocol integrations defined in `.mcp.json` or within `plugin.json`: ```json theme={null} { "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } } } ``` ### Skills Agent Skills in the `skills/` directory that extend Auggie's capabilities: ``` skills/ └── pdf-processor/ ├── SKILL.md └── scripts/ └── process.py ``` ## Compatibility with .claude-plugin Auggie's plugin system is designed to be **backwards compatible with Claude Code's `.claude-plugin` format**. This means: 1. **Directory Recognition**: Auggie recognizes both `.augment-plugin` and `.claude-plugin` directories 2. **Manifest Format**: The `plugin.json` schema is compatible between both systems 3. **Component Structure**: Commands, agents, hooks, MCP servers, and skills use the same directory layout 4. **Easy Migration**: Existing Claude Code plugins work with Auggie with minimal or no changes ### Using Claude Code Plugins If you have an existing Claude Code plugin with a `.claude-plugin` folder, Auggie can use it directly: ```sh theme={null} # Install from a marketplace containing Claude Code plugins auggie plugin marketplace add anthropics/skills # Then enable the plugin from /plugins in interactive mode ``` ### Creating Compatible Plugins To create plugins that work with both Auggie and Claude Code: 1. Use `.augment-plugin` as the primary configuration folder (Auggie will also check for `.claude-plugin`) 2. Follow the same manifest schema for `plugin.json` 3. Use the same directory structure for commands, agents, hooks, etc. ## Creating a Marketplace A marketplace is a GitHub repository that hosts one or more plugins. Anyone can create and share their own marketplace. ### Marketplace Structure ``` my-marketplace/ ├── .augment-plugin/ │ └── marketplace.json ├── plugins/ │ ├── hello-commands/ │ │ ├── .augment-plugin/ │ │ │ └── plugin.json │ │ └── commands/ │ │ └── hello.md │ ├── code-guard/ │ │ ├── .augment-plugin/ │ │ │ └── plugin.json │ │ └── hooks/ │ │ ├── hooks.json │ │ └── check.py │ └── full-example/ │ ├── .augment-plugin/ │ │ └── plugin.json │ ├── commands/ │ ├── agents/ │ ├── skills/ │ ├── hooks/ │ └── .mcp.json └── README.md ``` ## Hosting a Marketplace on GitHub To share your marketplace publicly, host it on GitHub: ### Step 1: Create the Repository 1. Create a new public GitHub repository 2. Add your marketplace structure with `.augment-plugin/marketplace.json` 3. Add your plugins in the `plugins/` directory ### Step 2: Add Plugin Manifests Each plugin needs its own `.augment-plugin/plugin.json`: ```json theme={null} { "name": "my-plugin", "description": "What this plugin does", "version": "1.0.0", "author": { "name": "Your Name" }, "keywords": ["productivity", "tools"] } ``` ### Step 3: Add a README Create a README.md to help users discover and understand your plugins: ```markdown theme={null} # My Plugin Marketplace A collection of plugins for Auggie. ## Installation \`\`\`sh auggie plugin marketplace add yourusername/your-repo \`\`\` ## Available Plugins - **hello-commands**: Simple greeting commands - **code-guard**: Security validation hooks ``` ### Step 4: Publish and Share 1. Push your code to GitHub 2. Share the repository path with users 3. Users can add your marketplace with: ```sh theme={null} auggie plugin marketplace add yourusername/your-repo ``` ### Example: Complete Marketplace Repository See [justinxu421/auggie-plugin](https://github.com/justinxu421/auggie-plugin) for a complete example marketplace with: * Multiple plugins demonstrating different capabilities * Commands, hooks, agents, and MCP server configurations * Proper manifest files and documentation To try this example: ```sh theme={null} # Add the example marketplace auggie plugin marketplace add justinxu421/auggie-plugin # Then run /plugins in interactive mode to enable full-example ``` ## Environment Variables Plugins can use these environment variables in their configurations: | Variable | Description | | :- | :- | | `${AUGMENT_PLUGIN_ROOT}` | Path to the plugin's root directory | | `${AUGGIE_PLUGIN_ROOT}` | Alias for `AUGMENT_PLUGIN_ROOT` | | `${CLAUDE_PLUGIN_ROOT}` | Alias for `AUGMENT_PLUGIN_ROOT` (for Claude Code compatibility) | These variables are supported in: * **Hook commands** (`hooks/hooks.json`) Example usage in `hooks/hooks.json`: ```json theme={null} { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "${AUGMENT_PLUGIN_ROOT}/hooks/format.sh $FILE" } ] } ] } } ``` ## Best Practices ### For Plugin Authors 1. **Use semantic versioning** for your plugin versions 2. **Add descriptive metadata** in your manifest files 3. **Include a README** with installation and usage instructions 4. **Test locally** before publishing using `--plugin-dir`: ```sh theme={null} auggie --plugin-dir ./my-plugin ``` ### For Marketplace Maintainers 1. **Organize plugins by category** in your marketplace 2. **Use tags** to help users discover plugins 3. **Keep the marketplace updated** by pulling the latest changes 4. **Document each plugin** with clear descriptions ## See Also * [Custom Commands](/cli/custom-commands) - Create reusable command templates * [Subagents](/cli/subagents) - Create specialized agents * [Hooks](/cli/hooks) - Automate actions with event hooks * [Integrations](/cli/integrations) - Connect external tools and services * [Interactive Mode](/cli/interactive) - Learn about Auggie's TUI features # Rules & Guidelines Source: https://docs.augmentcode.com/cli/rules Configure custom rules and guidelines to provide context-aware assistance in Auggie CLI. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/rules) . ## Overview Auggie automatically loads custom rules and guidelines from several file locations to provide context-aware assistance. These files help Auggie understand your project's conventions, coding standards, and preferences. > [!NOTE] > > The Auggie CLI uses the same rules system as the VSCode and JetBrains IDE extensions. For more information on IDE specific features like user guidelines, see [Rules & Guidelines for Agent and Chat](/setup-augment/guidelines). > [!NOTE] > > Looking for specialized domain knowledge? Check out [Skills](/cli/skills) - a standardized way to provide framework-specific guidance, tool usage patterns, and workflow procedures following the agentskills.io specification. ## Supported Rules Files Auggie loads rules from these locations: 1. **Custom rules** (via the `--rule` flag): a file or directory 2. **Workspace rules folder**: `/.augment/rules/` - Recursively searches `.md` and `.mdc` files 3. **User rules folder**: `~/.augment/rules/` - Recursively searches `.md` and `.mdc` files for user-wide rules 4. **AGENTS.md or CLAUDE.md**: Loaded from the current directory and every parent directory. In each directory, Auggie loads `AGENTS.md` if it exists and otherwise `CLAUDE.md` 5. **Workspace guidelines**: `/.augment-guidelines` Run `/rules` in interactive mode to see which rules are loaded and their types. Use `--no-rules` to turn off rule discovery. ### System prompt files Two more files change the system prompt itself: | File | Effect | | :- | :- | | `.augment/APPEND_SYSTEM.md` or `~/.augment/APPEND_SYSTEM.md` | Appended to Auggie's default system prompt | | `.augment/SYSTEM.md` or `~/.augment/SYSTEM.md` | Replaces Auggie's default system prompt | The project file is used when it exists; otherwise the user file is used. Rules and `AGENTS.md` files are still added when you use `SYSTEM.md`. > [!WARNING] > > `SYSTEM.md` replaces the built-in instructions Auggie relies on to use its tools well. Prefer `APPEND_SYSTEM.md` or rules unless you need full control. ### User Rules vs Workspace Rules Rules can be defined at two levels: | Scope | Location | Availability | | :- | :- | :- | | User | `~/.augment/rules/` | Available in all workspaces | | Workspace | `/.augment/rules/` | Available in current workspace only | **User rules** are stored in your home directory and apply to all projects. Use these for personal preferences, coding style guidelines, or conventions you want to follow across all your work. User rules are always treated as `always_apply` type and are automatically included in every prompt regardless of any frontmatter configuration. **Workspace rules** are stored in the project repository and apply only to that specific project. Use these for project-specific guidelines that should be shared with your team via version control. ## Rules File Format Rules files should be written in Markdown format with natural language instructions. Here's the recommended structure: ```markdown theme={null} # Project Guidelines ## Code Style - Use TypeScript for all new JavaScript files - Follow the existing naming conventions in the codebase - Add JSDoc comments for all public functions and classes ## Architecture - Follow the MVC pattern established in the codebase - Place business logic in service classes - Keep controllers thin and focused on request/response handling ## Testing - Write unit tests for all new functions - Maintain test coverage above 80% - Use Jest for testing framework ## Dependencies - Prefer built-in Node.js modules when possible - Use npm for package management - Pin exact versions in package.json for production dependencies ``` ## Frontmatter Configuration for Rules Rules files in the `/.augment/rules/` (workspace) directory support frontmatter to configure their behavior. Use YAML frontmatter at the beginning of your rule file to specify how the rule should be applied: > [!NOTE] > > User rules in `~/.augment/rules/` are always treated as `always_apply` and do not support other frontmatter types. Frontmatter configuration only affects workspace rules. | Frontmatter Field | Purpose | Options | Default | | :- | :- | :- | :- | | `type` | Controls when the rule is applied | `always_apply`, `agent_requested`, `manual` | `always_apply` | | `description` | Brief description of the rule's purpose (required for `agent_requested` type) | Any text | None | **Rule Types:** * **`always_apply`**: Rule contents are automatically included in every user prompt * **`agent_requested`**: Rule is automatically detected and attached based on the description field when relevant * **`manual`**: Rule is attached only when you reference it in a message as `$rule-name` ### Manual rules To attach a manual rule, type `$` followed by the rule name in your message. Interactive mode suggests manual rules as you type. For a rule in a subfolder, include the folder, for example `$frontend/react`. If the name has spaces, quote it: `$"my rule"`. ```text theme={null} Review this change and apply $security-review ``` > [!NOTE] > > User rules in `~/.augment/rules/` are always treated as `always_apply` regardless of frontmatter. **Terminology mapping (CLI ↔ IDE extensions):** | CLI (frontmatter `type`) | IDE display name | Behavior | | :- | :- | :- | | `always_apply` | Always | Included in every prompt | | `agent_requested` | Auto | Attached automatically when the agent decides the rule is relevant (based on `description`) | | `manual` | Manual | Attached on demand: `$rule-name` in the CLI, @ mention in the IDE | Use `agent_requested` over `always_apply` if you want to optimize context usage. For these rules, the agent will determine the rule is relevant to your current task, ensuring specialized guidelines are available when needed. **Example with frontmatter:** ```markdown theme={null} --- type: always_apply --- # TypeScript Guidelines - Use strict mode in all TypeScript files - Define explicit return types for all functions - Avoid using `any` type unless absolutely necessary ``` **Agent-requested example:** ```markdown theme={null} --- type: agent_requested description: React component development patterns and best practices --- # React Component Guidelines - Use functional components with hooks - Implement proper TypeScript interfaces for props - Follow the established folder structure in src/components/ ``` ## Hierarchical Rules In addition to workspace-level rules, the agent supports **hierarchical rules** through `AGENTS.md` and `CLAUDE.md` files placed in subdirectories. When working on files in a subdirectory, Augment automatically discovers and applies rule files from that directory and all parent directories. ### How Hierarchical Rules Work 1. When the agent reads, edits, or writes a file, Auggie looks for `AGENTS.md` or `CLAUDE.md` in the file's directory 2. It then walks up the directory tree, checking each parent directory up to the workspace root 3. Newly discovered files are added to the context for the rest of the session ### Example Directory Structure ``` my-project/ AGENTS.md <- Always included (workspace root) src/ AGENTS.md <- Included when working in src/ or subdirectories frontend/ AGENTS.md <- Included when working in src/frontend/ App.tsx backend/ AGENTS.md <- Included when working in src/backend/ server.ts tests/ AGENTS.md <- Only included when working in tests/ ``` When working on `src/frontend/App.tsx`: * `src/frontend/AGENTS.md` is loaded (current directory) * `src/AGENTS.md` is loaded (parent directory) * `AGENTS.md` at workspace root is loaded via standard rules * `src/backend/AGENTS.md` and `tests/AGENTS.md` are **not** loaded (different branches) ### Use Cases for Hierarchical Rules * **Framework-specific guidelines**: Place React-specific rules in your frontend directory and Node.js rules in your backend directory * **Module-specific conventions**: Define API design patterns in your `api/` directory * **Test-specific rules**: Add testing conventions that only apply when writing tests * **Team boundaries**: Different teams can maintain their own coding standards in their directories ### Important Notes * Only `AGENTS.md` and `CLAUDE.md` files are discovered hierarchically. If a directory has both, only `AGENTS.md` is used * Files in `.augment/rules/` are only loaded from the workspace root, not from subdirectories * Rules are cached per conversation session to avoid duplicate inclusion * Hierarchical rules are combined with workspace and user rules ## Best Practices for Rules Files 1. **Be Specific**: Provide clear, actionable guidelines rather than vague suggestions 2. **Use Examples**: Include code examples when describing patterns or conventions 3. **Keep Updated**: Regularly review and update rules as your project evolves 4. **Be Concise**: Focus on the most important guidelines to avoid overwhelming the AI 5. **Test Guidelines**: Verify that Auggie follows your rules by testing with sample requests ## Command-Line Flag You can load extra rules when starting Auggie. Pass a file or a directory, and repeat the flag to add more: ```bash theme={null} auggie --rule /path/to/custom-rules.md --rule /path/to/team-rules/ ``` Rules loaded this way are always applied, in addition to the rules Auggie discovers automatically. ## See Also * [Skills](/cli/skills) - Extend capabilities with specialized domain knowledge * [Rules & Guidelines for Agent and Chat](/setup-augment/guidelines) - Configure rules in VSCode and JetBrains IDEs * [CLI Reference](/cli/reference) - Complete command-line reference * [Workspace Context](/cli/setup-auggie/workspace-context) - Understanding workspace configuration * [Custom Commands](/cli/custom-commands) - Create reusable command templates # Settings Source: https://docs.augmentcode.com/cli/settings Configure Auggie CLI with the /settings menu or by editing settings.json. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/config) . ## The `/settings` menu The `/settings` slash command opens an interactive menu for common options. It replaces the `/config` command from Auggie 0.x. ```sh theme={null} # Start Auggie in interactive mode auggie # Then type the slash command /settings ``` Type to filter the list, use the arrow keys to move, and press `Enter` to change a value. Press `Escape` to go back. Changes made in `/settings` are always saved to your user settings file, `~/.augment/settings.json` (`C:\Users\\.augment\settings.json` on Windows). Auggie 1.x does not prompt you to choose a settings file. To change project or local settings, edit those files directly. ### Available options #### General | Option | Setting | Description | | :- | :- | :- | | Auto-compact | `compaction.enabled` | Automatically summarize the conversation when the context window fills up | | Steering mode | `steeringMode` | Send steering messages `one-at-a-time` or `all` at once | | Follow-up mode | `followUpMode` | Send queued follow-up messages `one-at-a-time` or `all` at once | | Double-escape action | `doubleEscapeAction` | What pressing `Escape` twice does: `tree`, `fork`, or `none` | | Tree filter mode | `treeFilterMode` | Default filter for `/tree` | | Auto-resize images | `images.autoResize` | Resize images to at most 2000x2000 before sending. Images fetched by the `web-fetch` tool are always resized | | Block images | `images.blockImages` | Never send images to the model | | Skill commands | `enableSkillCommands` | Register skills as `/skill:name` commands | | MCP tool discovery | `disableToolSearch` | Turn off automatic MCP tool discovery, which hides MCP tools behind `find-tool` and `execute-tool` when their definitions take up too much context. Appears only when automatic discovery is available | #### Display These options only change how the terminal UI looks. | Option | Setting | Description | | :- | :- | :- | | Theme | `theme` | Color theme: `dark`, `light`, `ansi`, or a custom theme | | Hide thinking | `hideThinkingBlock` | Hide reasoning blocks in the transcript | | Quiet startup | `quietStartup` | Hide the startup header | | Collapse changelog | `collapseChangelog` | Show a condensed changelog after updates | | Collapse prompt commands | `collapsePromptCommands` | Show custom command invocations as a single collapsed line | | Show images | `terminal.showImages` | Render images in terminals that support it | | Show hardware cursor | `showHardwareCursor` | Show the terminal cursor | | Editor padding | `editorPaddingX` | Horizontal padding for the input editor (0-3) | | Autocomplete max items | `autocompleteMaxVisible` | Number of visible autocomplete suggestions (3-20) | | Clear on shrink | `terminal.clearOnShrink` | Clear empty rows when content shrinks | Some options only appear when the related feature is available. To change the reasoning effort, use `/effort` or press `Shift+Tab`. ### Themes Auggie 1.x ships with `dark`, `light`, and `ansi` themes. Use `ansi` if your terminal does not support true color. The legacy `default-dark` value from 0.x is treated as `dark`. ```json theme={null} { "theme": "ansi" } ``` ## Settings files Auggie reads settings from these files, from highest to lowest precedence: 1. **Managed settings** (read-only) * `/etc/augment/settings.json` on macOS and Linux * `C:\ProgramData\augment\settings.json` on Windows * Set by organization admins and cannot be overridden by users 2. **Local project settings**: `/.augment/settings.local.json` * Personal, per-project overrides that should not be committed 3. **Project settings**: `/.augment/settings.json` * Shared, per-project configuration that should be committed to source control 4. **User settings**: `~/.augment/settings.json` * Personal defaults that apply across projects, and the file `/settings` writes to Higher-precedence files override lower-precedence files. Tool permission rules from all files are combined. Some commands still write to project or local settings when you ask them to, for example `auggie mcp add --project` or `auggie mcp add --local`. See [Integrations and MCP](/cli/integrations). The files support JSON with Comments (JSONC), so comments and trailing commas are allowed. After editing a file manually, restart Auggie for the changes to take effect. ### Example settings.json ```json theme={null} { "defaultModel": "sonnet", "theme": "dark", "shellPath": "zsh", "shellCommandPrefix": "source ~/.augment/startup.sh", "notificationMode": "desktop_notification", "autoUpdate": true } ``` ### Common settings | Setting | Description | | :- | :- | | `defaultModel` | Default model for new sessions | | `defaultThinkingLevel` | Default reasoning effort: `off`, `minimal`, `low`, `medium`, `high`, or `xhigh` | | `theme` | Color theme | | `shellPath` | Shell used by the `bash` tool: a full path, or `bash`, `zsh`, `fish`, `sh`, or `powershell`. `shell` (the 0.x name) still works | | `shellCommandPrefix` | Shell code run before every `bash` tool command, for example `source ~/.augment/startup.sh`. It's shell text, not a file path. `startupScript` (the 0.x name) still works | | `notificationMode` | Notify when the agent finishes or asks a question: `off`, `bell`, or `desktop_notification` | | `autoUpdate` | Automatically update Auggie in interactive mode. See [Automatic Updates](/cli/autoupgrade) | | `updateTerminalTitle` | Set the terminal title automatically | | `verbose` | Expand tool output by default | See [Permissions](/cli/permissions) for `toolPermissions` and [Integrations and MCP](/cli/integrations) for `mcpServers`. ## Keybindings Customize keyboard shortcuts in `~/.augment/keybindings.json`, then run `/reload` to apply them. Run `/hotkeys` to see all current shortcuts. # Login and authentication Source: https://docs.augmentcode.com/cli/setup-auggie/authentication You will need an active account and valid authentication session to use Auggie CLI, which you can get by following the instructions below. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/setup-auggie/authentication) . ## About authentication Before you can use Auggie, you will need to login to create an authentication session that can be used by Auggie in both interactive and automation modes. > [!NOTE] > > Augment authentication tokens are secrets and should be protected with the same level of security you'd use for any sensitive credential. Tokens are tied to the user who logged in, not to your team or enterprise account, so each user has a unique augment token. ## Logging in You can login by running the following command and following the prompts. Use `--headless` on machines without a browser. ```sh theme={null} auggie auth login ``` You can also run `/login` from interactive mode. If you are not signed in, Auggie shows a login screen when it starts. > [!NOTE] > > In Auggie 1.x, `auggie auth login` and `auggie auth logout` are replaced by `auggie auth login` and `auggie auth logout`. ## Checking your login status ```sh theme={null} auggie auth status ``` ## Logging out You can logout by running the following command. This will remove the local token from your machine and you will need to login again to use Auggie. ```sh theme={null} auggie auth logout ``` ## Getting your session details For automation, you will need to provide authentication details each time you run Auggie. After you have logged in above, you can print your current session JSON by running the following command. ```sh theme={null} auggie token print ``` ## Using your session details After you have your session details, you can pass them to Auggie through a number of methods depending on your use case and environment. ### Environment variables You can set the `AUGMENT_SESSION_AUTH` environment variable to the session JSON before running Auggie. Pass it before you run the command, add it to your environment, or add it to your shell's rc file to persist it. ```sh theme={null} AUGMENT_SESSION_AUTH='' ``` ### Command-line flag You can pass the session JSON directly using the `--augment-session-json` flag: ```sh theme={null} auggie --augment-session-json '' ``` ## Revoking your tokens You can revoke all the tokens for the current logged in user by running the following command. Using `auggie auth logout` will only remove the local token from your machine. ```sh theme={null} auggie token revoke ``` # Install Auggie CLI Source: https://docs.augmentcode.com/cli/setup-auggie/install-auggie-cli Install Auggie to get agentic coding capabilities in your terminal, on your server, or anywhere your code runs. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/setup-auggie/install-auggie-cli) . ```sh theme={null} npm install -g @augmentcode/auggie@prerelease ``` # About installing Auggie Installing Auggie CLI is easy and will take you less than a minute. You can install Auggie CLI directly from npm anywhere you can run Node 20 or later. Many systems do not ship with the latest version of Node.js, so you may need to upgrade Node to use Auggie. ## Release channels Auggie is published to npm as `@augmentcode/auggie` under these tags: | Tag | Version | Description | | :- | :- | :- | | `prerelease` | 1.x.x | Prerelease builds of 1.x. | | `v0-release` | 0.x.x | Stable Auggie 0.x releases. | | `v0-prerelease` | 0.x.x | Prerelease builds of 0.x. | To switch back to Auggie 0.x at any time: ```sh theme={null} npm install -g @augmentcode/auggie@v0-release ``` In every channel, the command is `auggie`. ## Automatic Updates Auggie CLI automatically updates itself when running in interactive mode to ensure you always have the latest features and bug fixes. This feature is enabled by default and works seamlessly in the background. You can [disable automatic updates](/cli/autoupgrade#disabling-automatic-updates). ## System requirements * [**Node.js 20+**](https://nodejs.org/en/download/) * **Platforms**: MacOS, Windows WSL, Linux * **Shells**: zsh, bash, fish ### Interactive mode Using Auggie in interactive mode requires a terminal that supports ANSI escape codes. We recommend using Ghostty, iTerm2, MacOS Terminal, Windows Terminal, Alacritty, Kitty, and other modern terminals. If you are connecting to your shell over SSH or through tmux you may need to adjust your terminal settings or configuration to enable proper color support, font rendering, and interactivity. # Workspace context Source: https://docs.augmentcode.com/cli/setup-auggie/workspace-context Auggie will automatically index the current working directory or directory you specify to give Augment a full view of your system. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/setup-auggie/workspace-context) . ## About Workspace Context Augment is powered by its deep understanding of your code. Your codebase will be automatically indexed when you run `auggie` from a git directory or you can specify a directory to index. If you run Auggie from a non-git directory, the current working directory is used as the workspace root. ## Specifying a directory to index To specify a directory other than the current working directory pass the target directory to the `--workspace-root` flag. ```sh theme={null} auggie --workspace-root /path/to/your/project ``` To learn more about what files are indexed and how to ignore files, see [Workspace indexing](/cli/setup-auggie/workspace-indexing). # Index your workspace Source: https://docs.augmentcode.com/cli/setup-auggie/workspace-indexing When your workspace is indexed, Augment can provide tailored code suggestions and answers based on your unique codebase, best practices, coding patterns, and preferences. You can always control what files are indexed. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/setup-auggie/workspace-indexing) . ## Security and privacy Augment stores your code securely and privately to enable our powerful context engine. We ensure code privacy through a proof-of-possession API and maintain strict internal data minimization principles. [Read more about our security](https://www.augmentcode.com/security). ## What gets indexed Augment will index all the files in your workspace, except for the files that match patterns in your `.gitignore` file and the `.augmentignore` file. [Read more about Workspace Context](/cli/setup-auggie/workspace-context). ## Ignoring files with .augmentignore The `.augmentignore` file is a list of file patterns that Augment will ignore when indexing your workspace. Create an `.augmentignore` file in the root of your workspace. You can use any glob pattern that is supported by the [gitignore](https://git-scm.com/docs/gitignore) file. ## Including files that are .gitignored If you have a file or directory in your `.gitignore` that you want to be indexed, you can add it to your `.augmentignore` file using the `!` prefix. For example, you may want your `node_modules` indexed to provide Augment with context about the dependencies in their project, but it is typically included in their `.gitignore`. Add `!node_modules` to your `.augmentignore` file. ```bash .augmentignore theme={null} # Include .gitignore excluded files with ! prefix !node_modules # Exclude other files with .gitignore syntax data/test.json ``` ```bash .gitignore theme={null} # Exclude dependencies node_modules # Exclude secrets .env # Exclude build artifacts out build ``` # Agent Skills Source: https://docs.augmentcode.com/cli/skills Extend Auggie's capabilities with specialized domain knowledge using the agentskills.io specification. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/skills) . ## Overview Skills provide a standardized way to give Auggie specialized domain knowledge and capabilities. Following the [agentskills.io](https://agentskills.io) specification, skills are modular packages of guidance, resources, and context that help the agent understand specific domains or workflows. ## What are Skills? Skills are self-contained packages that provide: * **Specialized knowledge**: Domain-specific guidance and best practices * **Contextual resources**: Links to documentation, APIs, or tools * **Workflow patterns**: Step-by-step procedures for common tasks * **Tool usage guidance**: How to use specific tools or frameworks Unlike rules (which provide general guidelines), skills are designed to be: * **Discoverable**: The agent can see what skills are available through their metadata * **Modular**: Each skill is independent and can be added or removed easily * **Standardized**: Following the agentskills.io spec ensures compatibility across AI tools ## Skill File Structure Skills are defined in `SKILL.md` files located in the `.augment/skills/`, `.claude/skills/`, or `.agents/skills/` directories (in either your workspace or home directory). Each skill must be in its own subdirectory: ``` .augment/skills/ ├── python-testing/ │ └── SKILL.md ├── api-design/ │ └── SKILL.md └── database-migrations/ └── SKILL.md ``` ### SKILL.md Format Each `SKILL.md` file must include YAML frontmatter with required metadata: **Example SKILL.md file:** ```markdown theme={null} --- name: python-testing description: Best practices for writing and running Python tests with pytest --- # Python Testing Skill This skill provides guidance on writing effective Python tests. ``` The file content after the frontmatter can include: * Markdown headings and text * Code examples (using code blocks) * Lists and other markdown formatting ### Required Frontmatter Fields | Field | Description | Requirements | | :- | :- | :- | | `name` | Skill identifier | 1-64 characters, lowercase alphanumeric and hyphens only, should match directory name | | `description` | What the skill does and when to use it | 1-1024 characters, helps the agent understand when to apply the skill | ### Skill Name Requirements Per the agentskills.io specification, skill names must: * Be 1-64 characters long * Use only lowercase letters, numbers, and hyphens * Not start or end with a hyphen * Not contain consecutive hyphens * Match the directory name containing the SKILL.md file **Valid names**: `python-testing`, `api-design`, `database-migrations`\ **Invalid names**: `Python-Testing`, `api_design`, `-database`, `my--skill` ## Skill Locations Skills are discovered from these locations, in order of precedence: | Location | Source | Description | | :- | :- | :- | | `~/.augment/skills/` | User | Available in all workspaces (highest precedence) | | `/.augment/skills/` | Workspace | Project-specific skills, can be version controlled | | `~/.claude/skills/` | User | Compatible with Claude Code | | `~/.agents/skills/` | User | Industry-standard location | | `.augment/skills/`, `.claude/skills/`, `.agents/skills/` in the current directory and its parents | Workspace | Searched up to the git repository root | Skills from all locations are loaded and made available to the agent. When multiple skills with the same name exist, the skill from the higher precedence location is used. You can also load skills from other paths: * Pass `--skill ` to load a skill file or directory for one run. Repeat the flag to add more. * Add paths to the `skills` array in [`settings.json`](/cli/settings). * Use `--no-skills` to turn off discovery. Skills passed with `--skill` still load. ## Invoking Skills In interactive mode, every discovered skill is registered as a slash command named `/skill:`. If you have a skill at `.augment/skills/my-skill/SKILL.md`, run it by typing: ``` /skill:my-skill ``` Any text after the command is passed to the skill along with its instructions: ``` /skill:my-skill focus on the payments module ``` Type `/skill:` to see the available skills and their descriptions in the autocomplete list. To turn off skill commands, set `enableSkillCommands` to `false` in `settings.json`. You don't have to invoke a skill yourself. The agent sees each skill's name and description and loads the full `SKILL.md` when a task matches. ## Creating Your First Skill **1. Create the skills directory** ```bash theme={null} mkdir -p .augment/skills/my-skill ``` **2. Create the SKILL.md file** Create a file at `.augment/skills/my-skill/SKILL.md` with the following content: ```markdown theme={null} --- name: my-skill description: Custom skill for my project's specific workflow --- # My Custom Skill Add your skill content here with guidance, examples, and resources. ``` **3. Verify the skill is loaded** Start Auggie and type `/skill:` to confirm your skill appears in the list. ## Skills vs Rules While both skills and rules provide guidance to the agent, they serve different purposes: | Feature | Skills | Rules | | :- | :- | :- | | **Purpose** | Specialized domain knowledge | General coding guidelines | | **Format** | agentskills.io specification | Markdown with optional frontmatter | | **Discovery** | Metadata-based (name + description) | Content-based or always-applied | | **Scope** | Specific domains/workflows | Project-wide conventions | | **Standard** | Cross-platform (agentskills.io) | Augment-specific | Use **skills** for: * Framework-specific knowledge (e.g., React patterns, Django best practices) * Tool usage guides (e.g., Docker workflows, CI/CD procedures) * Domain expertise (e.g., security practices, performance optimization) Use **rules** for: * Code style preferences * Project architecture guidelines * Team conventions ## Best Practices 1. **Be Specific**: Focus each skill on a single domain or workflow 2. **Include Examples**: Provide concrete code examples and commands 3. **Keep Updated**: Review and update skills as tools and practices evolve 4. **Use Clear Descriptions**: Help the agent understand when to use each skill 5. **Version Control**: Commit workspace skills to share with your team ## See Also * [agentskills.io Specification](https://agentskills.io/specification) - Official skill format specification * [Example Skills](https://github.com/anthropics/skills) - Collection of example skills from Anthropic * [Rules & Guidelines](/cli/rules) - Configure general project guidelines * [CLI Reference](/cli/reference) - Complete command-line reference # Subagents Source: https://docs.augmentcode.com/cli/subagents Configure custom agents for specific tasks to automate your workflow and share them with your team. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/subagents) . Availability ## About subagents Subagents are custom agents that you can configure for specialized tasks, like code review or project bootstrapping. Each subagent has its own tools and capabilities that you can delegate specific tasks to. You can have local subagents or share them with your team by adding their configuration to your repository. * Subagents have their own context window independent from the main agent * Subagents have a custom prompt that is used to instruct the agent * Subagents run in parallel with other subagents * Subagents will show a summary of their current progress in the main thread Auggie includes three built-in agents: `general-purpose`, `explore`, and `plan`. A custom agent with the same name overrides the built-in one. ## Create a subagent You can create a new subagent through the wizard by running `/agents` command in interactive mode. Or you can create the configuration file manually. ### Create a subagent with the wizard 1. Run the `/agents` command in interactive mode 2. Select "Create new agent" 3. Select where you want the agent configuration to be stored: the project (`.augment/agents/`) or your user directory (`~/.augment/agents/`) 4. Choose a creation method: * **Generate with Auggie**: Describe what the agent should do and give it a name. Auggie writes the configuration for you. * **Manual configuration**: Enter the name, description, tools, model, thinking level, and prompt yourself. `/agents` also lists running agents and available agent types. ### Create a subagent manually You can create a subagent manually by creating a configuration file. The configuration file should be a markdown file stored in either `~/.augment/agents/` (user only) or `./.augment/agents/` (shared). See the [Subagent configuration reference](#subagent-configuration-reference) for more details. **Example subagent configuration:** ```markdown theme={null} --- name: code-review description: Code review agent model: sonnet color: purple --- You are an agentic code-review AI assistant with access to the developer's codebase through Augment's deep codebase context engine and integrations. You are conducting a comprehensive code review for the staged changes in the current working directory. ## Review Areas to focus on: - **Potential Bugs**: Identify bugs, logic errors, edge cases, crash-causing problems. - **Security Concerns**: Look for potential vulnerabilities, input validation, authentication issues ONLY if the code is security-sensitive - **Documentation**: Report comments or documentation that is incorrect or inconsistent with the code. - **API contract violations** - **Database and schema errors** - **High Value Typos**: typos that affect correctness, UX-strings, etc. ``` ## Running your subagent Once you've configured the subagent, you can trigger it by sending a message that references the agent name. Augment will also automatically detect when a task is appropriate for a subagent and offer to use it. ``` > Use the code-review agent to review my staged changes ``` ## Subagent configuration reference ### File locations Subagents are configured in markdown files with YAML frontmatter. Subagents can be configured at the user level or the workspace level. User-level subagents are available in all workspaces, while workspace-level subagents are only available in the current workspace. | Scope | Location | Availability | | :- | :- | :- | | User | `~/.augment/agents/` | Available in all workspaces | | Workspace | `./.augment/agents/` | Available in current workspace only | Workspace agents override user agents with the same name. ### Frontmatter configuration | Field | Required | Purpose | | :- | :- | :- | | `name` | No | Name of the agent. Defaults to the filename without `.md` | | `description` | No | Description of the agent, used to decide when to delegate to it | | `color` | No | Label color: `red`, `blue`, `green`, `yellow`, `orange`, `purple`, `pink`, or `cyan` | | `model` | No | Model to use for the agent. If not specified, the current model is used | | `thinking` | No | Reasoning effort for the agent's model | | `tools` | No | Built-in tools the agent can use (allowlist). See [Tool restrictions](#tool-restrictions) | | `disabled_tools` | No | Tools the agent cannot use (denylist) | | `max_turns` | No | Maximum number of turns before the agent stops | | `replace_system_prompt` | No | `true` to use the prompt body as the whole system prompt instead of appending it. Default `false` | | `skills` | No | Names of the skills to load for the agent. Defaults to all skills | | `disable_skills` | No | `true` to load no skills | | `disable_rules` | No | `true` to skip rules | | `isolation` | No | `worktree` to run the agent in a separate git worktree | | `run_in_background` | No | `true` to run the agent in the background by default | | `enabled` | No | `false` to turn the agent off without deleting the file | ### Tool restrictions You can control which tools a subagent has access to using either an **allowlist** or a **denylist**: * **`tools` (allowlist)**: Only the listed built-in tools will be available: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, and `web-fetch`. Setting `tools` also removes all other tools, such as `codebase-retrieval`, `web-search`, integrations, and MCP tools. * **`disabled_tools` (denylist)**: All tools except the listed ones will be available. This works for any tool, including MCP and integration tools. **Important notes:** * If both are specified, a tool must be in `tools` and not in `disabled_tools`. * If neither is specified, the subagent has access to all tools the main agent has. * To keep `codebase-retrieval` or other non-built-in tools, use `disabled_tools` instead of `tools`. Tool restrictions are useful for: * **Security**: Preventing a subagent from modifying files or running commands * **Focus**: Giving a subagent only the tools it needs for its specific task * **Safety**: Preventing subagents from performing destructive operations **Common tool names:** * `read` - Read files * `grep` - Search file contents * `find` - Find files by glob * `codebase-retrieval` - Search the codebase * `edit` - Edit existing files * `write` - Create new files * `bash` - Run shell commands * `github-api` - Interact with GitHub * `web-fetch` - Fetch web content * `web-search` - Search the web **Example with YAML list format:** ```yaml theme={null} --- name: safe-reader description: A safe file reader that cannot modify or execute disabled_tools: - edit - write - bash --- ``` **Example with comma-separated format:** ```yaml theme={null} --- name: explorer description: A read-only explorer that can only search and view code tools: read, grep, find, ls --- ``` ### Supported models Subagents can use any model available in Auggie. To see a list of available models, run the following command: ```bash theme={null} auggie model list ``` Use a model name or part of one, such as `sonnet` or `opus`. Auggie picks the closest matching model. > [!NOTE] > > Model availability may vary depending on your Augment subscription and organization settings. ### Agent prompt The agent prompt is the main body of the markdown file. The prompt is used to instruct the agent on its role and capabilities. The prompt can include any information that you want to be available to the agent, including specific tools or instructions. The prompt is rendered as markdown and supports code blocks, lists, and other formatting. ## Best practices for subagents * **Subagents are most effective when they have a specific and focused task.** It is better to create multiple subagents for different tasks rather than trying to create a single agent for multi-step, long-running, or complex tasks. * **Subagents should have a detailed prompt**. The prompt should clearly define the agent's role, capabilities, and expected behavior. Include specific instructions, task lists, examples, and expected output. Take advantage of markdown formatting to make the prompt as clear as possible. * **Share your subagents with your team**. Subagents are a great way to share custom workflows with your team. Store your subagents in your projects `./.augment/agents/` directory to make them available to everyone. ## Example subagents ### Code review agent ```markdown theme={null} --- name: code-review description: Code review agent model: sonnet color: purple --- You are an agentic code-review AI assistant with access to the developer's codebase through Augment's deep codebase context engine and integrations. You are conducting a comprehensive code review for the staged changes in the current working directory. Review Areas to focus on: - **Potential Bugs**: Identify bugs, logic errors, edge cases, crash-causing problems. - **Security Concerns**: Look for potential vulnerabilities, input validation, authentication issues ONLY if the code is security-sensitive - **Documentation**: Report comments or documentation that is incorrect or inconsistent with the code. - **API contract violations** - **Database and schema errors** - **High Value Typos**: typos that affect correctness, UX-strings, etc. Review Areas to avoid: - **Style nags**: e.g. prefer `const` over `let`, prefer template strings, etc. - **Opinionated suggestions**: e.g. prefer `map` over `forEach`, etc. - **Low value typos**: e.g. spelling errors in comments, etc. ``` ### Read-only code reviewer (with tool restrictions) This example shows how to create a code review agent that can examine code but cannot make modifications: ```markdown theme={null} --- name: read-only-reviewer description: A read-only code reviewer that cannot modify files model: sonnet color: orange disabled_tools: edit, write, bash --- You are a read-only code review agent. You can examine code and provide feedback, but you cannot make any modifications to files. Review the code and provide feedback on: - Code quality and best practices - Potential bugs and issues - Suggestions for improvement ``` ### Test generation agent ```markdown theme={null} --- name: test-generation description: Generates and runs tests for new or modified code model: sonnet color: green --- You are an agentic test generation AI assistant. You are responsible for writing thorough and high quality automated tests for this software project. You have access to the codebase through Augment's deep codebase context engine and integrations, and are able to run commands through the terminal. Your goals: 1. Analyze recent code changes or diffs to identify new or modified functions, classes, or modules. 2. Determine which parts of the changes are missing test coverage. 3. Generate clear, idiomatic unit or integration tests using the project's existing testing framework and conventions. 4. Write test files or append tests to existing files in appropriate locations. 5. Run the test suite and summarize results, including: - Number of tests added or updated - Any failures or skipped tests - Edge cases or scenarios still untested 6. If a test fails immediately, analyze the likely cause and propose fixes or clarifications. Guidelines: - Favor readability, determinism, and minimal mocking. - Reuse existing helper utilities and fixtures if present. - Match the naming conventions and import patterns found in the repository. - Always include at least one negative test (an example where the function should fail). ``` ### API designer agent ```markdown theme={null} --- name: api-designer description: Use for designing REST/GraphQL APIs, OpenAPI specs, and API documentation model: sonnet color: blue --- You are an API design specialist focused on creating well-structured, intuitive, and maintainable APIs. You are responsible for designing and documenting APIs for this software project. You have access to the codebase through Augment's deep codebase context engine and integrations, and are able to run commands through the terminal. ## Design Principles - Use consistent naming conventions (plural nouns for resources) - Implement proper HTTP methods and status codes - Design for idempotency where appropriate - Include pagination for list endpoints - Provide filtering, sorting, and field selection - Follow HATEOAS principles for discoverability - Implement rate limiting considerations ## API Patterns **REST Best Practices:** - `/api/v1/resources` - Collection endpoint - `/api/v1/resources/{id}` - Single resource - `/api/v1/resources/{id}/relationships` - Nested resources - Use query params for filtering: `?status=active&sort=-created_at` **Error Responses:** - Return consistent error format with code, message, details - Use appropriate HTTP status codes (400, 401, 404, 422, 500) ## Documentation Style - Generate or update OpenAPI 3.0+ spec - Include examples for all endpoints ``` # What's new in Auggie 1.x Source: https://docs.augmentcode.com/cli/whats-new New features, breaking changes, and migration notes for upgrading from Auggie 0.x to 1.x. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/overview) . Auggie 1.x is a major rewrite of the Auggie CLI. It is a prerelease and is published under the `prerelease` tag on npm. ```sh theme={null} # Install the 1.x prerelease npm install -g @augmentcode/auggie@prerelease # Switch back to 0.x npm install -g @augmentcode/auggie@v0-release ``` ## New features * **Faster terminal UI**: A new renderer keeps scrolling and streaming smooth, and every menu supports type-to-filter. * **Reasoning effort**: Use `/effort`, press `Shift+Tab`, or press `Tab` in `/model` to change how much a reasoning model thinks. Your choice is remembered per model. * **Compaction**: Auggie summarizes the conversation automatically before it runs out of context. Run `/compact` to summarize on demand. * **Session tree**: `/tree` shows conversation branches and lets you jump between them. * **Git worktrees**: `/worktree` creates, switches, and deletes git worktrees from inside Auggie. * **Export and import**: `/export` saves a session as HTML or JSONL, and `/import` resumes a session from a JSONL file. * **Permissions manager**: `/permissions` shows active rules from every source and lets you add, edit, or remove rules in place. * **Custom keybindings**: Configure shortcuts in `~/.augment/keybindings.json` and apply them with `/reload`. Run `/hotkeys` to see all shortcuts. * **Themes**: Choose `dark`, `light`, `ansi`, or a custom theme in `/settings`. * **Manual rules**: Attach a rule on demand by typing `$rule-name` in a message. See [Rules](/cli/rules#manual-rules). * **New hook events**: `PromptSubmit` and `Notification` hooks. See [Hooks](/cli/hooks). ## Breaking changes ### `/config` is now `/settings` The `/config` slash command is replaced by [`/settings`](/cli/settings). Changes made in `/settings` are always saved to `~/.augment/settings.json`. Auggie no longer prompts you to choose between user, project, and local settings files. Edit project or local settings files directly. Your existing `settings.json` files continue to work. ### Personas replaced by agents `/persona`, `--persona`, and `auggie persona` are removed. Use these instead: * [Custom agents](/cli/subagents) in `.augment/agents/.md` or `~/.augment/agents/.md` * [Rules](/cli/rules) in `.augment/rules/` or `AGENTS.md`, or instructions added to the system prompt with `.augment/APPEND_SYSTEM.md` * [Permissions](/cli/permissions) to restrict or confirm specific tools ### Tool names Tools now use short names. Hook matchers that use the old names still match for now. Permission rules only recognize some old names, so update your rules before upgrading. | 1.x name | 0.x names | | :- | :- | | `read` | `view`, `read-file`, `read_file` | | `edit` | `str-replace-editor`, `str_replace_editor`, `edit-file`, `edit_file` | | `write` | `save-file`, `save_file`, `write-file`, `write_file` | | `grep` | `grep-search`, `grep_search` | | `find` | `file-search`, `file_search`, `find-by-name` | | `bash` | `launch-process`, `launch_process`, `shell` | See [Permissions](/cli/permissions#migrating-from-legacy-tool-names) for the old names that permission rules still recognize. ### Hook payloads `bash` hooks no longer list changed files. Use `git status` or `git diff` in your hook instead. See [Hooks](/cli/hooks). ### Commands and flags | 0.x | 1.x | | :- | :- | | `auggie login`, `auggie logout` | `auggie auth login`, `auggie auth logout` | | `auggie models list` | `auggie model list` | | `--quiet`, `--output-format json` | `--mode text` (default), `--mode stream`, or `--mode json` | | `--show-credits` | `--show-cost` (the old name still works) | | `--rules ` | `--rule ` (the old name still works) | | `--dont-save-session` | `--no-session` | | `--instruction-file ` | `@` | | `/sessions` | `/resume` | | `/rename` | `/name` | | `/stats` | `/session` | | `/editor`, `Ctrl+O` | `Ctrl+G` | | `Shift+Tab` toggles plan mode | `Shift+Tab` changes the reasoning effort | | `/` | `/skill:` | | `/:` | `/--:` | | `auggie mcp add -- `, `auggie mcp add ` | `auggie mcp add --command --args ""`, `auggie mcp add --url ` | | `auggie mcp add --header` short flag `-h` | `-H` | See the [CLI reference](/cli/reference) and [Interactive mode](/cli/interactive) for the full list. ### Removed * Inline completions while typing. The `enableChatInputCompletions` setting is ignored. * Gist-based session sharing (`/share` and `auggie session share`). * The task list (`/task`). * MCP server mode (`auggie --mcp`). * The `/skills` browser. Type `/skill:` to see available skills. * Rules shipped in plugins (`rules/` in a plugin). Plugin commands, agents, skills, hooks, and MCP servers still load. ## Sessions from 0.x Run `/import-legacy-sessions` to import sessions from Auggie 0.x. # Limitations Source: https://docs.augmentcode.com/cosmos/advisor/limitations What Cosmos Advisor can and can't do on its own — the two setup steps you still complete manually through the web UI. The Advisor can automate your entire SDLC for you, but there are two things you must do manually through the web UI. ## Steps that still need you * **Completing integration connections.** The Advisor tells you which integrations are needed and links you to the settings page, but the browser sign-in flow is finished by you — and some connections (GitHub App, Slack workspace, org-wide installs) require an admin. The Advisor never completes OAuth on its own. * **Storing secrets.** Credentials for non-built-in integrations (for example, a self-hosted GitLab token) must be stored by you in the secret manager before the Advisor can wire an Expert to them. ## See Also * [Cosmos Advisor Overview](/cosmos/advisor/overview) — what the Advisor does across its four phases. * [Sample Prompts](/cosmos/advisor/sample-prompts) — ready-to-use prompts for common Advisor tasks. * [GitHub configuration](/cosmos/config-github) — the connections you complete in the browser. # Cosmos Advisor Source: https://docs.augmentcode.com/cosmos/advisor/overview Your go-to agent for navigating Cosmos. ## What is Cosmos Advisor? **Cosmos Advisor** is a built-in Expert that sets up Cosmos for you. Instead of clicking through forms, describe what you want in plain language and the Advisor handles the setup — connecting [integrations](#connecting-integrations), building the [Environment](/cosmos/environments/overview) your agents run in, creating and tuning [Experts](/cosmos/experts), and wiring the [Automations](/cosmos/automations) that put them to work. It asks only what it needs, confirms the plan, and remembers your decisions across sessions. It works in four phases and resumes wherever you have open work: connect **dependencies** (integrations), stand up an **Environment**, create an **Expert**, then **analyze** how your agents are doing and tune them. > [!NOTE] > > The most successful Cosmos users configure everything through Cosmos Advisor rather than the web UI. Describing what you want in a session is faster than clicking through forms, and the Advisor picks the right defaults, wires up dependencies, and remembers your decisions across sessions. ## Connecting integrations Before your agents can do useful work, they need the right connections: code to read, places to post, and events to react to. Tell the Advisor what you want your agents to do and it identifies which integrations are required, checks what's already connected, and walks you through connecting the rest — GitHub, Slack, Linear, PagerDuty, GitLab, Jira/Confluence, and more. > [!NOTE] > > The Advisor tells you which integrations a given Expert depends on and flags any that aren't connected yet, but the browser sign-in flow is completed by you (or an admin) — the Advisor can't finish OAuth on its own. See [Limitations](/cosmos/advisor/limitations). Reference: [GitHub](/cosmos/config-github), [Linear](/cosmos/config-linear), and [Slack](/cosmos/config-slack) configuration. ## Creating and modifying Environments An [Environment](/cosmos/environments/overview) is the virtual machine your Experts run in — its base image, synced repositories, environment variables, and toolchain. Describe the project and the Advisor picks the image, syncs the repos, and installs what's needed, rather than you building it by hand in the environment form. ```text Example theme={null} Select: Cosmos Advisor Prompt: Help me create an Environment for a Ruby on Rails project. I want to use Ruby 3.4 and Sqlite3. ``` The Advisor can also update an existing Environment — adding a dependency, syncing another repository, or setting an environment variable. Updates only apply to future sessions. For all the ways to build and update one by hand, see [Cloud environments](/cosmos/environments/cloud). ## Creating and modifying Experts An [Expert](/cosmos/experts) is a reusable agent template. The Advisor can deploy Experts from a built-in catalog — PR Author, PR Fixer, Deep Code Reviewer, Pair Reviewer, PR Risk Analyzer, Personal Assistant, Backlog Dispatcher, Project Builder, and more — confirming your picks, deploying them in the right dependency order, and handing you a one-click link to try each one. For end-to-end code review coverage, it recommends deploying the review Experts together, since each covers a different stage from PR open to merge. When nothing in the catalog fits, the Advisor designs a **bespoke Expert** with you through a short conversation: it restates the goal, asks only what's genuinely ambiguous (how it fires, whose identity it acts as, who can launch it, where it posts, and whether to wire in memory — recommended by default), confirms the design in plain language, then creates it. You never see or edit a configuration file — the only thing you interact with is the finished Expert in your launcher. Reference: [Template Experts](/cosmos/experts-templates) and [Configure a custom Expert](/cosmos/experts-configure-custom). ## Creating and modifying Automations An [Automation](/cosmos/automations) launches an Expert whenever something happens — a PR opens, a Linear ticket changes state, a cron fires, or a custom webhook arrives. The Advisor wires the right trigger to the right Expert and lets you decide when it goes live. Many catalog Experts ship with triggers, but the Advisor deploys them **turned off** by default so nothing fires before you're ready — the Experts are usable from Home immediately; enabling triggers is a separate step. When you're ready, the Advisor turns triggers on in one step and lets you choose the scope: just the Experts you tried, or the full set you picked. For a bespoke Expert, it can also stage the rollout — create it with the trigger disarmed, let you try it once, then arm it when you confirm. Reference: [Understanding Automation](/cosmos/automations), [Schedules](/cosmos/config-schedules), and [Webhooks](/cosmos/config-webhooks). ## Analyzing and tuning your fleet Once your Experts have been running for a while, the Advisor's fourth phase is analysis: it pulls session data and looks for patterns worth acting on — repeated failures (edit the prompt), usage skew (retire dormant Experts, split overworked ones), sessions stuck mid-run or waiting on humans (tighten the prompt, route to Slack, swap models), and missing capabilities (return to integration or Environment setup). It surfaces the relevant cut, explains what it sees, and can apply the change in the same conversation. > [!NOTE] > > Cosmos doesn't ship built-in analytics dashboards for this; the Advisor works from session data directly. For tenant-wide usage and cost reporting, ask about the Cosmos ROI Analyst Expert. ## Next steps * **[Sample Prompts](/cosmos/advisor/sample-prompts)** — ready-to-use prompts for common Advisor tasks. * **[Limitations](/cosmos/advisor/limitations)** — what the Advisor can and can't do on its own. ## See Also * [Getting Started with Cosmos](/cosmos/getting-started) — the core concepts the Advisor works with. * [Experts](/cosmos/experts) — the catalog and custom Experts the Advisor can deploy. * [Understanding Automation](/cosmos/automations) — how triggers, events, and Experts fit together. # Sample Prompts Source: https://docs.augmentcode.com/cosmos/advisor/sample-prompts Ready-to-use prompts for common Cosmos Advisor tasks — connecting integrations, building Environments, deploying and tuning Experts, and wiring Automations. Select the **Cosmos Advisor** Expert from Home or the New Session menu, then paste one of these prompts as a starting point. The Advisor asks follow-up questions when it needs more detail, so you don't have to get everything right up front. ## Connecting integrations ```text theme={null} Help me connect GitHub so my agents can open PRs and react to reviews. ``` ```text theme={null} What integrations do I need to have an agent triage Slack messages into Linear tickets? ``` ## Environments ```text theme={null} Help me create an Environment for a Ruby on Rails project. I want to use Ruby 3.4 and Sqlite3. ``` ```text theme={null} Update my Node environment to add pnpm and run pnpm install on refresh. ``` ```text theme={null} Set up an Environment for our monorepo — sync the frontend and backend repos and install their dependencies. ``` ## Experts ```text theme={null} I want agents to review our pull requests and shepherd changes from a task to a merged PR. Set up the right Experts. ``` ```text theme={null} Set up these experts: PR Author, Deep Code Reviewer, Pair Reviewer. ``` ```text theme={null} Build me a custom Expert that watches our #support Slack channel and files a Linear ticket for each actionable report. ``` ```text theme={null} Tune our PR Author so it always runs the test suite before opening a PR. ``` ## Automations ```text theme={null} Turn on the trigger so Deep Code Reviewer runs automatically whenever a PR opens. ``` ```text theme={null} Set up a scheduled Expert that triages our backlog every weekday morning and dispatches ready tickets. ``` ```text theme={null} I want to try this Expert once before it starts firing on its own. ``` ## Analyzing your fleet ```text theme={null} How are my agents doing? Show me anything that's failing repeatedly or getting stuck. ``` ```text theme={null} Which of my Experts are dormant, and which are overworked? ``` ## See Also * [Cosmos Advisor Overview](/cosmos/advisor/overview) — what each phase does. * [Experts](/cosmos/experts) — the Experts these prompts deploy and tune. * [Limitations](/cosmos/advisor/limitations) — where you'll still need to step in. # Understanding Artifacts Source: https://docs.augmentcode.com/cosmos/artifacts View, search, and manage the durable outputs a Cosmos session produces — pull requests, Git branches, Linear issues, and custom links. ## About artifacts Cosmos saves the pull requests, branches, and Linear tickets a session creates so you can find them later, and lets you attach any external link as well. Cosmos stores each one alongside the session, surfaces them in the session details panel, and matches them in the Cmd+K command palette. Use artifacts to: * See the concrete outputs of a finished session. * Find the session that opened a specific pull request, branch, or Linear ticket. * Attach external context (a Linear ticket, a Notion doc, a dashboard URL) to a session so it stays discoverable. ## Viewing artifacts in a session Open any session and look for the **Artifacts** section in the session details panel. Each artifact shows its type, a label, and a link out to the underlying system. Empty sessions display a placeholder prompting you to attach a PR, Linear ticket, or custom link. Each artifact card has **Edit** and **Delete** controls. There is no toggle or enable/disable state — an artifact is either attached or removed. ## Artifact types There are four artifact types today. The headings below are the exact labels the UI uses. ### Pull request A GitHub pull request linked to the session. PR artifacts are auto-attached in two cases: when the Expert opens a PR through its GitHub tool, and when you send a chat message containing a GitHub PR URL. You can also add one manually from the Add-artifact dialog. The artifact stores the PR URL and renders as a link to GitHub. ### Git branch A branch associated with the session. Branch artifacts are recorded automatically from the running VM's git context — there is no manual option for Git branch in the Add-artifact dialog. ### Linear issue A Linear ticket linked to the session. Linear artifacts are auto-attached when you send a chat message containing a Linear URL, and you can add one manually by pasting a Linear URL or a bare issue identifier (for example, `AUG-12110`). > [!NOTE] > > The Linear artifact type is gated by the `poseidon_linear_integration_enabled` feature flag. When the flag is off for a tenant, Linear does not appear in the Add-artifact category dropdown and Linear URLs are not auto-attached. ### Link A custom external URL — for example, a Notion page, a runbook, or a dashboard. Use this type for anything that doesn't fit the categories above. The UI labels custom artifacts as "Link"; the storage-layer name is `CUSTOM`. ## Searching sessions by artifact The Cmd+K command palette matches artifact content alongside session names. Search by: * **PR number or URL** — e.g. `4821` or a full `github.com/...` URL. * **Branch name** — e.g. `fix/auth-token-refresh`. * **Linear identifier or URL** — e.g. `AUG-12110`. * **Custom link label or URL** — whatever you typed when attaching the link. Results show every session whose artifacts contain the query, scoped to your tenant. ## Adding artifacts manually The session details panel has an **Add** button above the Artifacts list. Use it to attach an artifact that wasn't auto-detected, or to record an external reference (Linear ticket, Notion doc, etc.) against a session. **1. Open the Add-artifact dialog** In the session details panel, click **Add** above the Artifacts list. **2. Pick a type** Choose **Pull request**, **Linear issue**, or **Link**. The Linear option is hidden when the Linear integration flag is off. Git branch is not a manual option — branch artifacts are recorded automatically from the VM's git context. **3. Enter the URL or identifier** Paste a URL for pull-request and link artifacts, or a URL or bare identifier (e.g. `AUG-12110`) for Linear. URLs must use `http://` or `https://`; Linear URLs must use `https://`. **4. Edit or remove later** Each artifact card in the list has **Edit** and **Delete** controls. Editing lets you change the label or URL; deleting removes the artifact from the session. Artifacts are per session — each session manages its own list. # Setting Up Automations with Advisor Source: https://docs.augmentcode.com/cosmos/automation-advisor Let Advisor recommend, deploy, and wire up automations conversationally — nothing fires until you say so. You don't have to wire any of this by hand. [Cosmos Advisor](/cosmos/advisor/overview) is a built-in Expert that sets up automations conversationally: describe the workflow you want — "review every PR that touches our billing service", "triage alerts from our incidents channel", "scan the backlog every morning and dispatch ready tickets" — and Advisor recommends the right Expert, checks that the integrations it depends on are connected, and deploys it for you. ## Opening Advisor Three ways in: * **From the Experts or Automations page** — the banner reading "Describe your workflow and an agent will set it up" opens Advisor with your request pre-seeded. * **From the home page** — pick **Cosmos Advisor** from the expert picker and start typing. * **From an Expert you're editing** — the "Ask an agent to tune this expert" banner opens Advisor scoped to that Expert. ## What To Ask For Describe the outcome, not the wiring. Advisor picks the trigger type, writes the JSONLogic filter, and creates or configures the Expert: * "Every weekday at 9am, DM me the PRs waiting on my review." * "Whenever review is requested on a non-draft PR targeting main, post a heads-up in #code-review." * "When a P1 PagerDuty incident fires, investigate and post findings to the incident channel." If your workflow matches one of the built-in [Expert templates](/cosmos/experts-templates) — PR authoring, code review, backlog dispatch, incident triage — Advisor recommends the template instead of building from scratch. ## The Staged Rollout Advisor never turns an automation on behind your back: 1. **Deploy with triggers off.** Advisor creates the Expert with its automation disabled. It's usable from the home page immediately, but it never fires on its own. 2. **Try it.** Advisor hands you a link to run the Expert against a real PR or task and confirm it behaves the way you want. 3. **Enable triggers.** When you're happy, Advisor flips the trigger on. From then on the automation fires on every matching event. If an integration the automation depends on isn't connected yet, Advisor calls it out and points you at the connect flow — the deploy still lands, but the automation isn't live until the connection is made. ## Advisor and the Manual Path Everything Advisor sets up is an ordinary Expert plus triggers — inspect or adjust it any time from the Experts and Automations pages, and pause it like any other automation (see [Managing Automations](/cosmos/manage-automations)). Build by hand when you want control over every field, or to understand the moving parts first — [Your First Automation](/cosmos/first-automation) walks both paths, and [Configuring Triggers](/cosmos/config-triggers) has the full reference. ## See Also * [Cosmos Advisor](/cosmos/advisor/overview) — everything the Advisor can set up, not just automations. * [Understanding Automation](/cosmos/automations) — how triggers, events, and Experts fit together. * [Your First Automation](/cosmos/first-automation) — build two automations end to end, by hand and with Advisor. # Other Workflow Automations to Explore Source: https://docs.augmentcode.com/cosmos/automation-explore Explore additional workflow automations including data engineering, CI/CD failure resolution, code review automation, and Linear ticket resolution. ## More Workflow Automations Workflow automations can take many shapes. A few patterns people build first: * **Data engineering**: Add columns, run backfills, and test changes via skills and webhooks. * **CI/CD failure resolution**: Detect a failed run and let an agent diagnose and push a fix. * **Code review automation**: A PR opens → an agent reviews it → it posts suggested changes. * **Linear ticket resolution**: Close low-hanging-fruit Linear tickets automatically. When you're ready to wire up your own, the [Expert Configuration](/cosmos/config-github) pages have the trigger and capability details. # Understanding Automation Source: https://docs.augmentcode.com/cosmos/automations What an automation is in Cosmos, how it wires an event source to an Expert, and where to inspect the events that fire one. An **automation** is a persistent binding between an outside event and an Expert. Something happens out in the world — a PR opens, a Linear ticket changes state, a cron fires, a third-party service POSTs a webhook — Cosmos opens a session from the matching Expert and drops the raw event payload in as the first message. The Expert takes it from there. If a Session is one conversation, an automation is the standing order that starts those conversations without you in the loop. > [!NOTE] > > You can — and it's strongly recommended to — ask [Cosmos Advisor](/cosmos/advisor/overview) to set up automations for you by prompting rather than hand-editing triggers. Describe when an Expert should fire and the Advisor wires the right trigger and turns it on when you're ready, instead of you configuring triggers by hand. ## How the Pieces Fit Three things show up in every automation: * **Expert** — the agent that runs. Its system prompt, capabilities, environment, and worker permissions decide what the session can do once it wakes up. * **Trigger** — the binding that listens for an event and points it at the Expert. Triggers live inside an Expert's configuration; an Expert can have several. * **Event** — the payload the trigger receives. Cosmos stores every event it sees so you can inspect what your filters are actually matching. Every trigger has a **type** — the kind of event source Cosmos is listening to. The types fall into three groups: **First-party integrations** — sources Cosmos has a managed integration for. Connect the integration once from the Integrations settings page — Cosmos owns the upstream registration — then any Expert can listen for its events. | Trigger type | Fires on | | - | - | | GitHub | Repository events from the connected GitHub App (PRs, pushes, comments, reviews). | | Linear | Issue and comment events from the connected Linear app. | | Slack | Mentions and messages from the connected Slack app. | | GitLab | Push, merge request, and pipeline events from a connected GitLab project. | | PagerDuty | Incident events routed by a PagerDuty integration key. | **Scheduled** — no outside event at all; Cosmos is the event source. A `scheduled` trigger fires on a 5-field cron expression in the timezone you pick. See [Schedules](/cosmos/config-schedules). **Webhook** — the escape hatch for anything without a managed integration (see below). See [Webhooks](/cosmos/config-webhooks). Each trigger also takes an optional filter that narrows the firing down to the subset of payloads you actually want. The filter runs against the raw event body before any session is created, so events you don't care about cost nothing. The full reference — event types, filters, and how to add a trigger to an Expert — is on the [Configuring Triggers](/cosmos/config-triggers) page. ## Webhooks Are a Trigger Type Webhooks deserve a callout because they're the escape hatch. The first-party types (GitHub, Linear, Slack, GitLab, PagerDuty) cover the systems Cosmos has a managed integration for. Anything else — Datadog, CircleCI, self-hosted GitLab, a service you wrote yourself — talks to Cosmos through a **custom webhook**: an HTTPS endpoint you create from the Webhooks page, paste into the source system's outbound-webhook config, and reference from a `webhook`-typed trigger. The same JSONLogic filter machinery works on a custom webhook's payload, so the receiving Expert only wakes up for the shapes you whitelist. Setup steps and common examples live in [Webhooks](/cosmos/config-webhooks). ## Subscriptions: Runtime Event Listeners Triggers aren't the only way an event reaches an agent. A **subscription** is the runtime counterpart of a trigger: instead of being declared in an Expert's configuration by a human, it's created by an agent mid-session using its `subscribe-event` tool. When a matching event arrives, Cosmos doesn't open a new session — it delivers the event as a message into the session that created the subscription. An agent typically creates subscriptions to: * Watch a specific PR for comments, CI status changes, or a merge * React to updates on a particular Linear ticket * Listen for Slack mentions in a thread it's already working * Poll on a schedule (cron-based health checks) without staying awake Subscriptions support the same event sources and JSONLogic payload filters as triggers. Which sources an agent can subscribe to is gated by its Expert's capabilities (e.g. the GitHub capability unlocks GitHub subscriptions); scheduled subscriptions are always available. A subscription lives only as long as the session that created it — when the session ends, its subscriptions expire. ### Triggers vs. Subscriptions | Aspect | Triggers | Subscriptions | | - | - | - | | Created by | A human, in the Expert's configuration | The agent, at runtime via `subscribe-event` | | Lifetime | Persistent | Scoped to the creating session | | On match | Opens a new session from the Expert | Delivers the event into the existing session | | Use case | "Start a reviewer whenever a PR opens" | "Tell me when *this* PR gets a comment" | When you're reading the events log, keep this distinction in mind: the same inbound event can fire a trigger (spawning a fresh session) and satisfy a subscription (waking an existing one). ## Workers and Automations Not every session in the events log was started by an automation. Some get launched as **workers** — sub-agents that a manager Expert spawns mid-session through `worker-launch`. A worker is its own session with its own messages and its own permissions, but it inherits the parent's environment and is bounded by the parent's `workerExpertIds` (or `useAllExpertsAsWorkers`) allowlist. When you're tracing what happened in response to an event, this matters: the automation fires the parent session, and the parent decides whether to delegate to one or more worker sessions. The events log only records the inbound event; the worker tree is visible from the parent session's run history. ## Inspecting What Fired The **events log** shows every event Cosmos has received across all sources, and **run history** shows what each Expert did in response. Both live under the **Automations** group in the sidebar. See [Managing Automations](/cosmos/manage-automations) for the events log, per-Expert run history, and how to pause a trigger without deleting it. ## See Also * [Configuring Triggers](/cosmos/config-triggers) — the trigger reference: types, event names, and JSONLogic filters. * [Webhooks](/cosmos/config-webhooks) — custom webhook URLs for everything else. * [Managing Automations](/cosmos/manage-automations) — the events log, run history, and pausing a trigger. * [Your First Automation](/cosmos/first-automation) — build two automations end to end. * [Setting Up Automations with Advisor](/cosmos/automation-advisor) — describe the workflow and have Advisor wire it up for you. * [Other Workflow Automations to Explore](/cosmos/automation-explore) — a few patterns people build first. # MCP Registry Source: https://docs.augmentcode.com/cosmos/config-mcp Extend Cosmos Experts with external tools and services through Model Context Protocol (MCP) servers. GitHub, Slack, and Linear are wired in directly. Everything else — databases, browser automation, third-party APIs — comes through MCP servers. Add and manage them under **Settings → Connectors** in the Cosmos menu, including partner servers like Atlassian, Sentry, Stripe, and Figma. If your menu shows **MCP Registry** under **Settings → Capabilities**, use that page instead. ## Managing MCP Configurations ### Updating or Removing Open a configured MCP server to update its credentials, manage access, or delete it when you no longer need it. ### Sharing an MCP Server **Manage access** controls who can use the MCP configuration. To give everyone in your organization use access: 1. Open the configured server under **Connectors**, then choose **Sharing → Manage access**. In the MCP Registry, use the server's menu → **Manage access**. 2. In the sharing dialog, set **General access → Organization access** to **Can use**. In versions that label the organization-wide row **Everyone**, choose **Can use** there: **Everyone → Can use** means everyone in your organization, not the public internet. 3. Save the changes and complete any connection-sharing confirmation. To share with fewer people, add only the intended people, groups, or service accounts with **Can use** instead. If the dialog offers **Individual accounts** or **Shared connection**, choose deliberately: individual accounts require each recipient to connect their own account; a shared connection lets recipients use the configured account. Only share a service account's connection with people who should have its downstream permissions. > [!NOTE] > > Older screens and screenshots may show a **Shared** toggle or **user/tenant scope**. In the access-based UI, use **Manage access** to confirm grants; a legacy scope label does not tell you who can use the server. If you cannot manage access, ask the configuration owner to grant it. ### Referenced Secrets Need Separate Access For a generic secret referenced from the server configuration, such as `$augment-MY_API_KEY`, configure the secret's access separately. Do not assume that sharing the MCP configuration also grants access to that secret. 1. Open the referenced secret in **Secrets**, then **Sharing → Manage access** (or the secret's menu → **Share**). 2. Grant **Can use** to the people or service accounts that will run the sessions. For organization-wide use, grant it to the organization as well as on the MCP configuration. 3. Check the secret's **Used in** settings: it must cover the target Space. **Organization-wide** covers every current and future Space; **Scoped access** covers selected Spaces. **Only me → Every Space** is still personal, not organization-wide sharing. See [Managing Secrets](/cosmos/config-secrets) for applicability, personal-secret limitations, and installation settings. Credentials managed by an MCP connection may follow that connection's authentication flow; the steps above are for separately created, generic secrets. ### Validate in a Fresh Session After changing the configuration, access grants, or secret settings, start a **new session in the target Space** with the MCP server attached, using the intended recipient's account. Test a harmless read-only tool call. An existing session may retain its earlier configuration or credentials, so it is not a reliable sharing test. Never print a secret value to verify access. ### Pinning to an Expert To make a registry server available inside a specific Expert, attach it from the **Tools** section of the Expert editor. The MCP server selector lists every server in the registry that the Expert can see — pick the ones you want and save. Pinned servers launch automatically with each session created from that Expert. ## See Also * [Skills](/cosmos/config-skills) — extend Experts with reusable knowledge packages using the agentskills.io specification * [Understanding Files](/cosmos/understanding-files) — the persistent storage layer that backs Skills and other Expert outputs # Using Schedules as Triggers Source: https://docs.augmentcode.com/cosmos/config-schedules Fire Cosmos Experts on a recurring cron schedule — daily standups, hourly health checks, and more. Cron-style triggers are how you fire an Expert on a clock. Daily standups, hourly health checks, the weekly report nobody wants to write — set the cron, pick a timezone, save. Add one from the **Triggers** section of the Expert editor. ## Adding a Schedule 1. Open **Experts** in the sidebar and click the Expert you want to schedule (or click **+ Create Expert** to make a new one). 2. Scroll to the **Triggers** section and click **+ Add Trigger**. 3. In the trigger row, set: * **Name** — a human-readable label (e.g. `weekday-standup`). * **Type** — `Scheduled`. * **Cron expression** — a 5-field cron string (see below). * **Timezone** — an IANA timezone name (e.g. `America/New_York`); leave blank for UTC. * **Auto-archive sessions created by this trigger** — toggle off if you want sessions to remain after they go idle. 4. Click **Save**. > [!NOTE] > > Once a schedule trigger is created, its **type** and **timezone** are fixed. To change them, delete the trigger and add a new one. ## Cron Syntax Cosmos uses **5-field crontab** (no seconds, no macros like `@daily` or `@hourly`): | Position | Field | Values | | - | - | - | | 1 | minute | `0–59` | | 2 | hour | `0–23` | | 3 | day of month | `1–31` | | 4 | month | `1–12` or `JAN–DEC` | | 5 | day of week | `0–6` (Sunday=0) or `SUN–SAT` | Special characters: `*` (wildcard), `,` (list), `-` (range), `/` (step). ## Common Cron Examples | Expression | Meaning | | - | - | | `* * * * *` | Every minute | | `*/5 * * * *` | Every 5 minutes | | `0 * * * *` | Top of every hour | | `0 0 * * *` | Daily at midnight | | `0 9 * * MON-FRI` | 09:00 every weekday | | `0 9-17/2 * * MON-FRI` | Weekdays at 09, 11, 13, 15, 17 | | `0 0 * * 0` | Weekly, Sunday midnight | | `0 0 1 * *` | Monthly, 1st at midnight | | `0 0,12 * * *` | Twice daily, midnight and noon | ## Concurrency and Reliability * Each schedule runs in **singleton mode**: if the next fire arrives while the previous run is still executing, that fire is **skipped** — runs are not queued. * Missed fires during pod transitions or leadership changes are **not backfilled**. * The session executes with the permissions of the user who created the schedule. # Managing Secrets Source: https://docs.augmentcode.com/cosmos/config-secrets Store API keys, tokens, and credentials in the Cosmos Secrets Manager and inject them into Expert VMs at boot. Anything that would be a bad idea to type into a chat — API keys, OAuth tokens, certs, DB URLs — goes in the Secrets Manager. Cosmos exports them into the Expert VM at boot. They're encrypted on disk and stripped from logs. > [!NOTE] > > **Use Secrets for sensitive environment variables in cloud agents.** A secret is automatically exported only when the session is authorized to use it, its applicability covers the session's Space, and auto-install is enabled. Environment-scoped environment variables (set on the Environment itself) are for **non-sensitive defaults only** (e.g. `NODE_ENV=development`) and are shared with every user of that environment. ## Where to Find It The Secrets Manager lives under **Settings → Capabilities → Secrets** in the Cosmos menu. You can add, edit, delete, and search secrets from there. Values are write-only — once saved, you cannot read them back. Rotating means editing and pasting the new value. ## Access and Applicability **Who can use a secret and where it applies are separate settings.** Sharing an MCP server or adding a resource to a Space does not replace the secret's own access settings. ### Sharing: Who Can Use It For a shareable secret, open **Sharing → Manage access** in its editor, or choose **Share** from the secret's menu. Grant **Can use** to the intended people, groups, or service accounts. For organization-wide access, set **General access → Organization access** to **Can use** (shown as **Everyone → Can use** in some versions), then save. This grants use within your organization, not public access, and does not reveal the stored value in the UI. Grant only the access needed. If the sharing control is unavailable, ask the secret owner to check your permissions. **Only me** secrets remain personal and cannot be shared directly; create a **Scoped access** or **Organization-wide** secret for shared use instead. > [!WARNING] > > Use access allows agents and automations to use the credential. People who can contribute to one of your shared sessions may also cause that session to use your personal secrets. Keep credentials out of prompts, repositories, and tool output. ### Used in: Where It Applies The **Used in** settings determine where the secret is selected for a session: | Choice | Applicability | | - | - | | **Only me** | Personal to sessions you own, in **Every Space** or **Selected Spaces**. Every Space includes future Spaces; it does not grant other people access. | | **Scoped access** | Applies in the selected target Spaces. Grant use access separately to the intended recipients. | | **Organization-wide** | Applies in every current and future Space. Available to admins when creating a secret; use access must still be granted separately. | The category is fixed at creation. You can later edit the selected Space coverage of personal or scoped secrets, but cannot turn a personal secret into an organization-wide one by changing its access grants. When multiple eligible values target the same environment variable or file path, personal values take priority over selected-Space values, which take priority over organization-wide values. A personal value for selected Spaces takes priority over one for Every Space. > [!NOTE] > > Older screens and guides may describe **Private/Shared visibility**. In the current UI, check **Sharing**, **Used in**, and installation independently; neither an organization-wide grant nor Every Space coverage alone guarantees a secret will reach a session. ## Creating a Secret 1. Go to **Settings → Capabilities → Secrets** from the Cosmos menu. 2. Choose **Add a secret** and the environment-variable option. 3. Fill in: * **Name** — used as the variable name when injected (e.g. `OPENAI_API_KEY`). * **Value** — the secret value. Pasted in once and never shown again. * **Applicability** — choose **Only me**, **Scoped access**, or **Organization-wide**, and select Space coverage where applicable. Review this later under **Used in**. * **Auto-install in environments** — leave on to inject the selected value into authorized new environments. Turn it off to store the secret without automatic injection. 4. Save the secret. For shared use, grant the intended recipients **Can use** through **Manage access** and confirm the grants saved. The new secret appears in the list. Validate it in a fresh session owned by an intended recipient in the target Space. ## Auto-Injection into VMs An authorized, applicable environment-variable secret with **Auto-install in environments** enabled is exported as a shell variable on VM boot. Installation does not grant access or change **Used in** coverage. The exported variable name is the **upper-snake-case** of the secret name: | Secret name | Exported as | | - | - | | `openai-api-key` | `$OPENAI_API_KEY` | | `pagerduty.token` | `$PAGERDUTY_TOKEN` | | `db_url` | `$DB_URL` | To verify a secret is available, start a new session in the target Space and prompt: *"Check whether `$OPENAI_API_KEY` is set in this workspace. Report only whether it is present; do not print its value."* For a generic secret referenced by an MCP server, also grant use access on the [MCP configuration](/cosmos/config-mcp#referenced-secrets-need-separate-access). Test a harmless read-only MCP call in a fresh session as the intended recipient; a successful test as the owner does not verify someone else's access. ## Secrets vs Environment Variables | Concern | Secrets Manager | Environment variables on an Environment | | - | - | - | | API keys, tokens, credentials | ✅ | ❌ — values are committed into the environment's version history | | Per-user values | ✅ (**Only me**) | ❌ — same value for everyone using the environment | | Public defaults (paths, feature flags) | Possible | ✅ | | Auto-exported as `$FOO` in VM shell | ✅ | ✅ | **Rule of thumb:** sensitive or per-user → Secrets Manager; public/shared defaults tied to an environment → environment variables on the Environment. ## Limits and Lifecycle * **Versioning** — each secret has an opaque version; saving a new value rotates it. * **Rotation** — there is no built-in scheduler. Rotate by editing the secret and entering the new value. Validate the change in a fresh session. * **Deletion and access changes** — deleting a secret or revoking access does not recall values already delivered to running sessions. If a credential has been exposed, revoke or rotate it at its source as well. # Skills Source: https://docs.augmentcode.com/cosmos/config-skills Extend the agent with domain-specific expertise using reusable knowledge packages that follow the agentskills.io specification. ## About Skills Skills are reusable knowledge packages that extend the agent with domain-specific expertise — deployment guides, debugging playbooks, framework best practices, and more. Each skill is a self-contained skill folder with a markdown file that provides specialized instructions the agent can draw on during conversations. Skills follow the [agentskills.io](https://agentskills.io) specification, ensuring compatibility across AI tools. ## Creating a Skill Each skill lives in its own named directory containing a markdown file that shares the name of the directory: ``` cosmos/files/organization/.augment/skills/ ├── python-testing/ │ └── python-testing.md ├── api-design/ │ └── api-design.md └── deploy-guide/ └── deploy-guide.md ``` ### Markdown Format Each markdown file must include YAML frontmatter with a `name` and `description`, followed by markdown content with instructions: ```markdown theme={null} --- name: deploy-guide description: Step-by-step deployment procedures for our production infrastructure --- # Deployment Guide ## Pre-deployment Checklist 1. Run all tests with `npm test` 2. Verify environment variables are set 3. Check database migrations are up to date ## Deploying to Production ... ``` ### Frontmatter Fields | Field | Description | Requirements | | :- | :- | :- | | `name` | Skill identifier | 1–64 characters, lowercase alphanumeric and hyphens only, must match directory name | | `description` | What the skill does and when to use it | 1–1024 characters | ### Skill Name Requirements Skill names must: * Be 1–64 characters long * Use only lowercase letters, numbers, and hyphens * Not start or end with a hyphen * Not contain consecutive hyphens * Match the directory name containing the markdown file **Valid names**: `python-testing`, `api-design`, `deploy-guide` **Invalid names**: `Python-Testing`, `api_design`, `-deploy`, `my--skill` ## Skill Locations Skills are discovered from multiple locations in order of precedence: | Location | Scope | Description | | :- | :- | :- | | `cosmos/files/organization/.augment/skills/` | Organization | Available to all users in your Organization (highest precedence) | | `cosmos/files/user/.augment/skills/` | User | Private to you across all sessions | | `//.claude/skills/` | Project | Compatible with Claude Code | | `//.agents/skills/` | Project | Industry-standard location | When multiple skills with the same name exist in different locations, the skill from the higher-precedence location is used. ## Getting Started **1. Create a directory to host your skill** Navigate to Files > Organization > .augment > skills and create a new directory for your skill. **2. Create the my-skill.md file** Upload a markdown file to directory using the Upload File button: ```markdown theme={null} --- name: my-skill description: Custom skill for my project workflow --- # My Custom Skill Add your domain-specific guidance, examples, and instructions here. ``` **3. Use the skill** The skill will be discovered automatically and injected into your Expert's context. ## Best Practices 1. **Focus each skill on a single domain** — keep skills modular and specific 2. **Include concrete examples** — provide code samples and commands 3. **Write clear descriptions** — help the agent understand when to apply each skill ## See Also * [agentskills.io Specification](https://agentskills.io/specification) — Official skill format specification * [Understanding Files](/cosmos/understanding-files) — the Files system where Skills are stored and managed * [Skills in Auggie CLI](/cli/skills) — Using skills with the CLI # Configuring Triggers Source: https://docs.augmentcode.com/cosmos/config-triggers Add triggers to a Cosmos Expert — pick an event source, choose an event type, and filter payloads with JSONLogic expressions. A **trigger** is how an outside event reaches an Expert. When it fires, Cosmos opens a session and drops the raw event payload in as the first message. Add and edit triggers from the **Automations** page in the sidebar. > [!NOTE] > > Prefer not to wire triggers by hand? Describe the workflow to [Cosmos Advisor](/cosmos/automation-advisor) instead and it wires the right trigger for you. ## Trigger Types Triggers come in three groups: * **First-party integrations** — GitHub, Linear, Slack, GitLab, PagerDuty. Connect the integration once from the Integrations settings page; Cosmos owns the upstream registration. PagerDuty triggers pick from the PagerDuty integrations (Events API routing keys) you've registered instead. * **Scheduled** — a 5-field cron expression and a timezone. No payload, no filter. See [Schedules](/cosmos/config-schedules). * **Webhook** — any service that can POST JSON to an HTTPS URL you mint yourself. See [Webhooks](/cosmos/config-webhooks). ## Adding a Trigger to an Expert 1. Open **Automations** in the sidebar and click **Create automation**. The trigger editor opens. 2. Pick the Expert you want to wire up from the **Expert** dropdown. (The Expert must already exist — create it from the Experts page first.) 3. Choose a **Trigger source**, then complete the editor fields: * **Trigger name** — a human-readable label (e.g. `on-pr-opened`). * **Event** — for first-party triggers, the provider event name (see the reference below). Scheduled triggers show a **Frequency** builder instead — every N minutes, hourly, daily, weekly, monthly, or a custom cron expression — plus a **Timezone**. * **Filter** — an optional [JSONLogic](https://jsonlogic.com) expression evaluated against the raw event payload. The trigger fires only when this expression returns true. * **Auto-archive sessions created by this trigger** — toggle off when you want to keep trigger-launched sessions accessible after they go idle (useful for revisitable agent-driven sessions like a PR-author). * **Run sessions as** — under **Permissions**, keep the trigger creator or choose a service account as the identity for triggered sessions. Availability is rollout-dependent: without delegated access, only workspace admins can choose a service account. With delegated access, non-admins see only service accounts shared with them, and saving a selection requires permission to attach that account. * **Maximum runs per minute** — an optional rate limit on how often the trigger can fire. 4. Click **Save**. To add another trigger, expand the automation on the **Automations** page and click **Add trigger**. To change **Run sessions as** later, expand the automation, select the trigger, and edit the field under **Permissions**. > [!NOTE] > > The trigger **type** is fixed once a trigger is created. To change it, delete the trigger and add a new one. ## Event Type Reference Each first-party trigger takes an **Event type** using the source's native event names: | Source | Event types | Notes | | - | - | - | | [GitHub](/cosmos/config-github) | `pull_request`, `pull_request_review`, `pull_request_review_comment`, `issues`, `issue_comment`, `push`, `check_suite`, `status`, `workflow_run`, `workflow_job`, `workflow_dispatch` | GitHub webhook event names. No `reaction` event — GitHub doesn't send webhooks for emoji reactions. | | [Linear](/cosmos/config-linear) | `Issue`, `Comment`, `Project` | Each delivers `action` ∈ `create` / `update` / `remove` in the payload — filter on it. | | [Slack](/cosmos/config-slack) | `app_mention`, `message` | An @-mention is delivered as **both** — always filter on `event.type` to avoid double-firing. | | [GitLab](/cosmos/gitlab-cloud) | `gitlab.push`, `gitlab.tag_push`, `gitlab.merge_request`, `gitlab.issue`, `gitlab.note`, `gitlab.pipeline` | A connected project registers these six by default; more are available on request. | | PagerDuty | — | Routed by integration key, not event type. Filter on `event.event_type` (e.g. `incident.triggered`). | The per-source pages have the payload shapes and filter recipes for each: [GitHub](/cosmos/config-github), [Linear](/cosmos/config-linear), [Slack](/cosmos/config-slack). ## Payload Filters The **Filter** field on a trigger is a [JSONLogic](https://jsonlogic.com) expression evaluated against the parsed JSON payload. Common examples: ```json theme={null} // Only PR opens {"==": [{"var": "action"}, "opened"]} // PRs targeting main {"==": [{"var": "pull_request.base.ref"}, "main"]} // Comments mentioning @auggie {"in": ["@auggie", {"var": "comment.body"}]} // Severity P0 or P1 {"in": [{"var": "severity"}, ["P0", "P1"]]} ``` To see the real shape of a payload before writing a filter, open the [events log](/cosmos/manage-automations), filter by source and event type, and inspect a captured event. The events log is the source of truth for what your triggers actually see — use it to confirm field paths and values before pasting a filter into a trigger. ### PagerDuty — P1 Incident Triggered PagerDuty triggers route by integration key rather than event type. Create a PagerDuty Events API v2 integration on the relevant service, register its **routing key** as a PagerDuty integration in Cosmos, then pick it from the **PagerDuty integration** dropdown on the trigger. Use the **Event** dropdown (incident triggered / acknowledged / resolved) and the **Filter** field to match specific incidents: ```json theme={null} {"and": [ {"==": [{"var": "event.event_type"}, "incident.triggered"]}, {"in": [{"var": "event.data.priority.name"}, ["P1"]]} ]} ``` ## See Also * [Understanding Automation](/cosmos/automations) — how triggers, events, and Experts fit together. * [Webhooks](/cosmos/config-webhooks) — custom webhook URLs for everything else. * [Schedules](/cosmos/config-schedules) — cron syntax, timezones, and concurrency rules. * [Managing Automations](/cosmos/manage-automations) — the events log and run history. # Webhooks Source: https://docs.augmentcode.com/cosmos/config-webhooks Wire any external event source to a Cosmos Expert using a custom webhook — receive JSON payloads and filter them with JSONLogic expressions. Webhooks are the escape hatch. The [first-party trigger types](/cosmos/config-triggers) cover the systems Cosmos has a managed integration for. Anything else — Datadog, CircleCI, self-hosted GitLab, a service you wrote yourself — talks to Cosmos through a **custom webhook**: an HTTPS endpoint you create, paste into the source system's outbound-webhook config, and reference from a `webhook`-typed trigger. The same JSONLogic filter machinery works on a custom webhook's payload, so the receiving Expert only wakes up for the shapes you whitelist. ## Creating a Custom Webhook A custom webhook can be shared with your organization or kept personal, and can be reused by any number of triggers. 1. Open **Webhooks** in the sidebar (under Capabilities in settings). 2. Create a webhook: pick a type — **Bearer Token** is the generic choice — give it a description, and choose whether it's shared or personal. 3. The confirmation page reveals the **Webhook URL** and the secret (shown as the **Signing Secret**) **once** — copy both before leaving the page. The secret cannot be retrieved later. Send it as a bearer token on every request (see below). The trigger URL has the form: ``` POST https://{tenant}.api.augmentcode.com/webhooks/{webhook_id} Authorization: Bearer Content-Type: application/json ``` The full raw HTTP body is forwarded to Cosmos as the event payload with no wrapping. When you add the **Webhook** trigger from the Automations page, pick the custom webhook by name from the webhook dropdown — that wires the trigger to the URL you just minted. ## Common Webhook Examples ### Datadog — Error Alert 1. Create a webhook and copy the URL + bearer secret. 2. In Datadog → Integrations → Webhooks, configure a custom webhook with the trigger URL and add `Authorization: Bearer ` under **Custom Headers**. 3. On the **Automations** page, add a **Webhook** trigger, pick the new custom webhook from the **Webhook** dropdown, and set **Filter** to match the alerts you care about: ```json theme={null} {"and": [ {"==": [{"var": "alert_type"}, "error"]}, {"in": [{"var": "priority"}, ["P1", "P2"]]} ]} ``` ### CircleCI — Workflow Failed 1. Generate a webhook the same way. 2. In CircleCI → Project Settings → Webhooks, configure a webhook with the trigger URL and add `Authorization: Bearer ` under headers. 3. On the **Automations** page, add a **Webhook** trigger pointing at the new custom webhook with **Filter**: ```json theme={null} {"and": [ {"==": [{"var": "type"}, "workflow-completed"]}, {"==": [{"var": "workflow.status"}, "failed"]} ]} ``` ### Test Any Custom Webhook with curl You can fire a test event into any custom webhook with curl: ```bash theme={null} curl -X POST "https://${TENANT}.api.augmentcode.com/webhooks/${WEBHOOK_ID}" \ -H "Authorization: Bearer ${WEBHOOK_BEARER_SECRET}" \ -H "Content-Type: application/json" \ -d '{"action": "ping", "message": "hello from curl"}' ``` Then open the [events log](/cosmos/manage-automations), filter by source = Webhook, and confirm the event was received. ## See Also * [Configuring Triggers](/cosmos/config-triggers) — the full trigger reference, including event types and filters. * [Managing Automations](/cosmos/manage-automations) — inspect captured webhook events in the events log. * [Your First Automation](/cosmos/first-automation) — build two automations end to end. # Configuring Cosmos Source: https://docs.augmentcode.com/cosmos/configuring-cosmos Connect your tools, set up an environment, and start your first session in Cosmos. ## Quickstart First-run setup is a single guided flow: connect a couple of integrations, pick where your agents run, and start a session. Skip anything you're not ready for and finish it later in Settings. ## Give your experts access to your repositories and tools that power your software development lifecycle **1. Connect GitHub** Click **"Connect GitHub"** to install the [Augment Code GitHub App](https://github.com/apps/augmentcode/installations/new). An administrator picks which repositories Cosmos can access. Once installed, agents can open PRs, comment on them, and read code from any repo you grant access to. **2. Connect Slack (Optional)** Click **"Connect Slack"** to authorize Cosmos to read and post in channels. The administrator specifies which channels Cosmos has access to. Now your Experts can post in those channels, react to messages, and reply in threads. **3. Connect Linear (Optional)** Click **"Connect Linear"** to allow Cosmos to access your projects, tickets, and events — including label changes such as moving a ticket from Backlog to In Progress. Agents can now read issues, post comments, and react to status changes — `Backlog → In Progress` is the usual trigger. ## Give your experts a place to work **1. Understanding your options** | Option | Description | | - | - | | **Self-hosted** | One command on your laptop, VM, or server. Fastest path if your repo and tooling are already there. | | **Cloud** | We host the VM. Start from a base image (or bring your own), point it at your repos. | **2. Choose a Starting Environment (Cloud only)** If you chose Cloud, pick a base image to start from. You can customize it later or bring your own. | Environment | Description | | - | - | | **Cosmos Default** | Ubuntu 24.04 with Python 3.12 and Node.js 22 installed | | **TypeScript 6.0** | Dev Container running Debian 12 with TypeScript 6.0 and Node 22 | | **Go 1.24** | Official Go 1.24 development environment with Node 22 | | **PHP 8.4** | Official PHP 8.4 development environment with Node 22 | | **Ruby 3.4** | Official Ruby 3.4 development environment with Node 22 | | **Rust 1.95** | Official Rust 1.95 development environment with Node 22 | **3. Add Repositories** A dropdown lets you select which repositories to clone into your environment. These are the repos shared via the GitHub integration. Add multiple repos to let Cosmos work across projects — you can add more later. Click **"Next"** when done, or **"Skip for now"** to continue without selecting repos. **4. Name Your Environment** Give your environment a name you'll recognize later (e.g. `weather-app-repo`). Optionally add a description that will appear on the environments list (e.g. *Pre-configured with Python 3.12, NumPy, and Jupyter*). Click **"Create Environment"** when ready. Cosmos provisions your environment automatically. A progress dialog shows each stage: * ✅ VM started * ⏳ Cloning repositories... * ⏳ Creating snapshot... * ⏳ Finishing up... Once complete, your environment is ready to use. **5. Pick Your Experts** Choose one or more Experts to install. If you don't know what to pick, install **PR Author** — it carries a PR from `git checkout -b` through merge, including the CI-failure cleanup nobody wants to do. Use **PR Fixer** for PRs created without PR Author. ## Put your experts to work **1. Start Your First Session** Click *New Session* to start your first session with your Expert. The session is the conversation with the Expert — it will automatically start in the environment you just created. # Integrate Azure DevOps Cloud Source: https://docs.augmentcode.com/cosmos/connectors/azure-devops-cloud Connect Azure DevOps Cloud to Cosmos to receive webhook events, access repositories, and automate pull request authoring and code review. ## Introduction In this document we’ll configure the native Cosmos integration with Azure DevOps Cloud (aka ADO), and learn how to: 1. Get ADO to push events to Cosmos via webhooks 2. Configure a Cosmos environment that git clones/fetches from ADO repo(s) 3. Get Cosmos to automatically review and comment on a PR when created 4. Deploy a PR Author and PR Deep Code Reviewer experts using the Cosmos Advisor For 4, below is the flow that will be followed by the Cosmos PR Deep Code Reviewer expert: ```mermaid theme={null} sequenceDiagram autonumber participant ADO as ADO participant A as Augment Code | Cosmos ADO->>A: Webhook: Pull Request created (PR payload) A->>A: Start Expert (spawn/run expert agent) A->>A: Expert analyzes PR (diff + context) A->>ADO: POST PR comment ADO-->>A: 201 Created (comment posted) ``` The native ADO integration also supports Work Items, so you can later deploy Ticket Triager and Dispatcher experts to manage your backlog of tickets. ## Prerequisites To configure the one-time connectivity between Cosmos and ADO: **Cosmos** * you must be a Augment admin **ADO** * you must either * have permissions to create a dedicated EntraID service account user with permissions to access ADO projects (with Project Collection Administrator role) * or have permissions to create a dedicated ADO service account user with permissions to access ADO projects (with Project Collection Administrator role) ## Step 1 - Configure the native ADO integration As a Augment admin, go to [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Connectors > Browse Connectors > Azure DevOps > click on it: ![Image](https://mintcdn.com/augment-mtje7p526w/HGhsP7-CI2q2qUiA/images/image.png?fit=max\&auto=format\&n=HGhsP7-CI2q2qUiA\&q=85\&s=85a8a1dbb80c31b8b5b06e715ae4755d) Note: if you don’t see the ADO option in your tenant, reach out to your Augment Solution Architect or send Augment a note: [https://www.augmentcode.com/contact](https://www.augmentcode.com/contact). You should land on that page: ![Image](https://mintcdn.com/augment-mtje7p526w/HGhsP7-CI2q2qUiA/images/image-3.png?fit=max\&auto=format\&n=HGhsP7-CI2q2qUiA\&q=85\&s=814f5824dff5c15a9fe4434209eb6119) 2 options: 1. EntraID OAuth route 2. ADO PAT token route ### Option1: Connecting to ADO via EntraID OAuth Let’s create a new EntraID user with Project Collection Administrator role on the corresponding ADO projects. Go to your EntraID admin portal [https://entra.microsoft.com/](https://entra.microsoft.com/) > Entra ID > Users > New user > Create new user: * UPN: ex: **[augmentcode@mycompany.com](mailto:augmentcode@mycompany.com)** * Display name: Augment Code Click on Review + create Now go to each ADO organization (`https://dev.azure.com//`) > Organization Settings > Users > Add users. In the users field type in the name of your EntraID service account user and select the matching user, select Access Level = Basic, select your projects and Azure DevOps Groups = Project Contributors. You should see this: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-03.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=61f6a9e0690abb41f3ebf878c63b189f) ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-04.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=500c6c217273587e5ccfcba0a6e99380) Then navigate to Organization Settings > Permissions, you should see this: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-05.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=384a379237574497c0b27967ae5618be) Click on Project Collection Administrators > Members tab > Add > type in the name of your EntraID service account user and select the matching user, then click on Save ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-06.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=d80bfcc17b19ef45fc6afc1961f5ff9b) You should see this: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-07.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=2da4ef4b3fe252e8b24b39286fe0769a) At this point, your EntraID service account user should be able to access your ADO project. Let’s test this out: open a new browser session (or new incognito window) > sign in using your EntraID service account user, and navigate to your ADO organization (`https://dev.azure.com//`). You should see this: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-08.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=25b4e362a9c2c8f139eeccc2dac728aa) In that same browser session, re-authenticate to Cosmos as an admin [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Connectors > Browse Connectors > Azure DevOps > and click on Connect with Entra OAuth: ![Image](https://mintcdn.com/augment-mtje7p526w/HGhsP7-CI2q2qUiA/images/image-4.png?fit=max\&auto=format\&n=HGhsP7-CI2q2qUiA\&q=85\&s=c70a14855f46af17d0501848c0425414) You should see this OAuth consent screen, click on Accept: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-10.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=20699957d34760c4138193ac396d0f93) You should then be redirected to Cosmos with the list of Repositories your service account has access to: ![Image](https://mintcdn.com/augment-mtje7p526w/HGhsP7-CI2q2qUiA/images/image-5.png?fit=max\&auto=format\&n=HGhsP7-CI2q2qUiA\&q=85\&s=1e39845d0015f7a4e58798c6b427aeea) ### Option2: Connecting to ADO via Personal access token For this option, you will complete the same steps as in Option1 to create a new dedicated EntraID service account user and grant it access to the corresponding ADO organization and projects, but instead of connecting ADO to Cosmos via OAuth, you’ll leverage a ADO PAT token. Make sure your service account user can access your ADO organization, you should see this when navigating to `https://dev.azure.com//`: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-12.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=5d97557e3553296ed39b8d3daabcbc7d) Click on the wheel icon top right > Personal access tokens ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-13.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=89bbe63b58231a4e97cb780eb8dcc2ce) You should see this: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-14.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=985c8eff49e92aa8df30c8c1d6e0d302) Click on New Token: * Name: Token01 * Organization: a specific organization or `All accessible organizations` (recommended if using multiple organizations) * Expiration: pick the date most far out * Scopes: `Custom defined`, then select * `Work Items (Read & Write)` * `Code (Read & Write)` You should see this: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-15.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=84f0d1d57dc14bb15d1743d824c13523) Click on Create, you’ll then be presented with a PAT token: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-16.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=154daacdea10d67f8ed709b07e2366c7) Copy this PAT token then go back to Cosmos as an admin [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Connectors > Browse Connectors > Azure DevOps > expand the section Use a personal access token instead ![Image](https://mintcdn.com/augment-mtje7p526w/HGhsP7-CI2q2qUiA/images/image-2.png?fit=max\&auto=format\&n=HGhsP7-CI2q2qUiA\&q=85\&s=2e2fa14deed370d29b4511f28738cfce) Enter your ADO organization name, PAT token, and click on Connect bot token: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-18.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=eb85e5005096efb8458e9cfac7df5981) You should then see the list of Repositories your service account has access to: ![Image](https://mintcdn.com/augment-mtje7p526w/HGhsP7-CI2q2qUiA/images/image-1.png?fit=max\&auto=format\&n=HGhsP7-CI2q2qUiA\&q=85\&s=7b938a2be47f7034a1c584ac785e1369) ## Step 2 - Create a cloud environment Let’s create a cloud environment with those ADO repos: Go to [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Environments > top right Create an environment > Cloud machine ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-20.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=7e448115f608508d1707507b7989eb3a) Configure your environment: * Name: ex: ADO ecomm-stack * Image: ex: keep the Cosmos default base image * Repositories: select your ADO repos * Refresh: toggle on * Spaces: keep the default space * Click on Create Environment ![Image](https://mintcdn.com/augment-mtje7p526w/HGhsP7-CI2q2qUiA/images/image-7.png?fit=max\&auto=format\&n=HGhsP7-CI2q2qUiA\&q=85\&s=e573a1aed46625e43dba7d7333d2c9f4) Cosmos will create the cloud environment, git clone your repos and keep them up to date: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-22.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=247beb45a27faf44675b515f1a69e172) ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-23.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=fbd6dda57c365cf88c6578f3c7bf8bb2) Click on Done. You’ll see your new environment in your “Mine” tab: ![Image](https://mintcdn.com/augment-mtje7p526w/HGhsP7-CI2q2qUiA/images/image-8.png?fit=max\&auto=format\&n=HGhsP7-CI2q2qUiA\&q=85\&s=745743220482cd569e6d609ece3f5c45) Now let’s do a quick test and create a session with that env: In the left sidebar click on ‘Back to app’ to get back to [https://cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New session > bottom left of the prompt select your cloud env, then click on Integrations and verify that ADO is selected, then send this prompt `What are those repos about?` ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-25.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=e084c99d432cc25cad17163d9fd98a02) That’ll start a session. Open the right sidebar by clicking on the icon top right, then note that Expert = Not set, Integrations include Azure DevOps App, your selected env and corresponding repos are visible: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-26.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=c34147a41076ee617dd993291799577c) From that session prompt `List the last open PRs on those repos`, Cosmos should return a list that looks like this: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-27.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=9b196d50539e893308263861160c4b03) Lastly, from that session prompt `List the most recent work items across those ADO orgs`, Cosmos should return a list that looks like this: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-28.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=b5f34f353e33daa13b51173fd7d613c8) Your ADO integration and your cloud env are ready! You can now leverage the Cosmos Advisor expert to create your ADO-specific experts. ## Step 3 - Create a PR Deep Code Reviewer expert Cosmos has a large knowledge base and greatly assists with creating new experts.\ A common expert you’d create for your ADO repos is the “PR Deep Code Reviewer”, whose job will be to auto react to PRs being created and auto review them. Whenever you need to create new experts go ask the Cosmos Advisor. Go to Cosmos ([https://cosmos.augmentcode.com](https://cosmos.augmentcode.com)) > New session > select the ‘Cosmos Advisor’ expert, make sure the ADO integration is selected and prompt with `Create a PR author, a PR risk analyzer, a PR deep reviewer. The PR review should start whenever a PR gets created. Those experts should reuse the cloud env attached to this session, and use the Azure DevOps integration`: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-29.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=15917f1f281320b5af9b9a4d526f3fef) The Cosmos Advisor may ask you to clarify what experts to deploy, it may recommend to deploy additional experts (ex: helper experts), and if an integration is missing it’ll guide you to add it. If you are deploying experts across different types of repos (ex: Github, Gitlab, ADO), don’t hesitate to prompt Advisor with `make sure all those experts have the (Azure DevOps) suffix` so you can quickly spot the ADO-specific experts vs the Github ones etc. Ultimately you should see this at the end of your session: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-30.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=541fb6611753695e4221b092ea51a178) ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-31.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=baa8e887cdf0c4cd3336c32aad34b878) Let’s see where the experts are created: go to Cosmos [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Experts > filter on expert name containing “Azure DevOps”: ![Image](https://mintcdn.com/augment-mtje7p526w/HGhsP7-CI2q2qUiA/images/image-9.png?fit=max\&auto=format\&n=HGhsP7-CI2q2qUiA\&q=85\&s=71ae08bd32a015a5212cedbcb3de07c8) Cosmos Advisor configured some experts to react to ADO events, you can see those configured in Cosmos [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Automations ![Image](https://mintcdn.com/augment-mtje7p526w/HGhsP7-CI2q2qUiA/images/image-10.png?fit=max\&auto=format\&n=HGhsP7-CI2q2qUiA\&q=85\&s=5ea2ab43af9b2feadd24bd6a4a3a14c1) If you expand the Deep Code Reviewer (Azure DevOps) you’ll see its triggers: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-34.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=1a74c5e1fd207ca2f9f95bb9fa68476e) > [!NOTE] > > The current native ADO integration automatically manages ADO PR webhooks, and soon Work Item webhooks will also be managed ## Step 4 - Create a new PR and observe your experts at work Go to Cosmos ([https://cosmos.augmentcode.com](https://cosmos.augmentcode.com)) > New session, implement a simple change ex: prompt with `add a hello world banner on top of the web app, then create a PR in ready to review state`: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-35.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=4f784ce482e99b06e75558b25679a22b) Then open your PR, you’ll see the PR Deep Code Reviewer expert commenting on the PR: ![](https://mintcdn.com/augment-mtje7p526w/XXVowgznyzYE_wgh/images/cosmos-integrations/azure-devops-cloud/azure-devops-cloud-36.png?fit=max\&auto=format\&n=XXVowgznyzYE_wgh\&q=85\&s=a641f879cdc4c7df968ccc477c4ad171) Congratulations, you’ve configured the native ADO integration and your first PR experts! 🎉 # Integrate ClickUp Source: https://docs.augmentcode.com/cosmos/connectors/clickup Connect ClickUp to Cosmos using webhooks and the ClickUp MCP server to receive task events and read workspace objects. ## Introduction In this page we’ll learn how to configure 2 things: * Get ClickUp to push events to Cosmos via webhooks ```mermaid theme={null} sequenceDiagram autonumber participant SOURCE as ClickUp participant COSMOS as Augment Code | Cosmos SOURCE->>COSMOS: Webhook: Issue Created (Ticket JSON) ``` * Get Cosmos to interact with ClickUp via the ClickUp MCP server ```mermaid theme={null} sequenceDiagram autonumber participant SOURCE as ClickUp participant COSMOS as Augment Code | Cosmos COSMOS->>SOURCE: Read objects via ClickUp MCP server SOURCE-->>COSMOS: 200 OK (Sync Complete) ``` ## Prerequisites To configure the one-time connectivity between Cosmos and ClickUp: **Cosmos** * any user who can self-create webhooks and configure MCP servers **ClickUp** * must have the Owner or Admin role * must be on the Business Plus plan (to enable Webhooks & Automation Integrations) ## Step 1 - Configure ClickUp to notify a Cosmos webhook ### Webhook receiver in Cosmos Let’s create a new webhook in Cosmos (so Cosmos can listen to ClickUp events). Go to Cosmos ([https://cosmos.augmentcode.com](https://cosmos.augmentcode.com)) > Settings > Webhooks ([https://cosmos.augmentcode.com/webhooks](https://cosmos.augmentcode.com/webhooks)) > Create a webhook > Custom Webhooks: * Enter Description: **ClickUp** * Keep Shared toggled on * Click on Create ![Image](https://mintcdn.com/augment-mtje7p526w/HEaes7Rs5TKLeUUz/images/image-35.png?fit=max\&auto=format\&n=HEaes7Rs5TKLeUUz\&q=85\&s=4464c1a2dc843a2336fcda82d0eab645) That gives you a url to POST to with a given Bearer token to pass as HTTP header. Curl request would look like: ```shell theme={null} curl -X POST https://XXX.api.augmentcode.com/webhooks/XXX \ -H "Authorization: Bearer whsec_XXX" \ -H "Content-Type: application/json" \ -d '{"event": "test", "data": "your payload here"}' ``` ### Webhook sender in ClickUp Let’s create a new webhook config in ClickUp (so ClickUp can POST to a given url when certain ClickUp events occur) In ClickUp as an Owner or Admin, click on your avatar top right > Settings > Automations Manager > Webhooks tab: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-02.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=7e1dfcbf813755e957c9101d61f91cb1) Click on Create Webhook: * Title: **Cosmos** * Description: **Notifies Cosmos when events occur in ClickUp** * Url: paste the webhook url Cosmos provided * Headers: * keep Content-type: **application/json** * add header **Authorization** and as value paste the **Bearer whsec\_xxxx** Cosmos provided * Keep Webhook status enabled * Click on Test webhook You should get a green checkmark confirming that the webhook was invoked: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-03.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=849a7a15feca2cde27f694007616bc38) Click on Create webhook, you should see you new webhook auto-enabled: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-04.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=1dd522768155363a172643c2ca85504e) Verify that Cosmos received the test payload: go to Cosmos ([https://cosmos.augmentcode.com](https://cosmos.augmentcode.com)) > Settings > Automations > Event Log tab > Click on the last entry with Source = Webhook, you should see this: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-05.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=5f0d0658b31dc61a0a99995980590448) That confirms that Cosmos received the test payload. Now configure ClicksUp Automations to automatically call the Cosmos webhook when certain events occur in ClickUp. Go to ClickUp > Settings > Automations Manager > Manage tab > Click on Add Automation: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-06.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=9d87835e49e3a6a0632602a2a98af27e) Configure Trigger: **Task or subtask created**, and Action: **Call webhook** with Webhook: **Cosmos**, then click on Create: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-07.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=983bb48a1eaaae5f10e5cde130bce91e) Click again on Add Automation > Trigger: **Task type changed** (From Any Task Type(s) to Any Task Type(s)), and Action: **Call webhook** with Webhook: **Cosmos**, then click on Create: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-08.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=729f8d981899101a15c252b59400a02f) Click again on Add Automation > Trigger: **Status changed** (From Any Status to Any Status), and Action: **Call webhook** with Webhook: **Cosmos**, then click on Create: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-09.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=baa5ca5a17d2fce8ac9a946980f74e7f) Click again on Add Automation > Trigger: **Comment added**, and Action: **Call webhook** with Webhook: **Cosmos**, then click on Create: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-10.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=af3a2d0ba6d14b41b2f395ecfd9d8c78) Rename your automations as **Notify Cosmos On \**: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-11.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=f94de5ddd47885cc33f50d9e076d3650) Create a new test ClickUp task: ClickUp Home > Click on + > Select your project, enter Name: **TestTask02**, then click on Create Task: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-12.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=27949e7da1dd294e7fc5678aad82ea7a) Verify that Cosmos received the payload: go to Cosmos ([https://cosmos.augmentcode.com](https://cosmos.augmentcode.com)) > Settings > Automations > Event Log tab > Click on the last entry with Source = Webhook, you should see this: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-13.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=a4976afb559c44f6f8cbab0125c81d1d) That confirms that Cosmos received the payload. At this point ClickUp will automatically notify Cosmos whenever a task is created/updated/commented on ✅ ## **Step 2: Integrate with ClickUp via a Service Account** For Cosmos to interact with ClickUp via a ClickUp service account we’ll leverage the ClickUp remote MCP server and authenticate it with said service account as we’d want Cosmos to run headless automations. Do NOT authenticate the remote MCP server using your human identity, use the dedicated service account user instead. As a ClickUp admin, create a dedicated service account user by going to Settings > Admin > People > Invite people > Enter Email: ex: **[augment@mycompany.com](mailto:augment@mycompany.com)** (you may have to create this email alias on your real admin email so you can receive and accept the invite). In an incognito window > Accept the ClickUp invite and login in ClickUp as **[augment@mycompany.com](mailto:augment@mycompany.com)**. In that incognito window > sign in in Cosmos as admin ([https://cosmos.augmentcode.com](https://cosmos.augmentcode.com)) > Settings > Connectors > Browse Connectors > search **ClickUp**: ![Image](https://mintcdn.com/augment-mtje7p526w/HEaes7Rs5TKLeUUz/images/image-36.png?fit=max\&auto=format\&n=HEaes7Rs5TKLeUUz\&q=85\&s=1e8990ed00b76bccdf69458679c9ca2d) Click on the + next to ClickUp, you should be redirected to a ClickUp consent screen > select the Workspace to grant access to, then click on Connect Workspace: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-15.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=c409c0117634da93f78e6a0198b90bd5) You should then be redirected back to the ClickUp MCP view in Cosmos. Make sure Clients **Cosmos and CLI are toggled on**, then save. Open **Sharing → Manage access**, grant **Can use** to the intended recipients (or **Everyone → Can use** for organization-wide use), and save the access changes. If prompted, choose **Shared connection** only if those recipients should use the service account's ClickUp permissions. > [!NOTE] > > The screenshot below shows the older **Shared** toggle. Use [Manage access](/cosmos/config-mcp#sharing-an-mcp-server) in the current UI. If you reference a separately created generic secret, configure its use access and **Used in** coverage independently. ![Image](https://mintcdn.com/augment-mtje7p526w/HEaes7Rs5TKLeUUz/images/image-37.png?fit=max\&auto=format\&n=HEaes7Rs5TKLeUUz\&q=85\&s=f0f3c08d6b03e50c2b986033e464f952) Hover over Connected > Click on Test connection: ![Image](https://mintcdn.com/augment-mtje7p526w/HEaes7Rs5TKLeUUz/images/image-38.png?fit=max\&auto=format\&n=HEaes7Rs5TKLeUUz\&q=85\&s=9b5fb5944bd7fa5058e3051fc42b5551) Select tool: **clickup\_filter\_tasks**, then click on Run test call ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-18.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=fa0c950cf488dab40d1e0401a0b7b8f3) You should see this: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-19.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=23c56648550bfb7c69ec00e31e718e25) ## Step 3 - Final Test Now test the end2end connectivity with a **new Cosmos session in the target Space, as an intended recipient**, using that remote MCP server. An owner-only test or an existing session does not verify the recipient's access. Do not print credential values. If you don’t have a Cosmos cloud environment yet, create an empty one for this test: Cosmos > Settings > Environment > Create an environment > Cloud Machine > Name: Test01 > Click on Create Environment. Go to Cosmos [https://cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New session > make sure the ClickUp remote MCP server is selected: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-20.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=1120e9d2452f6036355d3be590c03652) Submit this prompt **List the 10 most recent clickup tasks**. In your session’s right drawer you should see the ClickUp MCP tools, and in your session the list of tasks: ![](https://mintcdn.com/augment-mtje7p526w/Li1Y4coQkhgYOrJE/images/cosmos-integrations/clickup/clickup-21.png?fit=max\&auto=format\&n=Li1Y4coQkhgYOrJE\&q=85\&s=3c2b34564c1cdf8bd3a9c688a0c5b1fd) Congrats, you can now create Cosmos expert agents that integrate with ClickUp! 🎉 # Using GitHub as a Tool or Trigger Source: https://docs.augmentcode.com/cosmos/connectors/config-github Configure GitHub triggers and the GitHub API tool on your Cosmos Experts — listen for PRs, pushes, CI failures, and slash commands. Connect GitHub to let your Cosmos Experts work with repositories, pull requests, and issues. Use the GitHub API tools during a session, or create an automation that starts an Expert when a PR, push, CI failure, or comment arrives. ## Prerequisites Choose a connection based on the identity your Expert should use: | Connection | Capability | Identity | When to use | | - | - | - | - | | **GitHub App** | `GITHUB_APP` | Augment's bot identity | Expert posts as Augment — acts as a tenant-wide bot identity across every repository in your organization | | **GitHub personal OAuth** | `GITHUB` | The session owner's GitHub identity | Expert acts as the human user who triggered it — e.g. a personal review Expert running under your own credentials | ### Connect the GitHub App A Cosmos tenant admin must set up the team connection. The installer also needs permission to install the App on the target GitHub organization. 1. Open **Settings → Connectors → Browse Connectors** and search for **GitHub**. 2. Select the **GitHub App** connector and click **Add installation**. If GitHub Enterprise Cloud configuration is also shown, choose **Add GitHub.com installation**. 3. Complete the GitHub installation flow for the Augment Code GitHub App and select the repositories it can access. 4. Return to the connector page and click **Refresh** to check the installation and repository list. > [!NOTE] > > Installing the App does not automatically grant access to every repository. To change repository access later, open the installation's actions menu (3 dots) on the connector page, choose **Open on GitHub**, and update the repository selection there. ### Connect your personal GitHub account 1. Open **Settings → Personal → Linked Accounts**. 2. On the **GitHub** card, click **Connect** and complete the OAuth flow. The App and personal connections are separate and can coexist. Connecting your personal account does not replace the App installation needed for GitHub automations. For self-hosted GitHub, see [GitHub Enterprise Server](/cosmos/connectors/github-enterprise-server). ## Enabling GitHub as a Tool on an Expert 1. Open **Settings** > **Experts**, select your Expert, and edit it. 2. In **Tools → Integrations**, turn off **Automatically include all managed integrations** if you want to choose specific integrations. 3. Select **GitHub App** for the shared bot connection, or the personal GitHub integration to act as the session owner. 4. Save the Expert. The selected integration determines authentication and the tool name: * **GitHub App** → **`github-app-api`**, authenticated with the GitHub App installation token * **Personal GitHub** → **`github-api`**, authenticated with the session owner's OAuth token Both tools accept the same input shape: ```json theme={null} { "path": "/repos/{owner}/{repo}/pulls/{number}/reviews", "method": "POST", "data": { "body": "LGTM", "event": "APPROVE" }, "summary": "Approve PR #1234" } ``` `method` defaults to `GET`. `summary` is required and surfaces in run logs and the Expert UI. Set `details: true` to receive the full GitHub response payload instead of the trimmed default. > [!NOTE] > > GitHub's `/issues` endpoints return both issues **and** pull requests. Filter on `pull_request != null` in the response if you only want one or the other. ## Configuring GitHub Triggers > [!NOTE] > > You shouldn't manually edit triggers. Always use [Cosmos Advisor](https://docs.augmentcode.com/cosmos/guides/getting-started-on-cosmos) for that. Connect the GitHub App and save an Expert with the GitHub App integration before creating a trigger. 1. Open **Settings** > **Automations** and click **Create automation**. 2. Select the existing **Expert** you want to run. 3. Choose **GitHub** as the **Trigger source** and enter a **Trigger name**. 4. Select an **Event** using a GitHub webhook event name from the list below. If the event is not a preset, choose **Custom event type** and enter its name, such as `issue_comment`. 5. Optionally add a **Filter** — a [JSONLogic](https://jsonlogic.com) expression evaluated against the raw GitHub webhook payload. The trigger fires only when the filter returns true. 6. Click **Save**. To add another trigger to the same Expert, open **Settings** > **Automations**, expand its automation, and click **Add trigger**. See [Configuring Triggers](/cosmos/config-triggers) for permissions and other trigger settings. Top-level keys available to filter on vary by event type, but commonly include: `action`, `repository`, `sender`, `pull_request`, `issue`, `comment`, `ref`, `head_commit`, `workflow_run`, `installation`. **Available event types:** * **Pull requests**: `pull_request`, `pull_request_review`, `pull_request_review_comment` * **Issues**: `issues`, `issue_comment` * **Code**: `push` * **CI / checks**: `check_suite`, `status`, `workflow_run`, `workflow_job`, `workflow_dispatch` ### PRs Ready for Review Pick **Event type** `pull_request` and use this filter to fire on direct opens of non-draft PRs and on `ready_for_review` transitions out of draft: ```json theme={null} {"or": [ {"==": [{"var": "action"}, "ready_for_review"]}, {"and": [ {"==": [{"var": "action"}, "opened"]}, {"==": [{"var": "pull_request.draft"}, false]} ]} ]} ``` ### Push to main Pick **Event type** `push` and filter on the ref and repository: ```json theme={null} {"and": [ {"==": [{"var": "ref"}, "refs/heads/main"]}, {"==": [{"var": "repository.full_name"}, "myorg/myrepo"]} ]} ``` ### Slash Command in a PR or Issue Comment To match `/augment ` in a comment, pick **Event type** `issue_comment` and filter: ```json theme={null} {"and": [ {"==": [{"var": "action"}, "created"]}, {"in": ["/augment ", {"var": "comment.body"}]}, {"!": [{"==": [{"var": "comment.user.type"}, "Bot"]}]} ]} ``` > [!WARNING] > > The bot-type guard is critical here. If your Expert posts comments back via the GitHub API tool, those comments will themselves be delivered as `issue_comment` events — without the filter you'll create a feedback loop. ### Workflow Failure on main Pick **Event type** `workflow_run` and filter on the conclusion and branch: ```json theme={null} {"and": [ {"==": [{"var": "action"}, "completed"]}, {"==": [{"var": "workflow_run.conclusion"}, "failure"]}, {"==": [{"var": "workflow_run.head_branch"}, "main"]} ]} ``` ### Common Filter Recipes ```json theme={null} // Action filtering {"==": [{"var": "action"}, "opened"]} {"in": [{"var": "action"}, ["opened", "reopened", "synchronize"]]} // Repository / org scoping {"==": [{"var": "repository.full_name"}, "myorg/myrepo"]} {"==": [{"var": "repository.owner.login"}, "myorg"]} // Branch and ref scoping {"==": [{"var": "ref"}, "refs/heads/main"]} {"==": [{"var": "pull_request.base.ref"}, "main"]} // Label match (pull_request.labels is an array of objects) {"some": [{"var": "pull_request.labels"}, {"==": [{"var": "name"}, "needs-review"]}]} // Skip events authored by the Augment bot (avoid feedback loops) {"!": [{"==": [{"var": "sender.login"}, "augment-app[bot]"]}]} ``` > [!TIP] > > A typo like `pulll_request.draft` silently never matches and the trigger will look broken. Open **Settings** > **Automations → Event Log tab**, filter by **GitHub**, and use **Advanced Filter** to select the event type. Inspect a captured payload to confirm your field paths and filter before saving the trigger. ## Disabling GitHub Access You can scale back GitHub access at three levels, from least to most disruptive: 1. **Pause or remove a trigger.** Open **Settings** > **Automations**, select the automation, and use its **Triggers** controls to disable or remove the trigger. The Expert keeps its GitHub API tool. 2. **Remove GitHub from an Expert.** Disable or remove its GitHub triggers first. Open **Settings** > **Experts** and edit the Expert. Under **Tools → Integrations**, turn off **Automatically include all managed integrations** if enabled, deselect the GitHub integration, and save. 3. **Remove a connection.** For personal OAuth, click **Disconnect** on the GitHub card in **Settings → Personal → Linked Accounts**. For the team App, open **Settings → Connectors**, select **GitHub App**, and use the installation's actions menu to **Open on GitHub** and uninstall the App. An admin can also choose **Remove installation** and complete the confirmation. Removing an installation affects every Expert and automation that relies on it. # Using Linear as a Tool or Trigger Source: https://docs.augmentcode.com/cosmos/connectors/config-linear Configure Linear triggers and the Linear API tool on your Cosmos Experts — listen for issues, status changes, and comments. Cosmos can plug into Linear as both a trigger source and a writable API. Listen for new issues, state changes, or slash-style comments; respond by reading or writing through `linear-api`. ## Prerequisites Linear has two integration flavors. Pick the one that matches how your Expert should act: | Flavor | Capability | When to use | | - | - | - | | **Linear App (team install)** | `LINEAR_APP` | Expert reads and writes Linear data using a team-level token shared across all Experts in the tenant | | **Linear user OAuth** | `LINEAR` | Expert posts as the author who triggered it — e.g. a personal triage Expert running under your own credentials | To connect a team-wide install: 1. Go to **Settings → Capabilities → Integrations** from the Cosmos menu. 2. On the **Linear** tile, click **Connect** and complete the Linear Agent install flow. To connect personal Linear OAuth: 1. Open **Settings → Personal → Linked Accounts** from the user menu. 2. On the **Linear** card, click **Connect** and complete the OAuth flow. To remove a connection later, click **Disconnect** on the corresponding tile, or revoke the install from Linear's **Settings → API → Applications** page. You can connect both — `LINEAR_APP` and `LINEAR` are independent, and different Experts in the same tenant can use either. ## Enabling Linear as a Tool on an Expert In the Expert editor, the **Capabilities** section lists every capability you can grant the Expert. Toggle on **Linear App** (or **Linear** for per-user) and save. Saving adds the `linear-api` tool to the Expert — a thin wrapper around Linear's GraphQL API. Nothing else to configure. The capability mode determines authentication: * **Linear App** — requests are signed with the team-level Agent token * **Linear** — requests are signed with the invoking user's OAuth token ## Configuring Linear Triggers Linear triggers are added from the **Triggers** section of the Expert editor. Pick **Linear** as the trigger type, set **Event type** to a Linear webhook `type` value (see below), and (optionally) write a **Filter** — a [JSONLogic](https://jsonlogic.com) expression evaluated against the raw Linear webhook payload. The trigger fires only when the filter returns true. Top-level keys available to filter on: `action`, `type`, `data`, `url`, `createdAt`, `organizationId`, `webhookTimestamp`, `webhookId`. **Available event types:** * `Issue`, `Comment`, `IssueLabel`, `Project`, `ProjectUpdate`, `Cycle`, `Reaction`, `Attachment` — each with `action` ∈ `create`, `update`, `remove` ### Triage Every New Issue in a Specific Team Pick **Event type** `Issue` and filter on the action and team key: ```json theme={null} {"and": [ {"==": [{"var": "action"}, "create"]}, {"==": [{"var": "data.team.key"}, "BUG"]} ]} ``` ### React to a Status Change Pick **Event type** `Issue` and filter on the new state name: ```json theme={null} {"and": [ {"==": [{"var": "action"}, "update"]}, {"==": [{"var": "data.state.name"}, "In Review"]} ]} ``` ### Slash-Style Command in Comments Pick **Event type** `Comment` and match on the comment body: ```json theme={null} {"and": [ {"==": [{"var": "action"}, "create"]}, {"in": ["/spec", {"var": "data.body"}]} ]} ``` ### Common Filter Recipes ```json theme={null} // Action filtering {"==": [{"var": "action"}, "create"]} {"in": [{"var": "action"}, ["create", "update"]]} // Team / project / cycle scoping {"==": [{"var": "data.team.key"}, "ENG"]} {"==": [{"var": "data.project.id"}, ""]} {"==": [{"var": "data.cycle.number"}, 42]} // State and priority {"==": [{"var": "data.state.name"}, "In Progress"]} {"<=": [{"var": "data.priority"}, 2]} // Urgent or High // Label match {"some": [{"var": "data.labels"}, {"==": [{"var": "name"}, "security"]}]} // Skip the bot's own actions (avoid feedback loops) {"!": [{"==": [{"var": "data.user.email"}, "agent@your-tenant.com"]}]} ``` > [!TIP] > > A typo like `data.statee.name` silently never matches and the trigger will look broken. To test a filter against real Linear events, go to **Settings → Automations → Event Log**, filter by source = Linear and the event type you care about, and inspect the payload before saving the trigger. ## Disabling Linear Access You can scale back Linear access at three levels, from least to most disruptive: 1. **Remove a single trigger.** Delete the trigger row from the Expert editor and save. The Expert keeps the `linear-api` tool but no longer wakes up on that event. 2. **Remove the Linear capability.** Toggle off **Linear App** (or **Linear**) in the Expert's **Capabilities** section. The Expert loses the `linear-api` tool and any remaining Linear triggers will be rejected when you save. 3. **Disconnect the integration.** From **Settings → Capabilities → Integrations**, click **Disconnect** on the **Linear** tile, or revoke the install from Linear's **Settings → API → Applications** page. This revokes the token for every Expert in the tenant using that capability. # Using Slack as a Tool or Trigger Source: https://docs.augmentcode.com/cosmos/connectors/config-slack Configure the Augment Slack bot for Cosmos Experts — enable Slack as a tool, set up triggers, and interact with agents from Slack channels. The webapp and mobile aren't the only ways into Cosmos. `@Augment` lives in your Slack workspace and can do most of what a session can: answer codebase questions, open PRs, run scheduled workflows, without anyone ever opening a browser. ## Prerequisites A tenant admin must connect the Augment Slack app to your workspace before any Expert can use Slack: * Go to Cosmos [https://cosmos.augmentcode.com/](https://cosmos.augmentcode.com/) → **Settings → Connectors → Browse Connectors → Search for slack**. ![Image](https://mintcdn.com/augment-mtje7p526w/EqcqZC4PK3ssFG-2/images/image-44.png?fit=max\&auto=format\&n=EqcqZC4PK3ssFG-2\&q=85\&s=1ad938566edc2ac226da2407c75dacb5) * Click on the **Slack** tile, then click **Connect** to launch the Slack OAuth flow and install the bot into your workspace. ![Image](https://mintcdn.com/augment-mtje7p526w/EqcqZC4PK3ssFG-2/images/image-45.png?fit=max\&auto=format\&n=EqcqZC4PK3ssFG-2\&q=85\&s=5f496ed6e1b9228470041577a30ce88c) After install, invite the bot into each channel you want the Expert to act in: ```text theme={null} /invite @Augment ``` The Slack bot must be a member of a channel before it can read history, post messages, or add reactions there. ## Enabling Slack as a Tool on an Expert In the Expert editor, the **Capabilities** section lists every capability you can grant the Expert. Toggle on **Slack** and save. Cosmos automatically wires up the `slack-api` tool, no further setup required. Once saved, the Expert can call Slack methods including `chat.postMessage`, `chat.update`, `conversations.history`, `conversations.replies`, `reactions.add`, and `users.info`. > [!NOTE] > > Tokens are tenant-scoped: every Expert in your tenant uses the same Augment bot user when calling Slack. ## Configuring Slack Triggers Slack triggers are added from the **Triggers** section of the Expert editor. Pick **Slack** as the trigger type, set **Event type**, and (optionally) write a **Filter**: a [JSONLogic](https://jsonlogic.com) expression evaluated against the raw Slack event payload. The two most useful event types are: * `app_mention` — fires only when someone explicitly mentions `@Augment` * `message` — fires on every message in a channel the bot is in > [!WARNING] > > An `@-mention` is delivered **twice** — once as `app_mention` and once as `message`. Always include an `event.type` clause in your **Filter** to avoid your Expert firing twice on the same message. ### Respond to @Augment Mentions Pick **Event type** `app_mention` and filter on the channel: ```json theme={null} {"and": [ {"==": [{"var": "event.channel"}, "C0123456789"]}, {"==": [{"var": "event.type"}, "app_mention"]} ]} ``` ### Triage Every New Top-Level Message in a Channel Pick **Event type** `message`, turn off **Auto-archive sessions created by this trigger**, and use this filter: ```json theme={null} {"and": [ {"==": [{"var": "event.channel"}, "C0123456789"]}, {"==": [{"var": "event.type"}, "message"]}, {"!": [{"var": "event.thread_ts"}]}, {"!": [{"var": "event.bot_id"}]} ]} ``` The filter above targets a specific channel, only `message` events (avoiding the duplicate `app_mention` delivery), only top-level messages (no `thread_ts`), and skips messages the bot itself posted (no `bot_id`). Turning off auto-archive keeps the session alive across thread replies so follow-up messages reach the same Expert run. ### Common Filter Recipes ```json theme={null} // Only direct messages to the bot {"==": [{"var": "event.channel_type"}, "im"]} // Only messages from a specific user {"==": [{"var": "event.user"}, "U0123ABCDE"]} // Only thread replies (not the root message) {"and": [ {"!!": [{"var": "event.thread_ts"}]}, {"!=": [{"var": "event.thread_ts"}, {"var": "event.ts"}]} ]} ``` ## Workflow and Push Slack Notifications Cosmos workflows can be configured to post results to Slack channels when Experts complete tasks triggered by external events. **Use cases:** * **Ticket-to-PR automation**: Linear ticket assigned → agent creates PR → summary posted to Slack * **CI failure resolution**: CI fails → agent investigates and posts fix PR link to the team channel * **Scheduled reports**: Daily cron → agent generates a summary → posts to Slack ## Putting the Expert to Work Inside Your Slack Channel Slack is just a surface, there is no built-in `@Augment` bot persona. To make `@Augment` respond in a channel you need an Expert that: 1. Has the **Slack** capability enabled in its **Capabilities** section. 2. Has an `app_mention` trigger configured (see [Respond to @Augment Mentions](#respond-to-augment-mentions) above) that scopes the Expert to the channels you want it active in. 3. Has a system prompt that tells it how to behave when mentioned (e.g. "answer codebase questions in-thread", "open a PR that fixes the issue", etc.). Then `/invite @Augment` into each channel you want to use it from. Once invited, mentioning `@Augment` will fire the trigger and start an Expert session that posts back in-thread. What it actually does in there is whatever its system prompt tells it to do. ### Known Limitations | Limitation | Details | | - | - | | **Bot-owned agents** | Agents created via Slack are owned by the bot user, not the triggering Slack user. The Slack thread is the primary UI, you won't see "your" agent in the Cosmos web app. | ## Disabling Slack Access You can scale back Slack access at three levels, from least to most disruptive: 1. **Remove a single trigger.** Delete the trigger row from the Expert editor and save. The Expert keeps the `slack-api` tool but no longer wakes up on that event. 2. **Remove the Slack capability.** Toggle off **Slack** in the Expert's **Capabilities** section. The Expert loses the `slack-api` tool and any remaining Slack triggers will be rejected when you save. 3. **Disconnect the workspace.** From **Settings → Connectors → Slack → Manage** → **Disconnect**, or remove the Augment Slack app from your workspace's **Apps → Manage** page. This revokes the bot token for every Expert in the tenant. # Integrate Datadog Source: https://docs.augmentcode.com/cosmos/connectors/datadog Connect Datadog to Cosmos with webhooks and the Datadog MCP server so experts can respond to monitoring events and read logs. ## Introduction In this page we’ll learn how to configure 2 things: * Get Datadog to push events to Augment Cosmos via webhooks ```mermaid theme={null} sequenceDiagram autonumber participant J as Datadog participant AC as Augment Code | Cosmos J->>AC: Webhook: Issue Created (Ticket JSON) ``` * Get Augment Cosmos to interact with Datadog via the Datadog MCP server ```mermaid theme={null} sequenceDiagram autonumber participant J as Datadog participant AC as Augment Code | Cosmos AC->>J: Read logs via Datadog MCP server J-->>AC: 200 OK (Sync Complete) ``` ## Prerequisites * Cosmos side: any user who can self-create webhooks and MCP servers * Datadog side: any user with **Datadog Admin Role** or at least those permissions: * To create a service account: **Service Account Write** and \*\*User Manage Access \*\*permissions * To create an Organization API key: **API Keys Write** and **User Application Keys Write** permissions * To configure a webhook: **Integrations Manage** permission ## Step 1 - Configure Datadog to notify a Cosmos Webhook Let’s create a new webhook in Cosmos (so Cosmos can listen to Datadog events). Configuration steps: * Go to Cosmos ([https://cosmos.augmentcode.com](https://cosmos.augmentcode.com)) > Settings > Webhooks > Create Webhook > Custom Webhook * Description “Datadog” * Type: Bearer Token * Keep Shared toggled on ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-01.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=f1eb25f0f135f0015fe03e11d174eee8) * That gives us a url to POST with a given Bearer token to pass as HTTP header. Curl request would look like: ```shell theme={null} curl -X POST https://XXX.api.augmentcode.com/webhooks/XXX \ -H "Authorization: Bearer XXX" \ -H "Content-Type: application/json" \ -d '{"event": "test", "data": "your payload here"}' ``` Create a new webhook config in Datadog (so Datadog can POST to a given url when certain Datadog events occur): * In Datadog * Go to Integrations > search for Webhooks (ex: [https://us5.datadoghq.com/integrations?search=webhook\&integrationId=webhooks](https://us5.datadoghq.com/integrations?search=webhook\&integrationId=webhooks)) > Configure tab ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-02.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=28db5ca6f60438e8313437cf34e7d11e) ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-03.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=01af8f0225091ad420fb64cb8f65baa4) * Variables tab > New Variable and create variable **\$AUTH\_BEARER\_TOKEN** with value **Bearer \** ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-04.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=a0860a1d0e845b7f7dbed29949fad3f8) * Webhooks tab > New > Add > Enter the Cosmos webhook url, keep auth method empty, select Custom header and add ```plain text theme={null} { "Authorization": "$AUTH_BEARER_TOKEN" } ``` ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-05.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=e50a065cb21c741e7cda900d3f1fe429) * Click on Save Now let’s run a test with a Datadog monitor: * Datadog home > Monitoring > New monitor ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-06.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=8dcd096711a8deaff136d80a04ee2462) * Enter those parameters * detection method: **Threshold Alert** * Set alert conditions > Alert threshold > enter value “**1**” * Configure notifications & automations * Monitor name: Test Cosmos webhook config * Edit section: type in @ and select your webhook name in the drop down list ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-07.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=6159fa2eea2cced6d4247c3b1d9c1932) * Now click on Test Notifications > Run Test ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-08.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=b8798dc5b401e1ed6b1f7ab669ac87cb) Now let’s check that Cosmos received that event. * Go to Cosmos [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Automations > Event Log tab. You should see a new Custom.webhook entry ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-09.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=3d9021e38b816fe6e9d261dfc81a66fd) * Click on that event entry and you’ll see the test payload from Datadog ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-10.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=899b9730a0b3edfaf08262961723d3ee) At this point Datadog can invoke Cosmos ✅ ## Step 2: Integrate with Datadog via a Service Account For Cosmos to interact with Datadog via a Datadog service account we’ll leverage the Datadog remote MCP server and authenticate it with said service account as we’d want Cosmos to run headless automations. We’ll need 3 parameters: * A Datadog tenant region * A Datadog organization API key * A Datadog service account application key You should be able to tell what is your Datadog region from the dashboard url. If it’s [https://us5.datadoghq.com/monitors/create/metric](https://us5.datadoghq.com/monitors/create/metric) then your region is us5. We’ll use that value for the rest of this tutorial, just remember to replace it with yours. Now let’s create an organization API key: * Click on your username bottom left > Organization Settings > API Keys ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-11.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=521ceab56e5b99139890088007c77aff) * Click on New Key > Enter name: Cosmos > Create Key ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-12.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=b6eb23188cd410cebfd2dbfd5fa5d1f6) Copy your API Key, we’ll need it later on. Now let’s create a service account application key: * Click on your username bottom left > Organization Settings > Service Accounts ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-13.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=c815f1ef5094d6070ea6d172f7db5934) * Click on New Service Account > Enter a name, email, assign role \*\*Datadog Read Only Role \*\*> Create Service acccount ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-14.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=040d6cf4ec2c07bba3527372821c2786) * In the section Application Keys > Click on New Key > Name: Cosmos > Click on Create Key ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-15.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=bfbe0ee0d53aa2f8390e32118c502e81) * Stay on that view. In front of Scopes click on Edit > make sure that all those scopes are selected: * **mcp\_read** * **monitors\_read** * **dashboards\_read** * **metrics\_read** * **events\_read** * **logs\_read\_data** * **incident\_read** * Then click on Save. You should see this: ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-16.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=1867985ea15e71671e3f3ccdb08822d9) * Click on Copy to copy the application key (we’ll need it shortly), then click on Finish. Your Service account view should look like this: ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-17.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=b7bba632bee14b6e20927f784786dada) Now, let’s verify that your Datadog parameters are valid. Open a terminal on your laptop, edit and run this command (make sure to also edit your instance region in the url): ```bash theme={null} curl -s -w "\n%{http_code}" \ -X POST \ -H "DD-API-KEY: " \ -H "DD-APPLICATION-KEY: " \ -H "Content-Type: application/json" \ "https://mcp.us5.datadoghq.com/api/unstable/mcp-server/mcp" \ -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' ``` If everything is properly configured, you’ll get a 200 response. If you don’t, stop and review again the instructions above. Now you’re ready to configure the Datadog MCP server in Cosmos. * Go to Cosmos [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Connectors > Add Connector > MCP > Select Remote MCP * Name: **Datadog** * Server URL: **[https://mcp.us5.datadoghq.com/api/unstable/mcp-server/mcp](https://mcp.us5.datadoghq.com/api/unstable/mcp-server/mcp)** (make sure to edit your instance region) * Authentication Type: Header > Add those 2 headers * **DD-API-KEY**: \ * **DD-APPLICATION-KEY**: \ * Add Server ![Image](https://mintcdn.com/augment-mtje7p526w/fWRFzW3DNSyEIhom/images/image-42.png?fit=max\&auto=format\&n=fWRFzW3DNSyEIhom\&q=85\&s=1ae9c0d06123165f17097b228b0b1021) * Make sure **Clients Cosmos and CLI are toggled on**, then click on Save changes. * Open **Sharing → Manage access**, grant **Can use** to the intended recipients (or **Everyone → Can use** for organization-wide use), and save the access changes. If prompted, choose **Shared connection** only if those recipients should use the service account's Datadog permissions. > [!NOTE] > > The screenshot below shows the older **Shared** toggle. Use [Manage access](/cosmos/config-mcp#sharing-an-mcp-server) in the current UI. If the headers reference separately created generic secrets, configure each secret's use access and **Used in** coverage independently. ![Image](https://mintcdn.com/augment-mtje7p526w/fWRFzW3DNSyEIhom/images/image-43.png?fit=max\&auto=format\&n=fWRFzW3DNSyEIhom\&q=85\&s=66bfaaf58336abba773abb85cf82c8ac) Now test end2end connectivity with a **new Cosmos session in the target Space, as an intended recipient**, using that MCP server. An owner-only test or an existing session does not verify the recipient's access. Do not print credential values. * Go to Cosmos [https://cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New session * Make sure the Datadog MCP server is selected ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-19.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=7235011614a2c84c99368b01f3473022) * Submit this prompt “What tools can I access with the connected datadog mcp? what user/service account it is using?”. In your session’s right drawer you should see the Datadog MCP tools: ![](https://mintcdn.com/augment-mtje7p526w/yIfhAqnm6fBz5VQx/images/cosmos-integrations/datadog/datadog-20.png?fit=max\&auto=format\&n=yIfhAqnm6fBz5VQx\&q=85\&s=42760a735050692c96a0d2524cb42fa9) Congrats, you can now create Cosmos expert agents that integrate with Datadog! 🎉 # Integrate GitHub Enterprise Server (GHES) Source: https://docs.augmentcode.com/cosmos/connectors/github-enterprise-server Connect GitHub Enterprise Server to Cosmos with webhooks, a daemon, and the GitHub CLI to automate pull request reviews on your infrastructure. ## Introduction In this page you'll learn how to configure those items: 1. Get GHES to push events (ex: “new PR created”) to Cosmos via webhooks 2. Configure a Cosmos Daemon on a VM (where the GHES local repos will be cloned locally) 3. Get Cosmos to interact with GHES via the `gh` cli 4. Deploy your first Cosmos PR experts and v1.0 software factory Below is the flow showing how a PR deep code reviewer expert will automatically trigger when a PR is created: ```mermaid theme={null} sequenceDiagram autonumber participant A as Augment Code | Cosmos participant VM as VM participant GIT as GitHub Enterprise Server (GHES) GIT->>A: Webhook: Pull Request created (PR payload) A->>VM: run experts locally via Daemon VM->>VM: Start Expert (spawn/run expert agent) VM->>VM: Expert analyzes PR (diff + context) VM->>GIT: POST PR comment (gh CLI: create comment) GIT-->>VM: 201 Created (comment posted) ``` Below is a high level architecture diagram of the components at play: ![Image](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/image-51.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=8b2dc4a12820d2254efe47609fc413e3) ## Prerequisites To configure the one-time connectivity between Cosmos and GHES: **Cosmos** * must be an admin to create a Augment service account and webhooks **GHES** * must have admin role to create a new user acting as service account * must be an enterprise owner (and owner of the organizations that owns the repos) to add the service account as collaborator on repos * allow inbound connections from other VMs on your VPC into GHES (inbound calls will come from within your network) **Your infra** * must have the ability to deploy VMs in a VPC that has network connectivity to your GHES. Must enable outbound network connectivity to \*.[augmentcode.com](http://augmentcode.com/) (see [https://docs.augmentcode.com/setup-augment/network-configuration](https://docs.augmentcode.com/setup-augment/network-configuration)) ## Step 1 - Configure GHES to notify a Cosmos Webhook ### Webhook receiver in Cosmos Let’s create a new webhook in Cosmos (so Cosmos can listen to GHES events): * As an admin go to Cosmos [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Webhooks > Create a webhook > Click on GitHub: ![Image](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/image-48.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=ed39d96c88ceb8e837107ca86a9dac64) * Enter Description: **GHES + \** > Click on Create ![Screenshot 2026 09 07 At 9 15 29 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-9.15.29-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=4e867338134fcb071bd50943c42a4c11) You'll obtain a Webhook URL and a Secret token. Copy them and click on Done: ![Image](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/image-56.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=233b959d787846af14e4e98c9381f704) ### Webhook sender in GHES GHES enterprise owners can create a global webhook to subscribe to events that occur within their enterprise (recommended). Alternatively you can create a global webhook per organization in your enterprise. Create a new webhook config in GHES (so GHES can POST to a given url when certain GHES events occur): as an Enterprise Owner, go to your GHES instance > click on your profile picture > click on Enterprise settings > Settings > Hooks > Add webhook > Add those details: * Payload URL: the webhook url provided by Cosmos * Content-Type: **application/json** * Secret token: the secret provided by Cosmos * Enable SSL verification: **keep it selected** * Which events would you like to trigger this webhook?: select **Let me select individual events** * Select those events: * **Check runs** * **Commit comments** * **Issue comment** * **Pull request review comments** * **Pull requests** * **Pull request reviews** * **Pushes** * **Statuses** * **Workflow runs** * Active: **keep it selected** * Click on Add webhook ![Image](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/image-55.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=4bd9ca04a8e644818bfa307e5bb15375) ![Image](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/image-58.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=738233493ff2299a04b4b16fc5143013) You should see a banner confirming the hook has been created and a test payload has been sent: ![Image](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/image-57.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=b66c9b60b8c294ead0363f964df41f44) Now go back to Cosmos and check that Cosmos received the event: [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Automations > Events Log. You should see your event with source “Webhook · Github”: ![Screenshot 2026 09 06 At 12 30 01 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-12.30.01-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=f2a0ce8e75307f6c524e82503e16f42c) Click on the event to inspect the test payload: ![Screenshot 2026 09 06 At 12 31 02 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-12.31.02-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=00bc30438bc695fd3b14fbd395f7ce01) At this point GHES will automatically notify Cosmos whenever a PR is created/updated/commented on ✅ ## Step 2 - Create a GHES Service Account For headless automation and to start agentic workflows based on GHES events, you’ll create a dedicated GHES user acting as service account. Cosmos will use its access token to authenticate to GHES. Here we'll assume you've configured SSO authentication for all your GHES users. Two steps to create your GHES dedicated service account user: * first, you need to provision the new user **[cosmos@yourcompanydomain.com](mailto:cosmos@yourcompanydomain.com)** in your identity provider (Okta, EntraID) * then in a separate browser, authenticate to GHES as **[cosmos@yourcompanydomain.com](mailto:cosmos@yourcompanydomain.com)**: you'll be redirected to SSO, and then back to GHES (your GHES account is automatically created when you sign in the first time) Now, this service account needs to be granted access to the GHES repos in scope, either at the enterprise level, or at the organization level, or per repo. If per repo: ask a human repo owner to navigate to the repo > Settings tab > Collaborators > Add people > invite the service account. The repo owner should now see the service account as a collaborator: ![Image](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/image-60.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=5c6f38cf32a289fdb6a480ed143d3b46) As you're signed-in using that GHES service account user, click on your avatar top right > Settings > Developer settings > Personal access tokens > Fine-grained tokens > Generate new token, with those details: * Token name: **cosmos-token-01** * Resource owner: keep the selection as the GHES dedicated service account user **[cosmos@yourcompanydomain.com](mailto:cosmos@yourcompanydomain.com)** * Expiration: pick the furthest date possible * Repository access: select the repos where **[cosmos@yourcompanydomain.com](mailto:cosmos@yourcompanydomain.com)** was added as collaborator earlier. * Permissions: * **Content**: `Read and write` * **Issues**: `Read and write` * **Metadata**: `Read-only` * **Pull requests**: `Read and write` * Click on Generate token ![Screenshot 2026 09 06 At 3 56 23 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-3.56.23-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=b013c3bb82e5e81d2fdbe839a6b88348) You should see this popup: ![Screenshot 2026 09 06 At 4 02 38 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-4.02.38-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=a174cdbc0ad65e1a6972cf6c66de5be0) Click on Generate token, you'll see your PAT token value. Copy it you'll need it later: ![Screenshot 2026 09 06 At 4 03 05 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-4.03.05-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=00c5b3545995bb844b76df7d024082e1) ## Step 3 - Create a Augment service account Before we start the websocket tunnel from your VM to Cosmos, you’ll need to create a dedicated Augment service account, which will be used to authenticate and start the tunnel. As an admin go to [https://app.augmentcode.com](https://app.augmentcode.com) > Global Settings > Service accounts > Add Service Account > Enter: * Account Name: **Daemon-on-VM-to-access-GHES** * Description: **Authenticate daemon pool from the VM that accesses GHES** Click on Add: ![Screenshot 2026 09 06 At 7 46 57 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-7.46.57-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=ef5f9fba5e884faaa8876105274593ed) ![Screenshot 2026 09 06 At 7 48 49 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-7.48.49-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=86949994fb08b19329c48c0137331ec6) Click on Add API Token > token name: **token01** > Click on Add: ![Screenshot 2026 09 06 At 7 52 39 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-7.52.39-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=f736dab9163fe0eb797c40178bf92b6d) Click on Download JSON: ![Screenshot 2026 09 06 At 7 50 28 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-7.50.28-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=c424c89749d9f54e74d60218a9aaf753) You'll obtain a session.json, it will be used to authenticate the Cosmos daemon pool later on. ## Step 4 - Create a Cosmos daemon pool Since you’ll be leveraging a VM to host your daemon, it’s important to think about uptime and resilience: your VM could loose network connectivity or have an outage. The best practice is to create a daemon pool and attach your daemons to that daemon pool. Then you can later have N daemons (1 per VM) all tied to the same daemon pool, and Cosmos will use that pool which will automatically route to the next available daemon. In this guide you’ll create 1 daemon pool and 1 daemon running in 1 VM, but you can extend that approach to spin up 2 more VMs (and their respective daemons) for max resilience. More VMs and daemons also mean scaling horizontally the number of Cosmos sessions running at a given time. Go to [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Environments > Create an environment > Daemon Pool: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-19.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=c12edc37c50a7bb4b217c083a3121874) Configure the pool with: * Name: **Team01-Pool-GHES** * Daemon connector: select the dedicated service account you created in the section earlier (**Daemon-on-VM-to-access-GHES)** * Shared: **toggle on** * Workspace behavior: `Isolated workspace` Then click on Create Pool: ![Screenshot 2026 09 06 At 7 57 22 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-7.57.22-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=7c99a5803a762cb38b55750b3323ac98) You’ll get the confirmation that the pool has been created, note the pool-id: ![Screenshot 2026 09 06 At 7 58 17 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-7.58.17-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=db4769310568ae4417d01a4e41536dbd) Go back to your list of environments, you should see your pool (with no daemon online yet): ![Screenshot 2026 09 06 At 7 59 48 PM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-06-at-7.59.48-PM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=a769d3bbaa17192439ece275d4157c45) ## Step 5 - Configure your VM with local GHES repos, gh cli and Cosmos daemon In this section you’ll configure a VM with the following: * locally cloned GHES repos * `gh` cli so Cosmos local agents can communicate to GHES * a Cosmos pool + daemon (to establish an outbound websocket tunnel from the VM to Cosmos) ### Create the VM, with git and NVM/node Create a new Linux VM (ex: Ubuntu x86\_64) in a VPC that will be able to reach your GHES instance. Minimum config recommended: **4 vCPU, 16 GB RAM, 100 GB SSD.** Then SSH onto the VM. Install git: ```shellscript theme={null} sudo apt update && sudo apt install git -y ``` Verify the installation ```bash theme={null} which git git --version ``` You should get: ```text theme={null} nico@gcp-vm-behind-firewall:~$ which git /usr/bin/git nico@gcp-vm-behind-firewall:~$ git --version git version 2.34.1 ``` Install NVM ```shellscript wrap theme={null} curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash ``` Refresh the terminal profile ```shellscript theme={null} source ~/.bashrc ``` Install the latest Long-Term Support (LTS) version of Node & NPM ```shellscript theme={null} nvm install --lts ``` Verify the node install ```bash theme={null} node -v npm -v ``` You should get: ```text theme={null} nico@gcp-vm-behind-firewall:~$ node -v v24.20.0 nico@gcp-vm-behind-firewall:~$ npm -v 11.19.0 ``` ### Git clone your GHES repos locally Create a local \~/workspace/ folder In that workspace folder create folders for your GHES organizations In the corresponding organization folders, git clone your repos (you need at a minimum an empty git repo with at least one commit for the git worktree configuration to be valid and for the agent to start) You should have a “2 layers” folder structure like this: * \~/workspace/\/\/.git * \~/workspace/\/\/.git * \~/workspace/\/\/.git * \~/workspace/\/\/.git > [!NOTE] > > Note: at this moment you have to own making sure that the git repos are locally cloned and are kept up to date regularly. In a future release, daemons will be able to handle that on your behalf - stay tuned ### Install and authenticate the gh CLI Install the `gh` cli: make sure you’re in your root folder, install the `gh` cli using this command (source [https://cli.github.com/](https://cli.github.com/)): ```shell wrap theme={null} (type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \ && sudo mkdir -p -m 755 /etc/apt/keyrings \ && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \ && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \ && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \ && sudo mkdir -p -m 755 /etc/apt/sources.list.d \ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \ && sudo apt update \ && sudo apt install gh -y ``` Verify the version, run: ```shellscript theme={null} gh --version ``` You should get: ```text theme={null} nico@gcp-vm-behind-firewall:~$ gh --version gh version 2.100.0 (2026-09-03) https://github.com/cli/cli/releases/tag/v2.100.0 ``` Then authenticate the `gh` cli against your GHES instance, run: ```shellscript wrap theme={null} echo "" | gh auth login --hostname --with-token ``` Then verify `gh` is properly authenticated, run: ```shellscript theme={null} gh auth status ``` You should see: ```plain text theme={null} nico@gcp-vm-behind-firewall:~$ gh auth status ghes.internal ✓ Logged in to ghes.internal account nico (/home/nico/.config/gh/hosts.yml) - Active account: true - Git operations protocol: https - Token: github_pat_******************************************************** ``` ### Start the daemon cd into \~/workspace/ Run ```shell theme={null} nano ~/.augment/session.json ``` Paste in there the content of session.json you retrieved earlier when creating the Augment service account. Then CTRL-O + RETURN to save the file and CTRL-X + RETURN to exit Install Auggie ```bash theme={null} npm install -g @augmentcode/auggie ``` Start the Cosmos daemon using the Augment service account and attach the daemon to the pool, run: ```shell wrap theme={null} auggie daemon --pool-id --discover-workspaces=2 --allow-indexing ``` That will start the daemon, you should see this: ```text theme={null} nico@gcp-vm-behind-firewall:~/workspace$ auggie daemon --pool-id pool-352df5e6-8b03-4c55-b622-32ce65e21bf8 --discover-workspaces=2 --allow-indexing 2026-09-07 14:12:41.582 [info] 'daemon': Git version: 2.34.1 (daemon minimum: 2.31.0) 2026-09-07 14:12:41.595 [info] 'git-worktree-support': Git worktree support unavailable; treating workspace as UNSUPPORTED 2026-09-07 14:12:41.614 [info] 'git-worktree-support': Git worktree support unavailable; treating workspace as UNSUPPORTED 2026-09-07 14:12:41.625 [info] 'daemon': Launch dir is a non-git container; adopting 1 discovered git repo(s) as workspaces: 2026-09-07 14:12:41.626 [info] 'daemon': Discovered workspace: /home/nico/workspace/nico/ecomm-stack (git) 2026-09-07 14:12:41.626 [info] 'daemon': Git worktree support: supported 2026-09-07 14:12:41.634 [info] 'DaemonState': Loaded existing daemon state with VM ID: 7f6ae36c-f3a6-4e06-93ea-946d3a43a70b 2026-09-07 14:12:41.635 [info] 'daemon': Loaded VM ID from state: 7f6ae36c-f3a6-4e06-93ea-946d3a43a70b 2026-09-07 14:12:41.635 [info] 'daemon': Joining daemon pool: pool-352df5e6-8b03-4c55-b622-32ce65e21bf8 2026-09-07 14:12:41.645 [info] 'daemon': Daemon auto-update is DISABLED because it is gated by the cli_daemon_auto_update_enabled feature flag, which is off for this account 2026-09-07 14:12:41.646 [info] 'daemon': Configured 1 additional workspace(s): 2026-09-07 14:12:41.646 [info] 'daemon': Additional workspace: /home/nico/workspace/nico/ecomm-stack (git) 2026-09-07 14:12:41.649 [info] 'daemon': Indexing enabled for workspace: /home/nico/workspace 2026-09-07 14:12:41.649 [info] 'daemon': Indexing enabled for workspace: /home/nico/workspace/nico/ecomm-stack 2026-09-07 14:12:41.650 [info] 'daemon': Starting Auggie Daemon... 2026-09-07 14:12:41.650 [info] 'daemon': VM ID: 7f6ae36c-f3a6-4e06-93ea-946d3a43a70b 2026-09-07 14:12:41.650 [info] 'daemon': Name: gcp-vm-behind-firewall:workspace 2026-09-07 14:12:41.650 [info] 'daemon': Workspace: /home/nico/workspace 2026-09-07 14:12:41.650 [info] 'daemon': Max Agents: 100 2026-09-07 14:12:41.650 [info] 'daemon': Additional Workspaces: 1 2026-09-07 14:12:41.650 [info] 'daemon': - /home/nico/workspace/nico/ecomm-stack 2026-09-07 14:12:41.652 [info] 'daemon': Connecting to Cosmos... 2026-09-07 14:12:41.652 [info] 'daemon': URL: wss://e2.api.augmentcode.com/cloudagents/vm/ws?vm_id=7f6ae36c-f3a6-4e06-93ea-946d3a43a70b&last_seq_id=0&connection_type=AUGGIE_DAEMON&daemon_name=gcp-vm-behind-firewall%3Aworkspace&max_agents=100&workspace_path=%2Fhome%2Fnico%2Fworkspace&additional_workspace_path=%2Fhome%2Fnico%2Fworkspace%2Fnico%2Fecomm-stack&git_worktree_support=1&git_credential_mode=1&pool_id=pool-352df5e6-8b03-4c55-b622-32ce65e21bf8&cli_version=0.36.0&supports_diff=1&client_capabilities=worktree_cleanup&client_capabilities=git-user-oauth-v1&client_capabilities=git-github-app-v1&client_capabilities=pty&command_capability=EXECUTE_DAEMON_DIFF_OP&command_capability=EXECUTE_DAEMON_FS_OP 2026-09-07 14:12:41.696 [info] 'daemon': WebSocket connected 2026-09-07 14:12:41.779 [info] 'daemon': Daemon registered with Cosmos (multi-workspace: 2 repos) 2026-09-07 14:12:41.779 [info] 'daemon': Heartbeat enabled (5000ms interval) 2026-09-07 14:12:41.780 [info] 'daemon': Received command: CONNECTED (seq: 0) 2026-09-07 14:12:41.781 [info] 'daemon': --> Processing command: CONNECTED ``` Note in your daemon logs: * “Launch dir is a non-git container; adopting N discovered git repo(s) as workspaces \[…]” ⇒ check that all your local git repos have been discovered under /workspace/ * “Git worktree support: supported” * “Joining daemon pool: \” * “Indexing enabled for workspace: \[…]” * “Starting Auggie Daemon \[…]” * “Connecting to Cosmos...” You can now see the daemon running from Cosmos: [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Environments: ![Screenshot 2026 09 07 At 7 18 46 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-7.18.46-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=74c0a1c23db94592e20c629d73a2a841) Click on the pool. Note that 1 daemon is online, and you can see the VM IP/name under Connected daemons. Top right you can set this pool as default environment to run your agents: ![Screenshot 2026 09 07 At 7 19 04 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-7.19.04-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=dba5630b19f32ffe6a63e60ffd102367) ## Step 6 - Connectivity test Now you’ll create a session in Cosmos (cloud) and verify it can connect to the VM (internal network), make sense of the local repos and from that VM reach out to GHES via the `gh` CLI. Go to Cosmos [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New Session. Under the prompt, click on the dropdown list with the cloud icon > select Daemon > select your daemon pool: ![Screenshot 2026 09 07 At 7 24 37 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-7.24.37-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=2522a8333605dd6d6ddd78443758cd4f) Hover over Integrations and make sure "Github App" isn't selected (that's only for github.com): ![Screenshot 2026 09 07 At 7 25 32 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-7.25.32-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=8c752063fd7e90af9833d621bde1e0b8) Prompt the session with **What are those repos about?**, you should see a response powered by the Augment Context Engine that already made sense of your repos: ![Screenshot 2026 09 07 At 7 27 14 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-7.27.14-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=a5de507f62d4b04b01cb44792bd966df) The connectivity between Cosmos (cloud) and your remote VM has been verified ✅ Now prompt the session with: ```text theme={null} Use the gh cli to look up ``` ![Screenshot 2026 09 07 At 7 29 27 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-7.29.27-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=1e1297091d9e2c2e97a83a4b35d360db) Observe that the Cosmos session was able to use the `gh` cli to lookup the PR. ## Step 7 - Create your Cosmos Experts Now that connectivity is established, you can focus on creating your Cosmos experts. You're now ready to deploy the yellow code producing loop of the v1.0 software factory there [https://docs.nicopowered.com/cosmos-core-loops-software-factory](https://docs.nicopowered.com/cosmos-core-loops-software-factory) ![Screenshot 2026 09 07 At 7 43 58 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-7.43.58-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=0c1fc77a14697007e1483e8266c9bcd4) Go to Cosmos [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New Session > Select Cosmos Advisor > Make sure your GHES daemon pool is selected as environment, then edit and prompt with: ```text wrap theme={null} Create a PR Author, a PR Risk Analyzer, a Deep Code Reviewer, a PR Fixer, a Pair Reviewer. You must use the gh cli (do not use the github app anywhere. I already configured the webhook that listens to GHES events . My GHES repos are cloned on the VM available via the attached daemon pool. You must use the attached daemon pool for all the experts you're about to deploy. Make sure the experts are shared with as owner, and can-view with the rest of the organization. ``` You should see this before submitting: ![Screenshot 2026 09 07 At 9 30 14 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-9.30.14-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=fb44c9ff00db93723a291bcd8c61d993) > [!TIP] > > In the prompt you explicitly asked "Make sure the experts are shared with \ as owner" as by default the owner would be the Augment service account you authenticated the daemon pool with You should see this after submitting: ![Screenshot 2026 09 07 At 8 39 54 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-8.39.54-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=754787e6fabdaf5f7d215b47d96563c9) > [!TIP] > > Advisor will also recommend experts you should consider, as it did above for the Code Review Memory Manager. In a separate session you could also ask Advisor "what are all the experts you could help me deploy for my software factory" Your experts are now deployed, you can see them under [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > Settings > Experts > All tab: ![Screenshot 2026 09 07 At 8 13 43 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-8.13.43-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=ba9da2e3776956a18b8c095381697fd5) When you click on an expert > Share expert you can see Advisor applied the permissions you requested: ![Screenshot 2026 09 07 At 8 48 41 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-8.48.41-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=124f3feb1a0c4adc5b806252a39b8abb) The experts are 'stitched' together under [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > Settings > Automations > All tab. You can expand the first Deep Code Reviewer (GHES) automation and observe the high level events this expert will react to: ![Screenshot 2026 09 07 At 8 50 18 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-8.50.18-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=22a06b07d29a62c56613a7e4937dc7cf) > [!TIP] > > You can instruct Advisor to update your experts and use other native integrations (ex: Jira/Atlassian) as often you'll want to author PRs based on a ticket ## Step 8 - Test your PR author Create a sample PR to test your PR author. Go to [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New session > Select PR Author (GHES) and prompt with: ```text theme={null} create a hello world banner on the top of the main UI ``` or, if you already deployed your experts with the native Jira integration: ```text theme={null} implement this Jira ticket ``` ![Screenshot 2026 09 07 At 8 59 32 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-8.59.32-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=5bd5c92c68d0391cf1488b9c1f7127d7) You should see this: ![Screenshot 2026 09 07 At 9 05 27 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-9.05.27-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=cd5c76fd518020fa265d190f4521caa7) The PR Author created the PR, and downstream the PR Risk Analyzer, Deep Code Reviewer, PR Fixer and Pair Reviewer will trigger automatically. The PR Author is a powerful orchestrator that will handle all that for you, and keep tabs on the comments, CI statuses etc. Click on the PR link that the PR Author created, and you'll see all the code producing experts at play to get the PR ready for a final review: ![Screenshot 2026 09 07 At 9 13 48 AM](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/Screenshot-2026-09-07-at-9.13.48-AM.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=a70b60b3863c996101e6d7589de9a890) > [!TIP] > > When you start the PR author manually/interactively as you did earlier, it may author the PR in draft. Switch it to ready for review to observe the experts at play. Your PR author can also be invoked via automation and other expert like Project Builder Congratulations, you’ve deployed your first experts and v1 software factory code producing loop with GHES! 🎉 # Integrate GitLab Cloud Source: https://docs.augmentcode.com/cosmos/connectors/gitlab-cloud Integrate GitLab Cloud with Cosmos to receive webhooks, clone repositories, and deploy experts that author and review merge requests. ## Introduction In this page we’ll configure the native Gitlab integration and learn how to: 1. Get Gitlab to push events to Cosmos via webhooks 2. Configure a Cosmos environment that git clones/fetches from Gitlab repo(s) 3. Get Cosmos to automatically post onto a MR when the MR is created 4. Deploy the MR author and MR reviewer experts via the Cosmos Advisor For 4, below is the flow that will be followed by the Cosmos MR reviewer expert: ```mermaid theme={null} sequenceDiagram autonumber participant GL as GitLab participant A as Augment Code | Cosmos GL->>A: Webhook: Merge Request created (MR payload) A->>A: Start Expert (spawn/run expert agent) A->>A: Expert analyzes MR (diff + context) A->>GL: POST MR comment GL-->>A: 201 Created (comment posted) ``` ## Prerequisites To configure the one-time connectivity between Cosmos and Gitlab: * you must be a Augment admin * you must have Gitlab permissions to create a Gitlab service account and its access token with the `api` scope (required) and enable one of those four options: * (1) give that service account the **Maintainer** role on a group that would have access to the repos in scope OR * (2) give that service account a custom role with at least the **Developer** role and the `admin_web_hook` permission on a group that would have access to the repos in scope OR * (3) give that service account the **Maintainer** role on each of the repos in scope OR * (4) give that service account a custom role with at least the **Developer** role and the `admin_web_hook` permission on each of the repos in scope ## Step 1 - Configure the native Gitlab integration As a Augment admin, go to [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > Settings > Connectors > Browse Connectors > Gitlab Cloud > click on it: ![Image](https://mintcdn.com/augment-mtje7p526w/zVHHdGGV4mFtag5s/images/image-11.png?fit=max\&auto=format\&n=zVHHdGGV4mFtag5s\&q=85\&s=0977a2a9ba2927981aa79a93611658ee) You’ll be redirected to this view: ![Image](https://mintcdn.com/augment-mtje7p526w/zVHHdGGV4mFtag5s/images/image-22.png?fit=max\&auto=format\&n=zVHHdGGV4mFtag5s\&q=85\&s=57a10371c6050ebc2ae6c603fb2bbd3b) Let’s switch to Gitlab to create that group service account: * Navigate to your Gitlab group, then Settings > Service Accounts in the left sidebar ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-03.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=20463d82d98e675580a06c244471edf7) * Click on Add service account * Name: Cosmos * Username: ex: augment-code-cosmos ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-04.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=6dc5cb638ef0039a779329478bc1cb2b) * Next to your service account > click on the 3 dots > Manage access tokens ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-05.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=c00e1c995a33fadb4eb122b0eb172632) * Add new token * Name: Cosmos01 * Expiration date - set the maximum * Select `api` scope * Click on Generate token ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-06.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=f90c01140a08412d208c4e74cbf36045) * Copy the access token, we’ll need it shortly ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-07.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=9bb09d91686a56850358d7c13f1f9c75) Now you’ll make this service account a member of the projects/repos you want to surface in Cosmos. 3 options: * (1) give that service account the **Maintainer** role on a group that would have access to the repos in scope OR * (2) give that service account a custom role with at least the **Developer** role and the `admin_web_hook` permission on a group that would have access to the repos in scope OR * (3) give that service account the **Maintainer** role on each of the repos in scope OR * (4) give that service account a custom role with at least the **Developer** role and the `admin_web_hook` permission on each of the repos in scope Let's assume you're going with (3) and make the service account a maintainer on given projects/repos: * Go to your project > left sidebar > Manage > Members > Invite members > select your service account > role ‘Maintainer’ > select your project (or all projects in the group) > Invite ![Screenshot 2026 09 10 At 2 15 48 PM](https://mintcdn.com/augment-mtje7p526w/Rgt1ClTu2DHKjtcw/images/Screenshot-2026-09-10-at-2.15.48-PM.png?fit=max\&auto=format\&n=Rgt1ClTu2DHKjtcw\&q=85\&s=905f4d014081cacc23d71710986b6a66) You should see this: ![Screenshot 2026 09 10 At 2 16 41 PM](https://mintcdn.com/augment-mtje7p526w/Rgt1ClTu2DHKjtcw/images/Screenshot-2026-09-10-at-2.16.41-PM.png?fit=max\&auto=format\&n=Rgt1ClTu2DHKjtcw\&q=85\&s=ca81242d6c76a5387b7d57f18e32f4ca) Now go back to Cosmos. * Paste the group service account’s access token into Cosmos and click on ‘Connect bot’: ![Image](https://mintcdn.com/augment-mtje7p526w/zVHHdGGV4mFtag5s/images/image-13.png?fit=max\&auto=format\&n=zVHHdGGV4mFtag5s\&q=85\&s=d1eda429e345ffd64eddc897363b62d9) Cosmos will automatically: * Discover the repos * Register webhooks to react to events across those repos (if you added the service account as maintainer at the group level, Cosmos will automatically configure a centralized webhook at the group level to receive events from all the repos under that group. If instead you added the service account as maintainer per repo, Cosmos will automatically configure a webhook for each corresponding repo) You should see this: ![Image](https://mintcdn.com/augment-mtje7p526w/zVHHdGGV4mFtag5s/images/image-15.png?fit=max\&auto=format\&n=zVHHdGGV4mFtag5s\&q=85\&s=4e1797f744aa00f5a64dd4c5adfb7076) If you don’t see your repos, double check the scopes of your service account and that it’s added as a member of your projects with the proper role. ## Step 2 - Create a cloud environment Let’s create a cloud environment with those Gitlab repos: * Go to [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Environments > top right Create an environment > Cloud machine ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-12.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=eb186f4705a5306613faa5f429b9830d) * Configure your environment * Name: ex: ecomm-stack * Image: ex: keep the Cosmos default base image * Repositories: select your Gitlab repos * Refresh: toggle on * Spaces: keep the default space * Click on Create Environment ![Image](https://mintcdn.com/augment-mtje7p526w/zVHHdGGV4mFtag5s/images/image-17.png?fit=max\&auto=format\&n=zVHHdGGV4mFtag5s\&q=85\&s=15dd3de9f37e1fd43d3912b1dbed0294) Cosmos will create the cloud environment, git clone your repos and keep them up to date ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-14.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=a51ba924cff8eec8f627327983b02191) ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-15.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=4a3208af765d48c8a9879ebacc18c622) * Click on Done You’ll see your new environment in your “Mine” tab: ![Image](https://mintcdn.com/augment-mtje7p526w/zVHHdGGV4mFtag5s/images/image-18.png?fit=max\&auto=format\&n=zVHHdGGV4mFtag5s\&q=85\&s=30adbd8b0385cb5010f2bb2e75296127) Now let’s do a quick test and create a session with that env: * Click on ‘Back to app’ top left to get back to [https://cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New session > bottom left of the prompt select your env, then click on Integrations and verify that Gitlab is selected, then send this prompt “What’s this repo about?” ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-17.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=cfb907d5b7b87d70b3af3f5fc9eee21c) That’ll start a session. Notice on the right sidebar Expert = Not set, Integrations include Gitlab, your selected env: ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-18.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=7990774fd89f1067ef8983faa248e4f5) Your Gitlab integration and your cloud env are ready. It’s time to create your first Cosmos expert. ## Step 3 - Create a MR deep reviewer expert Cosmos has a large knowledge base and greatly assists with creating new experts. A common expert you’d create for your Gitlab repos is the “MR reviewer”, whose job will be to auto react to MRs being created and auto review them. Whenever you need to create new experts go ask the Cosmos Advisor: * Go to Cosmos ([https://cosmos.augmentcode.com](https://cosmos.augmentcode.com)) > New session > select the ‘Cosmos Advisor’ expert, make sure the Gitlab integration is selected and prompt with “Create a MR author, a MR risk analyzer, a MR deep reviewer. The MR review should start whenever a MR gets created. Those experts should reuse the ecomm-stack env of this session” ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-19.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=44584cdad6c1760d62454731bb3b4a7f) The Cosmos Advisor may ask you to clarify what experts to deploy, it may recommend to include other experts (ex: helper experts), and if an integration is missing it’ll guide you to add it. Ultimately you should see this at the end of your session: ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-20.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=ad7afc770e6bbe6b513bb0f1de704244) Go check where your experts are created: * Go to [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Experts > filter on expert name containing ‘gitlab’: ![Image](https://mintcdn.com/augment-mtje7p526w/zVHHdGGV4mFtag5s/images/image-19.png?fit=max\&auto=format\&n=zVHHdGGV4mFtag5s\&q=85\&s=6fa4534ed94401aaa53ffe88f8abbd88) Cosmos Advisor configured some experts to react to Gitlab events, you can see those configured in [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Automations: ![Image](https://mintcdn.com/augment-mtje7p526w/zVHHdGGV4mFtag5s/images/image-20.png?fit=max\&auto=format\&n=zVHHdGGV4mFtag5s\&q=85\&s=4aa67884fb886dd0f84d15f40f3d7c11) If you expand the Deep Code Reviewer (Gitlab Cloud) you’ll see its triggers: ![Image](https://mintcdn.com/augment-mtje7p526w/zVHHdGGV4mFtag5s/images/image-21.png?fit=max\&auto=format\&n=zVHHdGGV4mFtag5s\&q=85\&s=7c5ab2ac324e34cabd85792fe2cb4114) ## Step 4 - Create a new MR and observe your experts at work * Go to Cosmos ([https://cosmos.augmentcode.com](https://cosmos.augmentcode.com)) > New session, implement a simple change ex: prompt with “add a hello world banner on top of the web app, then create a MR in ready to review state” ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-24.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=23eed419eb3d516bbabade55c660dfcf) Then open your MR, you’ll see the MR Risk analyzer expert commenting on the MR, followed by the Deep Code Review expert: ![](https://mintcdn.com/augment-mtje7p526w/-GW3XrvrHYMzepvG/images/cosmos-integrations/gitlab-cloud/gitlab-cloud-25.png?fit=max\&auto=format\&n=-GW3XrvrHYMzepvG\&q=85\&s=5d58444e6efe52b45d96a5be3e1979c1) Congratulations, you’ve configured the native Gitlab integration and your first MR experts! 🎉 # Integrate GitLab Self-Hosted Source: https://docs.augmentcode.com/cosmos/connectors/gitlab-self-hosted Connect self-hosted GitLab to Cosmos using webhooks, a daemon, and the GitLab CLI to automate merge request workflows on your infrastructure. ## Introduction In this page we’ll learn how to configure those items: 1. Get Gitlab to push events (ex: “new MR created”) to Augment Cosmos via webhooks 2. Configure a Cosmos Daemon on a AWS EC2 instance/VM (where the Gitlab local repos will be cloned locally) 3. Get Augment Cosmos to interact with Gitlab via the `glab` cli 4. Deploy your first Cosmos MR experts Below is the flow we’ll configure with a simple MR reviewer expert: ```mermaid theme={null} sequenceDiagram autonumber participant A as Augment Code | Cosmos participant AWS as AWS EC2 participant GL as GitLab Self-Hosted GL->>A: Webhook: Merge Request created (MR payload) A->>AWS: run experts locally via Daemon AWS->>AWS: Start Expert (spawn/run expert agent) AWS->>AWS: Expert analyzes MR (diff + context) AWS->>GL: POST MR comment (GitLab CLI: create comment) GL-->>AWS: 201 Created (comment posted) ``` Below is a high level architecture diagram of the components at play: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-01.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=57cbb630ffe1de390e9846d20a45662c) ## Prerequisites To configure the one-time connectivity between Cosmos and Gitlab: **Cosmos** * must be an admin to create a Augment service account and webhooks **Gitlab Self-Hosted** * must have at least Maintainer or Owner role on a given project, or be Owner of a group that has access to given projects * allow inbound connections from other VMs on your VPC (inbound calls will come from within your network) **AWS** * must have the ability to deploy EC2 instances in a VPC that has network connectivity to your Gitlab self-hosted. Must enable outbound network connectivity to \*.[augmentcode.com](http://augmentcode.com/) (see [https://docs.augmentcode.com/setup-augment/network-configuration](https://docs.augmentcode.com/setup-augment/network-configuration)) ## Step 1 - Configure Gitlab to notify a Cosmos Webhook ### Webhook receiver in Cosmos Let’s create a new webhook in Cosmos (so Cosmos can listen to Gitlab events): * As an admin go to Cosmos [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Webhooks > Create a webhook > Click on GitLab: ![Image](https://mintcdn.com/augment-mtje7p526w/qArODLdQhFTnAnwS/images/image-23.png?fit=max\&auto=format\&n=qArODLdQhFTnAnwS\&q=85\&s=5a47ac1f1276b886124c1cd3d29c398d) * Enter Description: **GitLab MR events** > Click on Create ![Image](https://mintcdn.com/augment-mtje7p526w/qArODLdQhFTnAnwS/images/image-26.png?fit=max\&auto=format\&n=qArODLdQhFTnAnwS\&q=85\&s=5286403e6c8a00744d6044f95e76011c) You'll obtain a Webhook URL and a Secret token. Copy them and click on Done. ![Image](https://mintcdn.com/augment-mtje7p526w/qArODLdQhFTnAnwS/images/image-28.png?fit=max\&auto=format\&n=qArODLdQhFTnAnwS\&q=85\&s=5c679c012abb3c22806e5c307443e7fd) Run this curl request (with your own parameters) to do a quick test: ```shell theme={null} curl -i -X POST "https://XXX.api.augmentcode.com/webhooks/XXX" \ -H "Content-Type: application/json" \ -H "X-Gitlab-Event: Push Hook" \ -H "X-Gitlab-Token: whsec_XXX" \ -d '{"event": "test", "data": "your payload here"}' ``` You should get this response: ```plain text theme={null} HTTP/2 200 content-length: 30 content-type: application/json date: Sun, 02 Aug 2026 23:23:23 GMT via: 1.1 google alt-svc: h3=":443"; ma=2592000 {"message":"Webhook accepted"}% ``` ### Webhook sender in Gitlab Create a new webhook config in Gitlab (so Gitlab can POST to a given url when certain Gitlab events occur): as a Maintainer or Owner, go to your Gitlab repo > Settings > Webhooks > Add new webhook > Add those details: * Name: **Notify Cosmos on MR created/updated/merged/commented** * URL: the webhook url provided by Cosmos * Secret token: the secret provided by Cosmos * Trigger: `Comments` and `Merge request events` * Custom header: leave empty * Enable SSL verification: **keep it selected** * Click on Add webhook ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-05.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=5758e60ce9a61c451ba710758cc26d2d) Now run a test: in Gitlab go back to your list of Gitlab webhooks (Settings > Webhooks) > click on the Test dropdown > Merge request events ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-06.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=87c5c4676b2eb46059255c3a8b492095) You should see this banner at the top: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-07.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=589a352841e6a1b9588391e1aadb8672) Now go back to Cosmos and check that Cosmos received the event: [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Automations > Events Log. You should see your event with source “Webhook · GitLab”: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-08.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=67886dcdf73bad92e5adf1dab5f076d2) Click on the event to inspect the test payload: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-09.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=146d14eec9929f695c6ae49ccbf1e7f7) At this point Gitlab will automatically notify Cosmos whenever a MR is created/updated/commented on ✅ ## Step 2 - Create a Gitlab Service Account For headless automation and to start agentic workflows based on Gitlab events, you’ll create a dedicated Gitlab service account and its access token: Gitlab repo > Settings > Service accounts > Add service account > Add a name (ex: **Cosmos-XXX**) and username (ex: **cosmos-xxx**): ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-10.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=926e952200fc1c1b2e6b84ad5b633c77) Then next to that service account > 3 dots > Manage access tokens ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-11.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=3f68b0857e7a52f1cfe54d64efc494dd) Click on Add new token: * Enter a token name (ex: **Cosmos01**) * Set a max expiration date as far out as possible * Select scope `api` * Click on Generate token ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-12.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=32d4ae9bd4707e7b547aaeeb3aacbc26) Click on the copy icon to copy the GITLAB\_TOKEN in your clipboard ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-13.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=7aa58fe4edac7aea2f98493d45c8613e) Now get back to Gitlab and add your Gitlab service account with role=`Maintainer` onto the repos where the service account should be able to read/post (add it per repo or add it to the group that manages all the repos): Go to your Gitlab repo(s) > Manage > Members > Invite members > add your Gitlab service account and click on Invite: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-14.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=8a891740a6ac9e904434ddcba20fe03b) Now your Gitlab service account has permissions to collaborate across your repos. ## Step 3 - Create a Augment service account Before we start the websocket tunnel from your AWS EC2 instance to Cosmos, you’ll need to create a dedicated Augment service account, which will be used to authenticate and start the tunnel. As an admin go to [https://app.augmentcode.com/](https://app.augmentcode.com/) > Service Accounts > + Add Service Account > Add: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-15.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=21b748e4684eb6e389d6e35a1c4bac3f) Then click on + Add API Token: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-16.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=6739835eabc72bdd0a9b9141df63eade) Enter an API Token Name (ex: Token01): ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-17.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=2d03bd1849269c7a2c017c8d4d9f81ad) Click on Download JSON: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-18.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=5bd0ff8f57ba67dbd2cb8ab63afa4b5f) You'll obtain a session.json, it will be used to authenticate the Cosmos daemon later on. ## Step 4 - Create a Cosmos daemon pool Since you’ll be leveraging a AWS EC2 VM to host your daemon, it’s important to think about uptime and resilience: your VM could loose network connectivity or have an outage. The best practice is to create a daemon pool and attach your daemons to that daemon pool. Then you can later have N daemons (1 per VM) all tied to the same daemon pool, and Cosmos will use that pool which will automatically route to the next available daemon. In this guide you’ll create 1 daemon pool and 1 daemon running in 1 VM, but you can extend that approach to spin up 2 more VMs (and their respective daemons) for max resilience. Go to [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Environments > Create an environment > Daemon Pool: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-19.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=c12edc37c50a7bb4b217c083a3121874) Configure the pool with: * Name: **Team01-Pool-Gitlab-SelfHosted** * Daemon connector: select the dedicated service account you created in the section earlier * Shared: **toggle on** * Workspace behavior: `Isolated workspace` Then click on Create Pool: ![Image](https://mintcdn.com/augment-mtje7p526w/qArODLdQhFTnAnwS/images/image-29.png?fit=max\&auto=format\&n=qArODLdQhFTnAnwS\&q=85\&s=37cd005373f19a1d0208d2a6fc1afe47) You’ll get the confirmation that the pool has been created, note the pool-id: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-21.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=c7864ffc1b11e12576fd63a75ed234bc) Go back to your list of environments, you should see your daemon pool (with no daemon online yet): ![Image](https://mintcdn.com/augment-mtje7p526w/qArODLdQhFTnAnwS/images/image-30.png?fit=max\&auto=format\&n=qArODLdQhFTnAnwS\&q=85\&s=0afa1ba3c430141f230625839b583de2) Re-open your pool > Click on "Share daemon pool" > Update Organization access to "Can use" > Click on Save: ![Image](https://mintcdn.com/augment-mtje7p526w/A0PjRuyBOn7TlVny/images/image-50.png?fit=max\&auto=format\&n=A0PjRuyBOn7TlVny\&q=85\&s=8f8c92261c8df1008ef7c6a3a994c1f1) Any other user in your Cosmos tenant will then be able to start a new session with that daemon pool. ## Step 5 - Configure your VM with local Gitlab repos, glab cli and Cosmos daemon In this section you’ll configure a AWS EC2 VM with the following: * locally cloned Gitlab repos * `glab` cli so Cosmos local agents can communicate to Gitlab * a Cosmos pool + daemon (to establish an outbound websocket tunnel from AWS to Cosmos) ### Create the VM, with git and NVM/node Create a new AWS EC2 Linux instance (ex: Ubuntu x86\_64 - ami-091138d0f0d41ff90) in a AWS VPC that will be able to reach your Gitlab Self-Hosted instance. Minimum config recommended: **4 vCPU, 16 GB RAM, 100 GB SSD** ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-23.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=0e0d3b384faa2c40aa759698df18fd3b) Then SSH onto the AWS EC2 instance. Install git ```bash theme={null} sudo apt update && sudo apt install git -y ``` Verify the installation ```bash theme={null} which git git --version ``` ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-24.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=ce19eeb3c3d050a306a81d6a512ae8d2) Install NVM ```bash wrap theme={null} curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash ``` Refresh the terminal profile ```bash theme={null} source ~/.bashrc ``` Install the latest Long-Term Support (LTS) version of Node & NPM ```bash theme={null} nvm install --lts ``` Verify the node install ```bash theme={null} node -v npm -v ``` ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-25.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=193c253cdacd525aa8953a68b1216bfd) ### Git clone your Gitlab repos locally Create a local \~/workspace/ folder In that workspace folder create folders for your Gitlab organizations In the corresponding organization folders, git clone your repos (you need at a minimum an empty git repo with at least one commit for the git worktree configuration to be valid and for the agent to start) You should have a “2 layers” folder structure like this: * \~/workspace/\/\/.git * \~/workspace/\/\/.git * \~/workspace/\/\/.git * \~/workspace/\/\/.git > [!NOTE] > > Note: at this moment you have to own making sure that the git repos are locally cloned and are kept up to date regularly. In a future release, daemons will be able to handle that on your behalf - stay tuned ### Install and authenticate the glab CLI Install the `glab` cli: make sure you’re in your root folder, install the `glab` cli using this command: ```shell wrap theme={null} LATEST_TAG=$(curl -s "https://gitlab.com/api/v4/projects/gitlab-org%2Fcli/releases" | grep -o '"tag_name":"[^"]*' | head -n 1 | cut -d'"' -f4) && LATEST_VER="${LATEST_TAG#v}" && wget "https://gitlab.com/gitlab-org/cli/-/releases/${LATEST_TAG}/downloads/glab_${LATEST_VER}_linux_amd64.deb" -O /tmp/glab_latest.deb && sudo dpkg -i /tmp/glab_latest.deb && rm /tmp/glab_latest.deb ``` Then authenticate the `glab` cli, run: ```shell wrap theme={null} echo "" | glab auth login --hostname gitlab.yourdomain.com --stdin ``` You should see: ```plain text theme={null} ✓ Logged in as cosmos-xxx ✓ Stored your credentials in the configuration file. ``` ### Start the daemon cd into \~/workspace/ Run ```shell theme={null} nano session.json ``` Paste in there the content of session.json you retrieved earlier when creating the Augment service account. Then CTRL-O + RETURN to save the file and CTRL-X + RETURN to exit Install Auggie ```bash theme={null} npm install -g @augmentcode/auggie ``` Start the Cosmos daemon using the Augment service account and attach the daemon to the pool, run: ```shell wrap theme={null} auggie daemon --augment-session-json /PATH/TO/session.json --pool-id --discover-workspaces=2 --allow-indexing ``` That will start the daemon, note in your daemon logs: * “Launch dir is a non-git container; adopting N discovered git repo(s) as workspaces \[…]” ⇒ check that all your local git repos have been discovered * “Git worktree support: supported” * “Joining daemon pool: \” * “Indexing enabled for workspace: \[…]” * “Starting Auggie Daemon \[…]” * “Connecting to Cosmos...” ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-26.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=284e01f2011c1b679d1d7a2ec6b7b1ce) The daemon is connected. Enter CTRL-C to stop it. ### Install the daemon as a systemd service We want that daemon pool to be running all the time, and we want it to be automatically started in case the VM is rebooted. You'll then install the auggie daemon as a systemd service. Run ```shellscript theme={null} sudo nano /etc/systemd/system/auggie-daemon.service ``` Paste and edit that content in the file: ```systemd wrap theme={null} [Service] User=ubuntu Environment=HOME=/home/ubuntu WorkingDirectory=/home/ubuntu/workspace ExecStart=/bin/bash -ic 'exec auggie daemon --augment-session-json session.json --pool-id --discover-workspaces=2 --allow-indexing' Restart=always RestartSec=5 [Install] WantedBy=multi-user.target ``` CTRL-O then ENTER to save the file. CTRL-X then ENTER to close the editor. Then run: ```shellscript theme={null} sudo systemctl daemon-reload sudo systemctl enable --now auggie-daemon sudo systemctl status auggie-daemon --no-pager ``` The service is now active ![Image](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/image-46.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=f6eed50ed29f403f63d53df1889cbd5e) > [!NOTE] > > Check that there's no error message like (code=exited, status=1/FAILURE). If you see any, stop the service using `sudo systemctl stop auggie-daemon`, make sure you properly edited the auggie-daemon.service, then re-run the 3 sudo commands You can now see the daemon running from Cosmos: [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Environments: ![Image](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/image-48.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=ed39d96c88ceb8e837107ca86a9dac64) If you click on the pool, then top right you can set this pool as default environment to run your agents: ![Image](https://mintcdn.com/augment-mtje7p526w/RZVrMVl0y_uogG6Y/images/image-49.png?fit=max\&auto=format\&n=RZVrMVl0y_uogG6Y\&q=85\&s=8f7d8618957f5ddf23dda933a0f1b476) ## Step 6 - Connectivity test Now you’ll create a session in Cosmos (cloud) and verify it can connect to the VM, make sense of the local repos and from that VM reach out to Gitlab via the `glab` CLI. Go to Cosmos [https://cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New Session Under the prompt, click on the dropdown list with the cloud icon > select Daemon > select your daemon pool: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-29.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=6d7643b6423145cbdff213639ebd1dd0) Prompt the session with **What are those repos about?**, you should see a response powered by the Augment Context Engine that already made sense of your repos: ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-30.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=54ee68e18ffe232a5d49d0a65d2fb0cd) The connectivity between Cosmos (cloud) and your local VM has been verified ✅ Now prompt the session with: **Use the glab cli to look up \** ![](https://mintcdn.com/augment-mtje7p526w/8BrHp0zhabcfYque/images/cosmos-integrations/gitlab-self-hosted/gitlab-self-hosted-31.png?fit=max\&auto=format\&n=8BrHp0zhabcfYque\&q=85\&s=50efa4e3ead8fc395f777160fa9ca64d) Observe that the Cosmos session was able to use the `glab` cli to lookup the MR. ## Step 7 - Create your Cosmos Experts Now that connectivity is established, you can focus on deploying your Cosmos experts. You can follow the steps in [https://docs.augmentcode.com/cosmos/connectors/gitlab-cloud#step-3-create-a-mr-deep-reviewer-expert](https://docs.augmentcode.com/cosmos/connectors/gitlab-cloud#step-3-create-a-mr-deep-reviewer-expert) to create a MR author, MR Deep Code Reviewer etc. The only key difference is you’ll have to explicitly instruct Cosmos Advisor to do the following when deploying those experts: * **use the `glab` cli** (instead of the native Gitlab Cloud integration) * **use your daemon pool** (instead of the cloud environment) * **use the Gitlab webhook** (instead of the native Gitlab Cloud integration) Congratulations, you’ve integrated Cosmos with Gitlab Self-Hosted and deployed your first MR experts! 🎉 # Atlassian Jira Cloud Source: https://docs.augmentcode.com/cosmos/connectors/jira-cloud Configure Atlassian Jira Cloud app and user integrations for Cosmos, including workflow triggers, subscriptions, and user authorization. ## Introduction Need the legacy webhook/MCP setup instead? See [Atlassian Jira Cloud (legacy)](/cosmos/jira-cloud-webhooks-mcp). There are two kinds of Atlassian Jira integrations that work through Atlassian apps: | Flavor | Capability | When to use | | - | - | - | | **App integration** | `JIRA_APP` | Experts post as Augment. Supports triggering workflows and subscriptions. Requires the Forge app. | | **User integration** | `JIRA` | Experts post as the user. The user must complete a one-time OAuth flow that grants Augment privileges on their Atlassian app. | With the app integration, you can: * create automations triggered by Jira events * have sessions and experts listen for Jira events * have sessions and experts do operations against Jira. These will appear to come from the `Augment` app. To do the app integration, you must be a Cosmos administrator. You will need to work with a Jira Cloud administrator. Go to **Settings > Integrations** and click **Connect** in the **Atlassian** tile. Follow the instructions that appear. To do the user integration, go to **Settings > Linked Accounts** and click on **Connect** in the **Jira** tile. ### Using the integrations The easiest way to use the integrations is to ask Cosmos to create or modify an existing expert or workflow. When launching a new session, select **Jira App** for the app integration and **Jira** for the user integration. # Atlassian Jira Cloud (legacy) Source: https://docs.augmentcode.com/cosmos/connectors/jira-cloud-webhooks-mcp Set up the legacy Jira Cloud integration with Cosmos using webhooks for issue events and the Jira MCP server to read and update tickets. ## Introduction In this page we’ll learn how to configure 2 things: * Get JIRA to push events to Augment Cosmos via webhooks ```mermaid theme={null} sequenceDiagram autonumber participant J as Jira participant AC as Augment Cosmos J->>AC: Webhook: Issue Created (Ticket JSON) ``` * Get Augment Cosmos to interact with Jira via the Jira MCP server ```mermaid theme={null} sequenceDiagram autonumber participant J as Jira participant AC as Augment Cosmos AC->>J: Read/Update Ticket via Jira MCP server J-->>AC: 200 OK (Sync Complete) ``` ## Step 1 - Configure Jira to notify a Cosmos Webhook Let’s create a new webhook in Cosmos (so Cosmos can listen to Jira events). Prerequisites: * Cosmos side: any user can self-create webhooks * Jira Cloud side: any user (non-admin) can create automation-based webhooks as a "THEN" action. In this document we will not use legacy global Jira webhooks (only jira admins can create those) Configuration steps * Go to Cosmos ([https://cosmos.augmentcode.com](https://cosmos.augmentcode.com)) > Settings > Capabilities > Webhooks > Create Webhook ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-01.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=9d620c09ecf08c9ec9ce88e97abfb0b4) * That gives us a url to POST with a given Bearer token to pass as HTTP header. Curl request would look like: ```shell theme={null} curl -X POST https://XXX.api.augmentcode.com/webhooks/XXX \ -H "Authorization: Bearer XXX" \ -H "Content-Type: application/json" \ -d '{"event": "test", "data": "your payload here"}' ``` **Create a new webhook config in Jira** (so Jira can POST to a given url when certain Jira events occur) * Go to your Jira env ([https://augmentcode-demo.atlassian.net/jira/](https://augmentcode-demo.atlassian.net/jira/)) * Wheel icon > System ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-02.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=79b3282ce61721953facee0d663119ed) * Left nav bar > Automation > Global automation * Top right: Create rule > Create from scratch ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-03.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=b215d7693dc8d4fa0249e94a628cb0d8) * On the “Add a trigger” view, add trigger “Work item created”: ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-04.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=18705e2c9808f81acb6685e7e469b65f) * Click on add component under the When block: ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-05.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=43642ff07486bf18b3250b70281a31c4) * Click on “THEN: Add an action”, search “Send web request”: ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-06.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=a2a5ab1a8ef6c00d5046ad15868655c4) * Add * Web request URL: the Augment webhook url * Keep HTTP method to POST * Web request body: select Issue data (Automation format) * Headers, add: * Authorization: Bearer \ * Content-Type: application/json ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-07.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=c85a3c316a9327f6c735d35929c350d9) * Then click on rule details and add * Name * Keep scope: Global * Keep owner: yourself * Keep Actor: Automation for Jira * Click on turn on rule Now create a new Jira ticket. Then go back to Cosmos and check that Cosmos received the event: * Settings > Automations > Event Log. You should see your event with source “Custom” ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-08.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=ffcdd7698b9de4ea45bf5164f5833128) * Click on the event: * Verify it contains details about the Jira ticket you just created: ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-09.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=5cd4d48d312a42c2390f4120aad98600) At this point Jira can invoke Cosmos ✅. ## Step 2 - Integrate with Jira using your own identity ### Prerequisites Your Atlassian organization admin must authorize access from [https://cosmos.augmentcode.com/mcp/callback](https://cosmos.augmentcode.com/mcp/callback) to your Atlassian space ### Configure the native Atlassian integration via MCP server We’ll leverage the native Atlassian MCP Server integration: * Go to Cosmos [https://cosmos.augmentcode.com](https://cosmos.augmentcode.com) > Settings > Capabilities > MCP Registry * Search for Atlassian > click on “+” > My Identity (OAuth): ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-10.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=0cfbea539e24b24b15ef0ad4342bb443) * Make sure Jira and Confluence are selected, click on approve ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-11.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=38e0e6f9bfc835d49e6cb37d6faf37f6) * Select your Atlassian space, review the scopes/permissions and click on Accept: ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-12.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=3a2fa39be797cfe86b6a9574ee8b34af) * Toggle on “Cosmos Agent” and optionally “CLI”, then click on Close: ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-13.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=6c65a5ab1b0d1ee97bad24c9a993608f) ### Run a test * Open a new session ([https://cosmos.augmentcode.com](https://cosmos.augmentcode.com)) > New session * In the prompt, click on the Atlassian icon > MCPs > make sure Atlassian is toggled on: ![](https://mintcdn.com/augment-mtje7p526w/TwcxA1duL_U0xuBp/images/cosmos-integrations/jira-cloud/jira-cloud-14.png?fit=max\&auto=format\&n=TwcxA1duL_U0xuBp\&q=85\&s=c0da463adeec29af94a88be4ed10bd4f) * Now prompt Cosmos to look up a given ticket by its url: * Verify that Cosmos was able to look up the ticket: ![](https://mintcdn.com/augment-mtje7p526w/ws3FkwddjnEOseab/images/cosmos-integrations/jira-cloud/jira-cloud-15.png?fit=max\&auto=format\&n=ws3FkwddjnEOseab\&q=85\&s=41d15e0cd6e1f88c0bbf713f3cad9206) Congrats, now you can create a Cosmos expert that listens to the corresponding webhook and post to Jira/Confluence on your behalf 🚀 ## **Bonus: Integrate with Jira via a Service Account (recommended for headless automation)** ### **Create a Jira Service Account** For Cosmos to interact with Jira via a Jira service account we’ll leverage the Atlassian remote mcp server and authenticate it with said service account as we’d want Cosmos to run headless automations. Let’s create a dedicated Jira service account and its access token: As a Atlassian admin go to: * [https://admin.atlassian.com/](https://admin.atlassian.com/) * Directory > Service Account > Create a Service account * Enter the name “Augment Code” * Select app “Jira” with role “User” * Save * On that newly created Service account > click on Create credentials * Choose authentication type “API token” ![](https://mintcdn.com/augment-mtje7p526w/ws3FkwddjnEOseab/images/cosmos-integrations/jira-cloud/jira-cloud-16.png?fit=max\&auto=format\&n=ws3FkwddjnEOseab\&q=85\&s=f4438bb0f63658094210afd2a8a92cb7) * Next * Pick a name and expiration date (max 1 year out) * Select those scopes (look them up using the search bar): ```plain text theme={null} Read read:jira-work read:jira-user read:comment:jira read:comment.property:jira Manage (optional) manage:servicedesk-customer manage:jira-webhook manage:jira-project manage:jira-data-provider manage:jira-configuration Write write:jira-work write:comment:jira write:comment.property:jira write:request.comment:jira-service-management ``` * Next, then Create * Copy the API token ### Configure the Atlassian MCP server Now let’s configure the Atlassian MCP server with that service account’s access token in Cosmos: * Go to Settings > MCP Registry ([https://cosmos.augmentcode.com/mcp](https://cosmos.augmentcode.com/mcp)) * If you had an existing Atlassian MCP server configured with your human identity, delete it. * Search for Atlassian > click on “+” > Service Account (API Token): ![](https://mintcdn.com/augment-mtje7p526w/ws3FkwddjnEOseab/images/cosmos-integrations/jira-cloud/jira-cloud-17.png?fit=max\&auto=format\&n=ws3FkwddjnEOseab\&q=85\&s=7cf2cd9007a40d6813bac29fe4726f29) * API token: paste YOUR\_ATLASSIAN\_SERVICE\_ACCOUNT\_API\_TOKEN * Keep enabled products CLI and Cosmos Agent selected * Click on Save * Open the server's **Manage access** dialog (under **Sharing** in Connectors, or the server's menu in MCP Registry). Grant **Can use** to the intended recipients, or **Everyone → Can use** for organization-wide use, then save the access changes. If prompted, choose **Shared connection** only if those recipients should use the service account's Atlassian permissions. > [!NOTE] > > The screenshots below show the older sharing UI. Use [Manage access](/cosmos/config-mcp#sharing-an-mcp-server), not the legacy **Shared** toggle. If the configuration references a separately created generic secret, configure its use access and **Used in** coverage independently. ![](https://mintcdn.com/augment-mtje7p526w/ws3FkwddjnEOseab/images/cosmos-integrations/jira-cloud/jira-cloud-18.png?fit=max\&auto=format\&n=ws3FkwddjnEOseab\&q=85\&s=e9d3c2e4e4c236170e6eb42ed36f29e1) Note: when you save this configuration, the value of the Authorization header is stored securely in Cosmos’ secret manager. The older Secrets view is shown below: ![](https://mintcdn.com/augment-mtje7p526w/ws3FkwddjnEOseab/images/cosmos-integrations/jira-cloud/jira-cloud-19.png?fit=max\&auto=format\&n=ws3FkwddjnEOseab\&q=85\&s=b7e4117666c2e51162caa3d8c6289539) In your MCP registry you should now see your MCP server. ### Run a test Create a **fresh session in the target Space as an intended recipient** to test connectivity. An owner-only test or an existing session does not verify the recipient's access. Do not print credential values: * Left nav bar > + New session * Make sure the “Atlassian MCP server - service account” is attached to the session and that the native Atlassian integration is disabled * Prompt: lookup a given Jira ticket via its url * Send ![](https://mintcdn.com/augment-mtje7p526w/ws3FkwddjnEOseab/images/cosmos-integrations/jira-cloud/jira-cloud-20.png?fit=max\&auto=format\&n=ws3FkwddjnEOseab\&q=85\&s=07c4600d4ad2ade861d27ad4de85de89) * Then prompt the agent to add a hello world comment onto the ticket ![](https://mintcdn.com/augment-mtje7p526w/ws3FkwddjnEOseab/images/cosmos-integrations/jira-cloud/jira-cloud-21.png?fit=max\&auto=format\&n=ws3FkwddjnEOseab\&q=85\&s=9a627d2d26b088fd4c581c3fff37ba06) Verify that your Jira ticket has been updated: ![](https://mintcdn.com/augment-mtje7p526w/ws3FkwddjnEOseab/images/cosmos-integrations/jira-cloud/jira-cloud-22.png?fit=max\&auto=format\&n=ws3FkwddjnEOseab\&q=85\&s=41db3911672c1b8b5b46a78814c68fde) Congrats, now you can create a Cosmos expert that listens to the corresponding webhook, and leverage that Atlassian MCP server for full headless automation 🚀 # Integrate Microsoft Teams Source: https://docs.augmentcode.com/cosmos/connectors/microsoft-teams Connect Microsoft Teams so Cosmos Experts can read and respond to channel posts and chat messages. ## Introduction In this page we’ll configure the native MSFT Teams integration and learn how to: 1. Get Teams to notify Cosmos that new messages came in or that Augment/Cosmos was @ mentioned in a conversation 2. Configure Cosmos experts to react to those events, take action and reply back to the existing conversations 3. Deploy a simple expert that replies hello world to a Teams message ```mermaid theme={null} sequenceDiagram autonumber participant T as MSFT Teams participant A as Augment Code | Cosmos T->>A: Webhook: new message and/or new @ mention A->>A: Start Expert agent A->>T: Add eye emoji to the original post to indicate an agent is looking into it A->>A: Expert analyzes message and performs action. A->>T: Reply inline with response ``` ## Prerequisites To configure the one-time connectivity between Cosmos and Teams: **Cosmos** * you must be a Augment admin **Teams** * you must have Teams org-wide admin permissions to: * **enable custom apps globally** (Teams Admin Center [https://admin.teams.microsoft.com/](https://admin.teams.microsoft.com/) > Teams apps > Manage apps > Org-wide app settings > Turn on Custom apps) ![](https://mintcdn.com/augment-mtje7p526w/wvxDZZ1En2AtseBb/images/cosmos-integrations/microsoft-teams/microsoft-teams-01.png?fit=max\&auto=format\&n=wvxDZZ1En2AtseBb\&q=85\&s=f3f683746f90b57868e9617db525ed33) * **update the App Setup Policy**, as the specific user trying to upload the app ZIP file must be assigned an App Setup Policy that permits custom app uploads (Teams Admin Center [https://admin.teams.microsoft.com/](https://admin.teams.microsoft.com/) > Teams apps > Setup policies > Select the policy (e.g., Global) > Toggle Upload custom apps to On) ![](https://mintcdn.com/augment-mtje7p526w/wvxDZZ1En2AtseBb/images/cosmos-integrations/microsoft-teams/microsoft-teams-02.png?fit=max\&auto=format\&n=wvxDZZ1En2AtseBb\&q=85\&s=97c92b353baf69a851bbc8d1270c1c09) * **update Team-Level Setting** (if adding the app directly onto a Team). If a user wants to upload the app ZIP file directly into a specific team, the Team Owner must allow it. (Teams Client [https://teams.cloud.microsoft/](https://teams.cloud.microsoft/) > Go to the Team > More options (...) > Manage team > Settings > Member permissions > Check Allow members to upload custom apps.) ![](https://mintcdn.com/augment-mtje7p526w/wvxDZZ1En2AtseBb/images/cosmos-integrations/microsoft-teams/microsoft-teams-01.png?fit=max\&auto=format\&n=wvxDZZ1En2AtseBb\&q=85\&s=f3f683746f90b57868e9617db525ed33) ![](https://mintcdn.com/augment-mtje7p526w/wvxDZZ1En2AtseBb/images/cosmos-integrations/microsoft-teams/microsoft-teams-03.png?fit=max\&auto=format\&n=wvxDZZ1En2AtseBb\&q=85\&s=4c729e9efe4e11ddf7bb0c59c6f5522c) Once the app is available in your organization's app store (either an official MSFT app, a verified third-party app, or an approved custom app), installing it into a specific team channel requires the following permissions: * **App Permission Policy (Admin Level)**: the app must not be blocked by the organization's permission policies. The user installing it must have a policy that marks the app as "Allowed." (Teams Admin Center [https://admin.teams.microsoft.com/](https://admin.teams.microsoft.com/) > **Teams apps** > **Permission policies**.) ![](https://mintcdn.com/augment-mtje7p526w/wvxDZZ1En2AtseBb/images/cosmos-integrations/microsoft-teams/microsoft-teams-04.png?fit=max\&auto=format\&n=wvxDZZ1En2AtseBb\&q=85\&s=0306dc6a0a3893865e41725a498c1a22) * **Team Member Permissions (Team Level):** by default, all team members can add apps to channels. However, Team Owners can restrict this (Teams Client [https://teams.cloud.microsoft/](https://teams.cloud.microsoft/) > Go to the Team > **More options (...)** > **Manage team** > **Settings** > **Member permissions**. Ensure **Allow members to add and remove apps** is checked. If unchecked, *only* Team Owners can add apps to the channels.) ![](https://mintcdn.com/augment-mtje7p526w/wvxDZZ1En2AtseBb/images/cosmos-integrations/microsoft-teams/microsoft-teams-05.png?fit=max\&auto=format\&n=wvxDZZ1En2AtseBb\&q=85\&s=1b91613a5be0e2e9e7aaba214b464869) * **Tab Creation Permissions (Team Level):** because apps in channels often manifest as "Tabs" at the top of the channel, you also need to ensure members can manage tabs. (Teams Client [https://teams.cloud.microsoft/](https://teams.cloud.microsoft/) > Go to the Team > **More options (...)** > **Manage team** > **Settings** > **Member permissions.** Ensure **Allow members to create, update, and remove tabs** is checked.) ![](https://mintcdn.com/augment-mtje7p526w/wvxDZZ1En2AtseBb/images/cosmos-integrations/microsoft-teams/microsoft-teams-06.png?fit=max\&auto=format\&n=wvxDZZ1En2AtseBb\&q=85\&s=e71c1365771fbbde5705cb2ca07e4e55) > [!NOTE] > > Note: if you don’t see the Teams integrations in your tenant, reach out to your Augment Solutions Architect or send Augment a note: [**https://www.augmentcode.com/contact**](https://www.augmentcode.com/contact). ## Step 1 - Configure the native Teams integration As a Teams admin, go to [https://teams.cloud.microsoft/](https://teams.cloud.microsoft/) > left sidebar: Apps > Manage your apps: ![](https://mintcdn.com/augment-mtje7p526w/wvxDZZ1En2AtseBb/images/cosmos-integrations/microsoft-teams/microsoft-teams-07.png?fit=max\&auto=format\&n=wvxDZZ1En2AtseBb\&q=85\&s=4199b6cd751b16cf74b007d6b355ea4f) Click on Upload an app > Upload an app to your org’s app catalog: ![](https://mintcdn.com/augment-mtje7p526w/W82vGphL9_f3jMKm/images/cosmos-integrations/microsoft-teams/microsoft-teams-08.png?fit=max\&auto=format\&n=W82vGphL9_f3jMKm\&q=85\&s=43a2eb85cfcdea8f6424295fe5c9353e) If you’re on a Augment **US tenant**: * Download the app ZIP file from [https://github.com/augmentcode/integrations/raw/refs/heads/main/augment-teams-app-prod.zip](https://github.com/augmentcode/integrations/raw/refs/heads/main/augment-teams-app-prod.zip) and upload it to Teams If you’re on a Augment **EU tenant**: * Download the app ZIP file from [https://github.com/augmentcode/integrations/raw/refs/heads/main/augment-teams-app-prod-eu.zip](https://github.com/augmentcode/integrations/raw/refs/heads/main/augment-teams-app-prod-eu.zip) and upload it to Teams > [!NOTE] > > Once MSFT approves the Cosmos application in the Teams marketplace, it’ll replace the app ZIP file approach - stay tuned You should then be redirected to this: ![](https://mintcdn.com/augment-mtje7p526w/W82vGphL9_f3jMKm/images/cosmos-integrations/microsoft-teams/microsoft-teams-09.png?fit=max\&auto=format\&n=W82vGphL9_f3jMKm\&q=85\&s=11ca7d64541997cbc7e9de4317f505c8) Click on Cosmos > Add: ![](https://mintcdn.com/augment-mtje7p526w/W82vGphL9_f3jMKm/images/cosmos-integrations/microsoft-teams/microsoft-teams-10.png?fit=max\&auto=format\&n=W82vGphL9_f3jMKm\&q=85\&s=f4d7c7abf6115e7b7d1c68b95c93143b) You should see this (**DO NOT SELECT A CHANNEL YET!**): ![](https://mintcdn.com/augment-mtje7p526w/W82vGphL9_f3jMKm/images/cosmos-integrations/microsoft-teams/microsoft-teams-11.png?fit=max\&auto=format\&n=W82vGphL9_f3jMKm\&q=85\&s=32e56e81528b661f7cc8edbb2d503fa5) As an admin, go to Cosmos [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Connectors > Browse Connectors > Microsoft Teams > Click on it: ![Image](https://mintcdn.com/augment-mtje7p526w/DcSp85Sbl7ymWR-z/images/image-31.png?fit=max\&auto=format\&n=DcSp85Sbl7ymWR-z\&q=85\&s=064a17a100647d7e4801f1025c0ff6df) Select Consent on behalf of your organization > Click on Accept: ![](https://mintcdn.com/augment-mtje7p526w/W82vGphL9_f3jMKm/images/cosmos-integrations/microsoft-teams/microsoft-teams-13.png?fit=max\&auto=format\&n=W82vGphL9_f3jMKm\&q=85\&s=ecdfb908017765355afa6f5938e5474a) You should see your Microsoft Entra Tenant ID: ![Image](https://mintcdn.com/augment-mtje7p526w/DcSp85Sbl7ymWR-z/images/image-32.png?fit=max\&auto=format\&n=DcSp85Sbl7ymWR-z\&q=85\&s=def59f691f4e15bdc364047ed9218f46) Now you can go back to Teams: select a channel and click on Go: ![](https://mintcdn.com/augment-mtje7p526w/W82vGphL9_f3jMKm/images/cosmos-integrations/microsoft-teams/microsoft-teams-15.png?fit=max\&auto=format\&n=W82vGphL9_f3jMKm\&q=85\&s=2ea93a4910f6dc9841fd3759ef85d8c1) Let’s verify that Cosmos was notified that the app was added to a Teams channel: go to [cosmos.augmentcode.com](https://cosmos.augmentcode.com/) > Settings > Automations > Event Log tab. You should see this Microsoft Teams event: ![](https://mintcdn.com/augment-mtje7p526w/W82vGphL9_f3jMKm/images/cosmos-integrations/microsoft-teams/microsoft-teams-16.png?fit=max\&auto=format\&n=W82vGphL9_f3jMKm\&q=85\&s=32d32581a3b2aa0e6f6c7d28c1e79d0b) Click on that event, you’ll see the eventType “teamMemberAdded” (= Cosmos was added as member to this channel): ![](https://mintcdn.com/augment-mtje7p526w/W82vGphL9_f3jMKm/images/cosmos-integrations/microsoft-teams/microsoft-teams-17.png?fit=max\&auto=format\&n=W82vGphL9_f3jMKm\&q=85\&s=18d2008aa47b54f7a135b26651f3f68d) Teams is properly notifying Cosmos when events occur ✅ ## Step 2 - Run a test Now test the end2end connectivity with a test Q/A expert that will automatically reply to your messages in a given Teams channel. If you don’t have a Cosmos cloud environment yet, create an empty one for this test: Cosmos > Settings > Environment > Create an environment > Cloud Machine > Name: Test01 > Click on Create Environment. Go to Cosmos [https://cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New session > select the Cosmos Advisor expert, make sure the **Microsoft Teams** app is selected and prompt with **Deploy a Q/A test expert that will automatically reply to my messages in the Test-channel-listened-by-bot Teams channel**: ![](https://mintcdn.com/augment-mtje7p526w/W82vGphL9_f3jMKm/images/cosmos-integrations/microsoft-teams/microsoft-teams-18.png?fit=max\&auto=format\&n=W82vGphL9_f3jMKm\&q=85\&s=393fe69b7dfb37d068524bc8515d7947) Cosmos Advisor may ask you some clarification questions and then deploy the expert, you should see this: ![](https://mintcdn.com/augment-mtje7p526w/W82vGphL9_f3jMKm/images/cosmos-integrations/microsoft-teams/microsoft-teams-19.png?fit=max\&auto=format\&n=W82vGphL9_f3jMKm\&q=85\&s=2e4e7e69677f917c20b57db9e087d748) Now go to your Teams channel and run a test by typing **@ Cosmos** with a test message, then observe that Cosmos acknowledges and replies to it: ![](https://mintcdn.com/augment-mtje7p526w/W82vGphL9_f3jMKm/images/cosmos-integrations/microsoft-teams/microsoft-teams-20.png?fit=max\&auto=format\&n=W82vGphL9_f3jMKm\&q=85\&s=414ebe81ae3f47c5c9cc0d3af700c6e8) Congrats, you can now create Cosmos expert agents that integrate with Teams! 🎉 ## Understand how experts engage in conversations For channel events, Cosmos preserves the root channel post ID. The Expert uses that root ID for every reply, including responses to a message midway through the thread. For one-to-one and group chats, the Expert uses the chat conversation ID and posts messages sequentially. > [!NOTE] > > When debugging webhooks, triggers, or expert message routing, Teams channels and chats use different structures. [Channel posts](https://learn.microsoft.com/en-us/graph/teams-messaging-overview) are organized by tenant, [team](https://learn.microsoft.com/en-us/graph/api/resources/team), and channel, while [one-to-one and group chats](https://learn.microsoft.com/en-us/graph/api/resources/chat) belong directly to the tenant and use only a chat ID. This distinction determines which identifiers the Microsoft Teams integration uses to read context and route an expert's response: team, channel, and root post IDs for channel conversations, or a chat ID for chats. Every Expert post includes the Expert name and a link to the Cosmos session. > [!WARNING] > > Only grant Microsoft Teams access to experts that need it. Installing Cosmos in a team grants [resource-specific consent](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent) to read and send messages across that team's standard channels. Access to one-to-one and group chats is scoped to chats where Cosmos is installed. Summary of how an expert responds: | Teams surface | Conversation model | How an expert responds | | - | - | - | | Standard channel | A channel belongs to a team. Each channel post is the root of a reply thread. | Replies under the root channel post. | | Shared channel | A channel shared across organizational boundaries. | Expert participation is not supported. | | Private channel | A restricted channel with its own membership. | Expert participation is not supported. | | One-to-one chat | A sequential conversation between one person and Cosmos. | Posts the next message in the chat; there is no thread root. | | Group chat | A sequential conversation among multiple participants and Cosmos. | Posts the next message in the chat; there is no thread root. | # Integrate Twingate Source: https://docs.augmentcode.com/cosmos/connectors/twingate Configure a Cosmos cloud environment to securely access resources on a remote Linux virtual machine through Twingate. ## Introduction In this page we’ll explore how to configure a Cosmos cloud environment to connect to resources (ex: a local .html file) on a remote Linux VM via Twingate. ```mermaid theme={null} sequenceDiagram autonumber participant C as Cosmos Cloud Env participant TG as Twingate participant VM as Linux VM C->>TG: Outbound request
(Resource FQDN/IP) TG->>TG: Verify identity &
Zero Trust policy TG->>VM: Route traffic via
secure tunnel VM->>VM: Process request VM-->>TG: Response payload TG-->>C: Encrypted response ``` ## Prerequisites To configure the connectivity between Cosmos and ADO: * Cosmos * you must have edit access to the cloud env that will connect to a Twingate-protected resource * Twingate * you need a Twingate paid account (or active free trial) * you must have permissions to create a service account * you must have permissions to add a new connector: set of access token + refresh token to deploy a connector on the resource/network that will later be accessed by the Cosmos cloud env * AWS/GCP/Azure/on-prem * you must have SSH access to the Linux VM - this is where the Twingate connector will be deployed ## Step 1 - Twingate Connector configuration Go to your Twingate admin console > Network > Overview > Deploy connector > Cloud & Infrastructure > Linux. You should see “Install and Launch Connector Service”: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-01.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=891d2ecf8fb6ea666c45bc92fa034f63) Click on ‘Copy Command’, then ssh into your Linux VM and run the command copied above. You should see this: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-02.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=61bc0fb71d5a0a0b7f18d1da8fcab6c9) Then go back to Twingate > Networks > Connectors and observe that your connector has connected: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-03.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=6c128f64cf05668cf6bb4e37e3e41585) Now let’s create a test python server on that VM (that we’ll later allow-list as Resource in Twingate). First, get the private IP of that VM. From that VM run: ```text theme={null} hostname -I | awk '{print $1}' ``` You’ll get something like: 172.31.28.194 From that VM: * Create a test html file: ```text theme={null} echo "Hello, World!" > index.html ``` * Start a test python server (which will be serving the html file): ```text theme={null} python3 -c "import http.server, urllib.parse; H = type('H', (http.server.SimpleHTTPRequestHandler,), {'translate_path': lambda s, p: http.server.SimpleHTTPRequestHandler.translate_path(s, urllib.parse.urlparse(p).path)}); http.server.HTTPServer(('0.0.0.0', 8000), H).serve_forever()" ``` You should see this: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-04.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=2791be07c78b6ed08be527a16fb3a6bb) ## Step 2 - Twingate Service Account configuration Go to your Twingate admin console > Team > Services > Click on “+ Service” > Service Name = Cosmos > Create Service Account: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-05.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=53d93ce5e54c5e75f6d139f5325391d0) You should see this: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-06.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=5ee8781f0d455545cc284a1c6e7a0be9) Click on the service account name, the click on “+Service Key”: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-07.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=ea8cef483aaee7e3359821fdb48e3b69) Keep expiration = 365 days, then Generate: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-08.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=add62281955d4ec6e3137d543e4e0256) You’ll be offered to rename your key and download the service key token (ex: twingate-cosmos01.json). Then click on “Save & Close” ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-09.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=e7a093d44f6583d8ace44e94bd0a2037) ## Step 3 - Twingate Resource configuration Now we’ll add the Linux VM as “Resource” in Twingate. Go to your Twingate admin console > Network > Resources > “+Resource” > Select your network, enter as name “Linux VM”, enter the private IP of your Linux VM > click on Create Resource: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-10.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=2c4dd8aa0cb2401a094fda6bcf8f5c60) Then select your Cosmos service account > Grant Access: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-11.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=4636055b61df3668f67b325164ee03e2) You should see this: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-12.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=6a75045789c3a1ebf427c3bf9063c4b2) If you now go to your Cosmos service account view (Twingate admin console > Team > Services > Cosmos) you should see the granted resource: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-13.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=842170b5393a128f0b2662f40e581ea1) ## Step 4 - Cosmos cloud env configuration Go to your Cosmos cloud env from where you’d like to access your Twingate-protected resource. If you don’t have any, create a brand new env: [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > Settings > Environments > Create an environment > Cloud Machine: * Name: Test-Twingate * Base image: keep the Cosmos default * Repositories: select your repos * Refresh: toggle on * Click on Create Environment If you reopen your env, top right click on the 3 dots > Terminal: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-14.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=e23cb6c281a1abdd9491c4045595ba50) Install Twingate by running: ```text theme={null} curl -s https://binaries.twingate.com/client/linux/install.sh | bash ``` ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-15.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=2de7d60b66fdae710b8551c5ef587274) Now we’ll bring over the twingate-cosmos01.json key. Run: ```text theme={null} nano twingate-cosmos01.json ``` Then paste the content of your key, then CTRL-O to save the file, and CTRL-X to exit the file ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-16.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=1a2e8b3e2d9202907fcf53cfc7727add) Make sure twingate-cosmos01.json has been created: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-17.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=627a81b48e9f084e128cc5f333075ef4) Move up 1 folder: ```text theme={null} cd .. ``` ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-18.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=03eeb88c247de11f0d10f271a9916151) Now authenticate to Twingate by running: ```text theme={null} twingate setup --headless /workspace/twingate-cosmos01.json ``` You should see: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-19.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=bb1a6c48b59fdde0845edd51764cbde2) Let’s start Twingate in that terminal session: ```text theme={null} /sbin/twingated --http-proxy 127.0.0.1:9999 --tun off & ``` Then check that this process is running, paste and enter this: ```text theme={null} ps aux | grep twingated ``` You should see this: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-20.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=b32abb109e83b1bffba9be30443f6c82) Now let’s try to reach the index.html page: ```text theme={null} curl --proxy http://127.0.0.1:9999 http://172.31.28.194:8000 ``` And should see your Hello World!: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-21.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=75c263171b0eb0dcd617b0e2299770a1) Now click on “Update environment” to save your cloud env config, One more step: earlier Twingate was started only in that terminal session. Now we’ll ask Cosmos Advisor to update the cloud env’s startup script so it always starts Twingate upon booting the cloud env across all future sessions. Open a new Cosmos [https://cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New session > select Cosmos Advisor > select the Test-Twingate cloud env, prompt with ```text wrap theme={null} Incrementally update the existing Test-Twingate environment from its current snapshot. Do not rebuild or refresh it from the base image. Preserve all installed software, files, and configuration. Configure its user-controlled startup hook to run these commands on every VM startup: cd .. /sbin/twingated --http-proxy 127.0.0.1:9999 --tun off & Preserve any existing startup-hook content unless it directly conflicts with these commands. After updating the snapshot, launch a fresh test session using Test-Twingate and verify: 1. /sbin/twingated still exists. 2. A twingated process is running. 3. The proxy is listening on 127.0.0.1:9999. Do not report success based only on the environment update completing. Report the results of all three runtime checks. If any step would require a rebuild, stop and ask me first. When you delegate to a worker or background job, do not use its status field as evidence of completion. Confirm by reading its actual output or transcript. If a status check is inconclusive twice, switch tools rather than repeating it, and tell me what you tried. Never tell me "still waiting" more than once without having read the underlying output directly. ``` You should see: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-22.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=67571c03a2a2ee0a72941726031f11f8) ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-23.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=2a7d8b5a6134ef437b6f508429df4628) Any new session stemmed from that Test-Twingate cloud env will now have a Twingate tunnel running. ## Step 5 - Final Test Final check, start a brand new session without any expert and prompt `execute curl --proxy http://127.0.0.1:9999 http://172.31.28.194:8000`, you should see this: ![](https://mintcdn.com/augment-mtje7p526w/4zXBzN_O-cAt9KVy/images/cosmos-integrations/twingate/twingate-24.png?fit=max\&auto=format\&n=4zXBzN_O-cAt9KVy\&q=85\&s=ae28d7ee484798724eb29bde95f360bb) Congrats, you’ve configured Twingate with your Cosmos cloud env! You’re now able to leverage Cosmos experts to orchestrate Twingate-protected resources 🎉 # Cloud Environments Source: https://docs.augmentcode.com/cosmos/environments/cloud A cloud environment is a Augment hosted compute environment and filesystem for your agent to run. ## About cloud environments Cloud environments are Augment hosted compute for Cosmos. The environment consists of the base image, selected repositories, environment variables, and additional configuration that enable your agents to complete tasks. Each session starts from a fresh isolated snapshot of your environment and will automatically scale its resources for the workload. Cloud environments are used for both interactive and automation sessions. In most organizations, environments are configured for reuse by the entire team rather than a custom environment for each user. > [!NOTE] > > Putting sensitive information or credentials into an environment through environment variables or files will allow any user or agent that starts a session with the environment to access those secrets. ## Configuration ### Name Each environment must have a unique name across your entire organization. Environments are frequently named for the teams or projects they are built for: API Backend, Mobile Development, Analytics. ### Base image The base image is the Docker image that the environment is built from. You can choose from the curated list of images or choose any image from a public Docker registry with the required dependencies (`bash` and `git`). You can install additional packages after the environment is created. **Cosmos base images** | Name | Details | | - | - | | Cosmos Default | Ubuntu 26.04 with Python, Node.js 24, Go, Rust, .NET 10, and common dev tooling. Good general-purpose choice. | | TypeScript 6.0 | Debian 12 dev container with TypeScript 6.0 | | Python 3.12 | Official Python 3.12 dev environment | | Go 1.24 | Official Go 1.24 dev environment | | PHP 8.4 | Official PHP 8.4 dev environment | | Ruby 3.4 | Official Ruby 3.4 dev environment | | Rust 1.95 | Official Rust 1.95 dev environment | **Public registries** You can select any image available on a public Docker registry like DockerHub, GitHub Container Registry, or Google Artifact Registry. Enter the publically accessible URL like `docker.io/library/ubuntu:24.04`. Your selected image must have the following dependencies installed: `bash` and `git`. ### Repositories If you've connected your GitHub organization to Cosmos, you will be able to select which repositories are cloned to your environment automatically. You may select multiple repositories for a single environment and Cosmos will be able to work across them. If you have not installed the GitHub App or are using another source control platform, you can clone the repositories manually after the environment is created. Selected repositories are cloned into `/workspace/{org}/{repo}` automatically. You can add any additional git repositories to the `/workspace` directory that are not accessible with the GitHub App integration. ### Environment variables > [!NOTE] > > Do not store sensitive values in environment variables, use Secrets instead. Environment variables may appear in internal logs or session output, secrets are redacted automatically. Configure environment variables that will be loaded with each session. You may store up to 64kb of data as key-value pairs for your environment. * Names must start with a letter or underscore, and only contain letters, numbers, or underscores. * Name cannot start with `AUGMENT_`. * Names must be unique within the environment. ### Hooks You can utilize lifecycle hooks to run automatically to keep your environment and repositories up-to-date. All hook scripts are located in `/hooks`. You can customize the behavior of each of the hooks by editing the hook script. The available hooks are: | Hook | File | Description | | - | - | - | | Start | `on_startup.sh` | Runs when the environment first starts | | Refresh | `on_refresh.sh` | Manually run, or runs every 12 hours when enabled | ### Sharing Sharing an environment allows an entire team to utilize the best practices, tools, and configuration for a consistent agent experience. Environments utilize the object-level access controls (OLAC) that all other resources use in Cosmos. ### Networking All cloud environments have egress (outbound) network access only. Network access from the environment is separate from the network access configured for a Session. Tools like `curl` and other CLIs are able to connect to publicly accessible network resources from within the environment. Ingress traffic to the environment, from a web browser for example, is not enabled. #### Running Tailscale You can enable external access to the environment through services such as Tailscale, though you will need to configure it with [userspace networking](https://tailscale.com/docs/concepts/userspace-networking) instead of the default networking configuration. After you've installed `tailscaled` in the environment, start it with the following command: ```sh theme={null} tailscaled --tun=userspace-networking \ --outbound-http-proxy-listen=localhost:1054 \ --socks5-server=localhost:1055 ``` Add a **Secret** for your Tailscale authentication key and then run: ```sh theme={null} tailscale up --auth-key="$TS_AUTH_KEY" ``` You may want to add the above commands to your `on_startup.sh` hook to have Tailscale launch automatically with each session. Then start your app with the necessary proxy variables set, for example: ```sh theme={null} ALL_PROXY=socks5h://localhost:1055/ HTTP_PROXY=http://localhost:1054/ HTTPS_PROXY=http://localhost:1054/ pnpm dev ``` ## Additional dependencies and configuration After an environment is created, you can use the built-in terminal to run commands and install additional dependencies to finish the configuration for your projects. After you have run any additional commands (e.g., `pnpm install`), select `Update environment` to save the current environment state. ## Updating an environment You can update an environment in a number of ways: 1. Manually through the web terminal and environment form 2. By using an existing session's environment as the new base environment 3. Asking the Cosmos Advisor to update the environment for you Updates to an environment will only update future sessions, any existing session's environment will not receive the updates. ### Manual updates You can update an environment configuration such as Environment Variables, synced Repositories, or other metadata by going to the environment in Cosmos web and making changes. You can also select `Terminal` to launch an interactive terminal to change configuration on the filesystem, such as installed packages. After you make changes either in the web form or terminal, you must select `Update environment` to persist the changes. ### From existing session You may want to use an existing session as the base of your environment. This is particularly useful when you have an agent make changes to the environment for you, such as when you are first configuring an environment for a project. To save an environment from a session: 1. Go to the session that will be the source of your environment 2. Open the session sidebar 3. Under Environment, select the kebab menu 4. Select *Update environment from session*. If you do not have the proper permissions to update an environment, you can *Create a new environment* instead. The full environment state from that session will be saved as the new environmnet, this includes any in-progress changes to your codebase. It's best to check that you have a clean working directory and are on the default branch for each repository before saving the environment. ### Using Cosmos Advisor You can use **Cosmos Advisor** to update an environment for you. Select the Advisor expert and use natural language to describe the changes you want to make. ## Refreshing an environment Environments can be updated automatically to retrieve the latest changes to your codebase, keep your dependencies up-to-date, or any other maintenance task you need to run. Each environment has a built-in refresh `bash` script at `/hooks/on_refresh.sh` that you can update. Refreshing your environment will allow your agents to work more effectively. By default the refresh script includes automatically fetching the latest changes to your git repositories located in `/workspace`, even if they were manually added by you. Update the script to run other commands, like `pnpm install`, to keep them up-to-date with your repos. If enabled in the environment configuration, the refresh script will run every 12 hours. You can also manually run the refresh script from the Cosmos web UI. ## Deleting an environment You can permanently delete an environment from the Cosmos web UI from within the Environment detail page. Deleted environments are not recoverable. # Configure Self-Hosted Daemons with daemon-config.json Source: https://docs.augmentcode.com/cosmos/environments/daemon-config Configure Auggie's self-hosted daemon with discovered JSON files or generate configuration from explicit command-line flags. ## About `daemon-config.json` Use `daemon-config.json` to configure a self-hosted Cosmos daemon without repeating command-line flags. Auggie loads it automatically when you run `auggie daemon`; restart the daemon after changing it. > [!NOTE] > > `daemon-config.json` requires Auggie 1.x. If you currently run Auggie 0.x, follow [Migrate from Auggie 0.x](/cosmos/environments/daemons#migrate-from-auggie-0-x). For installation and authentication, see [Self-Hosted Environments](/cosmos/environments/daemons). See [Workspaces and Isolation](/cosmos/environments/daemon-workspaces) and [Daemon Pools](/cosmos/environments/daemon-pools) for related setup. ## Quickstart Create `.augment/daemon-config.json` in your workspace with only the settings you want to change. This configuration gives the daemon a recognizable name and limits it to 125 concurrent sessions: ```json theme={null} { "name": "development-daemon", "maxAgents": 125 } ``` Start Auggie from the workspace: ```sh theme={null} cd /path/to/workspace auggie daemon ``` This file sets only the daemon name and concurrency limit. Other effective values can still come from higher- or lower-precedence configuration, persisted daemon state, indexing permissions, or defaults. > [!NOTE] > > `daemon-config.json` uses strict JSON, so inline comments and trailing commas are not supported. Keep explanations outside the JSON document, as shown above. ## Example The following example configures a pooled team daemon with repository discovery, one additional repository, isolated-worktree behavior, and file logging. Replace the pool ID and paths before using it, or omit settings that do not apply to your environment. ```json theme={null} { "name": "team-daemon", "maxAgents": 125, "workspace": "/srv/repositories", "poolId": "replace-with-pool-id", "addWorkspaces": [ "/srv/standalone-repository" ], "allowIndexing": true, "gitCredentialMode": "none", "worktreeDir": "~/.augment/worktrees", "noWorktreePull": false, "discoverWorkspaces": { "enabled": true, "depth": 2 }, "logFile": "~/.augment/logs/daemon.log", "logLevel": "info" } ``` * `allowIndexing: true` enables indexing for eligible configured workspaces. Review the [indexing permission behavior](#indexing-and-indexing-permissions) before enabling it. * `gitCredentialMode: "none"` disables daemon-provided Git credentials. Review [Git credential mode](#git-credential-mode) before selecting another mode. * Set `noWorktreePull` to `true` to base new worktrees on local `HEAD` instead of the latest fetched upstream commit. * Omit `poolId` if the daemon should not join a pool. Use `spaceId` instead to assign a standalone daemon to a Space. * `vmId` and `newVmId` are intentionally omitted so Auggie can reuse the persisted daemon identity. ## Generate Configuration from Flags Auggie can convert explicitly supplied daemon flags into `daemon-config.json` fields. These actions run offline and exit without starting the daemon. ### Preview Generated JSON Use `--config-print` to print strict JSON to standard output: ```sh theme={null} auggie daemon \ --name team-daemon \ --max-agents 125 \ --allow-indexing \ --config-print ``` Only flags supplied in that command are included. Existing configuration values and parser defaults are not copied, and relative paths are converted to absolute paths from the invocation directory. The one-shot `--new-vm-id` action is omitted with a warning because persisting it would request a new identity on every launch. ### Write a Configuration File Use `--config-write=scope` to write the generated configuration directly: | Scope | Option | Destination | | - | - | - | | Global | `--config-write` or `--config-write=global` | Global daemon configuration | | Project | `--config-write=project` | `/.augment/daemon-config.json` | | Local project | `--config-write=local` | `/.augment/daemon-config.local.json` | For example: ```sh theme={null} auggie daemon \ --workspace /srv/repositories \ --name team-daemon \ --max-agents 125 \ --allow-indexing \ --config-write=project ``` Use the `--config-write=project` or `--config-write=local` equals-sign syntax. An explicit `--workspace` selects the destination workspace; otherwise Auggie uses the current Git root or current directory. > [!WARNING] > > Writing configuration replaces the entire destination file; it does not merge with existing content. Auggie asks for confirmation before replacing an existing file in an interactive terminal and refuses the replacement when confirmation is unavailable. Use `--config-print` and merge manually when you need to preserve existing settings. ## Configuration File Locations Daemon configuration follows the same file hierarchy described in [Hierarchical Settings File](/cli/settings#settings-files), using daemon-specific filenames. The scope locations are the same, but merge behavior differs: use the precedence and replacement rules documented on this page for `daemon-config.json`. Auggie checks four configuration scopes on every daemon start: | Scope | Location | Recommended use | | - | - | - | | Managed | `/etc/augment/daemon-config.json` on macOS and Linux; `C:\ProgramData\augment\daemon-config.json` on Windows | Organization-managed defaults for a host | | Local project | `/.augment/daemon-config.local.json` | Personal overrides for one workspace; add this file to `.gitignore` | | Project | `/.augment/daemon-config.json` | Team configuration that can be committed with the repository | | Global | `~/.augment/daemon-config.json` on macOS and Linux; `C:\Users\\.augment\daemon-config.json` on Windows | Personal defaults for every daemon | Configuration files are optional. Project and local files are resolved from an explicit `--workspace` path, otherwise from the current Git root or current directory. A `workspace` value inside the file changes the daemon's primary workspace but does not relocate config discovery. ## Precedence and daemon-specific merging `daemon-config.json` uses the same file-scope order as [`settings.json`](/cli/settings#settings-files): managed, local project, project, then global. The key precedence difference is that explicit daemon CLI flags sit above every file and can override managed daemon configuration, while managed `settings.json` values are locked and cannot be overridden by users. The formats also merge differently: | Behavior | `daemon-config.json` | `settings.json` | | - | - | - | | Managed values | Can be overridden by explicit daemon CLI flags | Cannot be overridden by users | | Arrays and objects | Replaced as complete values by the higher-precedence file | Generally combined across tiers, with field-specific rules | | File syntax | Strict JSON | JSON with Comments (JSONC) | Keep these daemon-specific rules in mind: * Missing keys inherit from lower-precedence scopes. Set a key to `null` to mask a lower value. * Arrays and objects are replaced, not combined or deep-merged. For example, a local `addWorkspaces` array replaces the project array. * `worktreeDir` falls back to its value in `settings.json` when it is absent from CLI flags and every daemon config scope. * `allowIndexing` is enable-only at the command line. Effective config `true` or `--allow-indexing` enables it; there is no CLI disable flag. * `vmId` cannot be combined with `newVmId`, and `poolId` cannot be combined with `spaceId`. When changing a configuration-only value, set the old key to `null` in the higher scope. * For persisted pool or Space membership, `null` only masks a lower config value. Use `poolId: ""` or `spaceId: ""` to actively clear existing membership. ## Path resolution `workspace`, `addWorkspaces`, `worktreeDir`, and `logFile` accept absolute paths or `~`-prefixed home paths. Other relative paths resolve from the directory containing the config file—not the workspace root. For example, `../../repo-b` in `/srv/repo-a/.augment/daemon-config.json` resolves to `/srv/repo-b`. > [!TIP] > > Use absolute paths in machine-specific global or managed configuration. ## Configuration reference Every key is optional. Any supported key may be set to `null` to mask a lower-precedence value. | Key | Type | Description | | - | - | - | | `name` | string | Name shown for the daemon. Defaults to `:`. | | `maxAgents` | positive integer | Maximum number of concurrent child-agent sessions. Defaults to `100`. | | `workspace` | string | Primary workspace path. Defaults to the directory from which the daemon is launched. A global or managed value applies to every daemon on the machine and produces a warning. | | `vmId` | UUID v4 string | Reconnect using a specific existing daemon identity. Allowed only in project or local project configuration. Most users should omit this key and let Auggie reuse its persisted identity. | | `newVmId` | boolean | When `true`, generate a new daemon identity. Prefer the one-time `--new-vm-id` flag unless every start should request a new identity. Cannot be combined with `vmId`. | | `poolId` | string | Join the specified daemon pool. Set to `""` to clear persisted pool membership. Cannot be combined with `spaceId`. | | `spaceId` | string | Assign a standalone daemon to a Space by UUID, name, or slug. Set to `""` to clear persisted Space membership. Cannot be combined with `poolId`; pooled daemons inherit Space membership from their pool. | | `addWorkspaces` | array of strings | Additional Git repository paths. Each entry is resolved independently. The daemon does not search these paths for nested repositories. | | `allowIndexing` | boolean | Allow child agents to index eligible configured workspaces. Defaults to `false`. Either effective config `true` or `--allow-indexing` enables it; there is no command-line disable flag. | | `gitCredentialMode` | string | Select daemon-provided Git credentials: `none`, `user-oauth`, or `github-app`. The file stores only the policy, not credential material. | | `worktreeDir` | string | Base directory for isolated-workspace Git worktrees. Defaults to `~/.augment/worktrees`. An empty `--worktree-dir=` flag is treated as absent and does not clear a configured value. | | `noWorktreePull` | boolean | When `true`, base new isolated worktrees on the daemon workspace's local `HEAD`. When `false` or omitted, use the latest fetched commit from the current branch's upstream when available. Existing agent worktrees are not rebased or recreated. | | `discoverWorkspaces` | object | Controls Git repository discovery beneath a non-Git primary workspace. See [Repository discovery](#repository-discovery). | | `logFile` | string | Daemon log path. If omitted, Auggie uses `augment-daemon.txt` in its temporary directory. The value `"-"` is not supported. | | `logLevel` | string | Logging verbosity: `error`, `warn`, `info`, or `debug`. Defaults to `info`. Values are lowercase. | ## Repository discovery See [Workspaces and isolation](/cosmos/environments/daemon-workspaces#configure-workspaces) for layouts and behavior. In `daemon-config.json`, set `discoverWorkspaces.enabled` to `true` or `false`; when enabled, optional `depth` must be from `1` through `5` and defaults to `1`. Discovery is refused at the user's home directory or a filesystem root. The daemon advertises up to 64 additional workspaces; overflow entries are dropped with a warning. ## Workspace isolation See [Workspace isolation](/cosmos/environments/daemon-workspaces#workspace-isolation) for requirements and behavior. `worktreeDir` controls where isolated worktrees are stored. By default, new worktrees use the latest fetched commit from the tracked upstream; set `noWorktreePull` to `true` to use local `HEAD` instead. Existing worktrees are not changed. ## Git Credential Mode `gitCredentialMode` controls whether the daemon provides Git credentials to child-agent Git operations: * `none` disables daemon-provided Git credentials. * `user-oauth` uses the daemon user's GitHub OAuth access and is supported on macOS and Linux. * `github-app` uses GitHub App access available to the daemon. The configuration stores only the selected policy, not tokens or other credential material. An explicit `--git-credential-mode` flag overrides configured values for that launch. > [!WARNING] > > Project configuration is treated as user-approved policy and can enable credential access for child sessions. Review `gitCredentialMode` before starting a daemon from a repository you do not trust. ## Indexing and Indexing Permissions Set `allowIndexing` to enable indexing for configured workspaces that do not already have an explicit indexing permission: ```json theme={null} { "allowIndexing": true } ``` Auggie evaluates indexing permissions separately for each eligible workspace: * Paths covered by `indexingDenyDirs` in `settings.json`, stored deny decisions, and the home-directory hard block remain disabled. `allowIndexing` does not override them. * Paths covered by `indexingAllowDirs` or a stored allow decision can be indexed without `allowIndexing`. * Eligible paths without an allow or deny rule are indexed only when effective config `allowIndexing` is `true` or the daemon starts with `--allow-indexing`. * Git worktrees inherit the indexing permission of their main repository. * When the daemon starts interactively without `allowIndexing`, it may prompt to save allow decisions for unruled workspaces. Non-interactive startup does not prompt, so those workspaces remain disabled. `indexingAllowDirs` and `indexingDenyDirs` belong in `settings.json`, not `daemon-config.json`. Their hierarchy and merge behavior are described in [Hierarchical Settings File](/cli/settings#settings-files). Stored decisions are written to `~/.augment/indexing-permissions.json` by default. To revoke a stored allow, remove the relevant entry, ensure the path is not enabled by `allowIndexing` or `indexingAllowDirs`, and restart the daemon. There is no `--no-allow-indexing` flag. To disable a configured value, change the file that enables it or mask a lower-scope value with `null` in a higher-precedence file. > [!WARNING] > > A committed project configuration applies to everyone who starts a daemon from that workspace. Review `allowIndexing` and `gitCredentialMode` before committing it, and never place credentials or secrets in a daemon configuration file. ## Local overrides Keep shared defaults in `.augment/daemon-config.json`. Add `.augment/daemon-config.local.json` to `.gitignore` and use it for personal overrides: ```json theme={null} { "allowIndexing": false, "logLevel": "debug", "logFile": "daemon.local.log" } ``` ## Override configuration for one launch Explicit flags override file values. For example, `auggie daemon --max-agents 125 --log-level debug`. An explicit `--pool-id` or `--space-id` also clears the configured alternative for that launch. Run `auggie daemon --help` for the full reference. ## Validation Auggie validates config at startup. Malformed JSON, invalid known values, forbidden global or managed `vmId`, and conflicting option pairs stop startup; unknown keys produce warnings and are ignored. A global or managed `workspace` is accepted with a warning because it affects every daemon on the machine. ## See also * [Self-Hosted Environments](/cosmos/environments/daemons) * [Workspaces and Isolation](/cosmos/environments/daemon-workspaces) * [Daemon Pools](/cosmos/environments/daemon-pools) * [Migrate from Auggie 0.x](/cosmos/environments/daemons#migrate-from-auggie-0-x) * [Auggie CLI authentication](/cli/setup-auggie/authentication) * [CLI reference](/cli/reference) # Use Self-Hosted Daemon Pools Source: https://docs.augmentcode.com/cosmos/environments/daemon-pools Group self-hosted daemon machines into a pool and configure connectors, workspace behavior, and routing. ## About daemon pools Daemon pools group distinct hosts into one Cosmos environment. When a session starts in a pooled environment, Cosmos routes it to an eligible daemon based on workspace requirements and current load, without requiring the user to choose a specific machine. Create and manage a pool in the Cosmos web UI or declaratively with [Auggie Cloud](/cli/cloud), then connect one or more daemons. ## Create a pool in the web UI Open the [Environments list](https://cosmos.augmentcode.com/environments), select **Create an environment**, then select **Daemon Pool**. ## Manage pools with Auggie Cloud Use a daemon pool bundle to create or update a pool from a YAML file. Initialize a bundle, set `spec.pool.workspaceIsolation` to `shared` or `isolated`, preview the change, and apply it: ```sh theme={null} auggie cloud pool init --name team-pool -o pool.yaml # Edit pool.yaml and set spec.pool.workspaceIsolation to shared or isolated. auggie cloud pool apply -f pool.yaml --dry-run auggie cloud pool apply -f pool.yaml ``` After an apply, the CLI writes `metadata.poolId` and `metadata.resourceVersion` to the bundle. Subsequent applies use them for concurrency-safe updates. To begin from an existing pool, export its bundle: ```sh theme={null} auggie cloud pool export -o pool.yaml ``` > [!NOTE] > > Daemon pool bundles are a Preview CLI feature available to early adopters. Run `auggie cloud pool --help` to confirm that your installed CLI includes these commands. ## Configure a pool ### Name The pool must have a unique name across your organization. ### Connector Only daemons with the proper authentication can connect to the pool. Select either the current user or a service account as the pool's connector. Every daemon must authenticate as that user or service account before joining. ### Workspace behavior Choose how sessions use the workspaces on connected daemons: * **Isolated Workspace**: Each agent uses its own Git worktrees. Every daemon connected to the pool must support Git worktree isolation across all configured repositories. A non-Git discovery container is supported, but every discovered or explicitly added workspace must be a Git repository. * **Shared Workspace**: Agents edit each daemon's working copy directly. Concurrent sessions can overwrite changes, create conflicts, or leave the checkout in an unexpected state. This setting applies to every session routed to the pool. Before choosing **Isolated Workspace**, configure each daemon to meet the [workspace isolation requirements](/cosmos/environments/daemon-workspaces#workspace-isolation). ## Connect a daemon to a pool Find the pool ID on the pool's detail page. Start the daemon with `--pool-id` while authenticated as the pool's configured connector: ```sh theme={null} auggie daemon --pool-id ``` For persistent configuration, set `poolId` in [`daemon-config.json`](/cosmos/environments/daemon-config). Do not also set `spaceId`; pooled daemons inherit their Space from the pool. ## See also * [Self-Hosted Daemon Overview](/cosmos/environments/daemons) * [Workspaces and Isolation](/cosmos/environments/daemon-workspaces) * [Daemon Configuration File](/cosmos/environments/daemon-config) # Configure Daemon Workspaces and Isolation Source: https://docs.augmentcode.com/cosmos/environments/daemon-workspaces Configure repositories, repository discovery, and isolated or shared workspaces for self-hosted Cosmos daemons. ## Configure workspaces A daemon starts with one primary workspace. If that path is a Git repository, the daemon uses it directly. If it is a non-Git container, the daemon can discover repositories beneath it. Add direct Git repositories to either configuration with `--add-workspace` or `addWorkspaces` in [`daemon-config.json`](/cosmos/environments/daemon-config). ### Single repository Point `--workspace` directly to the Git repository: ```sh theme={null} auggie daemon --workspace /path/to/repo-a ``` ### Repository collection For multiple repositories, place them beneath one non-Git container directory. For example: ```text theme={null} references/ ├── group-a/ │ ├── repo-a/ │ └── repo-b/ ├── group-b/ │ ├── repo-c/ │ └── repo-d/ └── group-c/ └── repo-e/ ``` Set the container as the primary workspace and specify how many directory levels the daemon should search: ```sh theme={null} auggie daemon --workspace /path/to/references --discover-workspaces=2 ``` `--discover-workspaces=2` searches beneath `--workspace` for repositories in a `references/group/repository` layout. Discovery searches only the primary workspace; it does not search directories passed with `--add-workspace`. ### Mixed mode Use `--add-workspace` to include direct Git repositories outside the discovery tree: ```sh theme={null} auggie daemon --workspace /path/to/references --discover-workspaces=2 \ --add-workspace /path/to/standalone-repo ``` This configuration includes repositories discovered beneath `references` and the explicitly added `standalone-repo`. The daemon does not search beneath `standalone-repo`. To add repositories explicitly without discovery, point `--workspace` to one Git repository and repeat `--add-workspace` for each additional Git repository. A non-Git container workspace can include up to 64 repositories across discovered repositories and explicit `--add-workspace` entries. ## Workspace isolation Cosmos offers two workspace behaviors for daemon-backed sessions: * **Isolated Workspace**: Gives each agent its own Git worktree so file edits do not affect the daemon workspace. For multiple repositories, the daemon creates a separate per-session worktree for each discovered or explicitly added Git repository. * **Shared Workspace**: Agents use the daemon workspace directly, so file edits affect its working copy. Concurrent sessions can overwrite changes, create conflicts, or leave the checkout in an unexpected state. We recommend **Isolated Workspace** when running concurrent sessions or when you want to keep agent changes separate from your working copy. Every discovered or explicitly added workspace must be a Git repository to use isolation. A non-Git discovery container is not placed in a worktree and does not prevent isolation. New isolated worktrees use the latest fetched commit from the current branch's tracked upstream by default. Start the daemon with `--no-worktree-pull` to base new worktrees on the daemon workspace's local `HEAD` instead. Existing worktrees are not rebased or recreated. Isolated daemon workspaces require **Git 2.31.0 or newer**, released March 15, 2021. At startup, the daemon logs the installed Git version and the minimum required version. If Git is old, unavailable, or its version cannot be parsed, the daemon remains online but reports worktrees as unsupported and cannot serve isolated pools. Upgrade or install Git, or use **Shared Workspace** instead. When aggregate worktree isolation is unsupported, startup emits one `Isolation blocker` warning for each failing prerequisite. Each warning identifies `Host Git` or the specific `Primary workspace` or `Additional workspace` path and includes a stable reason code. ## See also * [Self-Hosted Daemon Overview](/cosmos/environments/daemons) * [Daemon Configuration File](/cosmos/environments/daemon-config) * [Daemon Pools](/cosmos/environments/daemon-pools) # Self-Hosted Environments Source: https://docs.augmentcode.com/cosmos/environments/daemons You can run your agents on your own virtual or physical infrastructure with self-hosted daemons. ## About self-hosted daemons Self-hosted daemons are ideal for teams that want Cosmos agents to run on your own infrastructure. You can run a single daemon to quickly use your personal setup to work with Cosmos, or deploy a daemon pool to provide a group of workers to Cosmos to distribute sessions to. Daemons have access to the host machine's CPU, disk, and network; agents execute tools and make edits on the host machine but still make all LLM calls to Augment's external services. You can use **daemon pools** to group multiple separate machines into a single environment. Cosmos routes sessions to eligible daemons based on workspace requirements and current load, without requiring the user to select a specific machine. ## Using daemons Each host must run the daemon process included with Auggie CLI. ### Install Auggie CLI Install the latest Auggie CLI daemon release on each host. You need `npm` available on the host: ```sh theme={null} npm install -g @augmentcode/auggie@daemon ``` Confirm that Auggie reports a `1.x` version: ```sh theme={null} auggie --version ``` ### Authenticate Auggie CLI Log in to your Augment account. Your authentication is persisted on the host: ```sh theme={null} auggie login ``` You can also use [other available authentication methods](/cli/setup-auggie/authentication) to provide credentials. ### Start the daemon Start the daemon from the workspace you want it to use: ```sh theme={null} cd /path/to/workspace auggie daemon ``` When attached to a terminal, the daemon displays a dashboard with its connection status, configured workspaces, and running sessions. Press `Ctrl+C` to stop it cleanly. ### Keep the daemon up to date The daemon does not install updates while it is running. Periodically upgrade Auggie, then restart the daemon: ```sh theme={null} auggie upgrade ``` ### Configuration For repeatable settings, use [daemon configuration files](/cosmos/environments/daemon-config). Auggie automatically discovers global, project, local project, and managed `daemon-config.json` files. You can override file settings for one launch with command-line flags. Run `auggie daemon --help` for the complete command-line reference. ### Workspaces and Isolation Choose which repositories the daemon exposes and whether sessions use shared checkouts or isolated Git worktrees. See [Workspaces and Isolation](/cosmos/environments/daemon-workspaces) for repository discovery, mixed workspace layouts, requirements, and worktree behavior. ### Disconnecting You can disconnect the daemon at any time with `Ctrl+C` or by shutting down the host machine. Messages sent while the daemon is disconnected remain queued until it reconnects. The session expects the reconnected daemon to have the same filesystem state. Use isolated Git worktrees to reduce errors when sessions reconnect to a changed workspace. ### Networking Daemons need outbound access to Augment services to complete inference requests. See [Network configuration](/setup-augment/network-configuration) for the required domain allowlist. ## Migrate from Auggie 0.x Auggie 1.x uses the rebuilt agent harness. If a host still runs Auggie 0.x, use an identity-preserving cutover to retain the daemon identity, workspace changes, worktrees, and recoverable sessions. 1. Let active sessions finish their current turns. 2. Record the daemon's canonical workspace path and repeatable launch options. 3. Stop the existing daemon cleanly with `Ctrl+C`. 4. Install Auggie 1.x: ```sh theme={null} npm install -g @augmentcode/auggie@daemon ``` 5. Start the daemon from the same canonical workspace path with the recorded launch options, using the same Augment account and tenant: ```sh theme={null} cd /path/to/workspace auggie daemon ``` 6. Confirm that the expected daemon, workspaces, pool or Space, and connection status appear in Cosmos. 7. Start a test session and verify messages, tool execution, diff review, terminal access, and local changes. 8. Send a follow-up message to an idle session created before the upgrade to verify conversation recovery and workspace preservation. > [!WARNING] > > Do not pass `--new-vm-id` during the migration. Keep `~/.augment/daemon` and existing daemon worktrees in place, and never run Auggie 0.x and 1.x concurrently with the same daemon identity. > [!NOTE] > > **Optional: generate a configuration file.** After installing Auggie 1.x, you can convert the recorded launch options instead of continuing to pass them on every launch. Preview the generated JSON with `--config-print`: > > ```sh theme={null} > auggie daemon \ > --workspace /path/to/workspace \ > \ > --config-print > ``` > > If the output is correct, write it to your preferred scope. This example uses the local project scope for host-specific settings: > > ```sh theme={null} > auggie daemon \ > --workspace /path/to/workspace \ > \ > --config-write=local > ``` > > Both commands exit without starting the daemon. If you write the configuration, omit `` when starting the daemon in step 5. > > `--config-write` replaces the entire destination file after confirmation; it does not merge with existing configuration. If the destination already contains settings you need, use `--config-print` and merge the generated JSON manually. See [Generate Configuration from Flags](/cosmos/environments/daemon-config#generate-configuration-from-flags). The cutover preserves durable state; it does not hand off a running process. Existing shared-workspace changes and isolated worktrees remain available, and eligible idle sessions can recover their conversation. In-flight model calls, tool executions, shells, terminals, child processes, and other in-memory state are interrupted rather than transferred. ## Next steps * [Configure Daemon Workspaces and Isolation](/cosmos/environments/daemon-workspaces) * [Configure the Daemon with `daemon-config.json`](/cosmos/environments/daemon-config) * [Create and Manage Daemon Pools](/cosmos/environments/daemon-pools) # Cosmos Environments Source: https://docs.augmentcode.com/cosmos/environments/overview The compute environment where your agents access filesystem, repositories, execute code, and run tools. They can be an Augment-hosted cloud sandbox, virtual machine, or even your laptop. ## About environments Environments provide a consistent workspace for agents to run commands and execute code. An environment includes your repositories, toolchain, and Cosmos dependencies like [Auggie](/cli/overview). You can host your environment on Augment's cloud sandboxes, or use self-hosted daemons to use your own virtual machine infrastructure or laptop. The fastest way to experience Cosmos is to run the daemon on a development machine you already have configured, like your laptop. > [!NOTE] > > The fastest way to build or update an environment is to ask [Cosmos Advisor](/cosmos/advisor/overview) to do it for you — and it's strongly recommended over hand-editing the environment form. Describe your project in plain language and the Advisor picks the base image, syncs the right repositories, and installs your toolchain, rather than you configuring it by hand. ## Getting started | | **Cloud environment** | **Self-hosted daemon** | | - | - | - | | **Where it runs** | Augment infrastructure | Your machine (laptop, virtual machine, devbox) | | **Setup** | Configure with repos, tools, and secrets | Run `auggie daemon` on the host | | **Network access** | Configured egress only | Same as host | | **Concurrency** | Unlimited | Bounded by the number of daemons you've connected | | **Persistence between sessions** | New each sessions | Disk and other state persists | | **Cost model** | Billed per minute of uptime | No additional costs | | **Best for** | Most workflows. Reproducible, isolated, scales with the team. | Local-network access, custom hardware, regulated data that can't leave your premises. | ### Cloud environments A cloud environment is a reproducible image that Cosmos uses with each session. You build it once by choosing a base image, selecting repositories, set environment variables, and install dependencies and every session that targets it starts from that snapshot. Read more about [cloud environments](/cosmos/environments/cloud) or [create a new environment](https://cosmos.augmentcode.com/environments/create). ### Self-hosted daemons A daemon is a long-running Cosmos process on a machine you operate, virtual or physical. Sessions targeted at the daemon execute on that machine and have access to its CPU, disk, and network. Use daemons when the work needs to happen somewhere specific like your laptop, a VPC-bound virtual machine, a Mac mini that handles iOS builds, or a virtual devbox. Read more about [self-hosted daemons](/cosmos/environments/daemons). # Cosmos Experts Source: https://docs.augmentcode.com/cosmos/experts Reusable agent configurations for engineering workflows like authoring code, reviewing code, investigating incidents, and more. ## Overview An **Expert** is a reusable agent in Cosmos. It packages a system prompt, user instructions, integrations, environment, model, and workers that make a repeatable engineering workflow feel like a product surface instead of a one-off prompt. ## How to Engage an Expert * **Start a Session**: From the Cosmos sidebar, click New Session and select an Expert to begin chatting, coding or kicking off a task. * **Schedule It**: Set a recurring schedule and timezone for the Expert to run under [Automations](/cosmos/automations). * **Automate It**: Trigger your Expert using event-based integrations with GitHub, GitLab, Linear, Slack, PagerDuty, and more. ## Sharing Your Expert You have full control over who gets to use your Expert. Choose the level of access that works best for your workflow: * **Private**: Keep your Expert completely private for your own personal use. * **Specific teammates**: Invite specific team members to use your Expert. * **Spaces**: Restrict access to a specific [Space](/cosmos/spaces/overview) so only relevant groups can use your Expert. * **Organization**: Share with your entire organization. ## What an Expert includes An Expert brings together everything Cosmos needs to run a repeatable agent workflow: * **Identity and sharing**: a display name, description, visibility, and stable Expert ID. * **Instructions**: the system prompt, optional default system prompt, user-facing instructions, and placeholder text shown when someone starts a session. * **Model**: the model the Expert uses by default, with room for managed alternatives as the workflow evolves. * **Capabilities and integrations**: the tools the Expert can use, such as web access, code hosting, ticketing, communication, or organization-specific integrations. * **Environment**: the VM, runtime environment, repositories, and resources the Expert uses when it runs. * **Launch experience**: initial messages, user instructions, and input guidance that make it clear what someone should provide. * **Workers**: the other Experts this Expert can launch for delegated tasks, plus whether it can use all available Experts as workers. > [!NOTE] > > The fastest way to set up an Expert is to ask [Cosmos Advisor](/cosmos/advisor/overview) to do it for you — and it's strongly recommended to manage Experts by prompting the Advisor rather than hand-editing the configuration form. Describe the workflow you want in plain language and the Advisor deploys a Template Expert or designs a custom one end-to-end — picking the environment, capabilities, and triggers — rather than you configuring it by hand. ## Next steps * [Cosmos Advisor](/cosmos/advisor/overview) — have the Advisor set up and tune Experts for you conversationally. * [Template Experts](/cosmos/experts-templates) — start from a built-in Template Expert for common SDLC workflows. * [Configure a custom Expert](/cosmos/experts-configure-custom) — create a team-specific Expert when no template fits. * [Custom Expert best practices](/cosmos/experts-best-practices) — start from templates, keep workflows simple, and iterate with human feedback. * [Delegating Work](/cosmos/workers-subagents) — learn how Experts delegate work to other agents. * [Triggers, Subscriptions, and Integrations](/cosmos/experts-triggers-subscriptions-integrations) — understand how Experts respond to events and interact with the outside world. ## Related guides * [Configure a code review pipeline](/cosmos/experts-code-review) # Best Practices for Custom Experts Source: https://docs.augmentcode.com/cosmos/experts-best-practices Build effective Cosmos Experts with maintained templates, simple workflows, and iterative human feedback. 1. **Check whether you need a custom Expert.** Ask [Cosmos Advisor](/cosmos/advisor/overview) for a [Template Expert](/cosmos/experts-templates) from the Cosmos knowledgebase before building your own. Augment maintains the templates and optimizes their cost and quality. 2. **Lean on Cosmos Advisor.** Use it throughout setup and iteration to configure Experts, Environments, integrations, and Automations correctly, and get best-practice recommendations. 3. **Prefer one agent per end-to-end task.** Cosmos agents can reliably execute long sequences of instructions; splitting one workflow across an orchestrator and multiple workers is usually an anti-pattern that adds cost, coordination bugs, and debugging complexity. Delegate only for a clear need, such as keeping an event-listening agent responsive while independent tasks run. 4. **Optimize quality before cost.** Start with the model Cosmos Advisor recommends, typically a mid-range model. Get reliable results first, then test lower-cost options against the same quality bar. 5. **Roll out small and iterate.** Test on real tasks, deploy to a few users, and collect feedback. Inspect failures and improve context, prompts, or configuration until the output meets the standard you'd expect from a human doing the work. 6. **Keep humans in the loop.** Humans remain responsible for outcomes and judgment calls; agents often lack architectural and business context. Ask for input on choices such as frontend versus backend implementation, or whether backward compatibility matters for a product with no external users. # Configure a Code Review Pipeline Source: https://docs.augmentcode.com/cosmos/experts-code-review Configure a Cosmos PR-to-merge pipeline with specialized Experts for authoring, review, repair, verification, and approval. ## Configure a PR-to-merge pipeline In AI-native engineering organizations, generating code is no longer the slowest part of shipping software. Review, verification, repair, and human decision-making become the bottlenecks. Cosmos addresses the complete PR-to-merge loop: agents do the mechanical work while humans provide judgment, knowledge transfer, and the final merge decision. This is [loop engineering](https://www.augmentcode.com/blog/what-is-loop-engineering-and-how-are-leading-software-engineering-teams-using-it) applied to the PR lifecycle. Optimize the verified, understood, merge-ready outcome—not an individual review agent or time to first comment. ![Cosmos code review pipeline](https://mintcdn.com/augment-mtje7p526w/ditxIl-9-ytPi62z/images/cosmos/code-review-pipeline.png?fit=max\&auto=format\&n=ditxIl-9-ytPi62z\&q=85\&s=7055919d761e41719c6e1972705bc48b) ## The Cosmos code review fleet Each specialized Expert owns part of the loop. Together they turn a chain of manual handoffs into a coordinated system. ### PR Author / PR Fixer Choose the Expert that matches how the change entered review: * [**PR Author**](/cosmos/experts-pr-author) turns a task or ticket into a reviewed pull request or merge request, then stays with it through review comments, CI failures, and merge conflicts. * [**PR Fixer**](/cosmos/experts-pr-fixer) provides the same follow-up loop for changes created without PR Author. It repairs review findings, CI failures, and merge conflicts, explaining what changed and asking for human judgment when a safe repair is ambiguous. Together, they provide interchangeable paths into the author-side loop: PR Author for changes it creates, or PR Fixer for changes created elsewhere. Both pair with Deep Reviewer, Pair Reviewer, Verifier, and CI. ### Risk Analyzer [Risk Analyzer](/cosmos/experts-risk-analyzer) classifies every new or ready-for-review change and applies your organization's auto-approval policy to intrinsically low-risk changes. It routes higher-risk changes to human review with a focused explanation of what needs attention. * **Role in the pipeline**: Prevents every change from receiving the same expensive level of human attention. * **Pairs with**: Pair Reviewer for changes that need deeper context or human judgment. ### Deep Reviewer [Deep Reviewer](/cosmos/experts-deep-reviewer) performs exhaustive, line-by-line analysis for objective correctness defects. It runs autonomously and checks the change against repository guidance such as `AGENTS.md` and `CLAUDE.md`. * **Role in the pipeline**: Handles objective correctness review before a human spends attention on judgment calls. * **Pairs with**: PR Fixer, which can repair its findings, and Pair Reviewer for broader judgment. ### Pair Reviewer [Pair Reviewer](/cosmos/experts-pair-reviewer) reconstructs intent, architecture, product context, and tradeoffs, then guides a human through the decisions that require judgment. It posts comments or a verdict only after human authorization. When instructed, it can monitor whether its comments are addressed and approve on the reviewer's behalf. * **Role in the pipeline**: Preserves human judgment and knowledge transfer without requiring line-by-line human review. * **Pairs with**: Risk Analyzer for routing, PR Fixer for repairs, and Memory Manager for team-specific standards. ### Verifier [Verifier](/cosmos/experts-verifier) exercises affected behavior end to end in a running environment and reports inspectable evidence such as screenshots, logs, traces, and captured outputs. * **Role in the pipeline**: Replaces confidence based on code inspection alone with runtime evidence. * **Pairs with**: PR Fixer when verification finds a defect and Pair Reviewer when a human must assess the evidence. ### PR Dashboard Manager PR Dashboard Manager observes and summarizes each Expert's status, evidence, reviewed commits, and available actions. It is an observer and entry point, not a controller of the other Experts. * **Role in the pipeline**: Makes the complete review state legible without searching across comments and checks. ### `cosmos approve` A PR author can comment `cosmos approve` to request evaluation against a configurable approval policy. This path is disabled by default and is distinct from Risk Analyzer's automatic approval of intrinsically low-risk changes. A policy can require: 1. **Ownership**: The requester is the PR author and an effective CODEOWNER for every modified file. 2. **Current-head review**: There are no unresolved Deep Reviewer findings, Pair Reviewer blockers, or unaddressed human comments. 3. **Runtime evidence**: Verifier has not reported an unaddressed defect against the current commit. An approval never merges the change. A human always owns and performs the final merge. ### Memory Manager Memory Manager learns from merged changes and human feedback. It distills comments, replies, reactions, and Pair Reviewer sessions into reusable per-repository knowledge for future reviews. * **Role in the pipeline**: Makes the review system adapt to local conventions over time. * **Pairs with**: Every review Expert that benefits from shared team standards and prior feedback. ## Recommended rollout Start with the complete fleet except Verifier: PR Author, PR Fixer, Risk Analyzer, Deep Reviewer, Pair Reviewer, PR Dashboard Manager, and Memory Manager. This gives your team the core authoring, review, repair, and visibility loops immediately. Optionally enable `cosmos approve` after defining ownership and review requirements. Once the team is comfortable with that workflow, add Verifier. Runtime verification takes more time to set up because it needs a working test environment and access to exercise the affected behavior. Finally, customize the fleet for your organization: add custom Experts for domain-specific checks or workflows, and remove Experts that do not provide value for your team. > [!NOTE] > > Teams with strict compliance requirements should define which changes can be auto-approved, who can request approval, which paths always require human review, and how agent approvals are audited. ## What changes for engineers * Agents handle mechanical analysis, repair, and verification. * Humans focus on architecture, product behavior, security, rollout, and other consequential decisions. * Evidence and Expert state are visible in one place. * A human always makes the final merge decision. ## See Also * [Template Experts](/cosmos/experts-templates) — choose the Experts that make up the pipeline. * [PR Author](/cosmos/experts-pr-author) and [PR Fixer](/cosmos/experts-pr-fixer) — own new changes end to end or repair changes created elsewhere. * [Risk Analyzer](/cosmos/experts-risk-analyzer), [Deep Reviewer](/cosmos/experts-deep-reviewer), [Pair Reviewer](/cosmos/experts-pair-reviewer), and [Verifier](/cosmos/experts-verifier) — review and verify each change. # Code Review Memory Manager Source: https://docs.augmentcode.com/cosmos/experts-code-review-memory Use Code Review Memory to turn feedback from completed code reviews into durable, repository-specific guidance for future reviews. ## Code Review Memory Code Review Memory is a background Template Expert that helps code review adapt to your team's conventions. When a pull request or merge request is merged, it collects meaningful signals from the review and makes established learnings available to review Experts on future changes. It follows a **capture → curate → load** workflow: 1. **Capture**: It records useful human comments, reactions to agent findings, addressed change requests, and the outcome of the change. Routine acknowledgments, bot updates, and process-only comments are filtered out. 2. **Curate**: It combines repeated evidence into concise, repository-specific guidance. Explicit human feedback carries more weight than reactions or an inferred outcome, so strong feedback can become useful memory immediately while weaker signals must recur. 3. **Load**: Risk Analyzer, Deep Reviewer, and Pair Reviewer load relevant guidance for the repository and changed paths on their next run. They use it to avoid known false positives and recognize team-specific anti-patterns. Memory is stored in your organization's shared VFS and scoped to each repository or project. A raw breadcrumb log preserves the evidence collected from reviews, while a curated knowledge file contains the concise guidance consumed by review Experts. The Memory Manager updates that curated view after each completed change. > [!NOTE] > > Code Review Memory is not the same as creating a skill for every repository. Skills provide explicit, reusable instructions and workflows. Memory is evolving, evidence-backed context that review Experts load automatically for the repository they are reviewing. * **Best for**: Teams that want automated review to learn from recurring feedback and local conventions. * **How to use**: Configure Code Review Memory to run when changes merge, alongside Risk Analyzer or Pair Reviewer. It operates in the background rather than as an interactive Expert. ## See Also * [Memory](/cosmos/experts-memory) — understand how Expert memory is stored, scoped, and reused. * [Configure a code review pipeline](/cosmos/experts-code-review) — combine Code Review Memory with the review fleet. * [Risk Analyzer](/cosmos/experts-risk-analyzer), [Deep Reviewer](/cosmos/experts-deep-reviewer), and [Pair Reviewer](/cosmos/experts-pair-reviewer) — review Experts that use curated code review memory. # Configure a Custom Expert Source: https://docs.augmentcode.com/cosmos/experts-configure-custom Create a custom Cosmos Expert for a team-specific workflow when no existing Template Expert fits. ## Configure a custom Expert Before creating a custom Expert, check [Template Experts](/cosmos/experts-templates). Template Experts are the fastest path when your workflow matches a common pattern such as PR authoring, code review, verification, feedback triage, incident investigation, project building, or ticket dispatch. Create a custom Expert when the workflow is specific to your team, requires custom tools or instructions, or combines systems in a way no Template Expert covers. **1. Define the workflow** Write down what the Expert owns, what input it expects, what output it should produce, and where a human must make a decision. Good Experts have a narrow job and a clear stopping rule. **2. Choose the runtime environment** Select an Environment with the repos, CLIs, language toolchains, and network access the Expert needs. **3. Add integrations and capabilities** Grant only the integrations the Expert needs, such as code hosting, ticketing, communication, web access, or monitoring tools. **4. Write the system prompt** Describe the Expert's role, inputs, process, output format, allowed write operations, and handoff rules. Include idempotency checks for event-driven Experts so repeated triggers do not create duplicate comments, tickets, or sessions. **5. Configure launch guidance** Add user instructions and placeholder text that tell people what to paste when launching the Expert, such as a change request, incident channel, ticket, project brief, or PR/MR URL. **6. Add workers or triggers if needed** Attach worker Experts for delegated sub-tasks, or add triggers for code-hosting events, communication messages, schedules, or webhooks. Test the manual path first, then automate. **7. Validate with a real example** Run the Expert on a representative task, inspect the session, and tune the prompt or integrations before rolling it out to the team. ## Prompt checklist Strong Expert prompts usually define: * **Role and scope**: what the Expert owns and what it must not do * **Required inputs**: what to ask for before taking action * **Process**: the phases it should follow, including when to stop for human input * **Output format**: the exact shape of comments, reports, tickets, or summaries * **Allowed writes**: which external actions are permitted * **Idempotency**: how to detect prior runs and avoid duplicates * **Attribution**: how messages link back to the Cosmos session that produced them * **Memory**: where reusable team learnings should be read or written, if the workflow improves over time > [!NOTE] > > Experts are saved configurations, not one-off prompts. Keep each Expert focused on a clear workflow, prefer one agent to complete it end to end, and test on real examples. See [Custom Expert best practices](/cosmos/experts-best-practices) for rollout and iteration guidance. # Cosmos ROI Analyst Source: https://docs.augmentcode.com/cosmos/experts-cosmos-analyst Use the Cosmos ROI Analyst Expert to learn how Cosmos has impacted your engineering team using GitHub PR / GitLab MR activity and cost data. ## Cosmos ROI Analyst Cosmos ROI Analyst produces a **Cosmos-adoption engineering-ROI report**: how Cosmos changed an engineering team's output, paired with what Cosmos cost. It fetches merged-change activity from your GitHub (PRs) or GitLab (MRs), computes a fixed set of throughput and quality metrics — changes per engineer, complexity-weighted output, cycle time, revert rate, and lines of code — and sets them against Cosmos spend over the same window. The analyst is read-only by discipline — it never posts or approves. * **Best for**: Engineering managers and leaders who want to understand and communicate the impact and cost of Cosmos adoption across one or more repositories. * **How to use**: Point the Expert at a cloud [environment](/cosmos/environments/overview) and connect GitHub or GitLab. Start a session, then tell it the repositories or projects, the team or engineers, roughly when Cosmos adoption started (optional), and the data window. It asks any remaining questions, then runs the report end-to-end. ## See Also * [Data Analyst](/cosmos/experts-data-analyst) — the general-purpose analyst for questions against your own source-of-truth data. * [GitHub](/cosmos/config-github) and [GitLab](/cosmos/gitlab-cloud) — connect the code hosting the analyst reads from. * [Cosmos Advisor](/cosmos/advisor/overview) — have the Advisor deploy and tune this Expert for you conversationally. # Data Analyst Source: https://docs.augmentcode.com/cosmos/experts-data-analyst Use the Data Analyst Expert to answer questions about your data with read-only queries against your source-of-truth datasets, naming the source and window for every answer. ## Data Analyst Data Analyst is a vendor-neutral analyst that answers questions about your data with read-only queries against your source-of-truth datasets, naming the source and window for every answer. It depends on a **data guide** you supply — which dataset is authoritative for each domain, how to query it, and the metric definitions; without one it asks rather than guesses. Queries run through read-only tooling in the environment, so data credentials are supplied as Cosmos [secrets](/cosmos/config-secrets) rather than inlined. * **Best for**: Teams who want a single, authoritative place to ask data questions and get answers that always cite their source and window. * **How to use**: Point the Expert at a cloud [environment](/cosmos/environments/overview) with read-only query tooling, supply a data guide, and edit the built-in PII policy. Then ask a question naming the metric, population, and time window. ## See Also * [Cosmos ROI Analyst](/cosmos/experts-cosmos-analyst) — the ready-made analyst for Cosmos-adoption engineering-ROI and cost reporting. * [Cosmos Advisor](/cosmos/advisor/overview) — have the Advisor deploy and tune this Expert for you conversationally. * [Secrets](/cosmos/config-secrets) — how to supply read-only data credentials to the environment. # Deep Reviewer Source: https://docs.augmentcode.com/cosmos/experts-deep-reviewer Use the Deep Reviewer Expert for non-interactive, line-by-line correctness review with inline findings. ## Deep Reviewer Deep Reviewer checks a pull request or merge request without a chat loop. The agent reads the diff, checks changed files against repository guidance, and posts inline findings for objective issues. Deep Reviewer is the closest Cosmos Expert to a traditional automated code review tool. It is designed to catch bugs, missing edge cases, logic errors, and implementation gaps before a human reviewer spends time on the change. * **Best for**: Teams that want exhaustive correctness review before or alongside human review. * **How to use**: Start a session with Deep Reviewer and paste a change URL, or configure a trigger so review runs automatically when a change opens or is marked ready for review. ## See Also * [Configure a code review pipeline](/cosmos/experts-code-review) — how Deep Reviewer fits into the full review fleet. * [Risk Analyzer](/cosmos/experts-risk-analyzer) — route only higher-risk changes to deeper human review. # Feedback Triager Source: https://docs.augmentcode.com/cosmos/experts-feedback-triager Use the Feedback Triager Expert to classify Slack feedback, investigate technical reports, and create tickets or launch fixes when appropriate. ## Feedback Triager Feedback Triager watches a Slack channel you designate as your feedback inbox. Each fresh top-level message starts one session that claims the thread, subscribes to follow-ups, and classifies the report. The Expert stays focused on triage: it can read code, logs, and metrics to explain a problem, but it never changes code itself. For bugs, regressions, technical failures, and operational problems, Feedback Triager automatically investigates the root cause when the cause matters. It combines runtime and static evidence when both are available, labels uncertainty clearly, and stops when the evidence supports an actionable conclusion. It skips root-cause analysis for praise, feature requests, and questions with a direct documented answer. ### Tickets and next steps Feedback Triager can create tickets in Linear, Jira, or GitHub Issues. During setup, choose one of two modes: * **Automatic**: Create a ticket after classification and any applicable investigation, once the category-specific quality gate passes. * **On request**: Offer ticket creation when useful, but create it only after a clear request in the thread. Before filing, the Expert searches the configured project, board, or repository for plausible duplicates. It does not create a ticket for every message: pure praise receives a reaction, direct questions are answered directly, and incomplete reports receive at most one focused clarification question for each gap. When action is useful, the reply presents one numbered **Next Steps** list. Depending on the findings, options can include creating a ticket, routing a concise handoff to another configured Slack channel, gathering specific missing evidence, or launching [PR Author](/cosmos/experts-pr-author) for a recommended fix. Code changes require a clear human request, and repeated requests reuse the existing result instead of repeating side effects. Feedback Triager also remembers explicit standing guidance for classification, routing, deduplication, and when to stay silent within each configured channel. * **Best for**: Teams with a busy feedback or bug-report channel who want evidence-backed triage and consistent follow-through without turning every conversation into a ticket. * **How to use**: This Expert is event-driven — you don't launch sessions from it manually. Connect Slack and one supported ticket tracker, configure the feedback channel, ticket-creation mode, PR or MR Author worker, target repository, and any evidence sources or routing destinations. The Expert then handles each new top-level message in its own long-lived thread session. ## See Also * [PR Author](/cosmos/experts-pr-author) — the worker the triager dispatches when a human requests a recommended fix. * [Understanding Automation](/cosmos/automations) — how triggers and subscriptions drive event-driven Experts like this one. # Incident Investigator Source: https://docs.augmentcode.com/cosmos/experts-incident-investigator Use the Incident Investigator Expert to watch alert channels, post root-cause analyses in-thread, and accompany incidents through to resolution. ## Incident Investigator Incident Investigator is a single incident-response Expert with two activation modes: * **Alert-thread mode**: The Expert watches one or more long-lived alert channels that receive alerts from your incident-management platform as well as free-form incident reports. Each fresh top-level message launches a per-incident session that triages, investigates logs and metrics, posts a root-cause analysis in-thread, and subscribes to follow-ups. * **Stationed-channel mode**: A human launches the Expert with a link to an ad-hoc incident channel — or a trigger auto-launches it when a channel matching your incident-channel naming pattern is created. One session watches the channel, handles incident-like messages and follow-ups, and stays alive until released. In both modes, code fixes are gated on explicit human approval before the Expert launches a [PR Author](/cosmos/experts-pr-author) worker. * **Best for**: On-call teams who want triage, log/metric investigation, and root-cause analysis started the moment an alert fires — with findings posted where responders already are. * **How to use**: Connect your communication integration and point the Expert's triggers at your alert channels. For stationed-channel mode, start a session with the Expert and paste the incident channel link. The Expert needs skills for querying your logs and metrics backends — set these up when installing it. ## See Also * [PR Author](/cosmos/experts-pr-author) — the worker that opens fix changes once a human approves. * [Understanding Automation](/cosmos/automations) — triggers, subscriptions, and the events log behind this Expert. # Memory Source: https://docs.augmentcode.com/cosmos/experts-memory Learn how Experts retain useful context across sessions and apply it to future work. ## Memory Memory lets an Expert retain useful context across sessions. It stores scoped knowledge in the shared virtual filesystem (VFS), so future sessions can apply established preferences, conventions, and lessons without relying on the current conversation. An Expert's memory belongs to its team and is separated by a scope appropriate to the workflow. Repository-based Experts typically use one scope per repository, while other Experts can use a global, channel, project, or user-specific scope. Memory can be shared with an organization or kept within a user's VFS, depending on the Expert's visibility. Memory is enabled for all Template Experts. When you create a custom Expert with Cosmos Advisor, the Advisor also wires in lightweight memory by default unless you explicitly ask it not to. ## How memory works Memory has a write path and a read path: * **Capture**: A memory-enabled Expert identifies durable information that could change a future decision. In interactive sessions, it tells you when it remembers something so you can correct or veto it. * **Store**: The Expert writes the information as readable Markdown under its own VFS directory. Each Expert team owns and maintains its memory rather than modifying another team's curated knowledge. * **Load**: At the start of relevant work, the Expert loads memory for the current scope. It applies matching guidance and flags discrepancies when current evidence conflicts with a remembered rule. ## Memory models Cosmos supports two models depending on the quality and volume of the signals: * **Simple memory** is the default. It writes explicit, high-quality human feedback directly to a curated knowledge file. This works well for preferences and standing rules that are authoritative on their own. * **Noisy memory** uses an evidence log plus a curated knowledge file. It combines weaker signals over time and promotes a learning only after the evidence is strong enough. Code Review Memory uses this model because review comments, reactions, agent observations, and change outcomes carry different levels of confidence. Both models expose the same curated knowledge view to readers. The difference is how that view is produced: simple memory records trusted facts directly, while noisy memory distills repeated evidence before presenting it to future sessions. ## Best practices * Use the narrowest stable scope that matches the workflow, such as a repository for code review or a channel for feedback triage. * Save information only when it could change a future decision or area of focus. * Prefer simple memory unless the workflow genuinely needs repeated, weighted evidence. * Treat memory as evolving context, not an unquestionable rule. Experts should surface contradictions rather than ignore current evidence. * Use skills or Expert instructions for explicit workflows; use memory for context learned through ongoing work. ## See Also * [Code Review Memory](/cosmos/experts-code-review-memory) — see how the noisy memory model improves future code reviews. * [Template Experts](/cosmos/experts-templates) — explore built-in Expert workflows. * [Configure a custom Expert](/cosmos/experts-configure-custom) — create an Expert for a team-specific workflow. # Pair Reviewer Source: https://docs.augmentcode.com/cosmos/experts-pair-reviewer Use the Pair Reviewer Expert for interactive, intent-focused code reviews where a human makes the final judgment calls. ## Pair Reviewer Pair Reviewer is an interactive reviewer for changes where design intent, product behavior, security, rollout, tests, or architecture matters more than simply scanning every changed line. Pair Reviewer prepares a briefing, explains the important decisions, answers the human reviewer's questions, and posts finalized comments or a verdict only after human authorization. When asked, it can monitor whether its authorized comments are addressed and approve on the reviewer's behalf. * **Best for**: Complex or high-stakes changes where the review should preserve human context and judgment. * **How to use**: Start a session with Pair Reviewer and paste a change URL. The agent walks you through the review and helps decide what, if anything, to post back. ## See Also * [Configure a code review pipeline](/cosmos/experts-code-review) — how Pair Reviewer fits into the full review fleet. * [Risk Analyzer](/cosmos/experts-risk-analyzer) — the triage Expert that flags higher-risk changes for human review. * [PR Author](/cosmos/experts-pr-author) — the implementation Expert that opens changes and handles their follow-up. * [PR Fixer](/cosmos/experts-pr-fixer) — the repair Expert for changes created without PR Author. # PR Author Source: https://docs.augmentcode.com/cosmos/experts-pr-author Use the PR Author Expert to have an agent build a change from a task description — creating the branch, implementing changes, and handling follow-up. ## PR Author PR Author is the canonical Ticket-to-PR Expert. It turns a task description, ticket, or existing change into a reviewed pull request or merge request. It creates the branch, implements the change, opens the review, and stays with it through CI, merge conflicts, and review comments. * **Best for**: Any change where you want an Expert to own the implementation loop and follow-up work. * **How to use**: Start a session with PR Author and describe the task, paste a ticket, or reference an existing pull request or merge request. The agent implements the change, responds to comments, fixes failures, and keeps the review up to date. ## See Also * [Configure a code review pipeline](/cosmos/experts-code-review) — pair PR Author with reviewers that evaluate the changes it opens. # PR Fixer Source: https://docs.augmentcode.com/cosmos/experts-pr-fixer Use the PR Fixer Expert to repair review findings, CI failures, and merge conflicts on a pull request or merge request. ## PR Fixer PR Fixer owns the mechanical follow-up after a pull request or merge request is opened. It responds to review findings, diagnoses and fixes CI failures, resolves unambiguous merge conflicts, and explains the changes it makes. It never merges the change; a human owns the final merge decision. PR Fixer is for existing changes created without PR Author—for example, changes opened by a human or another coding tool. It gives teams a repair loop for those changes without requiring PR Author to have created them. * **Best for**: Changes created without PR Author that need review feedback addressed, CI repaired, or merge conflicts resolved. * **How to use**: Start a session with PR Fixer and provide a pull request or merge request URL, or comment `cosmos fix` when configured. It monitors the change, applies safe fixes, and asks for human judgment when intent is ambiguous. ## See Also * [PR Author](/cosmos/experts-pr-author) — implement a task and own the resulting change through follow-up. * [Configure a code review pipeline](/cosmos/experts-code-review) — see how PR Fixer closes the repair loop for other review Experts. # Project Builder Source: https://docs.augmentcode.com/cosmos/experts-project-builder Use the Project Builder Expert to turn a large feature into a reviewed design, ticket breakdown, and coordinated implementation. ## Project Builder Project Builder is an interactive Expert that takes a large feature from idea to shipped code in optional steps: product design, architecture, ticket breakdown, orchestration — launching a [PR Author](/cosmos/experts-pr-author) worker per unit of work in dependency waves — and comms, reporting when changes are ready for review and when the feature is complete. You can start from scratch or drop in an existing starting point — a mockup, doc, existing change, ticket, or rough spec — and enter at any step. The Expert researches the repo, drafts a design doc, iterates with you, breaks the work into tickets, and dispatches implementation to PR Author workers. It never merges implementation changes and never writes feature code itself; the PR Author workers and human reviewers own those. * **Best for**: Features too large for a single change — anything that needs a reviewed design and several coordinated implementation branches. * **How to use**: Start a session with the Project Builder Expert and describe the feature, or paste a link to the doc, mockup, change, or ticket you want to start from. Review and iterate on the design doc it produces, then let it break the work down and orchestrate the implementation. ## See Also * [PR Author](/cosmos/experts-pr-author) — the worker Project Builder dispatches for each implementation unit. * [Configure a code review pipeline](/cosmos/experts-code-review) — review the changes the orchestrated workers open. * [Understanding Automation](/cosmos/automations) — how workers relate to sessions and automations. # Risk Analyzer Source: https://docs.augmentcode.com/cosmos/experts-risk-analyzer Use the Risk Analyzer Expert to triage new code reviews and route complex changes to focused human review. ## Risk Analyzer Risk Analyzer runs when a pull request or merge request is opened or marked ready for review. It evaluates the change and decides whether it is low-risk or needs deeper review. Low-risk changes can be auto-approved with a short justification. Higher-risk changes are flagged for human review with a focused note that explains what needs human attention, such as architecture, security, rollout, tests, or product behavior. For those changes, a human can bring in [Pair Reviewer](/cosmos/experts-pair-reviewer) for an interactive, judgment-focused review. * **Best for**: Teams with high review volume who want humans focused on the changes that actually need judgment. * **How to use**: Configure it as an automated trigger on change creation or ready-for-review events. During setup, fill in repository allowlists and paths that always require human review. ## See Also * [Configure a code review pipeline](/cosmos/experts-code-review) — how Risk Analyzer fits into the full review fleet. * [Pair Reviewer](/cosmos/experts-pair-reviewer) — the interactive reviewer for changes that need human judgment. # Template Experts Source: https://docs.augmentcode.com/cosmos/experts-templates Choose a Template Expert for PR authoring and repair, code review, incident response, feedback triage, project building, or ticket management. ## Template Experts Template Experts are out-of-the-box Experts shipped by the Augment team. They have been battle-tested across engineering organizations that use standardized third-party integrations and are designed to produce high-quality sessions for common software development workflows. If a Template Expert fits your use case, we recommend using it instead of building a custom Expert from scratch. Template Experts are automatically managed and maintained by Augment, including model updates, prompt improvements, workflow tuning, and other quality improvements over time. For a Template Expert, the system prompt is a single include statement that references a prompt managed by Augment. Your customizations, such as which specific repositories to run on and other workflow-specific details, are appended below that include. This is what lets Augment keep improving the underlying prompt over time while your configuration stays intact. > [!NOTE] > > You don't have to deploy these by hand — ask [Cosmos Advisor](/cosmos/advisor/overview) to set them up for you. Describe your workflow and the Advisor deploys the right Template Experts in the correct dependency order, wires up their integrations and Environment, and hands you a link to try each one. * [Cosmos Advisor](/cosmos/advisor/overview) — your go-to agent for navigating Cosmos: it connects integrations, builds Environments, creates and tunes Experts, and wires Automations for you through prompting instead of hand-editing forms. * [PR Author](/cosmos/experts-pr-author) — the canonical Ticket-to-PR Expert for taking a request to a reviewed pull request or merge request. * [PR Fixer](/cosmos/experts-pr-fixer) — repairs review findings, CI failures, and merge conflicts on changes created without PR Author. * [Risk Analyzer](/cosmos/experts-risk-analyzer) — auto-approves low-risk changes and routes higher-risk reviews to the right level of attention. * [Deep Reviewer](/cosmos/experts-deep-reviewer) — performs non-interactive, line-by-line correctness review. * [Pair Reviewer](/cosmos/experts-pair-reviewer) — interactive review focusing on items in the change requiring human judgment and knowledge transfer: design and architecture, security, risks, and similar. * [Verifier](/cosmos/experts-verifier) — exercises a change against a running environment and reports evidence-backed findings. * [Incident Investigator](/cosmos/experts-incident-investigator) — investigates alerts or incident threads and summarizes findings. * [Feedback Triager](/cosmos/experts-feedback-triager) — classifies Slack feedback, investigates technical reports, and creates tickets or launches fixes when appropriate. * [Project Builder](/cosmos/experts-project-builder) — turns a large feature into a design, ticket breakdown, and coordinated implementation. * [Ticket Manager](/cosmos/experts-ticket-manager) — owns delegated Linear, Jira, or GitHub tickets from readiness checks through implementation and closure. * [Ticket Dispatcher](/cosmos/experts-ticket-dispatcher) — scans ready work and dispatches implementation workers under backpressure. * [Data Analyst](/cosmos/experts-data-analyst) — answers questions about your data with read-only queries against your source-of-truth datasets, naming the source and window for every answer. * [Cosmos ROI Analyst](/cosmos/experts-cosmos-analyst) — reports how Cosmos has impacted your engineering team using GitHub PR / GitLab MR activity and cost data. * [Code Review Memory](/cosmos/experts-code-review-memory) — learns repository-specific guidance from completed code reviews for future review sessions. # Ticket Dispatcher Source: https://docs.augmentcode.com/cosmos/experts-ticket-dispatcher Use the Ticket Dispatcher Expert to scan tickets on a schedule and launch implementation workers for work that is ready to implement. ## Ticket Dispatcher Ticket Dispatcher continuously scans a backlog and hands ready work to [PR Author](/cosmos/experts-pr-author). Some templates call this Expert **Backlog Dispatcher**; both names refer to the same pattern. The Expert runs on a schedule, scans configured ticket sources, applies a readiness rubric, and dispatches PR Author for tickets that are safe to attempt. It respects a maximum number of dispatcher-owned open changes so automation does not flood the review queue. * **Best for**: Teams with a steady backlog of small-to-medium implementation tickets that often become agent-ready after triage. * **How to use**: Configure the ticket sources, schedule, PR Author worker ID, and backpressure limits. The dispatcher scans on each scheduled run, dispatches ready work, and records concise skip reasons for tickets that need more human input. ## See Also * [PR Author](/cosmos/experts-pr-author) — the worker that implements dispatched tickets. * [Project Builder](/cosmos/experts-project-builder) — use for larger projects that need design and ticket breakdown first. * [Automations](/cosmos/automations) — understand schedules, triggers, and long-running sessions. # Ticket Manager: from ticket to PR Source: https://docs.augmentcode.com/cosmos/experts-ticket-manager Connect your tools, set up Ticket Manager with Advisor, and delegate your first ticket from GitHub, Linear, or Jira. Ticket Manager checks a ticket's requirements, asks [PR Author](/cosmos/experts-pr-author) to implement the change, and keeps the ticket updated. **Your team reviews and merges the change.** Get started in three steps: **connect your tools, set up with Advisor, and try a ticket in your tracker.** ## From ticket to PR ```mermaid theme={null} flowchart TD ticket["You delegate a ticket"] --> manager["Ticket Manager checks requirements"] manager -->|Ready| author["PR Author implements, tests, and opens a draft PR or MR"] manager -->|Spec needed| spec["You review and approve the spec"] spec --> manager author --> review["Your team reviews the change"] review -->|Changes requested| author review -->|Approved| merge["Your team merges"] classDef human fill:#fff7ed,stroke:#c2410c,color:#7c2d12; class ticket,spec,review,merge human; ``` Human steps are highlighted. ## 1. Connect your tools Connect your team's code host and ticket tracker in Cosmos: * **Code host:** [GitHub](/cosmos/connectors/config-github), [GitLab Cloud](/cosmos/connectors/gitlab-cloud), [Azure DevOps Services](/cosmos/connectors/azure-devops-cloud), or Bitbucket (custom setup with [Advisor](/cosmos/advisor/overview)). * **Ticket tracker:** GitHub Issues, [Linear](/cosmos/connectors/config-linear), or [Jira Cloud](/cosmos/connectors/jira-cloud). Follow the connector guides to authorize access to the repository and tracker. You may need an administrator to complete the setup. ## 2. Set it up with Advisor Open **Cosmos Advisor** from Home. Replace the placeholders and send: > Set up Ticket Manager for \[ticket tracker] with code in \[code host]. Show me how to delegate tickets. Advisor helps configure: * **The Experts:** Ticket Manager and the PR or MR Author that implements changes. * **The environment:** access to your repository and the tools needed to build and test it. * **The automation:** which delegation event starts work. For **GitHub Issues or Jira**, choose a delegation label with Advisor, such as `cosmos-ticket-manager`. Create it in your tracker if needed, and make sure the automation uses that exact label. Complete Advisor's setup checks, approve activation when prompted, and confirm the automation is enabled before delegating a ticket. ## 3. Try it in your ticket tracker Go to **GitHub, Linear, or Jira** and create a ticket in your usual project or repository. Start with a small text change so it's easy to check the result: > **Update the Save button text** > > Change the settings page's button label from "Save" to "Save changes". Keep its behavior and styling unchanged. Then delegate it: **GitHub Issues** Open the issue and add the delegation label you configured with Advisor. Ticket Manager removes the label after claiming the issue. This is expected; follow the ticket update rather than re-adding it. **Linear** Open the issue and delegate it to the Cosmos agent connected during setup. Ask Advisor which agent to select in Linear. Changing the issue's status alone does not delegate it. **Jira** Open the issue and add the delegation label you configured with Advisor. > [!NOTE] > > Delegating a ticket starts real work: it can update the ticket, push code, and > open a PR or MR. Check the ticket for a status update and session link. If a specification needs approval, follow **Review spec**, answer the questions, and approve the scope in that session. Once the ticket is ready for implementation, the Author makes the change and links the PR or MR back to it. > [!TIP] > > Nothing started? Check **Automations → Run History** in Cosmos. Give Advisor the > ticket and automation links and ask it to check the connection, trigger, and > delegation event before making changes. ## Related guides * [Setting up automations with Advisor](/cosmos/automation-advisor) * [Managing automations](/cosmos/manage-automations) * [PR Author](/cosmos/experts-pr-author) # How Experts respond to events Source: https://docs.augmentcode.com/cosmos/experts-triggers-subscriptions-integrations Understand how Cosmos Experts respond to events and interact with the outside world. Experts respond to the outside world through three mechanisms: * **Triggers** start Expert sessions from external events, schedules, or webhooks. * **Subscriptions** keep a running session listening for follow-up events after it has started. * **Integrations** give the Expert controlled access to external systems, such as code hosting, ticketing, communication, observability, and custom tools. For the full explanation of how these fit together, see [Understanding Automation](/cosmos/automations). ## See Also * [Understanding Automation](/cosmos/automations) — how triggers, subscriptions, and events wire an Expert to the outside world. * [Configuring Triggers](/cosmos/config-triggers) — the full trigger reference: types, event names, and filters. * [Webhooks](/cosmos/config-webhooks) — connect custom event sources. * [Schedules](/cosmos/config-schedules) — run Experts on cron schedules. * [Configure MCP Servers](/cosmos/config-mcp) — connect custom tools and context sources. # Verifier Source: https://docs.augmentcode.com/cosmos/experts-verifier Use the Verifier Expert to exercise a change in a running environment and report evidence-backed findings. ## Verifier Verifier is a runtime validation Expert for pull requests or merge requests. It acquires or uses a test environment, serves the change, provisions the identities or flags needed to exercise it, runs an end-to-end verification pass, and reports findings with linked evidence. Unlike a test runner that only returns pass or fail, Verifier focuses on merge confidence. It does not merge code or replace human judgment; it reports what it observed, what could not be observed, and what evidence supports the finding. * **Best for**: Changes that need runtime evidence from a real app, service, integration, or workflow before a reviewer is comfortable merging. * **How to use**: Start a session with Verifier and provide a change URL, or configure it to run from code-hosting events or an explicit rerun comment. During setup, define the target repositories, test environment, deploy or serve commands, auth and flag setup, observability sources, and reporting expectations. # Your First Automation Source: https://docs.augmentcode.com/cosmos/first-automation Build two automations from scratch — a personal daily PR nudger on a schedule, and a team-wide review nudger driven by GitHub events with a payload filter. The fastest way to understand automations is to build one. This page walks through two, end to end. The first uses the simplest trigger there is — a schedule — and you'll build it by hand so you see every moving part. The second reacts to a real GitHub event and uses a compound filter, which is the shape most production automations take — and for that one you can hand the wiring to [Advisor](/cosmos/automation-advisor), with the manual steps included if you'd rather do it yourself. ## Before You Start Both automations need two integrations connected. Open the Integrations settings page and confirm: * **GitHub** — the Expert reads your PRs through the connected GitHub App. * **Slack** — the Expert delivers its nudges through the connected Slack app. If either shows as not connected, run its connect flow first — it takes a minute each. ## Automation 1: A Personal Daily PR Nudger Every weekday morning, an Expert checks which open PRs are waiting on your review and sends you a Slack DM with the list. No PRs waiting — no message. ### 1. Create the Expert From the **Experts** page, click **Create an expert** and pick **Custom Expert**: * **Name** — something like `My PR Nudger`. * **Environment** — the default environment is fine; this Expert only needs GitHub and Slack access, no repo checkout. * **Tools** — enable **GitHub** and **Slack** in the integrations list. * **System Prompt** — paste something like this, filling in your own GitHub username and email: ``` You are my personal PR review nudger. Each time you run: 1. Find open GitHub pull requests where my review is requested (my GitHub username: YOUR_GITHUB_USERNAME). 2. Drop drafts and anything I've already reviewed since its last push. 3. If any remain, send me a Slack DM (look me up by email: you@company.com) with one line per PR: title, link, author, and how long it's been waiting. 4. If nothing needs my attention, finish without sending anything. ``` Save the Expert. New Experts are visible only to you until you share them — exactly right for a personal nudger. ### 2. Test it before wiring the trigger Open the Expert from the home page and send it a message: `run`. Watch it work — it should query GitHub, and either DM you or report that nothing needs attention. If the DM lands in the wrong place or the list includes drafts, tune the instructions and run it again. This is the cheapest place to iterate: nothing fires automatically yet. ### 3. Add the schedule Open **Automations** in the sidebar and click **Create automation**. In the panel that opens, pick your nudger Expert from the **Expert** dropdown, then under **New triggers** click **Add trigger** and pick **Scheduled** from the **Choose trigger type** picker: * **Trigger name** — `daily-nudge`. * **Frequency** — pick **Custom cron** and enter `0 9 * * 1-5` (9:00 every weekday). The daily/weekly presets work too if you'd rather not write cron. * **Timezone** — pick yours; the schedule fires in this timezone, DST-aware. * Leave **Auto-archive sessions created by this trigger** on — these are fire-and-forget runs you don't need to revisit. Save. That's the whole automation: tomorrow at 9:00 it runs without you. ### 4. Confirm it fired The next morning, open **Automations** in the sidebar, open your automation row's **⋯** menu, and choose **Run history** (the same view lives under **Run History** in the sidebar). You should see a session started by the trigger. Click into it to read exactly what the Expert did. ## Automation 2: A Team-Wide Review Nudger Now the event-driven version: whenever review is requested on a non-draft PR targeting `main`, an Expert posts a heads-up in the team's review channel — PR link, author, who's on the hook. Same building blocks, but the trigger listens to GitHub instead of a clock, and a payload filter decides which events matter. ### The Fast Way: Ask Advisor You already know the moving parts from Automation 1 — Expert, trigger, filter. This time, let [Advisor](/cosmos/automation-advisor) do the wiring. Open Advisor — the "Describe your workflow and an agent will set it up" banner on the Experts or Automations page, or pick **Cosmos Advisor** from the home page — and describe the outcome: > Set up a team-wide PR review nudger: whenever review is requested on a non-draft pull request targeting main, post one message to our #code-review Slack channel with the PR title, link, author, and requested reviewers. It should not review the PR itself. Advisor creates the Expert, writes the GitHub trigger and its payload filter, and stages the rollout — the Expert deploys with the trigger off, you try it against a real PR, and the trigger goes live only when you say so. See [Setting Up Automations with Advisor](/cosmos/automation-advisor) for the full flow. ### The Manual Way (Optional) Prefer to build it by hand — or want to see exactly what Advisor wired up? The same automation, step by step. #### 1. Create the Expert Same flow as before, with two differences: * **Sharing** — after saving, click **Share expert** in the Sharing section so the team can use it. * **System Prompt** — the Expert now reacts to an event payload instead of running a search: ``` You are the team's review nudger. You wake up when review is requested on a pull request. The event payload is your first message. 1. Read the PR title, URL, author, and requested reviewers from the payload. 2. Post ONE message to the #code-review Slack channel: PR title and link, author, who's requested, and a one-line summary of what the PR changes. 3. Do not review the PR yourself. Do not post more than one message. ``` #### 2. Add the GitHub trigger with a filter Back on the **Automations** page, click **Create automation**, pick the team nudger Expert, then under **New triggers** click **Add trigger** and pick **GitHub** from the **Choose trigger type** picker: * **Trigger name** — `on-review-requested`. * **Event** — `pull_request`. * **Filter** — this is where the trigger earns its keep. GitHub sends a `pull_request` event for every open, close, sync, label, and edit; the filter narrows it to exactly the ones you want: ```json theme={null} {"and": [ {"==": [{"var": "action"}, "review_requested"]}, {"==": [{"var": "pull_request.base.ref"}, "main"]}, {"==": [{"var": "pull_request.draft"}, false]} ]} ``` Three clauses: only review-request events, only PRs targeting `main`, never drafts. Events that fail the filter cost nothing — no session is created. #### 3. Validate the filter against real events Before trusting a filter, check it against payloads GitHub has actually sent. Open **Event Log** under the **Automations** group in the sidebar. Filter by source **GitHub**, then open the **Advanced Filter** dialog: set the event type to `pull_request` and paste your JSONLogic expression into the payload filter — the log narrows to the captured events that match. Click any row to inspect the raw payload if a field path isn't what you expected. #### 4. Turn it on and try it Save the trigger, then request review on a test PR targeting `main`. Within moments the event shows up in the events log, the trigger fires, and the message lands in the channel. If it fires too often or too rarely, adjust the filter — the trigger keeps its type and event type; only the expression changes. To pause the automation later without losing the configuration, expand its row on the Automations page and flip the trigger's enable toggle off. To retire it, delete the trigger — the Expert itself stays usable from the home page. ## Where To Go Next * [Configuring Triggers](/cosmos/config-triggers) — the full event-type and filter reference. * [Webhooks](/cosmos/config-webhooks) — wire in sources Cosmos doesn't have an integration for. * [Managing Automations](/cosmos/manage-automations) — the events log and run history in depth. * [Setting Up Automations with Advisor](/cosmos/automation-advisor) — have Advisor build and stage automations like these for you conversationally. # Getting Started with Cosmos Source: https://docs.augmentcode.com/cosmos/getting-started Understand the core building blocks of Augment Cosmos — Environments, Experts, Sessions, Capabilities, and Triggers. ## What is Augment Cosmos? Cosmos runs your agents in the cloud. They read your repos, work in sandboxed VMs, and wake up on events from GitHub, Slack, Linear, PagerDuty, webhooks, and cron. You drive them from the webapp, your phone, or Slack — whichever surface you're already in. You can build Automations inside Cosmos to put agents to work reviewing code as soon as PRs are created or assigning tickets to agents when new tickets are created. ## Core Concepts | Concept | What it is | | - | - | | **Expert** | A reusable template that defines an agent's behavior. It includes a name, instructions, environment, system prompt, model, and which capabilities it has access to, triggers and events it can react to, and visibility — either shared or private. | | **Environment** | A reusable virtual machine where your Experts run. Bundles a name, base image, repositories, environment variables, and visibility. | | **Capability** | A bundle of tools or MCP servers that give an Expert a specific ability (CLI Tools, GitHub, Linear, Slack, Web Access, etc.). | | **Trigger** | A structured notification that turns a real-world event into an Expert action. Sources include GitHub (a new PR), Linear (a status change), Slack (a new message), PagerDuty (a P0 incident), a cron schedule, or a custom webhook. | |   ↳ **Skills** | A reusable knowledge package (following agentskills.io) that provides specialized instructions or domain expertise to an Expert. Stored inside Files. | |   ↳ **Visibility** | Controls whether an Environment or Expert is private to you or shared across your organization. | | **Session** | The conversation with an Expert — every message, turn, and tool call. Sessions can be private or shared, and are accessible from the web, mobile, and Slack. | | **Automation** | A persistent, event-driven rule that tells Cosmos to launch an agent — or wake up a running one — whenever something happens in a connected services (GitHub, Linear, Slack, etc.). | | **Files** | Objects stored in a virtual file system that Experts can read and write. Shared files are visible to all members of an **Organization**, while private files are only visible to the **User** who created them. | ## Questions about Cosmos? Ask [Cosmos Advisor](/cosmos/advisor/overview) — your go-to agent for navigating Cosmos. It can answer all your questions about Cosmos and set things up for you: connecting integrations, building Environments, creating Experts, and wiring Automations. # Admin Checklist Source: https://docs.augmentcode.com/cosmos/guides/admin-checklist Set up your Cosmos enterprise tenant with this administrator checklist covering initial access, domains, users, and single sign-on. # Introduction You just entered an Enterprise Agreement with Augment Code, and are looking to configure your dedicated tenant as an admin. In this guide we'll cover the Cosmos admin checklist and the common questions to help you get started quickly. # Checklist ## 1. Identity: the first admin + primary domains Augment staff will ask you to provide the email address of the first admin to be onboarded. This admin will become the first user and admin of your dedicated tenant, and later will be able to self-add more users and configure SSO. Augment staff will also ask you to provide the primary domains your users will be using in their email addresses. As an admin you'll be able to self-provision users matching any of those domains tied to your tenant. ## 2. Identity: SSO You'll want to enforce SSO for all your users on your tenant. Augment staff will ask you which SSO and will guide you on next steps. * [Config steps for Okta](/setup-augment/sso-okta-express-config) * Config steps for EntraID 🚧 ## 3. Identity: provisioning / SCIM Once SSO is configured, you'll want to provision users and groups from your identity provider/directory into your tenant. Cosmos admins can self-service add/remove users and promote/demote them to/from admin via [https://cosmos.augmentcode.com/account/team](https://cosmos.augmentcode.com/account/team). From that view admins can also allow-list or block-list access to Cosmos. > [!NOTE] > > Augment will soon rollout support for SCIM for users/user attributes/groups/group membership, so you'll be able to automatically provision and deprovision users/groups from your Okta, EntraID, Sailpoint etc. - stay tuned! ## 4. Identity: audit logs 🚧 ## 5. Status page and trust center You can access Augment's status page via [https://status.augmentcode.com/](https://status.augmentcode.com/) You can access Augment's security/audit documents via [https://trust.augmentcode.com/](https://trust.augmentcode.com/) ## 6. Models - governance ### Controlling what frontier models are available You can allow-list/block-list access to models based on their data retention policy via [https://app.augmentcode.com/models/data-retention](https://app.augmentcode.com/models/data-retention) You can restrict the list of models further in the "User model selection" section in [https://app.augmentcode.com/models/allowlist](https://app.augmentcode.com/models/allowlist). In the "Default model override" section you can choose a given model to be preselected (if the user starts a session without an expert). > [!NOTE] > > ONLY FOR EU TENANTS > > You can optionally enforce EU-inference-only via [https://app.eu.augmentcode.com/models/eu-inference](https://app.eu.augmentcode.com/models/eu-inference), so Cosmos only surface models that will perform inference in EU regions Cosmos offers an intelligent model router called [Prism](https://www.augmentcode.com/blog/augment-prism-model-routing-to-reduce-cost-and-maintain-quality) that will automatically pick the right model and level of intelligence for the job. You can optionally enable your own custom Prism via [https://app.augmentcode.com/models/prism](https://app.augmentcode.com/models/prism) ### BYOK If you have an Enterprise Agreement with Anthropic, OpenAI, AWS or GCP and you'd like to bring your own API keys to perform inference for given families of frontier models, you can do so in [https://app.augmentcode.com/models/byok](https://app.augmentcode.com/models/byok) When BYOK is enabled for given models, you'll be able to tell the token costs associated with BYOK models vs when Augment performs the inference via [https://cosmos.augmentcode.com/analytics?tab=cost](https://cosmos.augmentcode.com/analytics?tab=cost) ### Budgets You can optionally assign budgets to your users, manually via [https://app.augmentcode.com/organization-dashboard](https://app.augmentcode.com/organization-dashboard) (Budget tab > Edit budget) or programmatically via the [Analytics REST API](https://docs.augmentcode.com/analytics/api-reference#post-/analytics/v0/set-user-budget-overrides) (see **POST** `analytics/v0/set-user-budget-overrides`**).** Both soft limits and hard limits can be configured. You can also assign usage limits for headless automations via [https://cosmos.augmentcode.com/usage-limits](https://cosmos.augmentcode.com/usage-limits) ### Tracking cost and usage Admins can track costs and usage: * manually via [https://cosmos.augmentcode.com/analytics?tab=cost](https://cosmos.augmentcode.com/analytics?tab=cost) (suggestion: use Primary Breakdown = User and Secondary Breakdown = Resource): ![Screenshot 2026 09 17 At 4 45 24 PM](https://mintcdn.com/augment-mtje7p526w/djYqgvNeE_z7eFjr/images/Screenshot-2026-09-17-at-4.45.24-PM.png?fit=max\&auto=format\&n=djYqgvNeE_z7eFjr\&q=85\&s=3ddef9657da865d7c3e632329bf9149c) * and programmatically via [**POST /analytics/v0/cost-analytics**](https://docs.augmentcode.com/analytics/api-reference#post-/analytics/v0/cost-analytics) Suggested payload to group by on the 2 dimensions above: ```shellscript wrap theme={null} curl -X POST 'https://api.augmentcode.com/analytics/v0/cost-analytics' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"group_by_keys":["COST_ANALYTICS_GROUP_BY_USER","COST_ANALYTICS_GROUP_BY_RESOURCE"]}' ``` Example of response: ```json theme={null} { "data_points": [ { "cost_metrics": { "base_cost_usd": "81.526176", "billed_amount_usd": "81.526176", "cache_read_tokens": 0, "cache_write_tokens": 0, "credits_consumed": "0", "estimated_customer_cost_usd": "81.526176", "input_tokens": 0, "output_tokens": 0, "surcharge_usd": "0" }, "end_date": "2026-09-16", "group_by_values": { "expert_info": null, "product_display_name": "", "resource_display_name": "Compute", "resource_type": "COST_ANALYTICS_RESOURCE_TYPE_COMPUTE", "user_info": { "user_email": "XXX", "user_type": "COST_ANALYTICS_USER_TYPE_USER" } }, "start_date": "2026-09-10" }, { "cost_metrics": { "base_cost_usd": "25.76036775", "billed_amount_usd": "33.488478075", "cache_read_tokens": 18359563, "cache_write_tokens": 2083765, "credits_consumed": "0", "estimated_customer_cost_usd": "33.488478075", "input_tokens": 386, "output_tokens": 142205, "surcharge_usd": "7.728110325" }, "end_date": "2026-09-16", "group_by_values": { "expert_info": null, "product_display_name": "", "resource_display_name": "Claude Opus 5", "resource_type": "COST_ANALYTICS_RESOURCE_TYPE_MODEL", "user_info": { "user_email": "XXX", "user_type": "COST_ANALYTICS_USER_TYPE_USER" } }, "start_date": "2026-09-10" } ] } ``` ## 7. Cosmos settings ### Connectivity to your tech stack As an admin you'll then focus on one-time connecting Cosmos to your tech stack: your git repos, your ticketing system, your collab apps (Slack/Teams) etc. 🚧 Once one-time connectivity is established, users will be able to configure their software factory, deploy and use their Cosmos experts. ### Managing resources Cosmos offers multiple controls to help with your rollout across several teams, including: * [Spaces](/cosmos/spaces/overview) to group the experts, environments, sessions, and settings for a team or workstream so everyone works from a shared, focused set of resources. * **Groups** via [https://cosmos.augmentcode.com/account/groups](https://cosmos.augmentcode.com/account/groups): organize people into groups to share experts, environments, and other resources with everyone at once. > [!NOTE] > > Additional settings and access controls are regularly added by Cosmos - stay tuned! ### Outcomes As your teams are deploying and using their software factories, you'll be able to measure the outcomes via [https://cosmos.augmentcode.com/analytics?tab=outcomes](https://cosmos.augmentcode.com/analytics?tab=outcomes) # 101 - Getting Started On Cosmos Source: https://docs.augmentcode.com/cosmos/guides/getting-started-on-cosmos Connect your tech stack & deploy your v1.0 software factory with Cosmos Advisor ## 0. Introduction - why a software factory With Cosmos, your team can configure, deploy, and run its own **software factory**: a connected set of Experts Agents that move work from ideas & incidents to reviewed, tested pull requests, with humans setting direction and approving changes. Instead of starting a new agent from scratch for every task, you give specialized Experts repeatable responsibilities, access to the right repositories & your existing tools. Triggers connect those Experts to the events that matter, such as a ticket becoming ready for implementation or a pull request receiving review feedback. A software factory: * **Listens 24x7 to what's going on in your tech stack**. Agents can react in real-time to events and take actions. * **Helps your team collaborate in real time.** Humans work in multiplayer mode on specifications, resolve open questions together, and make decisions faster. * **Drives a compounding organizational knowledge flywheel**, where agents continuously learn and evolve through Cosmos sessions and human-agent PR feedback. * **Keeps humans in the loop.** They approve requirements, review important decisions, and decide what merges and deploys. In this guide you'll learn how to connect Cosmos to your tech stack, deploy the v1.0 version of your software factory using Cosmos Advisor, and explore additional loops to be configured. Once your software factory is deployed, it can be visually represented like this: ![Screenshot 2026 10 22 At 6 45 20 PM](https://mintcdn.com/augment-mtje7p526w/rE_POrvN4ams8WBn/images/Screenshot-2026-10-22-at-6.45.20-PM.png?fit=max\&auto=format\&n=rE_POrvN4ams8WBn\&q=85\&s=1ea70d4d90bc8800e01462521858dd4e) Source: [Software factory core loops](/cosmos/guides/software-factory-core-loops) (if you select top right "v1.0": that's what you'll deploy first in this guide) > [!TIP] > > Deploying your software factory means using Cosmos Advisor to deploy and stitch together experts, environments, and triggers in Cosmos. You get to decide where the runtime should be for those experts: Cosmos cloud environments or on your own infrastructure with self-hosted k8s. ## 1. One-time connect Cosmos to your tech stack Before you deploy your software factory you'll first connect 3 types of systems to Cosmos: **your git repos, your ticketing system, and your collaboration tool**. Once your v1.0 software factory is running you can connect additional systems and take on more use cases/loops. ### A. Connect your Git repositories * GitHub.com ⇒ Install and configure the GitHub App there (not the personal oauth) [GitHub Cloud](/cosmos/connectors/config-github) * GitLab.com ⇒ [GitLab Cloud](/cosmos/connectors/gitlab-cloud) * Azure DevOps (ADO Cloud) ⇒ [Azure DevOps Cloud](/cosmos/connectors/azure-devops-cloud) * GitHub Enterprise Server (GHES) ⇒ [GitHub Enterprise Server](/cosmos/connectors/github-enterprise-server) * GitLab Self-Hosted (GLSH) ⇒ [GitLab Self-Hosted](/cosmos/connectors/gitlab-self-hosted) * Azure DevOps Server (ADOS) ⇒ 🚧 > [!NOTE] > > If you're using other types of code repositories, contact your Cosmos Solutions Architect for assistance Once configured, Cosmos can discover repos, makes sense of your sophisticated codebases, detect and react to PR/MR events. ### B. Connect your ticketing system * Jira / Atlassian Cloud ⇒ [Jira Cloud](/cosmos/connectors/jira-cloud) * Linear ⇒ [Linear](/cosmos/connectors/config-linear) * Azure DevOps work items ⇒ [Azure DevOps Cloud](/cosmos/connectors/azure-devops-cloud) * ClickUp tasks ⇒ [ClickUp](/cosmos/connectors/clickup) Once configured, Cosmos can detect and react to ticket events. ### C. Connect your collaboration tool * **Slack ⇒ [Slack](/cosmos/connectors/config-slack)** * **MSFT Teams ⇒ [Microsoft Teams](/cosmos/connectors/microsoft-teams)** Once configured, Cosmos can detect and react to messages in given channels and inline reply in-threads. ### D. Create and verify your environment An **environment** gives an expert the runtime with repositories, tools, dependencies, and network access it needs to work. In the **Connect your Git repositories** section above, you've already configured one of the 2 types of environment: * **[Cloud environment](/cosmos/environments/cloud):** experts's runtime is on Cosmos' infrastructure . A cloud env also contains the repos you'd be working against, which the Augment Context Engine will automatically makes sense of. To create a new Cloud env: **Settings** > **Environments** > **Create an environment** > **Augment Cloud** > enter a name, pick an image, select your repos, toggle on Refresh, click on Create Environment * [Self-hosted Kubernetes](/cosmos/guides/early-access/self-hosted-k8s) (this is the successor of [daemon pools](/cosmos/environments/daemon-pools))**:** experts's runtime is on your infrastructure, collocated with other resources on your VPC that aren't directly exposed to the internet (ex: local mcp servers, on-prem resources etc.) Your software factory is made up of experts, and each expert will be attached to their own environment. Some experts can share the same environment where it makes sense, some other can use another environment (cloud or self-hosted). **🏁 Checkpoint: one-time connectivity is completed when:** * [ ] A session attached to the chosen environment can read the intended repositories. * [ ] A session can list the last 10 PRs/MRs from your git repos * [ ] A session can list the last 10 issues from your ticketing system * [ ] A session can post a hello world to a given Slack/Team channel * [ ] Cosmos receives events: [https://cosmos.augmentcode.com/automations/events](https://cosmos.augmentcode.com/automations/events) (Event Log tab) surfaces git, ticketing, Slack/Teams events You now have a working cloud or self-hosted environment. ## 2. Deploy your v1.0 software factory You'll focus on deploying the code producing loop (yellow) and the spec driven development loop (green) to build your v1.0 software factory. Visually it'll look like: ![Screenshot 2026 10 06 At 10 59 01 AM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-06-at-10.59.01-AM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=bf2649f46e38ecbd09bd69b5259080c9) ### A1. Deploy the code producing loop The code producing loop is made up of experts. To deploy them you'll start a new session with Cosmos Advisor, select your environment, and prompt your session with the experts to deploy and stitch together. For some types of git repos (ex: self-hosted ones) you'll instruct Cosmos Advisor to use specific capabilities. Select the tab corresponding to your tech stack: **GitHub.com** For GitHub.com repos, you've previously configured the native GitHub.com integration and a cloud env with those repos. To deploy your code-producing loop: **New session > Cosmos Advisor** > select your cloud env > submit this prompt: ```text wrap theme={null} Create a PR Author, PR Risk Analyzer, Deep Code Reviewer, PR Fixer, Pair Reviewer, Memory Manager. Suggest other experts I could deploy. Those experts should be using the attached GitHub.com integration. ``` **GitLab.com** For GitLab.com repos, you've previously configured the native GitLab.com integration and a cloud env with those repos. To deploy your code-producing loop: **New session > Cosmos Advisor** > select your cloud env > submit this prompt: ```text wrap theme={null} Create a MR Author, MR Risk Analyzer, Deep Code Reviewer, MR Fixer, Pair Reviewer, Memory Manager. Suggest other experts I could deploy. Those experts should be using the attached GitLab.com integration. ``` **ADO Cloud** For ADO Cloud repos, you've previously configured the native ADO Cloud integration and a cloud env with those repos. To deploy your code-producing loop: **New session > Cosmos Advisor** > select your cloud env > submit this prompt: ```text wrap theme={null} Create a PR Author, PR Risk Analyzer, Deep Code Reviewer, PR Fixer, Pair Reviewer, Memory Manager. Suggest other experts I could deploy. Those experts should be using the attached ADO integration. ``` **Github Enterprise Server** 🚧 For GHES repos, you've previously configured a self-hosted env with those repos and the gh cli. To deploy your code-producing loop: **New session > Cosmos Advisor** > select your self-hosted env > submit this prompt: ```text wrap theme={null} Create a PR Author, PR Risk Analyzer, Deep Code Reviewer, PR Fixer, Pair Reviewer, Memory Manager. Suggest other experts I could deploy. Those experts should be using the gh cli (already installed in the attached self-hosted env). ``` **GitLab Self-Hosted** 🚧 For GLSH repos, you've previously configured a self-hosted env with those repos and the glab cli. To deploy your code-producing loop: **New session > Cosmos Advisor** > select your self-hosted env > submit this prompt: ```text wrap theme={null} Create a MR Author, MR Risk Analyzer, Deep Code Reviewer, MR Fixer, Pair Reviewer, Memory Manager. Suggest other experts I could deploy. Those experts should be using the glab cli (already installed in the attached self-hosted env). ``` **ADOS** 🚧 For ADO Server repos, you've previously configured a self-hosted env with those repos and the ADO local MCP server. To deploy your code-producing loop: **New session > Cosmos Advisor** > select your self-hosted env > submit this prompt: ```text wrap theme={null} Create a PR Author, PR Risk Analyzer, Deep Code Reviewer, PR Fixer, Pair Reviewer, Memory Manager. Suggest other experts I could deploy. Those experts should be using the attached ADO local MCP server. ``` This will start a new session with Cosmos Advisor which may ask you to clarify your intent, and then proceed with deploying experts and their corresponding automations as Cosmos will listen 24x7 to specific events in your tech stack and automatically trigger the corresponding experts. Cosmos Advisor may ask you if you want to first manually invoke those experts or go straight to enabling auto-trigger across all your repos. You'll find the deployed experts under **Settings** > **Experts**. Each expert will have a job description, a set of capabilities (native integrations, MCP server etc.), a given model (automatically picked by Cosmos Advisor) and may have corresponding workers (a worker is like a sub-expert that the parent expert is aware of and may trigger when needed). You'll find the corresponding automations under **Settings** > **Automations** > **Automations tab**. An automation is composed of triggers (= the events Cosmos is listening to, ex: a PR got created, a comment was posted onto a PR etc.) and the expert that will be triggered. ### A2. Test the code producing loop The input of the code producing loop is well fleshed out requirements. The output is PRs/MRs created, reviewed + fixed. To test your code producing loop: **New session > PR/MR Author**, edit and submit this prompt: ```text wrap theme={null} Implement this Jira ticket . Create a PR in ready-to-review state. ``` or ```text wrap theme={null} Implement this change: . Create a PR in ready-to-review state. ``` This will start a new session with PR/MR Author, which will be acting as an orchestrator for: PR/MR Risk Analyzer, Deep Code Reviewer, PR/MR Fixer, Pair Reviewer. You should observe that: * the PR/MR is created (click on its link), and the experts are acting on it/replying to it automatically * in **Settings > Automations > Run History tab** some sessions were started based on the downstream PR/MR events * in **Settings > Automations > Event Log tab** Cosmos was notified of those specific events The PR/MR should progress on its own to a ready-for-a-final-review-by-a-human state. The human can open the PR/MR and read & react to the Pair Reviewer verdict onto the PR itself or via the corresponding Pair Reviewer session link. Congrats you've configured your code producing loop! 🎉 ### B1. Deploy the spec driven development loop The spec driven development loop essentially consists of the Project Builder expert - a human will solo-player invoke Project Builder, which will generate a PRD (Product Requirement Document) and a tech spec as Cosmos files, which humans can multiplayer collaborate on to refine specs. To deploy Project Builder, you'll start a new session with Cosmos Advisor, select your environment, and instruct Cosmos Advisor to use specific capabilities. Edit and submit this prompt: ```text wrap theme={null} Deploy Project Builder to help my team iterate on PRD + tech specs. I'll provide the link to a JIRA ticket as input. Don't author PRs directly, instead when I'm ready I'll ask you to update a label on the original ticket to "ready-for-cosmos-implementation", and you should trigger the PR Author when this happens. Any questions? ``` > [!NOTE] > > For this v1.0 try with a simple ticketing system integration. At a later time you can update Project Builder to integrate with other apps like Figma etc.) This will start a new session with Cosmos Advisor which may ask you to clarify your intent, and then proceed with deploying the Project Builder expert and the corresponding automations when applicable. You'll find the Project Builder expert under **Settings** > **Experts**. Project Builder will author files/artifacts (ex: PRD, tech specs) that you'll find under Files > Organization > experts > project-builder. You'll find the corresponding automations under **Settings** > **Automations** > **Automations tab**. An automation is composed of triggers (= the events Cosmos is listening to, ex: a Jira ticket's label was updated to "ready-for-cosmos-implementation" etc.) and the expert that will be triggered (ex: PR/MR author). ### B2. Test Project Builder The input of the spec driven development loop/Project Builder is a high level ticket/EPIC that needs to be iterated on. The output is fleshed out requirements: well defined PRD and well defined tech spec. To test Project Builder: **New session > Project Builder**, edit and submit this prompt: ```text wrap theme={null} Help me iterate on that Jira EPIC . ``` or ```text wrap theme={null} I'd like to implement this change: . Create the corresponding Jira ticket and help me spec it. ``` This will start a new session with Project Builder, which may ask you to clarify some aspects that are ambiguous and make decisions regarding the scope, then it'll create a PRD. The session will surface the link to the PRD, and it'll also be listed under "artifacts" in the right-hand drawer ("Details" tab): ![Screenshot 2026 10 06 At 5 29 40 PM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-06-at-5.29.40-PM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=717277994ab9d5bd25718555a4d65a2c) When you click on the PRD, that'll open the file in a new tab in the right-hand drawer: ![Screenshot 2026 10 06 At 6 34 39 PM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-06-at-6.34.39-PM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=9711f59b2482cccf3261dbef821f6ec6) You can also right-click on the file tab > Open in a new tab to see the file in full screen: ![Screenshot 2026 10 06 At 6 35 19 PM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-06-at-6.35.19-PM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=0647e021b92da45b171895de3dbffbf7) You can edit the PRD, share it with other folks on your team, select a portion of text to comment and tag your teammates on it: ![Screenshot 2026 10 06 At 6 37 28 PM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-06-at-6.37.28-PM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=353696f5f0ffb59fed350e82cd91c16b) ![Screenshot 2026 10 06 At 6 38 29 PM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-06-at-6.38.29-PM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=4b1594f56f4c521cc42e070a0deb2737) > [!NOTE] > > By default Project Builder will create PRDs in your Organization files, which means that anyone can collaborate on them. If you create experts in spaces, by default the files will live in the Space files. You can also instruct your experts to create personal files, which you'll have to explicitly share with teammates. Iterate on your PRD, validate the scope and assumptions Project Builder brought to your attention. Then Project Builder will offer to create a tech spec and ask to choose a design posture based on the nature of the change (you can later in-session ask Project Builder to remember decisions for you/your team): ![Screenshot 2026 10 06 At 6 50 04 PM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-06-at-6.50.04-PM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=5a23798ab5ca0502c33f5578d9c8e028) You can open and review the tech spec in a new tab. Cosmos continuously makes sense of your codebase (thanks to the Augment Context Engine) and surfaces the very modules and components in your architecture that will be impacted by your decisions. ![Screenshot 2026 10 06 At 7 00 05 PM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-06-at-7.00.05-PM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=2c52e10804531edd326844698339ca8e) Once you approve the tech spec, Project Builder will suggest the next steps. > [!NOTE] > > You can later instruct Project Builder to remember to update the original Jira ticket with the PRD + Tech Spec and flip a label to "ready-for-cosmos-implementation" for an automated ticket-to-PR flow. At any time you can also ask Cosmos Advisor to perform those changes. You can choose to handoff to PR author for this first test. Project Builder will update the tech spec with a new section that breaks down the tasks and PRs to be created and in which sequence: ![Screenshot 2026 10 06 At 7 14 24 PM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-06-at-7.14.24-PM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=7540b2ea0cb04ff38cf98f016abeac6f) At the bottom of the Project Builder session, you'll see the worker session related to the PR Author, you can click on it from there: ![Screenshot 2026 10 07 At 10 44 48 AM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-07-at-10.44.48-AM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=a85bb6266d3981daefb867476e4553ba) You can also access the PR Author session in the left nav bar by expanding the Project Builder session: ![Screenshot 2026 10 07 At 10 45 49 AM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-07-at-10.45.49-AM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=526ae63931f496bd3d8fe6973b307b55) In the PR Author session, you'll see the PR link under Artifacts. On the PR you'll see the code producing loop experts interacting with it: ![Screenshot 2026 10 07 At 11 01 28 AM](https://mintcdn.com/augment-mtje7p526w/QVVaj2tGYlZcl2av/images/Screenshot-2026-10-07-at-11.01.28-AM.png?fit=max\&auto=format\&n=QVVaj2tGYlZcl2av\&q=85\&s=9e2881569ed573378231352b3a512075) Congrats you've successfully configured your code producing & spec driven development loops! 🎉 > [!NOTE] > > Coming soon: 102 - Advanced loops (in construction 🚧) # A portfolio of software factories: one per team Source: https://docs.augmentcode.com/cosmos/guides/n-software-factories-one-per-team A portfolio view of per-team software factories, shared environments, and Cosmos Advisor. # Self-hosted Kubernetes Source: https://docs.augmentcode.com/cosmos/guides/self-hosted-k8s Connect a self-hosted Kubernetes cluster to Cosmos using Minikube, generated manifests, or Helm chart. > [!NOTE] > > This feature is in early access and behind a feature flag. Contact your Augment Solutions Architect to enable it for your tenant > [!NOTE] > > Self-hosted k8s currently support linux only. In a future version, support for Windows sandboxes will be added # Introduction This guide walks through connecting a self-hosted Kubernetes cluster to Cosmos. It uses an AWS EC2 instance running Ubuntu and Minikube as a reference environment, then covers deployment with either generated k8s manifests or Helm. ## Prerequisites Cosmos * Must have access to [cosmos.augmentcode.com](https://cosmos.augmentcode.com) AWS * Must have permission to deploy and manage a AWS EC2 instance * Outbound access to * `gw.cosmos.augmentcode.com:443` (if US tenant) * `gw.eu.cosmos.augmentcode.com:443` (if EU tenant) * An x86\_64/amd64 Ubuntu host with KVM and nested virtualization enabled * At least 100 GB of storage * Permission to install Docker, Minikube, kubectl, and Helm # Configure AWS EC2 Ubuntu + Minikube > [!NOTE] > > Don't use the Minikube approach in production, it's for testing purpose only. See the EKS blueprint in a section below for production use ## Create a Cosmos service account Go to [cosmos.augmentcode.com](https://cosmos.augmentcode.com), go to **Settings > Service Accounts** > + **Create service account**: * Account name: `k8s-self-hosted` * Description: `To connect our hosted k8s cluster to Cosmos` You’ll get “You service account is ready”. Then click on Create API token > New token name: `token01` > click on Create token Then click on “Copy token” and store it securely. You will use it later to create a k8s secret. ## Create a Cosmos sandbox provider Go to [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > Settings > Sandbox Providers > + Create provider: * Display name: `my-k8s-0` * Slug: `my-k8s-0` * Enabled: keep toggled on * Click on Create provider You should see `my-k8s-0` in the list with an **Enabled** status.: ## Create an AWS EC2 instance + Minikube ### Deploy the EC2 instance Go to your AWS Console > deploy a new EC2 instance: * OS: `Ubuntu 26.04 LTS HVM` * Architecture: `64-bit (x86)` * Instance type: `m7i.2xlarge` * Configure storage: `100 GB gp3` * Advanced details > Nested virtualization > `Enabled` After launching the EC2 instance, verify the architecture, virtualization support, and KVM device: ```bash theme={null} uname -m # expected: x86_64 lscpu | grep -i virtualization # expected: VT-x sudo modprobe kvm_intel ls -l /dev/kvm ``` Expected result: ```text theme={null} crw-rw---- 1 root kvm 10, 232 /dev/kvm ``` ### Install Minikube ```bash wrap theme={null} curl -LO https://github.com/kubernetes/minikube/releases/latest/download/minikube-linux-amd64 sudo install minikube-linux-amd64 /usr/local/bin/minikube rm minikube-linux-amd64 ``` ### Install Docker Engine Follow the [Docker Engine installation guide for Ubuntu](https://docs.docker.com/engine/install/ubuntu/), or configure the official apt repository directly: ```bash theme={null} sudo apt update sudo apt install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc sudo tee /etc/apt/sources.list.d/docker.sources < [!NOTE] > > Minikube uses a container-in-container architecture, so Docker shows one Minikube container rather than each Kubernetes workload. Run `minikube stop` when you need to stop the cluster. Verify the cluster: ```bash theme={null} kubectl get pods -A ``` Expected result: ```text theme={null} NAMESPACE NAME READY STATUS RESTARTS AGE kube-system coredns-559f6c778d-fmf9b 1/1 Running 0 24s kube-system etcd-minikube 1/1 Running 0 30s kube-system kindnet-49t8x 1/1 Running 0 24s kube-system kube-apiserver-minikube 1/1 Running 0 30s kube-system kube-controller-manager-minikube 1/1 Running 0 30s kube-system kube-proxy-24l6k 1/1 Running 0 24s kube-system kube-scheduler-minikube 1/1 Running 0 30s kube-system storage-provisioner 1/1 Running 0 29s ``` ### Label the KVM-capable node ```bash theme={null} minikube kubectl -- label node minikube \ cosmos.augmentcode.com/pool-type=kvm --overwrite ``` Expected result: ```text theme={null} node/minikube labeled ``` ### Enable the Minikube registry via the built-in add-on and capture its cluster IP ```bash wrap theme={null} minikube addons enable registry kubectl -n kube-system wait \ --for=condition=Available deployment/registry --timeout=180s export REGISTRY_IP=$(kubectl -n kube-system get service registry \ -o jsonpath='{.spec.clusterIP}') echo "Registry inside Kubernetes: ${REGISTRY_IP}:80" ``` Expected result: ```text theme={null} * registry is an addon maintained by minikube. For any concerns contact minikube on GitHub. You can view the list of minikube maintainers at: https://github.com/kubernetes/minikube/blob/master/OWNERS - Using image registry.k8s.io/minikube/kube-registry-proxy:v0.0.11 - Using image docker.io/registry:3 * Verifying registry addon... * The 'registry' addon is enabled deployment.apps/registry condition met Registry inside Kubernetes: 10.107.78.112:80 ``` Create a port-forward to access that registry: ```bash theme={null} kubectl -n kube-system port-forward service/registry 5000:80 \ >/tmp/minikube-registry.log 2>&1 & echo "Host registry: localhost:5000" ``` Expected results: ```text theme={null} [1] 95790 Host registry: localhost:5000 ``` Before continuing, confirm that the registry IP is available: ```bash theme={null} export REGISTRY_IP="$( kubectl -n kube-system get service registry \ -o jsonpath='{.spec.clusterIP}' )" test -n "$REGISTRY_IP" || { echo "Registry IP not found"; exit 1; } echo "Registry: ${REGISTRY_IP}:80" ``` Expected result: ```text theme={null} Registry: 10.107.78.112:80 ``` ### Store the Cosmos service account token Create the controller namespace, then enter the Cosmos service-account token when prompted. This method does not store the token in a file or command argument. ```bash theme={null} minikube kubectl -- create namespace cosmos-ctrl \ --dry-run=client -o yaml | minikube kubectl -- apply -f - read -rsp 'Portal token: ' portal_token; echo printf '%s' "$portal_token" | minikube kubectl -- -n cosmos-ctrl create secret generic cosmos0-portal-token \ --from-file=token=/dev/stdin --dry-run=client -o yaml | minikube kubectl -- apply -f - unset portal_token ``` ## Option1: Deploy with k8s manifests ### Download the Cosmos deployment binary ```bash theme={null} curl -fsSL \ https://dist.augmentcode.com/cosmos/cosmos-linux-amd64 | install -m755 /dev/stdin cosmos ``` ### Generate and apply the k8s manifests Generate the manifests: ```bash theme={null} ./cosmos k8s deploy show \ --provider-name=my-k8s-0 \ --registry.repository "${REGISTRY_IP}:80/snapshots" \ -A--pool-selector="cosmos.augmentcode.com/pool-type=kvm" \ --sandbox.default-cpu="4" \ --sandbox.default-ram="8G" \ --sandbox.default-disk="16G" \ --create-namespace \ --sandbox.create-namespace \ --portal.address=gw.cosmos.augmentcode.com:443 \ > cosmos-sh.k8s.yaml ``` Add the Minikube KVM group ID to the sandbox pod security context: ```bash wrap theme={null} KVM_GID=$(minikube ssh -- stat -c '%g' /dev/kvm | tr -cd '0-9') sed -i.bak \ "s|\"serviceAccountName\":\"cosmos0-sandbox-sa\"}}|\"serviceAccountName\":\"cosmos0-sandbox-sa\",\"securityContext\":{\"supplementalGroups\":[${KVM_GID}]}}}|" \ cosmos-sh.k8s.yaml ``` Inspect `cosmos-sh.k8s.yaml` and confirm that the sandbox pod template includes the KVM group under `securityContext.supplementalGroups`, run: ```shellscript theme={null} nano --softwrap cosmos-sh.k8s.yaml ``` Expected node in your yaml: ```text wrap theme={null} - --pod-template={"metadata":{"labels":{"app.kubernetes.io/component":"sandbox","app.kubernetes.io/instance":"cosmos0","app.kubernetes.io/managed-by":"cosmos-k8s-deploy","app.kubernetes.io/name":"cosmos","cosmos.augmentcode.com/installation":" cosmos0","cosmos.augmentcode.com/provider":"my-k8s-0"}},"spec":{"containers":null,"serviceAccountName":"cosmos0-sandbox-sa","securityContext":{"supplementalGroups":[104]}}} ``` Validate the manifests before applying them: ```bash theme={null} minikube kubectl -- apply --dry-run=client -f cosmos-sh.k8s.yaml ``` Expected result: ```text theme={null} namespace/cosmos-ctrl unchanged (dry run) namespace/cosmos-sb unchanged (dry run) secret/cosmos0-portal-token configured (dry run) serviceaccount/cosmos0-controller-sa unchanged (dry run) serviceaccount/cosmos0-sandbox-sa unchanged (dry run) role.rbac.authorization.k8s.io/cosmos0-controller-role unchanged (dry run) rolebinding.rbac.authorization.k8s.io/cosmos0-controller-binding unchanged (dry run) networkpolicy.networking.k8s.io/cosmos0-sandbox-ingress unchanged (dry run) deployment.apps/cosmos0-controller configured (dry run) ``` Apply the manifests: ```bash theme={null} minikube kubectl -- apply -f cosmos-sh.k8s.yaml ``` Expected result: ```text theme={null} namespace/cosmos-ctrl unchanged namespace/cosmos-sb unchanged secret/cosmos0-portal-token unchanged serviceaccount/cosmos0-controller-sa unchanged serviceaccount/cosmos0-sandbox-sa unchanged role.rbac.authorization.k8s.io/cosmos0-controller-role unchanged rolebinding.rbac.authorization.k8s.io/cosmos0-controller-binding unchanged networkpolicy.networking.k8s.io/cosmos0-sandbox-ingress unchanged deployment.apps/cosmos0-controller unchanged ``` ### Set again the Cosmos service account token With the approach above, you generated cosmos-sh.k8s.yaml without the token value in it, and since `kubectl apply` is declarative (=the live object match the YAML) `apply` happened with an unset token value. Set the secret again: ```shellscript theme={null} read -rsp 'Portal token: ' portal_token; echo printf '%s' "$portal_token" | minikube kubectl -- -n cosmos-ctrl create secret generic cosmos0-portal-token \ --from-file=token=/dev/stdin --dry-run=client -o yaml | minikube kubectl -- apply -f - unset portal_token ``` Reload the controllers: ```shellscript theme={null} minikube kubectl -- -n cosmos-ctrl rollout restart deployment/cosmos0-controller ``` Why it’s important: updating a Kubernetes Secret does **not automatically restart the applications using it**. So perform a rolling restart of the three controller pods so each process reads the new token. Kubernetes replaces the pods gradually, keeping available old pods until replacements are ready. It does not restart Minikube or the EC2 instance. The mounted Secret file may eventually update automatically, but the controller might only read it during startup; the rolling restart guarantees immediate use. > [!NOTE] > > Token management is more elegantly handled via the Helm chart approach in the next section ### Verify the controller pods are running ```bash theme={null} kubectl -n cosmos-ctrl get pods ``` Expected result: ```text theme={null} NAME READY STATUS RESTARTS AGE cosmos0-controller-6778d69f44-f9kw6 1/1 Running 0 21s cosmos0-controller-6778d69f44-gcj77 1/1 Running 0 28s cosmos0-controller-6778d69f44-v8nbz 1/1 Running 0 2 ``` ## Option 2: Deploy with Helm > [!NOTE] > > If you already deployed the generated manifests, the Helm command below uses `--take-ownership` to adopt those resources. After migration, manage the installation only with `helm upgrade`; do not continue applying `cosmos-sh.k8s.yaml`. ### Install Helm Download and verify Helm: ```bash theme={null} HELM_VERSION=v3.22.0 HELM_ARCH=$(dpkg --print-architecture) case "$HELM_ARCH" in amd64|arm64) ;; *) echo "Unsupported: $HELM_ARCH"; exit 1 ;; esac helm_tmp=$(mktemp -d /tmp/helm-install.XXXXXX) archive="helm-${HELM_VERSION}-linux-${HELM_ARCH}.tar.gz" curl -fsSLo "$helm_tmp/$archive" "https://get.helm.sh/$archive" curl -fsSLo "$helm_tmp/$archive.sha256sum" \ "https://get.helm.sh/$archive.sha256sum" (cd "$helm_tmp" && sha256sum -c "$archive.sha256sum") ``` Expected response: ```text theme={null} helm-v3.22.0-linux-amd64.tar.gz: OK ``` Install Helm and take ownership: ```bash theme={null} tar -xzf "$helm_tmp/$archive" -C "$helm_tmp" sudo install -o root -g root -m 0755 \ "$helm_tmp/linux-${HELM_ARCH}/helm" /usr/local/bin/helm rm -r -- "$helm_tmp" hash -r helm version --short helm upgrade --help | grep -- --take-ownership ``` Expected response: ```text wrap theme={null} v3.22.0+g144ca65 --take-ownership if set, upgrade will ignore the check for helm annotations and take ownership of the existing resources ``` ### Create the file mapped to the Cosmos service account token Create `cosmos0-values.yaml`: ```yaml theme={null} cat <<'EOF' > cosmos0-values.yaml installationName: cosmos0 providerName: my-k8s-0 image: repository: dist.augmentcode.com/cosmos/cosmos-sh tag: latest controllerPullSecrets: [] sandboxPullSecrets: [] portal: # For EU, use: gw.cosmos.eu.augmentcode.com:443 address: "gw.cosmos.augmentcode.com:443" # Augment Cosmos portal gateway. tokenSecret: # Existing Kubernetes Secret containing the portal token. source: existing name: cosmos0-portal-token key: token tlsSecret: enabled: false name: "" certificateKey: tls.crt privateKeyKey: tls.key caBundleKey: ca.crt controller: replicas: 1 serviceAccount: create: true name: controller labels: {} annotations: {} resources: {} args: - --pool-selector=cosmos.augmentcode.com/pool-type=kvm - --pod-disk-reserve=6Gi # PER SESSION: Request 6Gi of pod storage beyond the guest disk. - --image.max-size=4Gi # PER IMAGE: Reject base images larger than 4Gi. - --snapshot.max-size=3Gi # PER SNAPSHOT LINEAGE: Limit snapshot content to 3Gi. - --snapshot.min-scratch=128Mi # PER RESTORED SESSION: Preserve at least 128Mi of scratch space. - --pod-image-cache=/var/lib/cosmos-sh/minikube/cache # PER NODE: Shared node-local base-image cache. - --image.cache-max-size=8Gi # PER NODE: Limit the shared image cache to 8Gi. sandbox: namespace: cosmos-sb namespaceResource: create: true labels: {} annotations: {} backendPort: 50051 serviceAccount: create: true name: sandbox labels: {} annotations: {} resources: cpu: "4" # PER NEW SESSION: Default guest vCPU count. ram: "8G" # PER NEW SESSION: Default guest memory. disk: "16G" # PER NEW SESSION: Default writable guest disk. podTemplate: {} rbac: create: true role: labels: {} annotations: {} roleBinding: labels: {} annotations: {} networkPolicy: create: false labels: {} annotations: {} EOF ``` The chart references the existing k8s secret without storing its value in the values file. ### Calculate Minikube-specific values ```bash theme={null} CHART=oci://dist.augmentcode.com/helm/cosmos REGISTRY_IP=$(minikube kubectl -- -n kube-system get svc registry \ -o jsonpath='{.spec.clusterIP}') KVM_GID=$(minikube ssh -- stat -c '%g' /dev/kvm | tr -cd '0-9') POD_TEMPLATE=$(printf '{"spec":{"nodeSelector":{"cosmos.augmentcode.com/pool-type":"kvm"},"securityContext":{"supplementalGroups":[%s]}}}' "$KVM_GID") ``` Verify the node label: ```bash theme={null} minikube kubectl -- get node minikube \ -L cosmos.augmentcode.com/pool-type ``` Expected result: ```text theme={null} NAME STATUS ROLES AGE VERSION POOL-TYPE minikube Ready control-plane 25h v1.37.0 kvm ``` Verify the chart: ```bash theme={null} helm show chart "$CHART" ``` Expected result: ```text theme={null} Pulled: oci://dist.augmentcode.com/helm/cosmos:0.0.0 Digest: sha256:44fc78c1ba0fc510d5cc0fcc320b2e9df021db7b75aeb4e97ceb3c26c6c69bc8 apiVersion: v2 appVersion: 0.0.0 description: Cosmos self-hosted Kubernetes sandbox provider (controller, RBAC, and credentials). home: https://www.augmentcode.com keywords: - cosmos - augment - sandbox kubeVersion: '>=1.25.0-0' name: cosmos type: application version: 0.0.0 ``` ### Dry-run and install Run a server-side dry run without displaying Secret values: ```bash theme={null} helm upgrade --install cosmos0 "$CHART" \ --namespace cosmos-ctrl \ -f cosmos0-values.yaml \ --set-string "registry.repository=${REGISTRY_IP}:80/snapshots" \ --set-json "sandbox.podTemplate=${POD_TEMPLATE}" \ --take-ownership \ --dry-run=server \ --hide-secret ``` Install the release: ```bash theme={null} helm upgrade --install cosmos0 "$CHART" \ --namespace cosmos-ctrl \ -f cosmos0-values.yaml \ --set-string "registry.repository=${REGISTRY_IP}:80/snapshots" \ --set-json "sandbox.podTemplate=${POD_TEMPLATE}" \ --take-ownership \ --wait \ --timeout 10m ``` Expected result: ```text theme={null} Release "cosmos0" does not exist. Installing it now. Pulled: us-central1-docker.pkg.dev/augment-research-gsc/cosmos/helm/cosmos0/cosmos:0.0.0 Digest: sha256:44fc78c1ba0fc510d5cc0fcc320b2e9df021db7b75aeb4e97ceb3c26c6c69bc8 NAME: cosmos0 LAST DEPLOYED: Fri Sep 18 19:59:27 2026 NAMESPACE: cosmos-ctrl STATUS: deployed REVISION: 1 TEST SUITE: None NOTES: Cosmos installation cosmos0 (provider my-k8s-0) controller: cosmos-ctrl/cosmos0-controller sandboxes: namespace cosmos-sb portal: gw.cosmos.augmentcode.com:443 snapshots: 10.107.78.112:80/snapshots API token: Secret cosmos-ctrl/cosmos0-portal-token, key token Referenced as an existing Secret; the chart does not manage it. Controller pods become ready once the reverse tunnel is established: kubectl -n cosmos-ctrl rollout status deployment/cosmos0-controller ``` Verify the deployment: ```bash theme={null} helm status cosmos0 -n cosmos-ctrl minikube kubectl -- -n cosmos-ctrl rollout status \ deployment/cosmos0-controller minikube kubectl -- -n cosmos-ctrl get pods ``` Expected result: ```text theme={null} NAME: cosmos0 LAST DEPLOYED: Fri Sep 18 19:59:27 2026 NAMESPACE: cosmos-ctrl STATUS: deployed REVISION: 1 TEST SUITE: None NOTES: Cosmos installation cosmos0 (provider my-k8s-0) controller: cosmos-ctrl/cosmos0-controller sandboxes: namespace cosmos-sb portal: gw.cosmos.augmentcode.com:443 snapshots: 10.107.78.112:80/snapshots API token: Secret cosmos-ctrl/cosmos0-portal-token, key token Referenced as an existing Secret; the chart does not manage it. Controller pods become ready once the reverse tunnel is established: kubectl -n cosmos-ctrl rollout status deployment/cosmos0-controller deployment "cosmos0-controller" successfully rolled out NAME READY STATUS RESTARTS AGE cosmos0-controller-bf5f5cc4b-5wgdr 1/1 Running 0 34s cosmos0-controller-bf5f5cc4b-6xjwx 1/1 Running 0 40s cosmos0-controller-bf5f5cc4b-vkg5x 1/1 Running 0 28s ``` ## (Optional) Rotate the service account token > [!NOTE] > > Note: if you have to update the secret after the cluster is already started, reset the value and reload the controllers. Set the secret again: ```shellscript theme={null} read -rsp 'Portal token: ' portal_token; echo printf '%s' "$portal_token" | minikube kubectl -- -n cosmos-ctrl create secret generic cosmos0-portal-token \ --from-file=token=/dev/stdin --dry-run=client -o yaml | minikube kubectl -- apply -f - unset portal_token ``` Reload the controllers: ```shellscript theme={null} minikube kubectl -- -n cosmos-ctrl rollout restart deployment/cosmos0-controller ``` ## Configure a new env in Cosmos In [cosmos.augmentcode.com](https://cosmos.augmentcode.com), go to **Settings > Environments > Create an environment > Self-hosted** * Name: `K8s on EC2` * Description: `Self-hosted k8s cluster on EC2` * Self-hosted compute > Sandbox Provider > Select `my-k8s-0` * Base image: keep `Cosmos Default` selected * Repositories: select your repositories from github.com, gitlab.com, ADO * Refresh: `toggle on` * Click on Create Environment ![Image](https://mintcdn.com/augment-mtje7p526w/4vURUEGMTUIrsg0u/images/image-64.png?fit=max\&auto=format\&n=4vURUEGMTUIrsg0u\&q=85\&s=8edd7f556b48fdd209165c08da8b2ffb) The environment will build (can range from 15sec to a few minutes) ![Screenshot 2026 09 18 At 12 10 10 PM](https://mintcdn.com/augment-mtje7p526w/9bsC_O9hjowbmJGe/images/Screenshot-2026-09-18-at-12.10.10-PM.png?fit=max\&auto=format\&n=9bsC_O9hjowbmJGe\&q=85\&s=f9da2ec0ec4cca6e2aa66e55daf3807d) Once completed you should see this: ![Screenshot 2026 09 18 At 12 11 19 PM](https://mintcdn.com/augment-mtje7p526w/9bsC_O9hjowbmJGe/images/Screenshot-2026-09-18-at-12.11.19-PM.png?fit=max\&auto=format\&n=9bsC_O9hjowbmJGe\&q=85\&s=28c25308d5cdf98fdbb6317deec2b27a) Click on Done. Now under In [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > Settings > Environments you'll see your new environment with a specific self-hosted icon (different from Cloud Environments that will have a cloud icon): ![Image](https://mintcdn.com/augment-mtje7p526w/4vURUEGMTUIrsg0u/images/image-65.png?fit=max\&auto=format\&n=4vURUEGMTUIrsg0u\&q=85\&s=01203486fefdb343c91c1dcd95570287) ## Run a test Cosmos session In [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New session > Bottom left of the prompt box select your "K8s on EC2" self-hosted env and prompt it with `What repos are available in this environment?` Your session would look like this below, note the env name on the right-side drawer and the list of the repos in that env: ![Image](https://mintcdn.com/augment-mtje7p526w/4vURUEGMTUIrsg0u/images/image-66.png?fit=max\&auto=format\&n=4vURUEGMTUIrsg0u\&q=85\&s=a56c79cc4cc62f61af9b94fb20b92598) Congrats you've configured Cosmos with your self-hosted k8s cluster! 🎉 ## Granting access to other team members to use that env To grant access to other team members to the env above you'll need to give them: * can-view permission on the env * can-use permission on the underlying sandbox provider After that they'll be able to select the env in the drop down list in the Cosmos > New Session view, and start new sessions using that env. ## Blueprint for AWS EKS, GKS, AKS > [!NOTE] > > You can take inspiration from the Helm chart approach above to bring your own k8s clusters, whether they are managed or not. This guide will later be updated with blueprints for EKS, GKS, AKS, stay tuned! # Software Factory: Core Loops Cosmos Can Help Build Source: https://docs.augmentcode.com/cosmos/guides/software-factory-core-loops Software Factory: Core Loops Cosmos Can Help Build - # Software Factory: Core Loops Cosmos Can Help Build Software Factory Fully built v1.0 (pilot day #1) Intake & triage loops Spec driven development 👤 human collaborates with 1 Project Builder Expertiterate on spec with agent and humans Cosmos Files PRD Tech spec Architecture EPIC / TICKETS Jira Linear Ticket and dispatch loop Sources Slack Teams Support Portal 1 Feedback Triager Backlog systems Jira Linear 2 Backlog Dispatcher 🚨Incident response loop Sources Slack Teams Sentry PagerDuty Grafana Datadog 1 Incident Investigator 2 Incident Responder + Post Mortem Writer Ready for implementation ⚙️ ### Code producing loop Repositories GitHub GitLab Bitbucket Azure DevOps PR Authorwrites the changes + tests → then PR Risk Analyzerassesses blast radius → then Deep Code Reviewersurface findings → then PR Fixerauto remediate findings → then E2E Verifier validates E2E\ (ex: w/ playwright) → then Pair Reviewercollaborative final review 👤 with human → then Memory Managercaptures learnings ↺ loop back Verification or review findings return to PR Author for another pass Inside E2E Verifier intake → detect → checkout → install → start web server → serve pages → verify → verdict → report # Cosmos Keyboard Command Reference Source: https://docs.augmentcode.com/cosmos/keyboard-command-reference A reference of all available keyboard shortcuts for navigating and controlling the Cosmos app. The Cosmos app provides keyboard shortcuts to help you navigate spaces, manage sessions, and work with files without leaving the keyboard. Each table lists the macOS and Windows & Linux keys separately. ## Global navigation | Command | macOS | Windows & Linux | | :- | :- | :- | | Open command palette | `Cmd` `K` | `Ctrl` `K` | | Go to sessions list | `Cmd` `Shift` `L` | `Ctrl` `Shift` `L` | | Go to files | `Cmd` `Shift` `E` | `Ctrl` `Shift` `E` | | Go to recent session (1-9) | `Option` `1`–`9` | `Alt` `1`–`9` | ## Command palette Open the command palette with `Cmd` `K` (macOS) or `Ctrl` `K` (Windows and Linux). Once open, use the following shortcuts to navigate the menu: | Command | macOS | Windows & Linux | | :- | :- | :- | | Navigate results | `Up` / `Down` | `Up` / `Down` | | Select or start session | `Enter` | `Enter` | | Edit resource | `Cmd` `Enter` | `Ctrl` `Enter` | | Close | `Esc` | `Esc` | ## Actions | Command | macOS | Windows & Linux | | :- | :- | :- | | New session | `Cmd` `Shift` `O` | `Ctrl` `Shift` `O` | ## Application | Command | macOS | Windows & Linux | | :- | :- | :- | | Toggle left sidebar | `Cmd` `.` | `Ctrl` `.` | | Toggle settings navigation | `Cmd` `Shift` `,` | `Ctrl` `Shift` `,` | | Show keyboard shortcuts | `Cmd` `/` | `Ctrl` `/` | ## Sessions | Command | macOS | Windows & Linux | | :- | :- | :- | | Previous turn | `Cmd` `↑` | `Ctrl` `↑` | | Next turn | `Cmd` `↓` | `Ctrl` `↓` | | Enhance prompt | `Cmd` `E` | `Ctrl` `E` | | Toggle right sidebar | `Cmd` `Shift` `.` | `Ctrl` `Shift` `.` | | Unfocus input | `Esc` | `Esc` | ## Files | Command | macOS | Windows & Linux | | :- | :- | :- | | Search files | `Cmd` `P` | `Ctrl` `P` | | New folder in selected folder | `Shift` `N` | `Shift` `N` | | Rename selected file or folder | `Enter` | `Enter` | | Delete selected file or folder | `Delete` / `Backspace` | `Delete` / `Backspace` | # Manage automations Source: https://docs.augmentcode.com/cosmos/manage-automations Review the schedules, webhooks, and events that trigger your Experts, and track each one's runs from a single page. Find **Automations** under **Settings**. Select an Expert's name to open its detail page and review what triggers it, what it's received, and what it's run. The detail page has three tabs: **Overview**, **Run History**, and **Event History**. **Overview** The **Overview** tab displays the automation's Expert configuration and status together with its schedules, webhooks, and integration triggers. It shows the automation's name, description, **Enabled** or **Disabled** status, **Owner**, and number of **Enabled workflows**, plus a **Triggers** section listing each one. Use this tab to confirm which Expert configuration and triggers belong to the automation before investigating an event or run. ### Pause or remove triggers Use the controls in the **Triggers** section to manage a trigger: * Turn off the enable toggle to pause the trigger without losing its configuration. Turn it on to resume the trigger. * Remove the trigger to stop it from starting the Expert. Removing a trigger does not change the Expert's capabilities or tools. * Use **Auto-archive sessions created by this trigger** to choose whether trigger-started sessions remain visible after they become idle. > [!NOTE] > > Cosmos runs schedules one at a time. If the next fire arrives while the previous run is still going, Cosmos skips that fire instead of queueing it or running it later. See [Schedules](/cosmos/config-schedules). **Run History** The **Run History** tab lists sessions that a trigger started for this automation. Select a run to open its session and inspect what the Expert did. If the session has workers, its worker tree appears in the session's right sidebar. Above the run list, the **Last 24 hrs** and **Last 7 days** summaries show succeeded and failed run counts. Use the **My runs** / **All runs** toggle to switch between your runs and all runs you can access; the summaries and run list update to match the selected scope. > [!NOTE] > > **Run History** in the Automations sidebar shows runs across automations. Open an automation's detail page when you only want runs for its Expert. **Event History** The **Event History** tab displays recent events grouped by the automation's event-driven triggers. Each group identifies the trigger and source, then lists the matched event type and relative time. This tab is a best-effort view based on each trigger's source, event type, payload and header filters, and webhook identity. It does not present the full cross-automation Event Log — see [Inspect events across automations](#inspect-events-across-automations) for that view. Scheduled triggers do not receive inbound events, so they do not appear here. > [!NOTE] > > An automation with no event-driven triggers has no event history to show. ## Inspect events across automations Open **Event Log** under **Automations** in the sidebar when you need to investigate events across all automations. The newest events appear first. You can: * Filter by source, such as GitHub, GitLab, Linear, Slack, Webhook, or PagerDuty. * Use **Advanced Filter** to filter by event type, JSONLogic payload filter, or header filter. * Select an event to inspect its source, event type, timestamp, JSON payload, and captured request headers. Use the global log to test a filter against payloads Cosmos has received before adding that filter to a trigger. See [Configuring triggers](/cosmos/config-triggers) for the event-type and filter reference. ## Related pages * [Understanding automation](/cosmos/automations) explains how triggers, events, and Experts fit together. * [Your first automation](/cosmos/first-automation) walks through creating two automations. # Using Sessions Source: https://docs.augmentcode.com/cosmos/sessions-overview Work with an Expert in a conversation — where you give the agent a task, watch it run and follow every turn. ## About sessions A Session is a conversation with a specialized agent, called an Expert. The Expert supplies the instructions, model, and capabilities (e.g. integrations with Slack, Linear or Jira); the [Environment](/cosmos/environments/overview) supplies the machine where the agent reads your repositories, runs commands, and executes tools. The Session is where the two meet, and where you work with the agent on a single task. Every message, agent turn, and tool call in that conversation belongs to the Session. A Session can be private to you or shared with your organization — see [Share a session](#share-a-session). You can open Cosmos at [cosmos.augmentcode.com](https://cosmos.augmentcode.com) in any browser, including the one on your phone; there is no separate iOS or Android app. You can also work with a Session from Slack when your administrator has connected Slack under **Settings** → **Integrations** and the Expert you're using supports it. > **[Core concepts](/cosmos/getting-started)** > > How Experts, Environments, and Sessions fit together. > **[Environments](/cosmos/environments/overview)** > > The machine an Expert runs on during a Session. ## Start a session **1. Inside the sidebar** **New Session** creates a new conversation and **Sessions** allow you to see all current and archived Sessions. Once opened, Recent Sessions will appear here as well. All three sit at the top of the sidebar. **2. Start from Home** You can quickly start right from Home, first choose the Expert you want, and describe your task in the prompt box at the bottom of the page. **3. Revisit past Sessions** Select **Sessions** to see every Session you can access. Open one to pick up the conversation where you left off. ## Write and send a prompt Once inside the Session, the prompt box sits at the bottom of the window. Type your prompt in the input — it reads `Ask anything or type / for commands` when empty — and press **Enter**. Type `/` to run a slash command. > [!NOTE] > > While the agent is working you can keep typing. Your next message is queued and sent when the current turn finishes. ```text Example theme={null} Select: Cosmos Advisor Prompt: Help me create an Environment for a Ruby on Rails project. I want to use the Ruby 3.4 and Sqlite3. ``` ## Attach files and images Give the agent more context by attaching files or images to a prompt: * **Attach files**: select the attach control next to the composer and pick files from your machine. * **Drag and drop**: drop files or images onto the composer. * **Paste**: paste an image straight from your clipboard. Attached images appear as thumbnails below your text. Remove one by hovering it and selecting the remove control. > [!NOTE] > > You can attach up to 10 files and up to 10 images per message. Files can be any type, up to 4 MB each and 4 MB combined. Images can be up to 10 MB each, in PNG, JPEG, GIF, WEBP, HEIC, HEIF, or AVIF format. If an attachment is too large or unsupported, the composer shows an inline message and skips it. ## Enhance your prompt Select the **Enhance prompt** button — the sparkle icon next to the composer — or press **⌘E** (**Ctrl+E** on Windows and Linux) to rewrite a short prompt into a fuller one grounded in your conversation and codebase. The button stays disabled until you type something. Press **⌘Z** / **Ctrl+Z** to restore your original text. ## Pin a session Under Recent Sessions, you can click the three dot overflow menu or right click to Pin session. Pinning keeps a Session within reach at the top of the sidebar. Drag pinned Sessions to reorder them within the section. Just to the right of Pinned menu is a set of hover tools that allows you to create Folders to organize your pinned Sessions, Filter pinned Sessions, and collapse all open folders. > [!NOTE] > > Pinned Sessions are scoped to your account. They appear in your sidebar only — pinning a Session doesn't change what your teammates see. You can unpin Sessions using the same three dot overflow menu or right click to Unpin session. ## Session lifecycle A Session's conversation is saved indefinitely — it doesn't expire. Reopen it from the **Sessions** page at any time to pick up where you left off. The Environment behind a Session is more short-lived. It pauses after a period of inactivity, and runs for up to 24 hours at a time. When you return to a paused Session and send a message, Cosmos restarts the Environment automatically — you don't need to resume it yourself — and the status shows it starting up. Your conversation is always preserved; if an Environment has been paused for a long time, it may restart from a clean state and lose uncommitted changes in its workspace. > [!NOTE] > > Sessions started by a trigger or automation may be archived automatically once the agent finishes its task. Archiving preserves the full conversation, so you can still open the Session later. > [!TIP] > > When a Session goes wrong — it fails, stalls mid-run, or produces a bad result — ask [Cosmos Advisor](/cosmos/advisor/overview) to diagnose it. The Advisor reads the Session data and identifies the root cause, such as missing authentication, an unconnected integration, or a missing capability or Environment setup, and points you at the fix. ## Share a session Every Session has a visibility: * **Shared** — everyone in your organization can open it. * **Private** — only you can open it. Private Sessions show a lock badge. The default depends on how the Session started: Sessions launched from an Expert that's shared with your organization, or by a trigger or automation, default to **Shared**, while Sessions launched from a personal Expert default to **Private**. To give specific teammates access, open the Session and select **Share** in the Session header. From the Share dialog you can search for a teammate, grant them viewer access, copy a link to the Session, and revoke access later. Sharing with individual teammates is available to the Session's owner. # Software Factory Source: https://docs.augmentcode.com/cosmos/software-factory/overview Connect planning, implementation, review, and feedback into a repeatable delivery workflow with Cosmos. Prompting an agent and supplying context at every step of the software development lifecycle (SDLC) leaves people coordinating each handoff. As code generation speeds up, that manual coordination becomes a bottleneck. A software factory connects specialized agents into repeatable workflows, so work moves forward without a new prompt at every step. ## The full flow ![Software Factory loop: Requirements to Ticket feeds Ticket to PR. PR to Merge connects Draft PR to Merged PR, then CI/CD leads to Production. Signal to Ticket brings production feedback back into the loop.](https://mintcdn.com/augment-mtje7p526w/jIa3R_I0BLxWwTsz/images/software-factory-loop.svg?fit=max\&auto=format\&n=jIa3R_I0BLxWwTsz\&q=85\&s=0e40ef25d0644e364243325adac1595a) Cosmos [Experts](/cosmos/experts) are specialized agents that drive work across the SDLC, from requirements to production. They bring in humans for judgment calls: approving scope, reviewing architecture, and performing the final merge. Your existing CI/CD pipeline deploys merged changes to production. Feedback and incidents feed the next round of work when follow-up is needed. ## Explore the four loops > **[Requirements → Ticket](/cosmos/software-factory/requirements-to-ticket)** > > Turn feature requirements into a reviewed design and actionable tickets. > **[Ticket → PR](/cosmos/software-factory/ticket-to-pr)** > > Implement a delegated ticket and open a draft PR for review. > **[PR → Merge](/cosmos/software-factory/pr-to-merge)** > > Review, repair, and verify a change before your team merges it. > **[Signal → Ticket](/cosmos/software-factory/signal-to-ticket)** > > Investigate feedback and incidents, and decide what follow-up work is needed. Each guide covers the relevant Experts, human checkpoints, and setup steps. ## Where to start Start with the loop that bottlenecks your team's throughput, or ask [Cosmos Advisor](/cosmos/advisor/overview) to help you choose and configure it. You don't need to set up the entire factory at once. # PR → Merge Source: https://docs.augmentcode.com/cosmos/software-factory/pr-to-merge Review and repair changes before a human merges them. ## How it works Mark the PR or MR ready for review. Review Experts analyze the change. If changes are needed, PR Author or PR Fixer handles fixes allowed by your settings or requested by you. The updated change is checked again before you decide whether to merge. ```mermaid theme={null} flowchart TD ready["👤 Human: mark the PR ready for review"] --> checks["🤖 Review Experts
• Risk Analyzer
• Pair Reviewer
• Deep Reviewer
• Verifier (when configured)"] checks --> decision["👤 Human: review the results"] decision -->|Ready| merge["👤 Human: merge"] checks -->|Automatic fixes allowed| fix["🤖 PR Author or PR Fixer
makes changes"] decision -->|Changes needed| fix fix -->|Check again| checks classDef agent fill:#e8f0fa,stroke:#315d83,color:#173753; classDef human fill:#fff7ed,stroke:#c2410c,color:#7c2d12; class checks,fix agent; class ready,decision,merge human; ``` Reviewers work independently, not in a fixed sequence. When configured, Verifier also tests the running behavior. The dashboard gathers their findings and test results in one place; your team makes the final merge decision. ## Where you participate * **Choose automatic fixing and approval settings.** Decide which feedback, CI failures, and conflicts Experts may fix, and whether low-risk changes can be approved automatically. * **Review the evidence.** Inspect findings, repairs, and verification gaps. Authorize Pair Reviewer before it posts comments or a verdict during interactive review. * **Make the final merge.** Agent approval is not a merge. A human decides and performs it. ## Template Experts * [Risk Analyzer](/cosmos/experts-risk-analyzer): assesses risk against your approval policy. * [Deep Reviewer](/cosmos/experts-deep-reviewer): finds correctness defects and repository-guideline violations. * [Pair Reviewer](/cosmos/experts-pair-reviewer): helps a person review architecture, context, and tradeoffs. * [PR Fixer](/cosmos/experts-pr-fixer) / existing [PR Author](/cosmos/experts-pr-author): repairs findings, failing checks, and conflicts. Author maintains its own changes; Fixer handles others. * [Verifier](/cosmos/experts-verifier): exercises behavior and records evidence and limitations. * [PR Dashboard Manager](/cosmos/experts-code-review#pr-dashboard-manager): summarizes status, reviewed commits, and evidence. * [Code Review Memory](/cosmos/experts-code-review-memory): captures reusable guidance from reviews and human feedback. ## Set it up 1. **Connect your code host and repository.** Prepare an Environment with repository access and test tools. 2. **Configure selected components with [Cosmos Advisor](/cosmos/advisor/overview).** Check **Automatic Fixing** and **Auto-approval & Pair Review**; see the [full pipeline guide](/cosmos/experts-code-review) for details. Enable runtime verification only when a runnable environment, test access, and instructions are ready. 3. **Complete setup and approve activation.** Open a PR or MR ready for review, or mark a draft ready. Inspect the dashboard and [automation run history](/cosmos/manage-automations) for findings and requests for human input. Example Advisor prompt: > Set up PR-to-Merge for \[code host]. Help me choose review, fixing, and verification settings. ## Next step Continue with [Signal → Ticket](/cosmos/software-factory/signal-to-ticket) to turn feedback and incidents into the next work. ## Further reading * [Optimizing the path from PR to merge](https://www.augmentcode.com/blog/optimizing-pr-to-merge-loop) * [The bottleneck moved to verification, so we automated that too](https://www.augmentcode.com/blog/the-bottleneck-moved-to-verification-so-we-automated-that-too) # Requirements → Ticket Source: https://docs.augmentcode.com/cosmos/software-factory/requirements-to-ticket Turn feature requirements into a reviewed design and actionable tickets. ## How it works [Project Builder](/cosmos/experts-project-builder) is an [Expert](/cosmos/experts), a specialized agent. Give it a feature brief, mockup, existing ticket, or rough design. It researches the relevant code and drafts a design for your review. On request, it breaks the reviewed design into ordered tickets with dependencies. The diagram shows the **ticketed path**: ```mermaid theme={null} flowchart TD brief["👤 Human: provide a feature brief"] --> design["🤖 Project Builder: research and draft a design"] design --> review["👤 Human: review scope and architecture"] review -->|Revise| design review -->|Approve design and request tickets| tickets["🤖 Project Builder: create ordered tickets"] tickets --> authorize["👤 Human: authorize implementation"] authorize --> next["Ticket → PR"] classDef human fill:#fff7ed,stroke:#c2410c,color:#7c2d12; class brief,review,authorize human; ``` Ticket creation is optional. When you request implementation, Project Builder delegates the work to PR Author workers and coordinates delivery. ## Where you participate * **Define the outcome.** Provide the problem, success criteria, constraints, and what is out of scope. * **Review the design.** You decide scope and architecture; the Expert researches options and explains tradeoffs. Resolve open questions before handing work off. * **Choose the next step.** Ask for tickets, implementation, or both. A design request alone is not permission to change code. ## Template Experts * [Project Builder](/cosmos/experts-project-builder) researches, drafts designs, and breaks work into tickets; it can also coordinate delivery when requested. * [PR Author](/cosmos/experts-pr-author) implements and tests work you hand off after planning. ## Set it up 1. **Connect your tools.** Connect your code host and, for ticket creation, your tracker. Provide access to the relevant repositories and product context. 2. **Ask [Cosmos Advisor](/cosmos/advisor/overview) to configure Project Builder.** Tell it which code host and ticket tracker you use. 3. **Start Project Builder with a feature brief.** Review its design and open questions, then decide whether to request tickets or implementation. Example Advisor prompt: > Set up Project Builder for \[code host] and \[ticket tracker] to turn feature requirements into designs and tickets. ## Next step Use [Ticket → PR](/cosmos/software-factory/ticket-to-pr) to turn approved work into a draft change for review. Already have a clear ticket? Start there directly. ## Further reading * [Accelerating large engineering projects with Cosmos](https://www.augmentcode.com/blog/accelerating-large-engineering-projects-with-cosmos) * [How we built Augment's software factory](https://www.augmentcode.com/blog/beyond-ai-coding-agents-how-we-built-augments-software-factory) * [Software Factories in September 2026](https://igoro.com/archive/software-factories/) # Signal → Ticket Source: https://docs.augmentcode.com/cosmos/software-factory/signal-to-ticket Turn feedback and incident findings into actionable follow-up. ## How it works The ready-made **Feedback Triager** uses Slack: it responds to new top-level messages in a configured channel, investigates reports, checks for duplicates, and follows the thread. It creates tickets automatically when quality checks pass, or only on request, according to your settings. Otherwise, it answers or asks for missing evidence. This diagram shows the **Slack setup**: ```mermaid theme={null} flowchart TD feedback["👤 Human: post a top-level Slack report"] --> triager["🤖 Triager: investigate and check duplicates"] triager -->|Ready; automatic mode| ticket["Ticket"] triager -->|Ready; on-request mode| request["👤 Human: request ticket creation"] request --> ticket triager -->|No ticket needed or more evidence needed| answer["🤖 Triager: answer or request evidence"] classDef human fill:#fff7ed,stroke:#c2410c,color:#7c2d12; class feedback,request human; ``` **Incident Investigator** supports two Slack-based modes: **alert-thread mode** investigates new reports in configured alert channels, and **stationed-channel mode** follows an incident channel. In both modes, code fixes require explicit human approval before it launches PR Author; ticket creation is not automatic. ## Where you participate * **Choose the filing policy.** Select automatic or on-request tickets, the tracker destination, and routing rules. * **Provide context.** Supply expected behavior, a reproduction, and missing evidence. Review findings separately from hypotheses. * **Authorize implementation.** Explicitly request a specific code fix or delegate a ticket. Ticket creation alone is not approval to implement. Investigation does not authorize production changes. ## Template Experts * [Feedback Triager](/cosmos/experts-feedback-triager): investigates Slack feedback and files in Linear, Jira, or GitHub Issues under your policy; it does not edit code. * [Incident Investigator](/cosmos/experts-incident-investigator): provides incident findings, recommended actions, and follow-up. * [PR Author](/cosmos/experts-pr-author): implements a human-requested fix and carries it into review. * [Ticket Manager](/cosmos/experts-ticket-manager): coordinates work explicitly delegated from the tracker. ## Set it up For the ready-made Slack setup: 1. **Connect Slack, your tracker, and code host.** Make sure the Slack app can access the channel and the Experts can access your repository and evidence sources. 2. **Configure [Feedback Triager with Cosmos Advisor](/cosmos/advisor/overview).** Advisor configures the channel, ticket destination, filing policy, repository, and required Author worker. That worker still needs your request before starting a fix. 3. **Complete setup and approve activation.** Post a top-level report in the configured channel. Inspect the thread and [automation run history](/cosmos/manage-automations) for evidence, duplicate handling, and the next step. Example Advisor prompt: > Set up Feedback Triager for \[Slack channel] and \[ticket tracker]. Create tickets \[automatically / only when requested]. ## Next step Delegate ready work to [Ticket → PR](/cosmos/software-factory/ticket-to-pr), or take broader needs to [Requirements → Ticket](/cosmos/software-factory/requirements-to-ticket). Code fixes continue through [PR → Merge](/cosmos/software-factory/pr-to-merge). ## Further reading * [Feedback triage with Cosmos](https://www.augmentcode.com/blog/feedback-triage-with-cosmos) * [Scaling incident management with Cosmos](https://www.augmentcode.com/blog/scaling-incident-management-for-an-ai-native-organization-using-cosmos) * [Why bug fixing is the least important part of a bug-fixing software factory](https://igoro.com/archive/bug-fixing-software-factory/) # Ticket → PR Source: https://docs.augmentcode.com/cosmos/software-factory/ticket-to-pr Turn a delegated ticket into a draft PR with Ticket Manager and PR Author. ## How it works Start by delegating a ticket to Cosmos through the connected Linear agent, or by adding the configured delegation label in Jira or GitHub Issues. Ticket Manager checks the problem, desired outcome, scope, and target repositories. If a specification is needed, it drafts one and waits for your explicit approval. Clear, bounded work can proceed without a specification. Once the ticket is ready, PR Author implements the change, runs checks, and opens a **draft** linked to the ticket. ```mermaid theme={null} flowchart TD ticket["👤 Human: delegate a ticket"] --> manager["🤖 Ticket Manager: check readiness"] manager -->|Specification needed| spec["🤖 Ticket Manager: draft a specification"] spec --> approval["👤 Human: review and approve specification"] approval --> manager manager -->|Ready| author["🤖 PR Author: implement, test, and open a draft"] author --> review["👤 Human: review draft and mark ready for review"] review -->|PR → Merge| next["Merged PR"] classDef human fill:#fff7ed,stroke:#c2410c,color:#7c2d12; class ticket,approval,review human; ``` You can also start PR Author directly with a task; if it needs a specification, your explicit approval is still required before implementation. ## Where you participate * **Provide scope.** Describe expected behavior, acceptance criteria, constraints, and relevant evidence. * **Approve a required specification.** Resolve open product questions and confirm what should be built. * **Review the draft and mark it ready for review.** Inspect the change, test results, and limitations; successful CI does not publish the draft or mark it ready. ## Template Experts * [Ticket Manager](/cosmos/experts-ticket-manager) checks readiness, delegates implementation, and keeps the ticket updated. * [PR Author](/cosmos/experts-pr-author) implements, tests, opens a draft, and handles review feedback, failing checks, and merge conflicts. * [Project Builder](/cosmos/experts-project-builder) helps when a larger requirement needs design or a ticket breakdown first. ## Set it up 1. **Connect your code host and tracker.** Follow the [Ticket Manager setup guide](/cosmos/experts-ticket-manager) for connector and tracker-specific delegation instructions. 2. **Complete setup with [Cosmos Advisor](/cosmos/advisor/overview).** Approve activation when prompted and confirm the automation is enabled. 3. **Delegate a ready ticket.** Use the configured delegation label or connected Linear agent. Follow the ticket's updates to the draft and review the result. Example Advisor prompt: > Set up Ticket Manager for \[ticket tracker] with code in \[code host]. Show me how to delegate tickets. ## Next step Continue with [PR → Merge](/cosmos/software-factory/pr-to-merge) for review and follow-up. ## Further reading * [How we built Augment's software factory](https://www.augmentcode.com/blog/beyond-ai-coding-agents-how-we-built-augments-software-factory) * [Why bug fixing is the least important part of a bug-fixing software factory](https://igoro.com/archive/bug-fixing-software-factory/) # Managing Spaces Source: https://docs.augmentcode.com/cosmos/spaces/managing Switch between Spaces, create new ones, assign experts and environments, and control who can manage them. Use the **Space picker** at the top-left of the Cosmos sidebar to switch the current Space, create new ones, and search across them. Your selection persists, and it drives which Space new experts, environments, and sessions default into. ## Switch Spaces **1. Open the Space picker** Click the Cosmos button in the sidebar to view all the Spaces for your organization. **2. Choose a Space** Select the Default space or any named Space. **3. Work within the Space** Only the sessions, experts, environments, secrets, and MCP servers that belong to that Space are available. ## Search through Spaces As your organization grows, use the search field at the top of the Space picker to filter the list. The list narrows as you type. Press **Enter** to select the first visible match. ## Create a Space Open the Space picker, type a name, and press **Enter**. The new Space becomes the current selection, and the **Create expert** and **Create environment** forms will default new resources into it. Space names must be unique within your organization. Creating a Space is open to any member of your organization, and the creator becomes the Space's owner. ## Assign resources to a Space **Experts and environments** default into the currently-selected Space when you create them, and the create form lets you override that choice. Once assigned, expert and environment cards show a Space pill so you can see where each one lives. You can move a resource by clearing or changing its Space assignment; leaving it unassigned returns it to the Default space. **Sessions** are assigned to a Space automatically when they start. Cosmos resolves a session's Space using the following order of precedence: 1. **Manager's Space**: a worker launched by a manager agent inherits the manager's Space, so an entire worker subtree stays together. 2. **Expert's Space**: the Space the launching expert is pinned to. 3. **Selected Space**: the Space selected when the session was launched, such as in the home-page launcher. 4. **Daemon's Space**: for daemon-routed sessions, the Space declared by the daemon. If none of these applies, the session isn't scoped to a named Space and lives in the Default space. > [!NOTE] > > An expert's pinned Space wins over the Space you have selected at launch. If an expert is pinned to a different Space, launching it from another Space still runs the session in the expert's Space. ## Delete a Space Deleting a Space does **not** delete the resources inside it. When you delete a Space, its experts, environments, projects, daemon pools, sessions, secrets, and MCP servers are **reassigned**, either to another Space you choose or to the Default space. Webhooks are the exception: they return to the Default-space view rather than being reassigned. Before you confirm, the webapp shows a preview of what will be affected, counting the live resources still associated with the Space. Terminated, completed, and archived sessions are not counted. ## Permissions * **Creating** a Space is open to any member of your organization. The creator becomes the Space's owner. * **Renaming, deleting, setting defaults, and changing membership** require an organization admin, or ownership (or the equivalent permission) on the Space and the resource being changed. All Space operations apply only within your own organization. # Cosmos Spaces Source: https://docs.augmentcode.com/cosmos/spaces/overview Spaces group the experts, environments, sessions, and settings for a team or workstream so everyone works from a shared, focused set of resources. ## About spaces A **Space** is a grouping of the experts, environments, sessions, secrets, and integrations your team uses in Cosmos. Each Space is a dedicated area of Cosmos for one team or workstream, showing resources associated with it that you have permission to access. Most organizations create one Space per team, such as Engineering, Data Science, Marketing, DevOps, IT, or Design. Each team can organize its experts and environments, configure secrets for its work, and set sensible defaults for new sessions, without the clutter of every other team's resources. Switching Spaces changes your working context, but **Space membership is not an access grant**. Resource access controls determine who may use a resource; secret applicability determines where a secret is selected. Resources configured for all Spaces can be available across teams, subject to their access controls. ## What belongs to a Space A Space can group most of the resources you configure in Cosmos: | Resource | In a Space | | - | - | | **Experts** | The agents your team runs, pinned to the Space so launches stay in context. | | **Environments** | Cloud environments and daemon pools available for the Space's sessions. | | **Sessions** | Interactive and automation sessions started while the Space is selected. | | **Secrets** | Values whose **Used in** coverage includes the Space; the session must also have use access. | | **MCP servers** | Configurations associated with the Space, subject to their own access grants. | | **Webhooks** | Inbound webhooks that trigger work within the Space. | | **Projects** | Project groupings associated with the Space. | A Space also shows how many experts and environments belong to it, so you can see at a glance how much each team has configured. ## Access and Secret Applicability To make an MCP server and its referenced generic secret usable by a teammate, check both resources: * **MCP access:** use **Manage access** to grant the intended recipients **Can use**, or **Everyone → Can use** for organization-wide access. * **Secret access:** separately grant appropriate use access on the referenced secret. Sharing the MCP configuration is not a substitute for configuring the secret's permissions. * **Secret applicability:** check **Used in**. **Scoped access** selects target Spaces; **Organization-wide** covers every current and future Space. A personal secret's **Every Space** coverage still applies only to its owner's sessions. Access grants do not change secret applicability, and selecting a Space does not grant access. For environment-variable injection, auto-install must also be enabled. Validate changes in a **fresh session in the target Space as the intended recipient**, without printing credential values. See [MCP sharing](/cosmos/config-mcp#sharing-an-mcp-server) and [Managing Secrets](/cosmos/config-secrets#access-and-applicability) for the complete flow. ## The Default space Every organization has a **Default space**. Resources with no Space assignment generally appear there; explicit all-Spaces settings and secret applicability are handled separately. It always exists, and it can't be renamed or deleted. Until you create a named Space, every expert, environment, and session lives in the Default space. You can start there and add named Spaces to organize your work as your team grows. ## When to use spaces Use Spaces when more than one team or workstream shares a Cosmos organization and you want to: * **Keep surfaces focused**: organize experts, environments, and sessions by team instead of browsing a shared, crowded list. * **Separate configuration**: select where secrets and MCP servers apply, and grant resource access independently. * **Set team defaults**: a Space can define a default expert and default environment, so new sessions started in that Space begin with the right setup. A single team getting started can stay in the Default space. As you add more teams, create a Space for each one. Read more about [managing spaces](/cosmos/spaces/managing) to switch, create, assign resources, and manage access. # Understanding Files Source: https://docs.augmentcode.com/cosmos/understanding-files Files persist across Expert Sessions — how Experts produce them, how they sync, and how you browse files and folders in Cosmos. **Files** is the storage layer Experts use between Sessions. Anything written there outlives the VM, shows up again in the next Session, and — if you scope it that way — is readable by your whole org. ## Scopes Files are scoped two ways: * **User** — private to you. Only your Sessions can read or write them. * **Organization** — shared with everyone in your organization. The right place for team knowledge and outputs an Expert wants to hand off to another Expert. ## How Experts Create Files You don't upload files yourself. Experts produce files as a side effect of doing their work, using the same file tools they use everywhere else. There is no special API or tool — an Expert writes to a path under the **User** or **Organization** scope and the sync layer takes care of the rest. Typical patterns: * A **research Expert** writes notes to `user/notes/.md` so the next Session can read them. * A **code-review Expert** writes a per-PR summary to `organization/pr-reviews//.md`. The next reviewer (human or agent) starts with that context already in front of them. * A **triage Expert** appends one JSON record per incident to `organization/incidents/log.jsonl`, building up a queryable history over time. Sync happens automatically at turn boundaries — once an Expert finishes a turn, every file change it made is uploaded and visible to the next Session. To add, edit, or remove a file, ask an Expert to do it from a Session: * *"Save the contents of this message as `user/notes/sync-strategy.md`."* * *"Read `organization/pr-reviews/repo-x/142.md` and update the conclusion section."* * *"Delete every file under `user/scratch/` older than 30 days."* The Expert performs the change, the sync layer persists it at the end of the turn, and the new state shows up next time you refresh the matching Files page. ## Browsing Files You can inspect Files from inside Cosmos. ### The Files pages **Files** is a sidebar group with two entries — **Organization** and **User** — each opening its own tree at `/app/vfs/org` or `/app/vfs/user`. 1. Pick a scope from the sidebar to open its tree. 2. Expand folders to drill down. Each row shows the path, size, last-modified time, and the agent that last wrote the file. 3. Select a file to preview it inline (text files up to 1 MB). 4. Use the per-row **⋯** menu (or the inline icons in the file viewer) to **Copy path**, **Copy content**, or **Download**. ### The Files tab inside a Session Open any cloud Session and switch to the **Files** tab in the right sidebar. Same tree and preview, plus a third scope option: **Workspace** — the running VM's live workspace at `/workspace` for that Session. ## Versioning and Recovery Every write to a file creates an immutable version snapshot. A buggy Expert cannot silently overwrite shared state without leaving a trail — every version is attributed to the agent that wrote it, and deletions are recorded as tombstones rather than erasures. Older versions are pruned on a time-decayed schedule: every version is kept for the first 15 minutes, then progressively thinned out as the file ages, with at least one version per week retained beyond 30 days. To restore an older version, ask an Expert in a Session to read the version you need and write it back as the current file. ## Limits * **1 MB** per file * **10,000** files per filesystem * **100 MB** total per filesystem * Writes that would exceed these limits are rejected at sync time ## Common Questions **My Expert wrote a file but I don't see it in the matching Files page.** File sync runs at turn boundaries. Wait for the Expert's current turn to finish, then refresh. **A teammate's Session wrote a file I need.** Open the **Organization** Files page. Files written there by any teammate's Expert are visible to everyone in the organization. ## Skills and Files Skills are a special category of file stored in the `.augment/skills/` directory within the Files system. They are discovered and loaded automatically by Experts, giving you a file-based way to manage reusable domain knowledge for your organization or personal use. * **Organization scope** — place skills under `cosmos/files/organization/.augment/skills/` to make them available to all users in your organization. * **User scope** — place skills under `cosmos/files/user/.augment/skills/` for personal, private skills. See [Skills](/cosmos/config-skills) for the full skill format and setup guide. ## See Also * [Skills](/cosmos/config-skills) — extend Experts with reusable knowledge packages stored in Files * [Configuring Cosmos](/cosmos/configuring-cosmos) — set up your Environment, Experts, and integrations # Delegating Work Source: https://docs.augmentcode.com/cosmos/workers-subagents The three ways a Cosmos Expert can hand off work — workers, subagents, and Expert-to-Expert interactions through integrations. ## Delegating Work Cosmos gives you three ways for one Expert to hand work off to another agent, letting a manager session keep coordinating the workflow while a specialized agent takes on a focused sub-task: * **Workers** — a manager Expert launches another **Expert** as a separate session with its own VM, Environment, integrations, and permissions. * **Subagents** — a session spins up a lightweight helper **agent** that shares the broader coding workflow but carries no Cosmos Expert configuration. * **Expert-to-Expert interactions** — two Experts coordinate indirectly through an integration they both work in, such as a pull request, rather than a direct launch. Reach for delegation when a workflow needs parallel or specialized execution — for example, Project Builder launching implementation workers, or PR Author responding to comments a reviewer Expert posts on its pull request. ## Why delegate work? The main reason to delegate is **focus**. In theory, one very broad Expert could try to do every task in a workflow. In practice, specialized Experts produce better results because the system prompt sets what the agent pays attention to. For example, PR Author is focused on building: implementing the requested change, opening the pull request or merge request, fixing CI failures, resolving merge conflicts, and driving the change toward merge. Deep Reviewer has a different focus — its prompt is tuned to be critical and catch bugs, asking whether an interface can be an attack vector, which inputs will crash the code, and what corner cases the implementation missed. Those are not the questions PR Author reasons about as thoroughly, because it is optimized for a different job. ## The three options at a glance | | **Worker** | **Subagent** | **Expert-to-Expert** | | - | - | - | - | | **What it is** | A separate Expert, launched as its own session | A lightweight helper agent inside the same workflow | Two Experts coordinating through a shared integration | | **Configuration surface** | Full Cosmos Expert: own Environment, integrations, permissions | Own prompt, context, and model — but no Expert config | Each is a full Expert; they never launch each other | | **Scope** | Organization or [Space](/cosmos/spaces) | Repo | Wherever the shared integration reaches | | **Coordination surface** | Manager ↔ worker messages | Manager ↔ subagent, in-session | The integration itself (e.g. PR comments) | | **Weight** | Heavyweight | Lightweight | Loosely coupled, event-driven | | **Best when** | A sub-task needs its own Environment or side effects | Focused research, validation, or review in one codebase | Agents can hand off through events humans can inspect | All three share some traits: each delegated agent has its own context window, its own system prompt, can define its own model, and runs in parallel with the manager, reporting progress back. ## Workers A **worker is an Expert**. Because of that, a worker is more heavyweight: it runs as a separate Cosmos session with its own VM and Environment, can define its own integrations, and can take side-effecting actions — posting comments, creating tickets, writing to external systems — depending on its permissions. Workers are scoped to either the whole organization or the [Space](/cosmos/spaces) they belong to. Unlike subagents, a session should be **explicitly prompted about when to launch a worker**, because a worker is a separate session with its own runtime environment and external permissions — Cosmos does not launch one implicitly. Use a worker when: * The parent Expert should coordinate the workflow but not do every task itself. * A sub-task needs its own Environment, integrations, or external side effects. * Multiple independent tasks can run in parallel as separate Cosmos sessions. * You want a clear parent session that tracks delegated work. **Configuring workers.** An Expert can be given a fixed list of worker Experts or allowed to discover available Experts at runtime. Keep worker permissions narrow — the parent should only be able to launch workers that make sense for its workflow. See [Automations](/cosmos/automations#workers-and-automations) for how worker sessions appear alongside trigger-created sessions. ## Subagents A **subagent is just an agent** — the standard delegation concept used by many coding tools: a focused agent that helps with research, validation, implementation, or review inside the same broader coding workflow. It has its own prompt and context, but it does not carry a Cosmos Expert's configuration surface (no separate Environment, integrations, or permissions), and it is scoped to a repo. Sessions are generally prompted to use subagents as they see fit, rather than needing explicit per-launch instructions. See [Subagents](/cli/subagents) in the Auggie documentation for how they are configured and used. ## Expert-to-Expert interactions Experts do not always need a direct worker relationship to interact — they can communicate through the systems they already work in. Here, the integration itself becomes the shared coordination surface. For example, PR Author creates a pull request. Deep Reviewer is triggered by the pull-request-created event, analyzes the change, and posts review comments. PR Author subscribes to events on that pull request, including newly posted comments, and responds to the review feedback. For a pull request created without PR Author, a human can start PR Fixer with the URL or comment `cosmos fix`. No Expert launches another; the pull request is the medium. This pattern is often conceptually simpler than workers, and it keeps humans in the loop: because the coordination happens in an integration, people can inspect the interaction between agents — for example, by reading the pull request comments — and intervene whenever they want. ## Choosing between them For Cosmos, **prefer Experts over subagents** when delegation is needed — whether as workers or through Expert-to-Expert interactions. An Expert is more natively supported in Cosmos: each one is a real session you can open in the browser, inspect in depth, and reason about independently. That said, delegate carefully. Worker orchestration can get complicated for the same reasons multi-threading is: coordination, complex interleavings, data races, deadlocks, and unclear ownership. Prefer a single Expert when the whole workflow fits in one context window. If delegation is necessary, prefer one or two workers with clean handoff boundaries — or an Expert-to-Expert interaction where the integration is the coordination surface. # Images from a private registry Source: https://docs.augmentcode.com/guides/import-images-from-private-registry Use a private AWS ECR image as Cosmos environment base image using static AWS IAM credentials or a AWS IAM role with a OIDC identity provider like Okta. # Introduction You can use a container image from a private registry as the base image for a [Cosmos cloud environment](/cosmos/environments/cloud). Store a registry credential in Cosmos, then select it when creating the environment. Cosmos uses the credential to authenticate and pull the image during the build; it is not automatically installed as an environment variable inside your session. This guide covers two ways to authenticate to AWS ECR (Elastic Container Registry): * **Static IAM credentials:** an AWS access key ID and secret. * **OIDC (recommended):** credentials for your identity provider that Cosmos exchanges for temporary AWS credentials through an IAM role. This avoids storing long-lived AWS IAM access keys, but still requires an identity-provider client secret > [!NOTE] > > Cosmos plans to eventually add support for private key for the OIDC client - stay tuned. # Before you begin * Have an image in a **private ECR repository**, with the dependencies required by Cosmos, including `bash` and `git`. * Copy the full image URI from ECR, including an **existing tag**, for example `123456789012.dkr.ecr.us-east-1.amazonaws.com/my-environment:24.04`. Replace the example account, region, repository, and tag with your own values. Do not assume your repository has a `latest` tag. * Have permission to configure IAM and ECR, create a registry credential in Cosmos, and create a cloud environment. * Use the same AWS region in the registry credential and the image URI. * If using **OIDC authentication**, have permission to configure an OIDC-compliant identity provider. This guide uses [**Okta**](https://okta.com) as an example, with a custom authorization server and a machine-to-machine (M2M) OIDC client using the **client credentials** grant type. > [!NOTE] > > The OIDC sign-in option must be enabled for your organization. If **IAM role (OIDC client credentials)** is not shown, contact your Augment Solutions Architect. This guide uses **cloud** environments; ECR support for [self-hosted k8s environments](/cosmos/guides/self-hosted-k8s) depends on your organization's configuration. # Import from AWS ECR using static IAM credentials ## 1. Grant read-only access to the repository Create a dedicated IAM user for image pulls, or use an existing identity approved by your AWS administrator. Attach an IAM permissions policy with the following access, replacing the repository ARN with your own: ```json wrap theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ecr:GetAuthorizationToken", "Resource": "*" }, { "Effect": "Allow", "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer", "ecr:BatchCheckLayerAvailability" ], "Resource": "arn:aws:ecr:us-east-1:123456789012:repository/my-environment" } ] } ``` `ecr:GetAuthorizationToken` requires `Resource: "*"`. Restrict the image and layer permissions to the repositories you need; push or administrator permissions are not required. For a cross-account repository, its repository policy must also allow the IAM identity to pull images. See [AWS ECR repository policies](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policy-examples.html). Create an access key for this IAM user and store it securely. Use the AWS access key pair, not a Docker username/password or a manually generated ECR login token. ## 2. Save the registry credential in Cosmos Open [cosmos.augmentcode.com](https://cosmos.augmentcode.com) → **Settings → Registry Credentials**, then select **Add a credential**. | Field | Value | | - | - | | **Name** | A descriptive name, such as `ecr-image-pull`. Use letters, numbers, underscores, or hyphens. | | **Registry type** | **AWS ECR** | | **Sign-in method**, if shown | **Access keys** | | **Access key ID** | Your IAM user's access key ID. | | **Secret access key** | The matching secret access key, entered directly in the secure form. | | **Region** | The region containing your ECR image, such as `us-east-1`. | Choose the available personal or shared access and Space settings so the intended environment creator can use the credential, then select **Create credential**. > [!NOTE] > > Saving a registry credential stores its configuration. It does **not** contact ECR or try to fetch `latest` (or any other tag), and does not prove that the credential can pull an image. Keep the key valid for future image builds, and rotate it according to your organization's policy. Continue to [Create the environment from the private image](#create-the-environment-from-the-private-image). # Import from AWS ECR using OIDC (recommended) With this method, Cosmos: 1. Requests an OAuth **access token** from your identity provider using the `client_credentials` grant. 2. Passes that access token to AWS STS `AssumeRoleWithWebIdentity` to obtain temporary IAM role credentials. 3. Uses those credentials to request an ECR authorization token and pull the image. Cosmos uses the token response's `access_token`, not an `id_token`. Your identity provider must issue a signed JWT access token that AWS STS accepts for web-identity federation. An opaque access token is not sufficient. This guide uses [**Okta**](https://okta.com) as an example of identity provider. ## 1. Configure your identity provider (Okta) Configure three separate objects in Okta: an **API Services application** (the machine-to-machine client), a **custom authorization server** (the token issuer), and an **access policy with a rule** that allows this client to request tokens. Creating the application alone does not authorize it to use the server. > [!NOTE] > > Your Okta organization must support custom authorization servers and the Client Credentials grant. API Access Management is required for custom authorization servers in production, and Client Credentials availability can depend on your Okta subscription. If the options below are missing, ask your Okta administrator to confirm availability. See [Okta's authorization-server guide](https://developer.okta.com/docs/guides/customize-authz-server/main/) and [access-policy requirements](https://help.okta.com/en-us/Content/Topics/Security/api-config-access-policies.htm). ### 1.1. Create the machine-to-machine application 1. Sign in to your organization's **Okta Admin Console** and open the **Applications** page. 2. Select **Create App Integration**. If the new integration wizard does not offer **API Services**, select **Classic experience**, as described in [Okta's Client Credentials setup guide](https://developer.okta.com/docs/guides/implement-grant-type/clientcreds/main/#set-up-your-app). 3. Choose **API Services** as the sign-in method, then select **Next**. Do not choose a browser-based web or single-page application: this flow has no interactive user sign-in or redirect URI. 4. Enter an application name, such as `Cosmos M2M - AWS ECR`, then select **Save**. 5. On the application's **General** tab, locate **Client Credentials**. Record the **Client ID** and store the **Client secret** securely for entry into Cosmos later. If grant types are editable, ensure **Client Credentials** is enabled. 6. Use **Client secret** authentication with the token-endpoint method **`client_secret_basic`**. Cosmos sends the client ID and secret in an HTTP Basic header, not in the request body. Do not configure this application to require a private-key JWT instead. See [Okta's client authentication methods](https://developer.okta.com/docs/api/openapi/okta-oauth/guides/client-auth). You M2M app should look like this: ![Screenshot 2026 10 22 At 4 49 32 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-4.49.32-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=14a9076824ddc85d1b27765ad879a2f6) You do not need to assign end users or grant Okta management API scopes for this image-pull flow. The next steps authorize this application against your custom server. ### 1.2. Create a custom authorization server 1. In the Okta Admin Console, open **Security → API → Authorization Servers**. 2. Select **Add Authorization Server**. 3. Enter a **Name**, such as `Cosmos AWS ECR`, and a **Description** explaining that the server issues tokens for private ECR image pulls. 4. Set **Audience** to `aws-ecr` for this guide's example. This is the audience issued in the access token; keep it consistent with the AWS OIDC provider and IAM trust policy configured below. If your organization requires a different audience, replace the example consistently throughout the setup. 5. Select **Save**. On the server's **Settings** tab, record its **Issuer** URL, including the `/oauth2/` path. 6. Open the server's **Metadata URI**, or its issuer URL followed by `/.well-known/openid-configuration`. Record the returned `issuer` and `token_endpoint` values. Use this exact HTTPS token endpoint in Cosmos; do not use a URL that redirects. > [!WARNING] > > Use a **custom** authorization server, not the org authorization server at the bare Okta domain. Your AuthZ server Settings tab should look like this: ![Screenshot 2026 10 22 At 4 55 02 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-4.55.02-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=c4dba8656613e761c3d2a02748ac3350) ### 1.3. Add the custom scope 1. On your custom authorization server, select **Scopes → Add Scope**. 2. Set **Name** to `fetch-image`. Enter a display phrase and description, such as `Pull private ECR images`. 3. Leave **Require user consent for this scope** unselected: client credentials requests have no user to provide consent. 4. Leave **Set as a default scope** unselected for this example; you will explicitly set `fetch-image` in Cosmos. 5. Select **Create**. Do not request `openid`, `profile`, or other user-oriented OpenID scopes for this machine-to-machine flow. The custom scope lets Okta authorize token issuance; the IAM permissions policy, not this scope, grants access to ECR repositories. Your AuthZ server Scopes tab should look like this: ![Screenshot 2026 10 22 At 4 58 49 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-4.58.49-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=cea3418bfc45416001fe174d7a72ddfe) ### 1.4. Create the access policy and rule 1. On the same authorization server, select **Access Policies → Add Policy**. 2. Enter a **Name**, such as `Cosmos ECR client`, and a description. 3. Under **Assign to**, choose **The following clients** and select the `Cosmos M2M - AWS ECR` application created above. Do not choose **All clients** for this dedicated policy. 4. Select **Create Policy**. Open the new policy and select **Add Rule**. 5. Enter a **Rule Name**, such as `Allow client credentials`, and configure: | Rule setting | Value | | - | - | | **IF Grant type is** | **Client Credentials** only. Expand **Advanced** if needed to find the option. | | **AND User is**, if shown | **No user**. A rule that requires an assigned user does not match a client credentials request. | | **AND Scopes requested** | Select the specific scope `fetch-image`, rather than allowing any scope. | | **Access token lifetime** | A short lifetime approved by your organization, for example **1 hour**. | 6. Select **Create Rule**. Confirm that both the policy and its rule are active. 7. Review policy and rule order. Okta evaluates them in priority order and uses the first matching policy and rule. Your AuthZ server Access Policies tab should look like: ![Screenshot 2026 10 22 At 5 05 24 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-5.05.24-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=352ef0ac9527adf1605f51746c1d267d) The corresponding rule should look like: ![Screenshot 2026 10 22 At 5 07 52 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-5.07.52-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=09c434cee97302c53856b7703971173c) ### 1.5. Test the configuration with Token Preview Use Okta's **Token Preview** to check the application's grant type, scope, and expected access-token claims before making a real token request. 1. On the same authorization server → Click on the **Token Preview** tab. In **Request Properties**, configure: | Field | Value | | - | - | | **OAuth/OIDC client** | Select **Cosmos M2M - AWS ECR**. Type the application name to find it. | | **Grant type** | **Client Credentials**. | | **Scopes** | Select **fetch-image**. | 1. Select **Preview Token** and inspect the **Access Token** result, not an ID token. 2. Confirm that the preview succeeds, `iss` matches your custom authorization server's issuer, `aud` is `aws-ecr`, and `scp` includes `fetch-image`. Inspect `sub` and whether `azp` is present; verify their actual issued values in the next step before configuring AWS. Your token preview should look like: ![Screenshot 2026 10 22 At 5 10 09 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-5.10.09-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=76c97033892cf86f2f5e208a34ed506e) If the preview reports an error, check that the client and scope belong to this setup, the policy is assigned to **Cosmos M2M - AWS ECR**, and an active rule permits **Client Credentials** with **fetch-image**. Review policy and rule priority if the expected rule does not match. ### 1.6. Record the values and verify token issuance The following are example values, not values to copy unchanged:
Setting Example or source
Issuer URL `https://example.okta.com/oauth2/authorization-server-id`; copy your server's actual issuer.
Token URL `https://example.okta.com/oauth2/authorization-server-id/v1/token`; copy `token_endpoint` from your server's metadata.
Client ID and client secret From the **Client Credentials** section on the API Services application's **General** tab. Store the secret securely.
Authorization-server audience `aws-ecr`, configured on the server.
Custom scope `fetch-image`, configured on the server and allowed by the policy rule.
Before configuring AWS, run this curl request in a trusted local terminal. Replace the example URL with your authorization server's `token_endpoint` and `YOUR_CLIENT_ID` with the client ID of **Cosmos M2M - AWS ECR**: ```bash wrap theme={null} curl --request POST \ --url 'https://example.okta.com/oauth2/authorization-server-id/v1/token' \ --basic --user 'YOUR_CLIENT_ID' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=fetch-image' ``` When curl prompts for a password, enter the application's **client secret**. You should get this response: ```json wrap theme={null} { "token_type": "Bearer", "expires_in": 3600, "access_token": "XXXX.XXXX.XXXX", "scope": "fetch-image" } ``` ## 2. Register the issuer in AWS IAM In the AWS console, open **IAM → Identity providers → Add provider**, then choose **OpenID Connect**. * Set **Provider URL** to the token's exact `iss` value, including any authorization-server path. For the Okta example, use `https://example.okta.com/oauth2/authorization-server-id`, not just `https://example.okta.com` and not the `/v1/token` URL. * Set the AWS provider's **Audience** to the token's `aud` value. **If the token includes `azp`, AWS uses that value instead** for this check. * Create the provider in the same AWS account as the IAM role you will configure next. Your identity provider should look like this: ![Screenshot 2026 10 22 At 5 23 58 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-5.23.58-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=1bbeac0cdff80e3b8f24bd04473f2a23) ![Screenshot 2026 10 22 At 5 25 00 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-5.25.00-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=1c918897cda9a1b1158a93ee247a3f8e) ## 3. Create the IAM role and trust policy Create an IAM role, such as `OktaECRPullRole`. Attach the same repository-scoped **ECR permissions policy** shown in the [static IAM credentials section](#1-grant-read-only-access-to-the-repository). Separately, configure the role's **trust policy** to allow `sts:AssumeRoleWithWebIdentity` from your IAM OIDC provider. Restrict it to the expected audience and application subject. For the example issuer above, a trust policy is: ```json wrap theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/example.okta.com/oauth2/authorization-server-id" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "example.okta.com/oauth2/authorization-server-id:aud": "aws-ecr", "example.okta.com/oauth2/authorization-server-id:sub": "EXPECTED_APPLICATION_SUBJECT" } } } ] } ``` Replace the account ID, issuer host/path, audience, and subject with your own values. The provider ARN and condition-key prefixes include the issuer path but omit `https://`. This example assumes the token has **no `azp` claim**. If it has one, the `:aud` condition must match `azp`; AWS exposes the original `aud` as `:oaud`. Review [AWS's OIDC claim-to-condition mapping](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#condition-keys-wif) before adapting the policy. The trust policy controls **who can assume the role**; the attached permissions policy controls **which ECR images the role can pull**. Both are required. ## 4. Save the OIDC registry credential in Cosmos Open [cosmos.augmentcode.com](https://cosmos.augmentcode.com) → **Settings → Registry Credentials → Add a credential** and fill in:
Field Value
**Name** A descriptive name, such as `aws-ecr-oidc-pull`.
**Registry type** **AWS ECR**
**Sign-in method** **IAM role (OIDC client credentials)**
**Role ARN** Your role ARN, for example `arn:aws:iam::123456789012:role/OktaECRPullRole`.
**Token URL** Your identity provider's HTTPS token endpoint, for example `https://example.okta.com/oauth2/authorization-server-id/v1/token`
**Client ID** The machine-to-machine application's client ID.
**Client secret** The application's secret.
**Audience** Keep blank. Set only if your provider requires an `audience` parameter in the token request.
**Scope** The scope your provider requires; for the example above, `fetch-image`.
**Region** The region containing your ECR image, such as `us-east-1`.
Your Add registry credential view should look like: ![Screenshot 2026 10 22 At 5 43 14 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-5.43.14-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=6694ad1748b99b905067e6c2c576614f) Choose the appropriate access and Space settings, then select **Create credential**. Do not enter static AWS access keys for this method. > [!NOTE] > > **The Cosmos Audience field and the JWT audience are different settings.** Cosmos only sends an `audience` request parameter when this field is filled in. Leaving it blank does not mean the token has no `aud` claim. For the Okta custom-authorization-server example, configure `aws-ecr` on the authorization server and leave the Cosmos field blank if no request parameter is required. AWS must still accept the audience actually issued in the token, accounting for `azp` when present. # Create the environment from the private image After saving either a static IAM or OIDC registry credential, use these steps to create the environment: 1. Open [cosmos.augmentcode.com](https://cosmos.augmentcode.com) → **Settings → Environments**. 2. Select **Create an environment → Augment Cloud**. 3. Enter an environment name. 4. Under **Base image**, select **Private registry**. 5. In **Registry URL**, enter the complete ECR image URI, including its existing tag. Do not add `https://`. 6. In **Registry credential**, select the static IAM or OIDC credential you created. 7. Select **Create Environment** and wait for the build to finish successfully before starting a session. Your Create Environment view should look like: ![Screenshot 2026 10 22 At 5 58 06 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-5.58.06-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=59812187b7f83b08bc2d543b033966b1) The environment will build: ![Screenshot 2026 10 22 At 6 01 18 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-6.01.18-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=9a496342af410b8b0d497c049713990a) You should see this when created: ![Screenshot 2026 10 22 At 6 02 48 PM](https://mintcdn.com/augment-mtje7p526w/QpTEtdVcZkrEalR1/images/Screenshot-2026-10-22-at-6.02.48-PM.png?fit=max\&auto=format\&n=QpTEtdVcZkrEalR1\&q=85\&s=8f81afa11cc09fedea4879cf044039a1) The build is the check that Cosmos can authenticate, retrieve the selected image, and prepare the environment. A successful standalone IdP → STS → ECR test confirms authentication and image access, but does **not** verify a Cosmos environment build or that the image contains the required tools. Congrats, you've configured a cloud environment pulling a custom image from ECR! 🎉 ## Troubleshooting | Symptom | What to check | | - | - | | OIDC sign-in method is missing | The option must be enabled for your Augment tenant. Contact your Augment Solutions Architect. | | Token request fails | Confirm the client ID/secret, HTTP Basic authentication, allowed client-credentials grant, scope, and any provider-required audience parameter. Use the final publicly reachable HTTPS token URL; redirects and private-network endpoints are not supported. | | AWS reports no matching OIDC provider or an invalid token/audience | Match the complete issuer URL, including its path. Check AWS access to discovery/signing keys and the provider's accepted audience; account for `azp`. | | STS returns access denied | Check the role ARN and trust policy's provider, `sts:AssumeRoleWithWebIdentity` action, and exact audience/subject conditions. Do not substitute unsupported custom claims such as `scp`. | | ECR denies authentication or image access | Check `ecr:GetAuthorizationToken`, repository-scoped pull permissions, region, and any cross-account repository policy. | | Pull returns `MANIFEST_UNKNOWN` or image/tag not found | Confirm the repository and explicit tag exist. Successful authentication does not create a missing `latest` tag. | # Introduction Source: https://docs.augmentcode.com/introduction Augment Code is the AI-native coding platform built for enterprise-grade software engineering. Transform how you build and ship software with powerful coding agents, deep codebase intelligence, and flexible automations. ![Cosmos by Augment Code](https://mintcdn.com/augment-mtje7p526w/aEvQ6p7VacBQ05kr/images/cosmos.png?fit=max\&auto=format\&n=aEvQ6p7VacBQ05kr\&q=85\&s=c3a5bc3610859e2a95eb632c6fbc4c16) ## Get started in minutes > ![Cosmos](https://mintcdn.com/augment-mtje7p526w/aEvQ6p7VacBQ05kr/images/logo/cosmos-logo-black.svg?fit=max\&auto=format\&n=aEvQ6p7VacBQ05kr\&q=85\&s=6cdfa6e4ee42b0f061e75f355a4b19f9) > > ## Cosmos > > Combine custom triggers and specialized agents to build powerful software development automations. > > [Open](cosmos/getting-started) > ![Auggie CLI](https://mintcdn.com/augment-mtje7p526w/OQGzHw_wD-n9a1ch/images/cli.svg?fit=max\&auto=format\&n=OQGzHw_wD-n9a1ch\&q=85\&s=bdc9aed7bd4c71864560604d3d0b7f77) > > ## Auggie CLI > > All the power of Augment's agent, context engine, and tools in your terminal. > > [Open](/cli/overview) Looking for Augment for your favorite IDE? See documentation for [Visual Studio Code](setup-augment/install-visual-studio-code) or [JetBrains IDEs](jetbrains/setup-augment/install-jetbrains-ides). ## Automate your SDLC Cosmos ships with built-in experts that enable you to automate how you build, review, and ship code to production. > **[Code](cosmos/experts-pr-author)** > > Go from prompt to implementation, and handle follow-ups automatically. > **[Review](/cosmos/experts-code-review)** > > Automatically review every PR to catch critical bugs. > **[Other automation](cosmos/automations)** > > Run a specialized agent from a trigger or on schedule. # Docker Compose in cloud envs Source: https://docs.augmentcode.com/run-docker-compose-with-cloud-envs Configure a Cosmos cloud env to run docker compose commands # Introduction In this guide you'll configure a Cosmos cloud env to run docker compose commands, start a test instance of a given app and preview it via Cosmos tunnels. # Configuration Create a new env with support for Docker: [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > Settings > Environments > Create an environment > Augment Cloud: * Name - ex: `env01 (VM)` * Base image - keep the default image * Repositories - you can leave unselected for now and come back to it after completing this guide * Runtime - make sure to select **Virtual Machine** (=VM) * Refresh - toggle on Scheduled refresh * Click on Create environment Once your cloud env is created: [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New session > Select Cosmos Advisor > Select the env you created above > Submit this prompt: ```text theme={null} In the attached env, Install Docker + Docker Compose during the environment rebuild: #!/usr/bin/env bash set -euo pipefail apt-get update DEBIAN_FRONTEND=noninteractive apt-get install -y ca-certificates curl Add Docker's official GPG key: install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc chmod a+r /etc/apt/keyrings/docker.asc Add the repository to Apt sources: . /etc/os-release printf 'deb [arch=%s signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian %s stable\n' "((dpkg --print-architecture)" ")VERSION_CODENAME" > /etc/apt/sources.list.d/docker.list apt-get update Install Docker Engine AND Compose from Docker's official servers DEBIAN_FRONTEND=noninteractive apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin docker compose version find /var/lib/apt/lists -mindepth 1 -delete ========== Then start docker on every VM boot: #!/usr/bin/env bash set -euo pipefail rm -f /var/run/docker.pid nohup dockerd >/tmp/dockerd.log 2>&1 & for _in {1..30};do docker info >/dev/null 2>&1 &&exit 0 sleep 1 done cat /tmp/dockerd.log >&2;exit 1 ``` Note: in the thought process of the session, Cosmos Advisor created the corresponding provision and startup .sh scripts and applied them to the env: ![Screenshot 2026 10 19 At 11 14 48 AM](https://mintcdn.com/augment-mtje7p526w/whnxw0Pwkwaf6BZ5/images/Screenshot-2026-10-19-at-11.14.48-AM.png?fit=max\&auto=format\&n=whnxw0Pwkwaf6BZ5\&q=85\&s=c23374a3327685ec5669a227b4915700) The session should give you a confirmation when the env is updated: ![Screenshot 2026 10 19 At 11 17 07 AM](https://mintcdn.com/augment-mtje7p526w/whnxw0Pwkwaf6BZ5/images/Screenshot-2026-10-19-at-11.17.07-AM.png?fit=max\&auto=format\&n=whnxw0Pwkwaf6BZ5\&q=85\&s=11ebb070224d117f0604f95f2a62d619) # Run a test session Test a docker compose command with a simple repo: [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New session > Select the env you create above > Submit this prompt: ```text theme={null} deploy this app https://github.com/augment-solutions/docker-based-app ``` The session will run docker compose and offer to expose the app via a Augment authenticated url - select that option. Note on the right drawer the tunnel has been created (forwarding port 8080): ![Screenshot 2026 10 19 At 11 53 16 AM](https://mintcdn.com/augment-mtje7p526w/whnxw0Pwkwaf6BZ5/images/Screenshot-2026-10-19-at-11.53.16-AM.png?fit=max\&auto=format\&n=whnxw0Pwkwaf6BZ5\&q=85\&s=49a86bfb7012cc70fcf83629fe1fe1c8) If you click on "temporary preview is live" or the tunnel link in the right drawer, you'll see the app preview: ![Screenshot 2026 10 19 At 11 55 27 AM](https://mintcdn.com/augment-mtje7p526w/whnxw0Pwkwaf6BZ5/images/Screenshot-2026-10-19-at-11.55.27-AM.png?fit=max\&auto=format\&n=whnxw0Pwkwaf6BZ5\&q=85\&s=e3f2feb34cc724ae4e25ee8a87e1ee91) Congrats, your cloud env can now run docker compose! 🎉 You can run this cloud env to spin up a new test instance of your app, which is very helpful to run end2end tests as part of the [code producing loop (yellow)](/cosmos/guides/software-factory-core-loops) # Experts sharing instructions Source: https://docs.augmentcode.com/sharing-some-instructions-across-n-experts # Introduction In this guide, you will configure two Cosmos experts, each with its own specific instructions as well as a shared set of skills. # Configure two simple test experts Open [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > New session > Select Cosmos Advisor > Edit and submit this prompt: ```text wrap theme={null} Create 2 custom experts: hello1 and hello2. Those 2 experts should be sharing in common in their definition an include cosmos file that will contain a given firstname (ex: "nico"). When prompted, hello1 expert should reply hello1 + . When prompted, hello2 expert should reply hello2 + ``` The session will confirm when the experts are created: ```text wrap theme={null} Created hello1 and hello2. Both reference the same shared Cosmos file. nico is defined there only, and not hard-coded in either prompt. Saved definitions and include rendering verified. Try hello1 Try hello2 Any additional rules or skills to add? For skills, share the exact file location. ``` Open the hello1 expert definition > System Prompt, you should see: ![Screenshot 2026 10 20 At 3 20 51 PM](https://mintcdn.com/augment-mtje7p526w/1VUJBk6grX9XLELV/images/Screenshot-2026-10-20-at-3.20.51-PM.png?fit=max\&auto=format\&n=1VUJBk6grX9XLELV\&q=85\&s=1a0a8aa35daf74498af5d5e13e1d3359) Note that the hello1 expert has its own system prompt with hello1 specific instructions, and also includes a "Shared Firstname" vfs\:// file where the value of firstname is stored. > [!NOTE] > > VFS stands for Virtual File System, that's what powers Cosmos Files Open the hello2 expert definition > System Prompt, you should see: ![Screenshot 2026 10 20 At 3 25 22 PM](https://mintcdn.com/augment-mtje7p526w/1VUJBk6grX9XLELV/images/Screenshot-2026-10-20-at-3.25.22-PM.png?fit=max\&auto=format\&n=1VUJBk6grX9XLELV\&q=85\&s=fbaefd1b42e836d214dc5e5ca1f8c0bd) Like the hello1 expert, hello2 has its own system prompt with hello2 specific instructions, and includes the same "Shared Firstname" vfs\:// file where the value of firstname is stored. In the example above, the include url of the file is vfs\://org/experts/hello/shared-firstname.md, which should be read as: * The file resides in the **org** VFS * The file is tied to experts, corresponding path: /experts/hello/ * Filename: shared-firstname.md Open shared-firstname.md: [cosmos.augmentcode.com](https://cosmos.augmentcode.com) > Files > Select Organization > experts > hello > Click on shared-firstname.md ![Screenshot 2026 10 20 At 4 43 08 PM](https://mintcdn.com/augment-mtje7p526w/1VUJBk6grX9XLELV/images/Screenshot-2026-10-20-at-4.43.08-PM.png?fit=max\&auto=format\&n=1VUJBk6grX9XLELV\&q=85\&s=b27cbfc8b066a8d04bbb812fc14eb4dc) You can manually edit this file and change its content, however it's recommended to use Cosmos Advisor to verify and apply given sets of instructions. Congratulations, you've created your first custom experts sharing some centralized instructions! 🎉 # Bring over existing skills As you've deployed your software factory (see [101 - Getting Started On Cosmos](/cosmos/guides/getting-started-on-cosmos)), you'll be able to apply a similar approach to share instructions across your code producing experts. Make sure you specifically ask Cosmos Advisor to centralize given instructions and share them across given experts. If you have existing skills that you used pre-Cosmos that you'd like to bring over, attaching them to a session with Cosmos Advisor and asking Advisor its suggestion on how to bring them over is a good starting point. Your skills may be brought over as-is, or they may be simplified before they are brought over. Keep in mind that the Augment Context Engine automatically and continuously makes sense of your codebase, so you don't need to craft nor maintain skills for that. Cosmos Memory Manager automatically remember the human feedback on PRs so you don't have to. For your custom instructions and skills, focus on context that's not already in your codebase, and Cosmos Advisor will suggest how and where to put this context - this could be at the expert level, or as a Cosmos file included onto that expert. # Usage Dashboards & Budgets Source: https://docs.augmentcode.com/analytics/credit-dashboard-and-quotas Monitor usage and manage budgets across your organization. > [!NOTE] > > **Enterprise-Only Feature** > > Usage Dashboards and Budgets are available exclusively to Enterprise customers. > > Usage is shown in your organization's billing unit: dollars on [token-based pricing](/models/token-based-pricing), or credits on legacy credit-based Enterprise contracts. ## Overview Augment provides tools to monitor usage and manage budgets. This guide covers the Organization Usage dashboard for organization-wide monitoring, the My Usage dashboard for individual usage tracking, and the Budget system for controlling usage allocation. | Feature | Purpose | | - | - | | **Organization Usage Dashboard** | Monitor organization-wide and per-user usage with detailed model usage breakdowns | | **My Usage Dashboard** | View your own personal usage with model and daily breakdowns | | **Budgets** | Set monthly budgets at the organization and user level to control spending | ## Organization Usage The Organization Usage dashboard gives administrators visibility into usage across their organization. This feature is **available exclusively to Enterprise customers**. To access Organization Usage, visit [app.augmentcode.com](https://app.augmentcode.com) and navigate to **Organization Usage** in the sidebar. ### Date Filtering The entire dashboard supports filtering by date range. Use the date selector at the top of the page to view usage for a specific period. ### Summary Metrics The dashboard displays key metrics at the top: * **Usage Consumed** — Total usage in the selected time period * **Avg Usage / Day** — Daily average consumption to help forecast usage ### Model Usage Distribution A visual breakdown showing usage by AI model. You can filter the chart to focus on specific models and export the data as CSV for further analysis. ### Per-User Usage Table A detailed table showing usage by user: | Column | Description | | - | - | | User | Email address or service account name | | Usage | Total usage by this user in the selected period | | Model Breakdown | Mini chart showing which models each user is utilizing | The table supports: * **Sorting** by any column * **Searching** for specific users * **CSV export** of the complete user usage data > [!NOTE] > > When [budget configuration mode](#configuring-budgets) is enabled, additional columns for **Budget** and **Usage** (a visual bar showing consumption relative to budget) appear in the table. ## My Usage The My Usage dashboard lets individual enterprise users view their own usage without needing administrator access. Any enterprise user can access this page to understand their own consumption. To access My Usage, visit [app.augmentcode.com](https://app.augmentcode.com) and navigate to **My Usage** under the **Analytics** section in the sidebar. ### My Monthly Budget Below the date range selector, a **My Monthly Budget** card shows your usage from the first day of the current calendar month through today. This makes it easy to see how your usage tracks against your monthly budget without manually selecting dates. ### Date Filtering Use the date range selector to view your usage for a specific period. Standard presets (7 days, 30 days, 90 days) and custom date ranges are available. ### Summary Metrics The page displays two key metrics: * **Usage Consumed** — Total usage in the selected time period * **Avg Usage / Day** — Your daily average consumption ### Model Usage Distribution A horizontal stacked bar chart shows your usage by AI model, so you can see at a glance which models you use most. Up to seven models are shown individually; the rest are grouped under "Other." ### Daily Usage Trend A bar chart shows your usage by day over the selected period, helping you spot usage trends and identify high-consumption days. ## Budgets Budgets allow administrators to set monthly usage limits to govern consumption. ### Budget Types Augment supports the following budget configurations: | Budget Type | Scope | Description | | - | - | - | | **Org Monthly Budget** | Entire organization | Maximum usage the entire organization can consume per month | | **Default Monthly User Budget** | All users | Default monthly budget applied to every user (can be overridden per-user) | | **User Override** | Individual user | Custom budget for a specific user, overriding the default | ### Budget Behavior * **Enforced Budget**: When **Enforce budget** is enabled and consumption reaches the configured budget, access to Augment is paused until the next calendar month. This applies at both the organization and individual user level. * **Non-Enforced Budget**: When **Enforce budget** is disabled, usage can exceed the budget without cutoff. The budget serves as a tracking threshold only. * **No Budget Configured**: Users without a budget can consume usage without restriction (subject only to the organization budget). * **Override Takes Precedence**: A user-specific override always takes precedence over the default monthly user budget. * **Monthly Reset**: Budgets reset at the beginning of each calendar month (UTC). ### Alert Notifications Administrators can configure alert notifications to be warned before users approach or exceed their budget: * **Notify admin / Notify user**: Enable alert notifications. Alert notifications for "Org Monthly Budget" go to the admins. Alert notifications for user budgets go to the user. * **Alert threshold (%)**: Set a percentage of the budget at which the notification is triggered (e.g., 80 means an alert fires when 80% of the budget is consumed). Alerts are independent of budget enforcement — you can receive notifications whether or not the budget is enforced. ### Configuring Budgets 1. Visit [app.augmentcode.com](https://app.augmentcode.com) and navigate to **Organization Usage** 2. Open the **Budget** tab and click **Edit budget** on the Organization Monthly Budget card 3. The budget configuration panel and per-user budget column will appear ### Setting Organization & Default Monthly User Budgets The **Configure Budget** panel contains two sections — **Org monthly budget** and **Default monthly user budget**. Each section has the following controls: 1. **Budget amount** — Enter the monthly budget 2. **Enforce budget** — Toggle on to cut off access when the budget is reached; toggle off to allow overage 3. **Notify admin / Notify user** — Toggle on to enable alert notifications 4. **Alert %** — Set the percentage of the budget at which a notification is sent Click **Save** to apply changes. These settings take effect immediately. ### Setting Individual User Budgets Individual user budgets override only the budget amount. Enforcement and alert settings are inherited from the **Default monthly user budget** configuration — there is no way to set per-user enforcement or alert preferences. There are two ways to set budgets for specific users: #### Inline Editing 1. Find the user in the usage table 2. Click the budget value (or "not configured") 3. Enter the new budget and press Enter 4. The change saves automatically #### Bulk Upload via CSV For managing budgets across many users: 1. Click **Bulk Manage** in the Configure Budget panel 2. **Download** the CSV template (pre-populated with all users and current budgets) 3. Edit the CSV: * Column A: `user` — Email address or `SA ServiceName` for service accounts * Column B: `budget` — Budget amount (leave empty to clear the override) 4. **Upload** the edited CSV 5. Review any validation warnings 6. Click **Save** to apply all changes **CSV Format Example:** ```csv theme={null} user,budget alice@company.com,10000 bob@company.com,5000 SA MyServiceAccount,2000 charlie@company.com, ``` *Note: An empty value clears any existing override, causing the user to fall back to the default monthly user budget.* ### Service Accounts Service accounts (non-interactive users like CI/CD integrations) are included in budget management. They appear in the user table with an "SA" prefix and can have budgets set via inline editing or CSV upload. Alerting notifications for service accounts are not supported yet. ## Known Limitations * **Usage Refresh Rate**: The Organization Usage dashboard updates approximately every 90 minutes. Recent usage may take up to 90 minutes to be reflected. * **Context Engine MCP**: Usage consumed via Context Engine MCP is not currently shown in the dashboard. ## Coming Soon Future releases will include: * **Model & Activity Restrictions**: Limit which models or features specific users can access ## Frequently Asked Questions **Q: What happens when a user exceeds their budget?** A: If **Enforce budget** is enabled, their access to Augment features (chat, agent, CLI) is paused until the next calendar month. They'll see a message directing them to contact their administrator. If **Enforce budget** is disabled, usage continues beyond the budget without interruption. **Q: Can I set unlimited usage for specific users?** A: Yes. Leave the budget field empty or clear an existing override to give a user unlimited access (subject to the organization budget). **Q: How do organization and user budgets interact?** A: Both are checked. A user is paused if they hit their individual enforced budget OR if the organization's enforced budget is exhausted. **Q: When do budgets reset?** A: At the beginning of each calendar month (UTC). **Q: Are service accounts subject to budgets?** A: Yes. Service accounts can have budgets set just like regular users. **Q: How do alert notifications work?** A: When alerts are enabled, a notification is sent when a user's (or the organization's) usage reaches the configured alert threshold percentage of their budget. Alerts are independent of budget enforcement. # Overview of Analytics Source: https://docs.augmentcode.com/analytics/overview Monitor team usage patterns and analyze Augment Code adoption across your organization. > [!NOTE] > > **Enterprise-Only Feature** > > Exclusive to Enterprise customers, access the Team Usage under Analytics at [app.augmentcode.com/dashboard](https://app.augmentcode.com/dashboard). ## Feature Metrics at a Glance > **Monthly Active Users** > > Number of unique users in the current calendar month > **Lines of Code All Sources** > > Total lines of code generated from all sources during the selected period > **User Messages & Tool Calls** > > Total number of user messages and tool calls during the selected period ## Understand adoption inside of your organization Review detailed per-user metrics to understand power-user usage patterns or inactivity inside your organization. ### Available Columns | Column | Description | | - | - | | **User** | Email or service account name (with visual indicator for service accounts) | | **First Seen** | Date user first appeared in the system | | **Last Seen** | Date of user's most recent activity | | **Active Days** | Number of days user was active in the selected period | | **Completions** | Total code completions generated | | **Accepted Completions** | Number of completions accepted by user | | **Accept Rate** | Percentage of completions accepted | | **Chat Messages** | Total chat messages sent | | **Agent Messages** | Messages from agent interactions | | **Remote Agent Messages** | Messages from remote agent sessions (deprecated feature) | | **Interactive CLI Agent Messages** | Interactive CLI agent interactions | | **Non-Interactive CLI Agent Messages** | Non-interactive CLI agent interactions | | **Tool Uses** | Total number of tool invocations | | **Total Modified Lines of Code** | All lines of code modified | | **Completion Lines of Code** | Lines from completions | | **Instruction Lines of Code** | Lines from instructions (deprecated feature) | | **Agent Lines of Code** | Lines from agent edits | | **Remote Agent Lines of Code** | Lines from remote agent (deprecated feature) | | **CLI Agent Lines of Code** | Lines from CLI agent | ## Data Export Export your usage data for custom analysis, reporting, or integration with other tools: * **CSV Download** - Export all user statistics to a CSV file * **Filename Format** - `user-feature-stats-YYYY-MM-DD-to-YYYY-MM-DD.csv` * **Complete Data** - Includes all columns from the user statistics table ## Mobile Experience The dashboard is fully optimized for mobile devices with: * Card-based layout for easy viewing on smaller screens * Mobile sort selector dropdown for choosing sort column and direction * Responsive pagination controls adapted for touch interfaces * All key metrics and data accessible on any device ## Getting Help If you have questions about the Enterprise Dashboard or need assistance interpreting your usage data: > **Contact Sales** > > Reach out to your sales representative for strategic guidance > **[Contact Support](https://support.augmentcode.com)** > > Get technical support at support.augmentcode.com ## Related Resources > **[Analytics API](/analytics/analytics-api)** > > Programmatic access to usage metrics via REST API > **[API Reference](/analytics/api-reference)** > > Detailed API endpoint documentation # ACP Mode Source: https://docs.augmentcode.com/cli/acp/agent Auggie is a fully compatible Agent Client Protocol (ACP) agent enabling you to bring the power of Augment to any compatible client. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/acp/agent) . ## About ACP Mode [Agent Client Protocol](https://agentclientprotocol.com/overview/introduction) (ACP) is an open protocol that provides a standardized way to connect AI agents to different text editors, IDEs, and other tools. ACP mode uses JSON-RPC over standard input and output to communicate between the agent and the client. You can see a [overview of the protocol](https://agentclientprotocol.com/protocol/overview) to learn more. ## Using ACP Mode To use Auggie in ACP mode, you need to pass the `--acp` flag when starting Auggie. You can pass additional [command-line arguments](/cli/reference) to set the model, authentication, and other options. ```sh theme={null} auggie --acp ``` To use Auggie in a ACP-compatible client, you need to configure the client to launch Auggie with the `--acp` flag and follow the client-specific instructions. See the [ACP Clients](/cli/acp/clients) page for more details. ## Compatibility ACP is an emerging protocol and is in active development. Not all features available in interactive mode are supported in ACP mode. We are looking forward to working with the community to add support for more features in the future. # ACP Clients Source: https://docs.augmentcode.com/cli/acp/clients Configure Auggie to run in any Agent Client Protocol (ACP) compatible client like Zed, Neovim, or Emacs. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/acp/clients) . ## About ACP Clients [Agent Client Protocol](https://agentclientprotocol.com/overview/introduction) (ACP) is an open protocol that provides a standardized way to connect AI agents to different text editors, IDEs, and other tools. Auggie is a fully ACP compatible agent enabling you to bring the power of Augment to editors like Zed, Neovim, or Emacs. See a [full list of supported clients](https://agentclientprotocol.com/overview/clients) in the ACP docs. ## Prerequisites * Auggie CLI [installed and configured](/cli/setup-auggie/install-auggie-cli) * Login to Augment with `auggie auth login` * A compatible ACP client ## Client configuration If you have an ACP client that you would like to have listed here, please [open an issue](https://github.com/augmentcode/auggie/issues/new) and we'll be happy to add it. ### Zed > [!NOTE] > > We recommend installing and configuring Auggie in [Zed](https://zed.dev/) using the [Auggie extension](https://zed.dev/extensions/auggie). If you want to configure Auggie manually through Zed's settings, you can use the following configuration. You can pass additional [command-line arguments](/cli/reference) to Auggie by adding them to the `args` array or use alternative [authentication methods](/cli/setup-auggie/authentication) by passing environment variables in the `env` object. ``` { "agent_servers": { "Auggie CLI": { "command": "auggie", "args": ["--acp"], "env": {} } } } ``` ### JetBrains > [!NOTE] > > We recommend installing and configuring Augment in [JetBrains IDEs](/jetbrains/setup-augment/install-jetbrains-ides) using the [Augment extension](https://plugins.jetbrains.com/plugin/24072-augment-ai-coding-assistant-for-professionals). To use Auggie with JetBrains IDEs, you can configure it in your IDE settings. You can pass additional [command-line arguments](/cli/reference) to Auggie by adding them to the `args` array or use alternative [authentication methods](/cli/setup-auggie/authentication) by passing environment variables in the `env` object. ```json theme={null} { "agent_servers": { "Auggie CLI": { "command": "auggie", "args": [ "--acp" ], "env": {} } } } ``` ### Neovim To use Auggie with Neovim, you can use one of the following plugins: #### [**Avante.nvim**](https://github.com/yetone/avante.nvim) Add the following to your lazy.nvim configuration: ```lua theme={null} { "yetone/avante.nvim", event = "VeryLazy", build = "make", dependencies = { "nvim-lua/plenary.nvim", "MunifTanjim/nui.nvim", }, opts = { provider = "auggie-acp", acp_providers = { ["auggie-acp"] = { command = "auggie", args = { "--acp" }, }, }, behaviour = { auto_suggestions = false, auto_set_highlight_group = true, auto_set_keymaps = true, auto_apply_diff_after_generation = false, support_paste_from_clipboard = false, }, }, }, ``` #### [**Agentic.nvim**](https://github.com/carlos-algms/agentic.nvim) Add the following to your lazy.nvim configuration: ```lua theme={null} { "carlos-algms/agentic.nvim", opts = { provider = "auggie-acp", acp_providers = { ["auggie-acp"] = { command = "auggie", args = { "--acp" }, }, }, }, } ``` #### [**CodeCompanion.nvim**](https://github.com/olimorris/codecompanion.nvim) Add the following to your lazy.nvim configuration: ```lua theme={null} { "olimorris/codecompanion.nvim", opts = { strategies = { chat = { adapter = "auggie_cli", }, inline = { adapter = "auggie_cli", }, }, }, } ``` ### Emacs To use Auggie with emacs, you can use one of the following plugins: * [agent-shell.el](https://github.com/xenodium/agent-shell) # CLI Flags and Options Source: https://docs.augmentcode.com/cli/reference A comprehensive reference for all command-line flags available in the Auggie CLI. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/reference) . ## CLI flags | Command | Description | | :- | :- | | `auggie` | Start Auggie in interactive mode | | `auggie --print "Summarize the staged changes"` (`-p`) | Run one instruction in print mode and exit | | `auggie --print --mode stream "Summarize the staged changes"` | Stream text and tool activity as it happens | | `auggie --print --mode json "Summarize the staged changes"` | Output structured JSON events for automation workflows | | `auggie --print --show-cost "Summarize the staged changes"` | Include cost and credit usage in the output | | `auggie --acp` | Run Auggie as an [ACP](/cli/acp/agent) agent for compatible editors and clients | ### Input | Command | Description | | :- | :- | | `auggie "Fix the typescript errors"` | Provide an initial instruction in interactive mode | | `auggie --print "Summarize the staged changes"` | Provide an instruction and exit | | `cat file \| auggie --print "Summarize this data"` | Pipe content through stdin | | `auggie @prompt.md @screenshot.png "Explain this UI error"` | Include files and images in the initial message | | `auggie --print --enhance-prompt "Fix the flaky test"` | Run the prompt enhancer before sending the instruction | | `auggie --append-system-prompt ` | Append text or file contents to the system prompt | ### Custom Commands | Command | Description | | :- | :- | | `auggie command list` | List available custom commands | | `auggie command [args...]` | Execute a custom command | | `auggie command help ` | Show help for a custom command | See [Custom Commands](/cli/custom-commands) for detailed information on creating and managing custom commands. ### Sessions | Command | Description | | :- | :- | | `auggie --continue` (`-c`) | Continue the most recent session | | `auggie --resume` (`-r`) | Interactively choose a saved session to resume | | `auggie --session ` | Use a specific session file | | `auggie --fork ` | Fork a session file or partial session ID into a new session | | `auggie --session-dir ` | Directory for session storage and lookup | | `auggie --no-session` | Do not save the session | | `auggie --export [output.html]` | Export a session file to HTML and exit | | `auggie session list` | List saved sessions from the current workspace (`--all`, `--json`, `-n `) | | `auggie session stats [sessionId]` | Show session statistics, including cost and credit usage | Resuming a session restores its `--permission` and `--add-workspace` values unless you pass them again. ### Workspace | Command | Description | | :- | :- | | `auggie --workspace-root /path/to/project` (`-w`) | Specify the root of the workspace (defaults to the git root) | | `auggie --add-workspace /path/to/another/project` | Index an additional workspace alongside the primary workspace (repeatable) | | `auggie --discover-workspaces[=depth]` | Discover git repositories under a non-git workspace root | | `auggie --no-discover-workspaces` | Disable git repository discovery | | `auggie --worktree [slug]` | Create or reuse a git worktree for this session | | `auggie --allow-indexing` | Allow indexing for the current workspace and skip the confirmation screen | | `auggie --wait-for-indexing` | Wait for workspace indexing to finish before the first agent turn | | `auggie --augment-cache-dir /path/to/dir` | Relocate the Augment config and cache directory (default `~/.augment`) | ### Models | Command | Description | | :- | :- | | `auggie --model "name"` | Select the model. Append `:` to set the reasoning effort, for example `sonnet:high` | | `auggie --thinking ` | Set the reasoning effort. Use `default` to clear the override | | `auggie --models ` | Comma-separated model patterns to cycle through | | `auggie model list [search]` | List available models (`--json` for full metadata) | ### Rules, skills, and resources | Command | Description | | :- | :- | | `auggie --rule ` | Load a rule file or directory (repeatable) | | `auggie --no-rules` | Disable rule discovery | | `auggie --skill ` | Load a skill file or directory (repeatable) | | `auggie --no-skills` | Disable skill discovery | | `auggie --prompt-template ` | Load a prompt template file or directory (repeatable) | | `auggie --theme ` | Load a theme file or directory (repeatable) | > [!NOTE] > > Skills are loaded automatically from `.augment/skills/` and `.claude/skills/` directories in both your workspace and home directory. See [Skills](/cli/skills) for more information. ### Tools | Command | Description | | :- | :- | | `auggie --tools read,bash,edit,write` | Enable only the listed built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) | | `auggie --no-tools` | Disable all built-in tools | | `auggie --remove-tool ` | Remove a tool by name for the current session (repeatable) | | `auggie --permission bash:ask-user` | Set a tool permission rule for the current run (repeatable) | | `auggie --enable-tool-search` | Hide individual MCP tools behind `find-tool` and `execute-tool` | For fine-grained control over tool behavior (allow, deny, ask-user), see [Permissions](/cli/permissions). ### Plugins and extensions | Command | Description | | :- | :- | | `auggie plugin marketplace add ` | Add a plugin marketplace from a repository or URL | | `auggie --plugin-dir ` | Load and enable plugins from a local marketplace directory (repeatable) | | `auggie install [-l]` | Install an extension package and add it to settings (`-l` for project settings) | | `auggie remove [-l]` | Remove an extension package from settings | | `auggie update [source]` | Update installed extension packages | | `auggie list` | List installed extension packages | | `auggie config` | Enable or disable package resources | | `auggie --extension ` (`-e`) | Load an extension file for this run (repeatable) | | `auggie --no-extensions` | Disable extension discovery | Use `/plugins` in interactive mode to browse and manage plugins. See [Plugins and Marketplaces](/cli/plugins). Auggie 1.x is built on [pi](https://github.com/earendil-works/pi), so [pi extensions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md) should work in Auggie. Install them with `auggie install` instead of `pi install`. > [!WARNING] > > Extensions are third-party code that runs with your user permissions and can read your files, run commands, and > send data anywhere. Augment does not review, control, or support third-party extensions and is not responsible for > what they do, including any data they access or share. Only install extensions from sources you trust. > > Auggie includes changes to pi, so an extension may behave differently in Auggie than in pi. If something isn't > working, let us know with `/feedback`. ### MCP and integrations | Command | Description | | :- | :- | | `auggie mcp add [options] ` | Create or update a named MCP server configuration (`--project` or `--local` to choose the settings file) | | `auggie mcp add-json ` | Add an MCP server from JSON configuration | | `auggie mcp list` | Display all configured MCP servers | | `auggie mcp remove ` | Remove a named MCP server configuration | | `auggie --mcp-config ` | Load MCP server configuration from inline JSON or a file (repeatable) | > [!NOTE] > > `--mcp-config` overrides MCP servers defined in settings files. For detailed usage examples, options, settings.json format, and precedence rules, see [Integrations and MCP](/cli/integrations#manage-mcp-servers-with-the-auggie-cli). ### Cloud | Command | Description | | :- | :- | | `auggie --cloud` | Stream this session to Cosmos so it is visible and steerable from the web UI | | `auggie --no-cloud` | Disable cloud mode | | `auggie cloud ` | Manage cloud resources. See [Cloud](/cli/cloud) | ### Authentication | Command | Description | | :- | :- | | `auggie auth login [--headless]` | Log in to Augment and store the session locally | | `auggie auth logout` | Remove the local session | | `auggie auth status` | Show the current authentication status | | `auggie token print` | Print the current session JSON for automation | | `auggie token revoke` | Revoke tokens for the current user and remove the local session | | `auggie --augment-session-json ` | Authenticate with inline session JSON or a session file | ### Diagnostics | Command | Description | | :- | :- | | `auggie --log-file ` | Write logs to the given file. Defaults to a temp file | | `auggie --log-level ` | Set the log level: `error`, `warn`, `info` (default), or `debug` | | `auggie --verbose` | Show the startup header even if `quietStartup` is set | | `auggie --offline` | Disable startup network operations | | `auggie --check-startup` | Boot, print startup diagnostics as JSON, and exit | ### Additional commands | Command | Description | | :- | :- | | `auggie upgrade` | Upgrade Auggie to the latest version in its channel | | `auggie --help` (`-h`) | Show help | | `auggie --version` (`-v`) | Show version | ## Environment Variables | Variable | Description | | - | - | | `AUGMENT_SESSION_AUTH` | Authentication JSON | | `AUGMENT_DISABLE_AUTO_UPDATE` | Disable automatic CLI updates | ## See Also * [Settings](/cli/settings) - Configure Auggie with `/settings` and `settings.json` * [Custom Rules and Guidelines](/cli/rules) - Configure custom rules for project-specific guidance * [Skills](/cli/skills) - Extend capabilities with specialized domain knowledge * [Custom Commands](/cli/custom-commands) - Create reusable command templates * [Plugins and Marketplaces](/cli/plugins) - Manage and install plugins to extend Auggie * [Permissions](/cli/permissions) - Configure tool permissions and security * [Integrations](/cli/integrations) - Connect external tools and services # Auggie SDK Source: https://docs.augmentcode.com/cli/sdk Build custom integrations and agents using the Auggie SDK. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/sdk) . > **[TypeScript SDK](/cli/sdk-typescript)** > > Build Node.js and TypeScript applications with the Auggie SDK > **[Python SDK](/cli/sdk-python)** > > Build Python applications with the Auggie SDK ## Installation ```sh TypeScript theme={null} npm install @augmentcode/auggie-sdk ``` ```sh Python theme={null} pip install auggie-sdk ``` ## Authentication The Auggie SDK supports multiple authentication methods: 1. **Using `auggie auth login` (Recommended)** - Creates a session file at `~/.augment/session.json` 2. **Using Environment Variables** - Set `AUGMENT_SESSION_AUTH` to the session JSON from `auggie token print` 3. **Passing Credentials Directly** - Provide `apiKey` and `apiUrl` parameters when initializing ### Finding your credentials > [!NOTE] > > For production deployments and CI/CD, consider using [Service Accounts](/cli/automation/service-accounts) when they are available for your plan. First, log in to create a local session: ```bash theme={null} auggie auth login ``` For automation or non-interactive environments, get your session JSON: ```bash theme={null} auggie token print ``` Then set the `AUGMENT_SESSION_AUTH` environment variable to the session JSON: ```bash theme={null} export AUGMENT_SESSION_AUTH='' ``` The session JSON includes both your access token and tenant URL, so no separate URL variable is needed. ## Quick Start ```typescript TypeScript theme={null} import { Auggie } from "@augmentcode/auggie-sdk"; const client = await Auggie.create({ model: "sonnet4.5" }); const response = await client.prompt("What files are in the current directory?"); console.log(response); await client.close(); ``` ```python Python theme={null} from auggie_sdk import Auggie agent = Auggie(model="sonnet4.5") result = agent.run("What is 2 + 2?", return_type=int) print(result) # 4 ``` ## Key Features Both SDKs provide: * **High-level API** - Simple interface for common tasks * **Multiple Output Modes** - String responses, typed returns, streaming, and more * **Codebase Awareness** - Automatic indexing and context from your workspace * **Custom Tools** - Extend Auggie with your own tools and integrations ## TypeScript-Specific Features The TypeScript SDK also includes: * **AI SDK Provider** - Use Augment as a language model provider with [Vercel's AI SDK](https://sdk.vercel.ai/docs) * Compatible with `generateText`, `streamText`, and other AI SDK functions * Full support for tool calling (function calling) * Works with API credentials only (no local Auggie installation needed) * See the [TypeScript SDK documentation](/cli/sdk-typescript#ai-sdk-provider-vercel-ai-sdk) for details # Python SDK Source: https://docs.augmentcode.com/cli/sdk-python Build custom integrations and agents using the Auggie Python SDK. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/sdk-python) . ## About The Auggie Python SDK provides a programmatic interface to Auggie for building custom integrations and agents in Python applications. ## Installation ```sh theme={null} pip install auggie-sdk ``` ## Usage ### Basic Initialization ```python theme={null} from auggie_sdk import Auggie # Simple initialization agent = Auggie(model="sonnet4.5") # Run a task result = agent.run("What is 2 + 2?", return_type=int) print(result) # 4 ``` ### Full Configuration ```python theme={null} from auggie_sdk import Auggie from auggie_sdk.acp import AgentEventListener # Optional: Create a custom event listener class MyListener(AgentEventListener): def on_agent_message_chunk(self, text: str): print(text, end="", flush=True) agent = Auggie( # Working directory for the agent (default: current directory) workspace_root="/path/to/workspace", # Model to use: "haiku4.5" | "sonnet4.5" | "sonnet4" | "gpt5" model="sonnet4.5", # Event listener for real-time updates (optional) listener=MyListener(), # Allow codebase indexing (default: True) allow_indexing=True, # Default timeout in seconds (default: 300) timeout=600, # API key for authentication (optional) api_key="your-api-key", # API URL (optional) api_url="https://your-tenant.api.augmentcode.com", # Rule file paths (optional) rules=["/path/to/rules.md"], # Additional CLI arguments (optional) cli_args=["--thinking", "high"] ) # Use the agent result = agent.run("Your question here", return_type=str) print(result) ``` ### Custom CLI Arguments The `cli_args` parameter allows you to pass additional command-line arguments to the Auggie CLI when spawning the agent process. This is useful for passing custom or experimental CLI flags that aren't exposed as dedicated parameters. ```python theme={null} from auggie_sdk import Auggie # Example 1: Set the reasoning effort agent = Auggie( cli_args=["--thinking", "high"] ) # Example 2: Skip the indexing confirmation and wait for indexing agent = Auggie( cli_args=["--allow-indexing", "--wait-for-indexing"] ) # Example 3: Add custom rules and skills agent = Auggie( cli_args=[ "--rule", "/path/to/custom-rules.md", "--skill", "/path/to/skills" ] ) # Example 4: Configure tool permissions agent = Auggie( cli_args=[ "--permission", "web-search:allow", "--permission", "bash:ask-user" ] ) ``` **Common CLI arguments:** * `--thinking ` - Set the reasoning effort * `--allow-indexing` - Skip the indexing confirmation * `--wait-for-indexing` - Wait for workspace indexing before the first turn * `--rule ` - Additional rule file or directory (repeatable) * `--skill ` - Additional skill file or directory (repeatable) * `--permission ` - Set tool permissions with 'tool-name:policy' format The `cli_args` are appended after all other CLI arguments, giving you flexibility to pass any additional flags or options supported by the underlying Auggie CLI. See the [CLI reference](/cli/reference) for available command-line options. ## Output Modes The Python SDK supports multiple output modes to fit different use cases: ### Typed Returns Specify the exact type you expect, and the SDK ensures the agent returns data in that format: ```python theme={null} from auggie_sdk import Auggie agent = Auggie() # Get an integer result = agent.run("What is 15 + 27?", return_type=int) print(result) # 42 # Get a dictionary weather = agent.run( "Get weather info for Tokyo", return_type=dict ) # Get a list files = agent.run( "List all Python files", return_type=list ) ``` ### Automatic Type Inference When no `return_type` is specified, the agent automatically infers the best type: ```python theme={null} result, inferred_type = agent.run("What is 15 + 27?") print(f"Result: {result} (type: {inferred_type.__name__})") # Result: 42 (type: int) ``` ### Structured Data with Dataclasses Return complex structured data using Python dataclasses: ```python theme={null} from dataclasses import dataclass from typing import List @dataclass class Task: id: int description: str is_done: bool # Get a single object task = agent.run( "Create a sample task for 'Buy groceries'", return_type=Task ) # Get a list of objects tasks = agent.run( "Create 3 sample tasks for a weekend to-do list", return_type=List[Task] ) ``` ### Streaming Mode Listen to real-time updates using an event listener: ```python theme={null} from auggie_sdk import Auggie from auggie_sdk.acp import AgentEventListener class MyListener(AgentEventListener): def on_agent_message_chunk(self, text: str): """Called when agent sends response chunks (streaming).""" print(text, end="", flush=True) def on_tool_call(self, tool_call_id, title, kind=None, status=None): """Called when agent makes a tool call.""" print(f"\n🔧 Using tool: {title}") agent = Auggie(listener=MyListener()) result = agent.run("Your question here") ``` **Supported return types:** `int`, `float`, `str`, `bool`, `list`, `dict`, `List[T]`, `Dict[K, V]`, `dataclasses`, `Enum` ## Custom Functions The Python SDK supports **custom function calling**, allowing you to provide Python functions that the agent can intelligently call during execution. This enables the agent to interact with external systems, perform calculations, fetch data, and more. ### Creating Custom Functions Define Python functions with type hints and docstrings. The agent will automatically understand how to use them: ```python theme={null} from auggie_sdk import Auggie import datetime def get_current_weather(location: str, unit: str = "celsius") -> dict: """ Gets the weather for a given location. Args: location: The city and state, e.g. San Francisco, CA unit: Temperature unit ('celsius' or 'fahrenheit') """ # In a real app, you'd call a weather API here return {"temp": 72, "unit": unit, "forecast": "sunny"} def get_time() -> str: """Returns the current time.""" return datetime.datetime.now().strftime("%H:%M") agent = Auggie() # The agent will call the appropriate function(s) to answer the question response = agent.run( "What's the weather like in NYC right now, and what time is it there?", functions=[get_current_weather, get_time], ) print(response) ``` ### Function Requirements For functions to work properly with the agent: 1. **Type Hints Required**: All parameters must have type annotations 2. **Docstrings Required**: Function must have a docstring with: * Function description (first paragraph) * Parameter descriptions in the `Args:` section 3. **JSON-Serializable**: Arguments and return values must be JSON-serializable 4. **Keyword Arguments**: Functions must accept keyword arguments ### Example with Multiple Functions ```python theme={null} from auggie_sdk import Auggie def add_numbers(a: int, b: int) -> int: """Add two numbers together. Args: a: First number b: Second number """ return a + b def multiply_numbers(a: int, b: int) -> int: """Multiply two numbers together. Args: a: First number b: Second number """ return a * b agent = Auggie() result = agent.run( "What is (15 + 27) multiplied by 3?", return_type=int, functions=[add_numbers, multiply_numbers], ) print(result) # 126 ``` ### How It Works 1. Function schemas are automatically generated from type hints and docstrings 2. The agent receives the instruction and available functions 3. The agent intelligently decides when to call functions 4. The SDK executes the functions and sends results back to the agent 5. The agent continues processing and can call more functions if needed 6. Final response is returned according to `return_type` > [!NOTE] > > **Function Calling Limits**: Function calling is limited to 5 rounds to prevent infinite loops. ## See Also * [Python SDK on PyPI](https://pypi.org/project/auggie-sdk) * [TypeScript SDK](/cli/sdk-typescript) * [ACP Clients](/cli/acp/clients) # TypeScript SDK Source: https://docs.augmentcode.com/cli/sdk-typescript Build custom integrations and agents using the Auggie TypeScript SDK. You're viewing docs for **Auggie 1.x.x** (prerelease). To see Auggie 0.x.x, go to [the 0.x.x docs](/cli/v0/sdk-typescript) . ## About The Auggie TypeScript SDK provides a programmatic interface to Auggie for building custom integrations and agents in Node.js and TypeScript applications. The SDK offers two main interfaces: 1. **Agent Interaction (ACP)** - Launch and communicate with a local Auggie agent process 2. **AI SDK Provider** - Use Augment as a language model provider with Vercel's AI SDK (API-only, no local installation required) ## Installation ```sh theme={null} npm install @augmentcode/auggie-sdk ``` ## Agent Interaction (ACP) **⚠️ Requires Local Auggie Installation** The Agent Interaction interface allows you to launch Auggie in ACP mode and communicate bidirectionally. This requires a local Auggie installation. ## Usage ### Basic Initialization ```typescript theme={null} import { Auggie } from "@augmentcode/auggie-sdk"; // Simple initialization const client = await Auggie.create({ model: "sonnet4.5" }); // Send a prompt const response = await client.prompt("What files are in the current directory?"); console.log(response); // Close the connection await client.close(); ``` ### Full Configuration ```typescript theme={null} import { Auggie } from "@augmentcode/auggie-sdk"; const client = await Auggie.create({ // Path to Auggie executable (default: "auggie") auggiePath: "/path/to/auggie", // Working directory for the Auggie process (default: process.cwd()) workspaceRoot: "/path/to/workspace", // Eg: "haiku4.5" | "gpt-5" | "sonnet4.5" | "sonnet4" model: "sonnet4.5", // Allow codebase indexing (default: true) allowIndexing: true, // API key for authentication (optional) apiKey: "your-api-key", // API URL (optional) apiUrl: "https://your-tenant.api.augmentcode.com", // Custom tools to provide to Auggie (optional) tools: { // Your custom tools here }, // Rule file paths (optional) rules: ["/path/to/rules.md"], // Additional CLI arguments to pass to the Auggie process (optional) cliArgs: ["--thinking=high"] }); // Use the client const response = await client.prompt("Your question here"); console.log(response); await client.close(); ``` ### Advanced CLI Arguments The `cliArgs` option allows you to pass additional command-line arguments directly to the Auggie CLI process. These arguments are appended after all SDK-generated flags, allowing you to use advanced configurations or experimental flags not exposed through standard SDK options. ```typescript theme={null} import { Auggie } from "@augmentcode/auggie-sdk"; // Pass custom CLI flags const client = await Auggie.create({ model: "sonnet4.5", cliArgs: ["--thinking=high"] }); // Arguments can use either format: // 1. Separate flag and value: ["--thinking", "high"] // 2. Combined with equals: ["--thinking=high"] const client2 = await Auggie.create({ model: "sonnet4.5", cliArgs: ["--allow-indexing", "--wait-for-indexing"] }); ``` **Note:** Since `cliArgs` are appended after SDK-generated flags, they can override default values when the CLI uses a last-value-wins strategy. Refer to `auggie --help` for available CLI flags. ## Output Modes The TypeScript SDK supports multiple output modes to fit different use cases: ### String Response (Default) By default, the SDK returns the complete agent response as a string: ```typescript theme={null} const client = await Auggie.create({ model: "sonnet4.5" }); const response = await client.prompt("What files are in the current directory?"); console.log(response); // Full response as string ``` ### Answer-Only Mode Get only the final answer after all tool calls complete, excluding intermediate reasoning: ```typescript theme={null} const finalAnswer = await client.prompt( "List all TypeScript files in this project", { isAnswerOnly: true } ); // Returns only the final response after tool execution ``` ### Streaming Mode Listen to real-time updates as the agent processes your request: ```typescript theme={null} client.onSessionUpdate((event) => { switch (event.update.sessionUpdate) { case "agent_message_chunk": if (event.update.content.type === "text") { process.stdout.write(event.update.content.text); } break; case "tool_call": console.log(`\nTool: ${event.update.title}`); break; case "tool_call_update": console.log("Output:", event.update.rawOutput); break; } }); const response = await client.prompt("Your question here"); ``` ## Custom Tools The TypeScript SDK supports **ai-sdk compatible tools**, allowing you to extend Auggie with custom functionality. You can provide tools that the agent can call during execution. ### Creating a Custom Tool Here's an example of a custom weather tool: ```typescript theme={null} import { Auggie } from "@augmentcode/auggie-sdk"; import { tool } from "ai"; import { z } from "zod"; // Define a custom tool const weather_tool = tool({ name: "get_weather", description: "Get the weather in a location", inputSchema: z.object({ location: z.string().describe("The location to get the weather for"), }), execute: ({ location }) => { console.log(`\n Weather tool called for location: ${location}`); return `The weather in ${location} is sunny.`; }, }); // Initialize Auggie with the custom tool const client = await Auggie.create({ model: "sonnet4.5", tools: { get_weather: weather_tool, }, }); // The agent can now use the weather tool const response = await client.prompt("What's the weather like in San Francisco?"); console.log(response); await client.close(); ``` ### Key Points * **ai-sdk Compatible**: Tools follow the [Vercel AI SDK](https://sdk.vercel.ai/docs) tool format * **Zod Schemas**: Use Zod for input validation and type safety * **Automatic Discovery**: The agent automatically discovers and uses available tools when relevant * **Multiple Tools**: Pass multiple tools in the `tools` object ### Tool Structure Each tool requires: * `name` - Unique identifier for the tool * `description` - Clear description of what the tool does (helps the agent decide when to use it) * `inputSchema` - Zod schema defining the tool's input parameters * `execute` - Function that implements the tool's logic ## AI SDK Provider (Vercel AI SDK) **✅ No Local Auggie Required - API Only** The AI SDK Provider allows you to use Augment as a language model provider with [Vercel's AI SDK](https://sdk.vercel.ai/docs). This interface only requires API credentials and works without a local Auggie installation. ### Features * Compatible with `generateText`, `streamText`, and other AI SDK functions * Full support for tool calling (function calling) with automatic execution * Multi-turn conversations with context retention * Streaming responses for real-time output * Works with API credentials only (no local Auggie installation needed) ### Quick Start ```typescript theme={null} import { AugmentLanguageModel, resolveAugmentCredentials } from "@augmentcode/auggie-sdk"; import { generateText } from "ai"; // Resolve credentials from environment or ~/.augment/session.json const credentials = await resolveAugmentCredentials(); // Create the Augment language model const model = new AugmentLanguageModel("claude-sonnet-4-5", credentials); // Use with AI SDK functions const { text } = await generateText({ model, prompt: "Explain TypeScript in one sentence.", }); console.log(text); ``` ### Streaming Responses ```typescript theme={null} import { streamText } from "ai"; const { textStream } = await streamText({ model, prompt: "Write a haiku about coding.", }); for await (const chunk of textStream) { process.stdout.write(chunk); } ``` ### Tool Calling ```typescript theme={null} import { generateText, tool, stepCountIs } from "ai"; import { z } from "zod"; const weatherTool = tool({ description: "Get the weather in a location", inputSchema: z.object({ location: z.string().describe("The location to get the weather for"), }), execute: async ({ location }) => { return `The weather in ${location} is sunny.`; }, }); const { text } = await generateText({ model, tools: { weather: weatherTool }, stopWhen: stepCountIs(5), prompt: "What's the weather like in San Francisco?", }); ``` ### Multi-turn Conversations ```typescript theme={null} const messages = [ { role: "user" as const, content: "What's 2+2?" }, ]; const response1 = await generateText({ model, messages }); messages.push({ role: "assistant" as const, content: response1.text }); messages.push({ role: "user" as const, content: "Multiply that by 3" }); const response2 = await generateText({ model, messages }); console.log(response2.text); // "12" ``` ### Authentication The AI SDK Provider uses the same authentication methods as the rest of the SDK: 1. **Session File (Recommended)** - Use credentials from `~/.augment/session.json` (created by `auggie auth login`) 2. **Environment Variable** - Set `AUGMENT_SESSION_AUTH` to the session JSON from `auggie token print` 3. **Direct Credentials** - Pass credentials directly to `AugmentLanguageModel` ```typescript theme={null} // Option 1: Auto-resolve from session file or environment const credentials = await resolveAugmentCredentials(); const model = new AugmentLanguageModel("claude-sonnet-4-5", credentials); // Option 2: Pass credentials directly const model = new AugmentLanguageModel("claude-sonnet-4-5", { apiKey: "your-api-key", apiUrl: "https://your-tenant.api.augmentcode.com", }); ``` # Adding Another Organization Source: https://docs.augmentcode.com/codereview/adding-another-organization Configure Augment Code Review across multiple GitHub organizations for Enterprise accounts. ## Multi-Organization Support for Enterprise Enterprise accounts can configure Augment Code Review across multiple GitHub organizations. This is powered by the Augment GitHub App, which can be installed on multiple organizations within your enterprise. ### Adding another GitHub Organization To add Augment Code Review to additional organizations: 1. **Install the Augment GitHub App on each organization**: * Visit [https://github.com/apps/augmentcode/installations/new](https://github.com/apps/augmentcode/installations/new) * Select the organization you want to add * Grant the necessary permissions (see [Permissions requested by the Augment GitHub App](/codereview/setup-guide-enterprise#permissions-requested-by-the-augment-github-app)) 2. **Configure repository access for each organization**: * Navigate to [app.augmentcode.com/settings/code-review](https://app.augmentcode.com/settings/code-review) and click "configure which repositories." * On GitHub, select the organization under "Where do you want to install AugmentCode?" * Select the repositories you want to add under Repository Access. Select option for either: All repositories or Only select repositories. * Returning back to [app.augmentcode.com/settings/code-review](https://app.augmentcode.com/settings/code-review), all repositories from all enabled organizations will appear. * Set Review Triggers (Automatic, Manual Command, or Disabled) for the new repositories. ### Removing an Organization To remove Augment Code Review from an organization: 1. Navigate to the GitHub Apps installed on that organization: * In the top right corner of GitHub, click your profile picture, then click **Your organizations** * Next to the organization name, click **Settings** * In the sidebar, under "Third-party Access," click **GitHub Apps** 2. Next to the Augment GitHub App, click **Configure** 3. In the Danger zone section, click **Uninstall** # Analytics Dashboard Source: https://docs.augmentcode.com/codereview/analytics-dashboard Track code review metrics and measure the impact of Augment Code Review on your team. ## Code Review Analytics Use the Code Review Analytics dashboard to track the review load automated by Augment, along with the comments made by Code Review that developers ultimately addressed. 1. **Navigate to Code Review** - In your browser, visit [Code Review Analytics](https://app.augmentcode.com/code-review/analytics). 2. **Filter by Date** - Refine your Analytics using the tabs for Last 7 Days, Last 30 Days, or Last 60 Days. ### Metric Definitions * **Total PRs Reviewed**: The number of PRs that have been reviewed by Augment Code Review. * **Total Reviews Performed**: The number of reviews that have been run by Augment Code Review. One PR can have multiple reviews if people manually trigger more reviews. * **Total Comments**: The total number of inline comments left by Augment Code Review. * **Percentage of Comments Addressed**: A comment is addressed if the developer resolved the concerns raised by the Augment Code Review comment. The percentage is calculated by dividing the number of addressed comments by the total number of comments left by Augment Code Review. * **Percentage of Thumbs Up Reactions**: A thumbs up reaction is counted if a user reacts with the Thumbs Up emoji on GitHub on an inline comment left by Augment Code Review. The percentage is calculated by dividing the number of thumbs up reactions by the total number of thumbs up and thumbs down emoji reactions. * **Estimated Dev Hours Saved**: Number of PRs multiplied by 10 minutes ### Reading the Charts * **Addressed Comments**: A chart detailing total number of comments per day broken down by unaddressed (gray) vs addressed (green). You can interpret the green bar to mean Augment Code Review caught issues that developers fixed and may not have without the comment. * **Reviewed PRs**: A chart detailing the total number of reviewed PRs per day (blue). # Auto-Generated PR Descriptions Source: https://docs.augmentcode.com/codereview/auto-generated-pr-descriptions Generates comprehensive PR descriptions using Augment Code's Context Engine. After Augment Code Review has reviewed your pull request, it will leave a comment summarizing the work to that point. This description saves reviewers time by handling the 'what' and 'how' of the changes, allowing them to focus on explaining the 'why' and the broader context. The result: faster reviews, better collaboration, and more time on building. ## How It Works 1. **Create Your PR**: Open a pull request in GitHub with your code changes 2. **Automatic Analysis**: Augment's Context Engine analyzes your code diff and understands the changes in the context of your entire codebase 3. **Description Generation**: A comprehensive PR description is automatically generated, covering what changed, how it works, and potential impacts 4. **Review and Edit**: Review the generated description and add any additional context about why the changes were made 5. **Faster Reviews**: Reviewers can quickly understand your changes and provide meaningful feedback ## Best Practices **Review Before Accepting**: Always review the auto-generated description to ensure accuracy and completeness. The AI understands your code, but you understand the business context. **Add the 'Why'**: Supplement the generated description with the reasoning behind your changes. This helps reviewers understand not just what changed, but why it matters. **Keep PRs Focused**: Smaller, focused PRs result in more accurate and useful descriptions. Avoid mixing unrelated changes in a single PR. **Update for Significant Changes**: If you make substantial changes to your PR after the description is generated, consider regenerating or manually updating the description. **Use as a Starting Point**: Treat the auto-generated description as a foundation. Enhance it with project-specific context, design decisions, and any nuances the AI might miss. **Give Reviewers Context**: Give reviewers comprehensive context upfront, leading to faster and more thorough reviews. At the same time, help new team members understand changes more quickly with detailed, consistent PR descriptions. # Cross Repo Context Source: https://docs.augmentcode.com/codereview/cross-repo-context Give Augment Code Review visibility into external repositories for better cross-codebase context during reviews. ## Prerequisites Before using Cross Repo Context, make sure you have: 1. **Installed the Augment GitHub App** and granted it access to both your primary repository and any external repositories you want to reference. See [Install Augment GitHub App](/setup-augment/install-github-app) for setup instructions. 2. **Configured Augment Code Review** for your repositories with review triggers enabled. See the [Enterprise Setup Guide](/codereview/setup-guide-enterprise) or [Setup Guide for Other Plans](/codereview/setup-guide-otherplans). 3. **Added the Augment MCP server** to your Code Review configuration. Navigate to [MCP for Code Review](https://app.augmentcode.com/settings/code-review/mcp) and add `https://api.augmentcode.com/mcp` as a remote MCP server. See [MCP Servers](/codereview/mcp-context) for details. ## Reviewing code that depends on external repositories Many projects depend on code that lives in other repositories — SDKs, shared libraries, API contracts, or upstream services. By giving the code review agent visibility into those external codebases, it can provide more accurate and context-aware feedback. Cross Repo Context lets you declare external repositories that Augment Code Review should reference when reviewing pull requests. The code review agent can use external repos to: * **Understand types and interfaces** defined in external SDKs or libraries your code depends on * **Verify API compatibility** by checking how external services define their contracts * **Validate integration patterns** against the source of truth in another repository * **Catch breaking changes** when your code relies on external contracts that may have changed ## Configuring Cross Repo Context with AGENTS.md Cross-repo context is configured through an `AGENTS.md` file at the root of your repository (`/AGENTS.md`). If you already have an `AGENTS.md`, add a cross-repo context section to it. ### Example ```markdown theme={null} # External Repositories Read External Repository descriptions below and whenever the diff relates to or implements a listed repo, call `augment_code_search` tool with repo_owner, repo_name, and a natural language query to look up the relevant definitions, get information or have better context on the changes. Make multiple targeted calls to understand different aspects of the external code being used. This ensures the review is based on the actual external API. When commenting on findings, cite the external repo and file path. - repo: "your-org/payments-sdk" description: "Internal SDK for payment processing. Defines transaction types, payment method enums, and refund interfaces. Used as the source of truth for all payment-related API client types." - repo: "your-org/shared-types" description: "Shared TypeScript type definitions used across all services. Includes Order, CartItem, and ShippingAddress interfaces. All services must conform to these shared interfaces." - repo: "your-org/inventory-service" description: "Go microservice for stock reservations and availability checks. The checkout service calls its reservation and stock endpoints during order placement." ``` > [!NOTE] > > The more detail you provide about each external repository, the faster and more efficient the agent's cross-repo lookups will be. ### Customizing the Lookup Instruction The instruction block at the top of the example tells the code review agent how to use the external repos: > *Read External Repository descriptions below and whenever the diff relates to or implements a listed repo, call `augment_code_search` tool...* This is just a starting point — you can customize it to fit your workflow, and the more specific you make it the more targeted the cross-repo lookups will be. ## Best Practices * **Only add repos that are genuinely relevant.** Stick to repos that define interfaces, types, or contracts your code directly depends on. * **Make sure the Augment GitHub App has access to all external repos.** You can update repository access in your [GitHub App settings](https://github.com/settings/installations). # Code Review Enterprise Features Source: https://docs.augmentcode.com/codereview/enterprise-features Advanced features and capabilities available to Enterprise plan customers for Augment Code Review. ## Overview Augment Code Review Enterprise provides advanced features designed for organizations that need greater control, deeper integrations, and comprehensive analytics. This page outlines the key differences between self-serve and Enterprise plans. ## Feature Comparison | Feature | Self-Serve | Enterprise | | - | - | - | | **Advanced Analytics** | Total reviews performed | Full dashboard with reviews, comments addressed, and team insights | | **User Allowlist** | All repo users get reviews | Control exactly which users receive PR reviews | | **MCP Integration** | Not available | Connect to Jira, Linear, Notion, feature flags, and more | | **Multi-Org Support** | Single GitHub organization | Multiple GitHub organizations per tenant | | **GitHub Enterprise Server** | Not available | Full support for self-hosted GitHub instances | | **Seats** | Up to 20 seats | Unlimited seats | | **Connected Repos** | Limited | Unlimited repositories | ## Available Enterprise Features ### Advanced Analytics Enterprise customers have access to a comprehensive analytics dashboard that goes beyond basic metrics: * **Reviews Performed**: Track the total number of reviews completed by Augment Code Review * **Comments Addressed**: See how many review comments were acted upon by developers * **Engagement Metrics**: Understand how your team interacts with Code Review feedback Self-serve users see only the total number of reviews performed. > [!NOTE] > > Access the analytics dashboard at [Code Review Analytics](https://app.augmentcode.com/code-review/analytics). ### User Allowlist Enterprise administrators can specify exactly which GitHub users can trigger Augment Code Review. This provides fine-grained control over feature access within your organization. When Allowlist Mode is active: * Only users in the allowlist can trigger Augment Code Review * Automatic and manual reviews are disabled for all other users * Useful for phased rollouts or restricting access to specific teams > [!NOTE] > > Manage your allowlist at [User Access Settings](https://app.augmentcode.com/settings/code-review/user-access). ### MCP Integration Connect Augment Code Review to your existing tools through Model Context Protocol (MCP). This enables the code review agent to gather additional context from your organization's systems: * **Ticketing Systems**: Jira, Linear, and other issue trackers * **Documentation**: Notion, Confluence, and internal wikis * **Feature Flags**: LaunchDarkly, Split, and other feature management tools * **Other Systems**: Any MCP-compatible tool relevant to your development workflow This additional context allows Code Review to provide more informed and relevant feedback based on your team's specific requirements and documentation. > [!NOTE] > > Configure MCP servers at [MCP Settings](https://app.augmentcode.com/settings/code-review/mcp). ### Multi-Organization Support Enterprise customers can install the Augment Code Review GitHub bot across multiple GitHub organizations or accounts. This is essential for: * Organizations with separate GitHub orgs for different products or teams * Companies that have acquired other organizations with existing GitHub structures * Enterprises with strict organizational boundaries between business units All organizations connect to a single Augment Enterprise tenant for unified management and billing. ### GitHub Enterprise Server Support Enterprise customers can connect Augment Code Review to self-hosted GitHub Enterprise Server instances. This enables organizations with on-premises or private cloud GitHub deployments to benefit from Augment's code review capabilities while maintaining their existing infrastructure and security requirements. Key capabilities: * **Self-Hosted Integration**: Connect to your organization's GitHub Enterprise Server instance * **Custom Registration**: Register a dedicated Augment GitHub App on your Enterprise Server * **Same Features**: Access all Code Review features available on GitHub Cloud * **Unified Management**: Manage both Cloud and Enterprise Server installations from a single Augment tenant > [!NOTE] > > GitHub Enterprise Server support requires the Enterprise plan. See the [GitHub Enterprise Server Setup Guide](/codereview/setup-github-enterprise-server) for configuration instructions. ### Unlimited Seats Enterprise plans provide access to Augment Code Review for your entire organization without seat limitations. Self-serve plans are limited to 20 seats. ### Unlimited Connected Repositories Enterprise customers can enable Code Review on an unlimited number of repositories. Self-serve plans have a cap on the number of repositories that can be connected. ## Getting Started with Enterprise To upgrade to Enterprise or learn more about Enterprise features, visit [augmentcode.com/pricing](https://augmentcode.com/pricing) or contact our sales team. If you're already an Enterprise customer, visit your [Code Review Configuration](https://app.augmentcode.com/settings/code-review) to configure these features. # Fix in Augment Source: https://docs.augmentcode.com/codereview/fix-with-augment Automatically address issues found during code review directly using the agent in your IDE or paste the details into your preferred environment to address it yourself. When Augment Code Review identifies issues in your pull request, you can use the "Fix in Augment" button inside the comment to automatically address the issue. ![Fix in Augment button](https://mintcdn.com/augment-mtje7p526w/NsS6pjzbr2jAhbIL/images/codereview-fixwithaugment-inline.png?fit=max\&auto=format\&n=NsS6pjzbr2jAhbIL\&q=85\&s=979f17210ac453068daa2332e60ed8dd) Options include: * **Open in Agent Session**: For VS Code only, allows you to copy the prompt and start a new thread inside the Augment Code extension * **Copy to Clipboard**: Allows you to paste the prompt into your preferred environment, e.g. Auggie CLI, Augment Code for JetBrains, etc. ![Fix in Augment options](https://mintcdn.com/augment-mtje7p526w/NsS6pjzbr2jAhbIL/images/codereview-fixwithaugment.png?fit=max\&auto=format\&n=NsS6pjzbr2jAhbIL\&q=85\&s=bf9f109456c5843cdbbd60d0ac699de5) > [!NOTE] > > **Reminder:** To use "Fix in Augment", make sure you have connected your GitHub account in your IDE extension settings under Integrations / Services. This allows Augment to access your repository and create fixes directly in your IDE. *** ## Best Practices **Review the Fix**: Always review the changes proposed by Agent before accepting them. While Agent has full context, you should verify the fix aligns with your intent. **Test the Changes**: Run your tests after applying the fix to ensure the issue is resolved and no new issues are introduced. **Update the PR**: After pushing your fix, you can reply to the Code Review comment to indicate you've addressed the issue. **Request Follow-up Review**: If you make significant changes, consider requesting another review by commenting `auggie review` on your PR. # Adding Context with MCP Source: https://docs.augmentcode.com/codereview/mcp-context Connect Augment Code Review to external context sources through Model Context Protocol. ## Configuring Model Context Protocol (MCP) Servers Administrators can connect Augment Code Review to external context sources through Model Context Protocol (MCP). MCP servers provide additional context to the code review agent, such as access to documentation, APIs, databases, or other external systems that can help improve review quality. To configure MCP servers, visit [MCP for Code Review](https://app.augmentcode.com/settings/code-review/mcp). ### Types of MCP Servers Augment Code Review supports both remote and local MCP servers: * **Remote MCP servers** run remotely and are hosted by providers. Once you add a remote MCP server, you may need to complete an OAuth flow to authenticate before it can be used by the code review agent. * **Local MCP servers** run in their own environment within the code review agent's workspace. You can specify environment variables for local servers when adding them. Environment variables are write-only and can only be overwritten or removed (not viewed) after the server has been added. ### Adding MCP Servers There are three ways to add MCP servers to Code Review: #### 1. Add Local MCP Server (+ MCP) To add a local MCP server: 1. Navigate to [MCP for Code Review](https://app.augmentcode.com/settings/code-review/mcp) 2. Click **+ MCP** to add a local server 3. Enter the following information: * **Name**: A descriptive name for your MCP server * **Command**: The executable command to run the server * **Arguments**: Command-line arguments (optional) 4. Add environment variables if needed: * Click **+ Environment Variable** * Enter the variable name and value * Repeat for additional variables 5. Click **Add Server** to save 6. Add a review guideline telling Augment Code Review when to use the MCP server (see [Review Guidelines](/codereview/review-guidelines) for more information) > [!NOTE] > > Environment variables for local MCP servers are stored securely and cannot be viewed after saving. You can only overwrite or remove them. #### 2. Add Remote MCP Server (+ Remote MCP) To add a remote MCP server: 1. Navigate to [MCP for Code Review](https://app.augmentcode.com/settings/code-review/mcp) 2. Click **+ Remote MCP** to add a remote server 3. Enter the following information: * **Name**: A descriptive name for your MCP server * **URL**: The full URL of the remote MCP server (e.g., `https://mcp.example.com`) 4. Click **Add Server** 5. If the server requires OAuth authentication, you'll be redirected to complete the authentication flow 6. After successful authentication, you'll be redirected back to the settings page 7. Add a review guideline telling Augment Code Review when to use the MCP server (see [Review Guidelines](/codereview/review-guidelines) for more information) Remote MCP servers that require authentication will show a status indicator: * **Connected** (green): Server is authenticated and ready to use * **Authenticate** (yellow): Server needs authentication or re-authentication #### 3. Import from JSON To import MCP server configurations from a JSON file: 1. Navigate to [MCP for Code Review](https://app.augmentcode.com/settings/code-review/mcp) 2. Click **Import from JSON** 3. Paste your JSON configuration in the format: ```json theme={null} { "mcpServers": { "server-name": { "command": "npx", "args": ["-y", "@example/mcp-server"], "env": { "API_KEY": "your-api-key" } } } } ``` 4. Click **Import** to add the servers 5. Add a review guideline telling Augment Code Review when to use the MCP server (see [Review Guidelines](/codereview/review-guidelines) for more information) > [!NOTE] > > The JSON format matches the structure used in Augment's settings.json file, making it easy to share configurations across your team. ### Managing MCP Servers Once added, MCP servers appear in the "Configured MCP Servers" list. For each server, you can: * **View status**: See if the server is connected or needs authentication * **Re-authenticate**: Click the **Authenticate** button for remote servers that need re-authentication * **Remove**: Click the trash icon to remove a server from Code Review All configured MCP servers are available to the code review agent when analyzing pull requests. ### Example: Review Guideline for MCP Servers After adding an MCP server, you should create a review guideline that tells Augment Code Review when and how to use it. Add guidelines to your `code_review_guidelines.yaml` file at `/.augment/code_review_guidelines.yaml`. Here's an example guideline for using the Linear MCP server: ```yaml theme={null} areas: linear_ticket_verification: description: "Verify PRs implement their linked Linear tickets correctly" globs: - "**" rules: - id: "verify_linear_ticket_implementation" description: "If a Linear ticket is linked in the PR description, use the Linear MCP server to retrieve the ticket description and verify that the PR correctly implements the requirements specified in the ticket." severity: "high" ``` This guideline instructs the code review agent to: 1. Check if a Linear ticket is referenced in the PR description 2. Use the Linear MCP server to fetch the ticket details 3. Verify that the code changes align with the ticket requirements For more information on writing review guidelines, see [Review Guidelines](/codereview/review-guidelines). # Migrate from the Code Review bot to Cosmos Source: https://docs.augmentcode.com/codereview/migrate-to-cosmos Move all active GitHub Code Review bot reviews to Cosmos in one coordinated cutover. > [!NOTE] > > Ready to migrate? Complete Cosmos onboarding first if you're new, then open [Code Review bot settings](https://app.augmentcode.com/settings/code-review) and select **Migrate to Cosmos**. The button prepares an Advisor draft without changing your settings or enabling reviews. If you sign up for Cosmos with a new Augment account, you may be eligible for complimentary credits. Credits are not guaranteed, and migrating an existing Code Review bot setup does not automatically grant them. ## What Cosmos adds to code review | Benefit | What it brings to your team | | - | - | | **A configurable PR-to-merge workflow** | Combine specialized Experts for line-by-line review, risk triage, human-guided review, repair, and runtime verification. Add PR authoring when you want the workflow to cover more than review. A human always makes the final merge decision. [Explore the code review pipeline](/cosmos/experts-code-review). | | **Model choice** | Select a supported model when configuring an Expert or starting a session, and change it as your needs evolve. [See available models](/models/available-models). | | **Team-specific reviews** | Use repository guidance, tune Expert instructions, or create a custom Expert for your workflow. Code Review Memory can carry forward repository conventions and useful feedback. [Configure a custom Expert](/cosmos/experts-configure-custom) · [Code Review Memory](/cosmos/experts-code-review-memory). | | **Automation that fits your process** | Start reviews from GitHub events or manual commands, filter by repository and event details, and choose a run identity where available. [Configure triggers](/cosmos/config-triggers). | | **More context and tools** | Extend an Expert with approved MCP servers such as Sentry or Atlassian, alongside Cosmos's direct GitHub integration. [Configure MCP servers](/cosmos/config-mcp). | | **Visible review activity** | Inspect Expert sessions, run history, findings, and artifacts instead of treating review as a black box. [Review the code review pipeline](/cosmos/experts-code-review) · [Manage automations](/cosmos/manage-automations). | This guide moves your active GitHub pull-request reviews from the current Code Review bot on GitHub to [Cosmos](https://docs.augmentcode.com/cosmos/getting-started). The current Code Review bot on GitHub will be sunset. Migrate all repositories with active legacy reviews together in one coordinated cutover; keep repositories already configured as disabled off. Prepare two base shared Cosmos triggers per supported GitHub host, with repository allow-lists, and keep them disabled during setup. If a JSONLogic filter exceeds Cosmos's 4,096-byte limit, split its repository allow-list across additional non-overlapping shared triggers; include all triggers in the same full cutover. At cutover, disable the legacy triggers for the full active inventory, update the allow-lists, and enable the Cosmos triggers. The existing Augment GitHub App is used by Cosmos too. Keep its installation and repository access in place during the migration. ## Before you start You will need: * A Cosmos tenant admin to configure the GitHub integration, the Deep Reviewer expert, and automations. * A GitHub organization admin if the existing Augment GitHub App installation needs access to additional repositories. * Access to the [Code Review bot settings](https://app.augmentcode.com/settings/code-review) page, where you can use **Migrate to Cosmos**. Review the prefilled inventory for tenant-level Code Review bot status, each repository's exact `owner/repository` name and saved trigger, author allow/deny lists, connected MCP server IDs, and any custom review guidance you want to carry over. Keep the current Code Review bot settings unchanged while preparing Cosmos. Configure the shared Cosmos triggers disabled with the complete allow-lists. At the approved full cutover, disable legacy triggers for all active repositories in the inventory, then enable the Cosmos triggers with those same allow-lists. Keep repositories saved as disabled out of the filters. ### What the migration button does If this is your first time using Cosmos, complete Cosmos onboarding before starting the migration so Cosmos Advisor is available. Then select [**Migrate to Cosmos**](https://app.augmentcode.com/settings/code-review) in Code Review bot settings. It prepares a draft from the saved, non-secret settings on the page; review and send it to start the Cosmos Advisor session. If the complete prompt is too long for a link, the page copies it for you and offers a separate link to open Advisor. The button does not change Code Review bot settings, create the Deep Reviewer expert or automations, configure trigger filters, or enable anything. Check the repository inventory before sending the prompt. Or start from this [prefilled Cosmos Advisor session](https://cosmos.augmentcode.com/home?expertName=Cosmos+Advisor\&message=Help%20me%20migrate%20my%20complete%20saved%20Augment%20Code%20Review%20setup%20to%20Cosmos.%20Configure%20Deep%20Reviewer%20with%20one%20pull_request%20trigger%20for%20automatic%20reviews%20and%20one%20All%20events%20comment%20trigger%20whose%20advanced%20JSONLogic%20filter%20combines%20PR%20conversation%20and%20inline%20review%20comments%20with%20repository%20allow-lists.%20If%20a%20filter%20exceeds%20Cosmos%27s%204%2C096-byte%20limit%2C%20split%20its%20repository%20allow-list%20across%20additional%20non-overlapping%20shared%20triggers%20in%20the%20same%20full%20cutover.%20Keep%20all%20triggers%20disabled%20until%20I%20approve%20the%20cutover%20for%20all%20active%20repositories.). This link opens a generic draft; it does not load settings from Code Review. Add the recorded settings and custom review guidance, then send the prompt to start the session. The button's prompt includes MCP server IDs, not connected MCP servers. Configure those MCP servers in Cosmos and grant access separately (see [MCP configuration](/cosmos/config-mcp)). Never paste credentials into Cosmos Advisor. > [!NOTE] > > If the MCP servers you used for Code Review are already connected in Cosmos, you can attach the matching MCP configs to the Deep Reviewer expert. The IDs in the button's migration prompt can help identify them, but the button does not attach them automatically. Before cutover, confirm the expert has MCP access and the identity Cosmos uses to run reviews is authorized to use those servers. ## 1. Confirm Cosmos can access the repository 1. Open [GitHub integration settings](https://cosmos.augmentcode.com/integrations/github) and confirm the organization-level GitHub App connection is active. 2. Confirm the existing app installation has access to the target repositories. Ask your GitHub organization admin to grant access if a repository is missing. 3. Use the organization-level GitHub App integration for review access and posting as Augment. For triggered sessions, choose a dedicated service account under **Run sessions as** when that option is available; otherwise, use an appropriate trigger owner. For the setup flow, see [Getting Started with Cosmos](/cosmos/getting-started) and [Using GitHub as a Tool or Trigger](/cosmos/connectors/config-github). ## 2. Set up Deep Reviewer and its triggers To use Cosmos Advisor, use either option above. Review the draft prompt, add any missing settings or custom review guidance, and send it to start the session. Ask Cosmos Advisor to configure **Deep Reviewer only**, using the existing Deep Reviewer template as the setup model, and prepare two base shared GitHub triggers per supported host: one `pull_request` trigger for automatic reviews and one comment trigger with **All events** selected. Give the comment trigger an advanced JSONLogic filter that ORs PR-conversation comments (`issue.pull_request` present) with inline diff comments (top-level `pull_request` present), requires a new human comment containing a review command, and restricts `repository.full_name` to automatic and manual-command repositories. If a JSONLogic filter exceeds Cosmos's 4,096-byte limit, split its repository allow-list across additional non-overlapping shared triggers; include all triggers in the same full cutover. Put only automatic repositories in the `pull_request` allow-list; omit disabled repositories from both. Keep both triggers disabled until the approved full cutover for all active repositories. Never paste credentials. The PR Author expert is **not required to migrate from the Code Review bot**; it is a separate expert for creating and maintaining pull requests. Choose a dedicated service account under **Run sessions as** when available; this sets the session identity, while the organization-level GitHub App controls posting as Augment. Confirm the app can access each target repository. See [Configuring Triggers](/cosmos/config-triggers) for permissions. Configure the shared triggers to match the saved behavior: * **Automatic (`pull_request`):** include only automatic repositories; run for pull requests opened or marked ready for review, excluding drafts. * **PR comments:** the combined **All events** trigger includes both automatic and manual repositories. Its advanced filter matches new human comments containing `cosmos review`, `augment review`, or `auggie review`, and ORs the PR-conversation payload (`issue.pull_request`) with the inline diff-thread payload (top-level `pull_request`). This excludes ordinary issue comments and unrelated GitHub events. * **Disabled:** omit the repository from both allow-lists. * **Author restrictions:** preserve allowlists or denylists where supported. For public repositories, confirm the required membership, collaborator, or contributor access check. Review both repository allow-lists and event filters before cutover. Keep the shared Cosmos triggers disabled during setup. At the full cutover, disable the legacy triggers for all active repositories in the inventory, then enable the Cosmos triggers with the complete allow-lists. Do not leave a subset of active repositories on the legacy service. The handoff is coordinated but not atomic, so a GitHub event may arrive during the transition. See [Configure a Code Review Pipeline](/cosmos/experts-code-review) and [Automations](https://cosmos.augmentcode.com/automations) for more information. ## 3. Cut over the full inventory Cut over all repositories with active legacy reviews together. Repositories saved as disabled remain disabled and are omitted from the Cosmos filters. The handoff is coordinated but not atomic: a GitHub event may arrive between disabling the legacy triggers and enabling Cosmos. 1. In [Code Review bot settings](https://app.augmentcode.com/settings/code-review), disable the legacy triggers for every active repository in the migration inventory. 2. In Cosmos Advisor or the automation settings, set the shared repository allow-lists to the complete active inventory and enable the shared triggers. 3. Confirm that expected reviews start across the migrated inventory and that no duplicate reviews are posted. Leave saved disabled repositories disabled. Keep the existing Augment GitHub App installation and repository access for Cosmos. After all active repositories have moved and the legacy bot is off tenant-wide, you may add the former manual command as a Cosmos alias. ## 4. Troubleshoot with Cosmos Advisor If something does not work as expected during migration, ask the Cosmos Advisor agent to troubleshoot the configuration and help you complete the move. Do not leave both systems enabled for the same automatic or manual trigger behavior; that can create duplicate reviews. ## Learn about Cosmos [101 - Getting Started On Cosmos](/cosmos/guides/getting-started-on-cosmos) # Support for Other Platforms Source: https://docs.augmentcode.com/codereview/other-platforms Use Augment Code Review with GitLab, Bitbucket, Azure DevOps, and other platforms. > [!NOTE] > > For GitHub Enterprise Server, see the dedicated [GitHub Enterprise Server](/codereview/setup-github-enterprise-server) setup guide. ## GitLab, Bitbucket, Azure DevOps & Other Platforms You can set up code review on GitLab, Bitbucket, Azure DevOps, and other code review platforms using a **CLI-based automation**. This approach integrates Augment into your existing CI/CD pipelines to provide automated review comments on merge requests and pull requests. > [!NOTE] > > Enterprise customers can contact our sales team to get started — we'll help configure the CLI-based code review to use the Augment Code Review engine, > and help you deploy for your platform and environment. > **[Contact Sales](https://www.augmentcode.com/contact-sales)** > > Get in touch to set up CLI-based code review for your platform # Using Augment Code Review Source: https://docs.augmentcode.com/codereview/overview A native GitHub experience to catch critical issues, comment on pull requests, and collaborate on fixes. ## Quickstart **New Users** **1. Create an Augment Account** Visit [augmentcode.com](https://www.augmentcode.com) and click **Sign Up**. Complete registration with your email address, verify your email, and accept the terms of service during onboarding. **2. Connect GitHub to Configure your Repos for Code Review** Log in to [app.augmentcode.com](https://app.augmentcode.com), navigate to **Settings** → **Code Review** → **Configuration**, and click **Connect GitHub**. You'll be redirected to GitHub to authorize the app. Select the repositories you want to grant access to (all repositories or specific repos) and click **Install & Authorize**. **3. Choose Your Review Style** While on [Configuration](https://app.augmentcode.com/settings/code-review), select your preferred review style. **Thorough** (default) provides comprehensive coverage, catching 50% more bugs, while **Precise** focuses on the most critical issues with fewer comments. Learn more about [Review Styles](/codereview/review-style). **4. Set Review Trigger for Repositories** Navigate to **Settings** → **Code Review** → [Configuration](https://app.augmentcode.com/settings/code-review). Under **Repositories**, set the **Review Trigger** for each repository: **Automatic** (review triggers when a PR comes out of draft), **Manual Command** (review triggers by commenting `auggie review`), or **Disabled** (no reviews). **5. Submit Your First Review** Create a pull request on GitHub in any enabled repository. For automatic reviews, mark the PR as "ready for review" and Augment will analyze it within minutes. For manual reviews, add a comment with `auggie review` to trigger the analysis. **Enterprise Plan** **1. Contact Your Enterprise Administrator** Before using Code Review, your Enterprise Plan administrator must enable the feature for your organization. Request access to specific repositories or organization-wide access, and confirm any custom enterprise policies or guidelines. Provide your GitHub organization name and list of repositories you want to enable. **2. Install the Augment GitHub App** If not already installed, navigate to [app.augmentcode.com/settings/code-review](https://app.augmentcode.com/settings/code-review) and click **Connect GitHub**. Select your organization (requires organization admin permissions), choose repository access level, and click **Install & Authorize**. See [Setup Guide for Enterprise](/codereview/setup-guide-enterprise) for detailed instructions. **3. Choose Your Review Style** Navigate to **Settings** → **Code Review** → [Configuration](https://app.augmentcode.com/settings/code-review), select your preferred review style. **Thorough** (default) provides comprehensive coverage, catching 50% more bugs, while **Precise** focuses on the most critical issues with fewer comments. Review style will apply to all Repositories. Learn more about [Review Styles](/codereview/review-style). **4. Set Review Trigger for Repositories** **For Admins:** Navigate to **Settings** → **Code Review** → [Configuration](https://app.augmentcode.com/settings/code-review). Under **Repositories**, set the **Review Trigger** for each repository: **Automatic** (review triggers when a PR comes out of draft), **Manual Command** (review triggers by commenting `auggie review`), or **Disabled** (no reviews). **For Non-Admins:** Contact your administrator to request access to additional repositories. **5. Start Using Code Review** Create a pull request in an enabled repository. For automatic reviews, mark the PR as "ready for review". For manual reviews, comment `auggie review`. Code Review will analyze and post review comments. Address feedback and use the **Fix with Augment** button to resolve issues in your IDE. > **[Setup Guide for Enterprise Plan](/codereview/setup-guide-enterprise)** > > Enterprise Plan administrators can configure Augment Code Review and grant repository access on GitHub. **Business Plan** Follow these steps if you are on the Business plan. **1. Connect GitHub to Configure your Repos for Code Review** Visit [app.augmentcode.com/settings/code-review](https://app.augmentcode.com/settings/code-review) and log in. Click **Connect GitHub to Get Started** to install the Augment GitHub App. You'll be redirected to GitHub to authorize the app and select repositories. Choose **All repositories** for organization-wide access or **Only select repositories** for specific repos, then click **Install & Authorize**. **2. Set Review Trigger for Repositories** As an Administrator, navigate to **Settings** → **Code Review** → [Configuration](https://app.augmentcode.com/settings/code-review). Under **Repositories**, set the **Review Trigger** for each repository: **Automatic** (review triggers when a PR comes out of draft), **Manual Command** (review triggers by commenting `auggie review`), or **Disabled** (no reviews). **3. Choose Your Review Style** While on [Configuration](https://app.augmentcode.com/settings/code-review), select your preferred review style. **Thorough** (default) provides comprehensive coverage, catching 50% more bugs, while **Precise** focuses on the most critical issues with fewer comments. Learn more about [Review Styles](/codereview/review-style). **4. Start Reviewing Pull Requests** Create or open a pull request in GitHub. For automatic reviews, mark the PR as "ready for review". For manual reviews, comment `auggie review`, `augment review`, or `augmentcode review`. Code Review will add 👀 to show it's reviewing and post comments on any issues found. > **[Setup Guide for Business Plan](/codereview/setup-guide-otherplans)** > > Learn more about setting up Augment Code Review for the Business plan. *** ## Context powered code reviews focus on high-impact issues Augment Code Review prioritizes high signal-to-noise ratio by focusing on high-impact issues: * **Bugs**: Logic errors, edge cases, and potential runtime issues * **Security concerns**: Vulnerabilities, unsafe operations, and data exposure risks * **Correctness**: Null handling and error management * **Cross-system problems**: Breaking changes, API compatibility, and integration issues The agent avoids low-value style nags and focuses on objective issues by gathering context from multiple sources: * **PR Contents**: The agent analyzes the complete code diff to understand what changed and why. * **Entire Repository**: Through Augment's Context Engine, the agent has access to your full codebase, enabling it to identify cross-system impacts and maintain consistency with existing patterns. * **PR Title and Description**: More detailed PR descriptions help the agent provide better, more targeted reviews. Include information about: * What the PR accomplishes * Why the changes were made * Any special considerations or context *** ## Best Practices **Write detailed PR descriptions**: The more context you provide in your PR title and description, the better the agent can understand your intent and provide relevant feedback. **Use custom guidelines**: Define repository-specific review guidelines to help the agent focus on your team's priorities and domain-specific concerns. **Provide feedback**: Give feedback on comments using the thumbs up emoji to indicate whether the comment is useful or thumbs down if the comment was not helpful. **Ask for a follow-up review**: If you make significant changes to the PR and want another review, then ask for a follow-up review by commenting on your PR with the same comments as a manual request: `auggie review`, `augment review`, or `augmentcode review`. The agent will add 👀 to the comment so you know it is reviewing the PR. # Providing Feedback Source: https://docs.augmentcode.com/codereview/providing-feedback Learn how to provide feedback on Augment Code Review comments directly in GitHub. ## Providing feedback You can provide in product feedback directly in GitHub by reacting with a thumbs up or thumbs down emoji to the inline comment left by Augment Code Review. ![Code Review Feedback using GitHub Reactions](https://mintcdn.com/augment-mtje7p526w/hzSJfA0z3IKtZraV/images/code-review-github-feedback.png?fit=max\&auto=format\&n=hzSJfA0z3IKtZraV\&q=85\&s=4b5230f9a1ea82235d8275689aec130f) # Review Guidelines Source: https://docs.augmentcode.com/codereview/review-guidelines Configure custom guidelines to help Augment Code Review focus on specific areas and domain knowledge. Learn which files are automatically skipped and how to customize file exclusions. ## Tell Augment Code Review to check specific areas with guidelines Some domain knowledge cannot be inferred from code alone. Tell Augment Code Review exactly what to check by adding custom guidelines. ### Using AGENTS.md and CLAUDE.md If your repository already contains `AGENTS.md` or `CLAUDE.md` files, Augment Code Review automatically discovers and applies them. Rules from these files are included alongside any other guidelines you configure, so you don't need to duplicate content across formats. This is the recommended way to define guidelines for Augment Code Review, as it keeps your rules in one place and works across all Augment products. ### Adding code-review specific guidelines For more granular control over code review, you can define additional guidelines in a YAML file. This format supports structured severity levels, glob-scoped areas, and per-guideline analytics — features not available in markdown rule files. `/.augment/code_review_guidelines.yaml` Scope guidelines to the appropriate sub-directories and focus on objective issues that can cause bugs, expose vulnerabilities, etc. and less on stylistic or subjective things. ### Example Augment Code Review Guidelines For a complete working example, see the [Code Review Best Practices](https://github.com/augmentcode/code-review-best-practices) repository. ```yaml theme={null} # Guidelines exclusive to augmentcode/auggie areas: databases: description: "Data and Database related rules" globs: - "**" rules: - id: "no_pii_in_bigquery" description: "Never store PII data in BigQuery tables." severity: "high" - id: "no_guid_keys" description: "GUID foreign keys can slow lookups" severity: "medium" memory_safety: description: "Ensure Memory Safety" globs: - "kernel/**" rules: - id: "avoid_unsafe_rust" description: "Avoid unsafe Rust operations." severity: "high" ``` > [!NOTE] > > Common **globs** or pattern matching syntax: > > * `**` - Matches any number of directories (recursive wildcard) > * Example: `**/test.py` matches `test.py`, `src/test.py`, `src/utils/test.py`, etc. > * `*` - Matches any sequence of characters within a single directory level > * Example: `*.py` matches `file.py`, `main.py` but not `src/main.py` > * `?` - Matches exactly one character > * Example: `test?.py` matches `test1.py`, `testA.py` but not `test10.py` * **Rules:** Areas can contain more than one rule. Each rule contains: * **ID**: Double quoted unique identifier * **Description**: Double quoted message summarizing intent of the rule * **Severity**: Expects double quoted "high", "medium" or "low". Sets the priority of review by Augment Code Review ## Files Automatically Skipped During Review Augment Code Review automatically skips certain file types that are not typically code files. This helps focus the review on meaningful code changes and avoids wasting time on binary files, generated content, and other non-reviewable assets. > **File Extensions Automatically Ignored** > > The following file extensions are automatically skipped during code review: > > **Archive files:** > > * `.bz2`, `.gz`, `.xz`, `.zip`, `.7z`, `.rar`, `.zst`, `.tar`, `.jar`, `.war`, `.nar` > > **Image files:** > > * `.ico`, `.svg`, `.jpeg`, `.jpg`, `.png`, `.gif`, `.bmp`, `.tiff`, `.webm` > > **Font files:** > > * `.ttf`, `.otf`, `.woff`, `.woff2`, `.eot` > > **Document files:** > > * `.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx` > > **Data files:** > > * `.csv`, `.tsv`, `.dat`, `.db`, `.parquet` > > **System files:** > > * `.DS_Store`, `.tags` > > **Cscope files:** > > * `.cscope.files`, `.cscope.out`, `.cscope.in.out`, `.cscope.po.out` > > **Log and output files:** > > * `.log`, `.map`, `.out`, `.sum`, `.work`, `.md5sum` > > **3D and graphics files:** > > * `.tga`, `.dds`, `.psd`, `.fbx`, `.obj`, `.blend`, `.dae`, `.gltf` > > **Shader files:** > > * `.hlsl`, `.glsl` > > **Game engine files:** > > * `.unity`, `.umap`, `.prefab`, `.mat`, `.shader`, `.shadergraph`, `.sav`, `.scene`, `.asset` > > **Python compiled files:** > > * `.pyc`, `.pyd`, `.pyo`, `.pkl`, `.pickle` > > **Protocol buffer files:** > > * `.pb.go`, `.pb.gw.go` > > **Terraform files:** > > * `.tfstate`, `.tfstate.backup` > > **Minified files:** > > * `.min.js`, `.min.js.map`, `.min.css` > > **Lock and dependency files:** > > * `.lock`, `.lockb`, `.lockfile` > > **Debug and trace files:** > > * `.trace`, `.dump` > > **Backup files:** > > * `.bak`, `.backup` > > **Database files:** > > * `.sql.gz` > **File Patterns Automatically Ignored** > > In addition to specific extensions, the following file patterns are also skipped: > > * `*lock.json`, `*lock.yaml`, `*lock.yml` - Lock files with specific patterns > * `go.sum` - Go module checksum files > * `*.bundle.js`, `*.chunk.js` - JavaScript bundle files > * `**/generated/**`, `**/*.generated.*` - Generated files > * `*_snapshot.json` - Snapshot files ## Customizing Files to Skip You can add additional files or paths to skip during code review by specifying them in your custom guidelines file. This is useful for repository-specific generated files, large data files, or other content that shouldn't be reviewed. ### Adding Custom File Paths to Ignore Use the `file_paths_to_ignore` section in your `code_review_guidelines.yaml` file. This field supports doublestar glob patterns for flexible matching. ```yaml theme={null} # File paths to ignore during code review (supports doublestar glob patterns) file_paths_to_ignore: - "services/code_review/**/category_taxonomy.json" - "**/generated/**" - "**/*.generated.ts" - "dist/**" - "build/**" ``` > **Complete Example with Custom Ignores** > > ```yaml theme={null} > # Guidelines for myproject > > # Custom files to skip during review > file_paths_to_ignore: > - "services/code_review/**/category_taxonomy.json" > - "**/*.generated.graphql" > - "public/assets/**" > > areas: > databases: > description: "Data and Database related rules" > globs: > - "**" > rules: > - id: "no_pii_in_bigquery" > description: "Never store PII data in BigQuery tables." > severity: "high" > ``` # Understanding Review Styles Source: https://docs.augmentcode.com/codereview/review-style Choose the appropriate style for Augment Code Review to analyze your pull requests: Thorough (catch more) or Precise (less noise). ## Differences between the two Review Styles Augment Code Review offers two review styles that vary in coverage yet maintain the same low false positive rate. * **Thorough**: Provides comprehensive coverage, catching 50% more bugs than Precise. Ideal for teams that want maximum code quality assurance. * **Precise**: Focuses on the most critical issues with fewer overall comments. Best for teams that prefer a more targeted review approach. Set your review style on the [Configuration](https://app.augmentcode.com/settings/code-review). > [!NOTE] > > **Thorough** is the default review style for all users, but you can switch to **Precise** at any time. # Code Review with GitHub Enterprise Server Source: https://docs.augmentcode.com/codereview/setup-github-enterprise-server Configure Augment Code Review for GitHub Enterprise Server instances. ## GitHub Enterprise Server Support for Code Review Augment Code Review supports GitHub Enterprise Server (GHES) through a dedicated GitHub App integration. > [!NOTE] > > GitHub Enterprise Server support requires the Enterprise plan. You must be an administrator of your GitHub Enterprise Server organization to complete the setup. ## Installation For detailed installation instructions — including registration, permissions, and network requirements — see the [GitHub Enterprise Server Setup](/setup-augment/setup-github-enterprise-server) guide. Once the GitHub App is installed, return to this page to configure Code Review-specific settings. > [!NOTE] > > GHES integration requires bidirectional network connectivity between your GHES instance and Augment. Review the [network requirements](/setup-augment/setup-github-enterprise-server#network-requirements--limitations) before getting started. If your GHES instance does not support bidirectional connectivity, you can use a [CLI-based approach](/codereview/other-platforms) instead. ## Configuring Triggers Per Repository After installation, configure triggers the same way as GitHub Cloud. See the [Enterprise Setup Guide](/codereview/setup-guide-enterprise#configuring-triggers-per-repository) for full details on configuring automatic, manual, and disabled triggers. ## Next Steps Now that you've set up GitHub Enterprise Server, you can configure additional features: > **[Review Guidelines](/codereview/review-guidelines)** > > Set custom guidelines to focus reviews on specific areas > **[MCP Context](/codereview/mcp-context)** > > Connect external context sources via Model Context Protocol > **[User Access](/codereview/user-access)** > > Manage which users can trigger Code Review > **[Analytics Dashboard](/codereview/analytics-dashboard)** > > Track metrics and measure Code Review impact ## Need Help? If you encounter any issues during setup, check out our [Troubleshooting](/codereview/troubleshooting) guide. # Setup Guide for Enterprise Source: https://docs.augmentcode.com/codereview/setup-guide-enterprise Configure Augment Code Review for Enterprise accounts with multi-organization support. ## Using Augment Code Review natively inside of GitHub Augment Code Review helps professional software teams complete code-reviews faster inside GitHub while also catching more critical bugs before they hit production. Backed by Augment's industry-leading Context Engine, the agent understands your codebase at a deep level, providing reviews that are more meaningful and account for codebase-wide effects. Augment prioritizes high signal-to-noise ratio by focusing on high-impact issues like bugs, security concerns, correctness, and cross-system problems while avoiding low-value style nags. > [!NOTE] > > Augment Code Review relies on the Augment GitHub App which is compatible with GitHub Enterprise Cloud and github.com. For GitHub Enterprise Server, see the [GitHub Enterprise Server Setup Guide](/codereview/setup-github-enterprise-server). ## About the installation process Visit [app.augmentcode.com/settings/code-review](https://app.augmentcode.com/settings/code-review) and log in. Settings are accessible to all members of the Enterprise plan, but only configurable for Administrators of the Enterprise plan. If you aren't sure if you are an Administrator, please contact your solutions team. ### Install the Augment GitHub App Before you can configure repositories, install the Augment GitHub App and grant it access to the repositories you want to enable for Code Review. 1. Visit [app.augmentcode.com/settings/code-review](https://app.augmentcode.com/settings/code-review) and log in. 2. Click on the **Install GitHub App** button to begin the installation process. 3. Follow the prompts to grant Augment access to the repositories you want to enable for Code Review. For details on permissions, troubleshooting, and who can install the app, see [Install Augment GitHub App](/setup-augment/install-github-app). ### Configuring Triggers Per Repository As the Administrator, you control when Augment Code Review triggers via [Settings](https://app.augmentcode.com/settings/code-review). Look for "Set Review Trigger" to the right of the repository name. * **Automatic**: Augment Code Review will automatically review and post a comment as soon as the PR is opened for review in GitHub. Use it when your teams want immediate feedback on all pull requests. * **Manual Command**: Augment Code Review is only triggered when someone comments on the PR with any of the following: `auggie review`, `augment review`, or `augmentcode review` on GitHub. Use it when you want full control over when a review happens. * **Disabled**: Augment Code Review will not run on the repository. ![Trigger Types](https://mintcdn.com/augment-mtje7p526w/hzSJfA0z3IKtZraV/images/code-review-settings-triggers.png?fit=max\&auto=format\&n=hzSJfA0z3IKtZraV\&q=85\&s=96c0f0dfc2186287a71bba713f7c31a6) If the repo is set to "Automatic" or "Manual Command", to run additional rounds of reviews on a subsequent commit of any PR, you can use the same manual trigger keywords (`auggie review`, `augment review`, or `augmentcode review`). On public repositories, reviews are only triggered for PRs whose authors are members of the GitHub organization, outside collaborators to the organization or repository, or contributors to that repository. ## Next Steps Now that you've completed the basic setup, explore these additional features to get the most out of Augment Code Review: > **[GitHub Enterprise Server](/codereview/setup-github-enterprise-server)** > > Set up Code Review for self-hosted GitHub instances > **[Adding Another Organization](/codereview/adding-another-organization)** > > Configure Code Review across multiple GitHub organizations > **[Review Guidelines](/codereview/review-guidelines)** > > Set custom guidelines to focus reviews on specific areas > **[MCP Context](/codereview/mcp-context)** > > Connect external context sources via Model Context Protocol > **[User Access](/codereview/user-access)** > > Manage which users can trigger Code Review > **[Analytics Dashboard](/codereview/analytics-dashboard)** > > Track metrics and measure Code Review impact > **[Providing Feedback](/codereview/providing-feedback)** > > Learn how to provide feedback on reviews ## Need Help? If you encounter any issues during setup, check out our [Troubleshooting](/codereview/troubleshooting) guide. # Setup Guide for Business Plan Source: https://docs.augmentcode.com/codereview/setup-guide-otherplans Get started with Augment Code Review for the Business plan. ## Using Augment Code Review Augment Code Review is available as an add-on feature for individuals and teams. It provides automated code review directly in GitHub, helping you catch bugs and improve code quality before merging. Backed by Augment’s industry-leading Context Engine, the agent understands your codebase at a deep level, providing reviews that are more meaningful and account for codebase-wide effects. Augment prioritizes high signal-to-noise ratio by focusing on high-impact issues like bugs, security concerns, correctness, and cross-system problems while avoiding low-value style nags. ## About the installation process Visit [app.augmentcode.com/settings/code-review](https://app.augmentcode.com/settings/code-review) and log in. Settings are accessible to all [Team members](https://docs.augmentcode.com/teams/teams-admin-guide), but only configurable by Administrators of the plan. ### Install the Augment GitHub App Install the Augment GitHub App and grant it access to the repositories you want to enable for Code Review. 1. Visit [app.augmentcode.com/settings/code-review](https://app.augmentcode.com/settings/code-review) and log in. 2. Click on the **Install GitHub App** button to begin the installation process. 3. Follow the prompts to grant Augment access to the repositories you want to enable for Code Review. For details on permissions, troubleshooting, and who can install the app, see [Install Augment GitHub App](/setup-augment/install-github-app). > [!NOTE] > > Self-serve plans support a single GitHub organization. If you need to use Augment Code Review across multiple GitHub organizations, see [Enterprise Features](/codereview/enterprise-features#multi-organization-support). ### Configuring Triggers Per Repository As the Administrator, you control when Augment Code Review triggers via [Settings](https://app.augmentcode.com/settings/code-review). Look for "Set Review Trigger" to the right of the repository name. * **Automatic**: Augment Code Review will automatically review and post a comment as soon as the PR is opened for review in GitHub. Use it when your teams want immediate feedback on all pull requests. * **Manual Command**: Augment Code Review is only triggered when someone comments on the PR with any of the following: `auggie review`, `augment review`, or `augmentcode review` on GitHub. Use it when you want full control over when a review happens. * **Disabled**: Augment Code Review will not run on the repository. ![Trigger Types](https://mintcdn.com/augment-mtje7p526w/hzSJfA0z3IKtZraV/images/code-review-settings-triggers.png?fit=max\&auto=format\&n=hzSJfA0z3IKtZraV\&q=85\&s=96c0f0dfc2186287a71bba713f7c31a6) If the repo is set to "Automatic" or "Manual Command", to run additional rounds of reviews on a subsequent commit of any PR, you can use the same manual trigger keywords (`auggie review`, `augment review`, or `augmentcode review`). On public repositories, reviews are only triggered for PRs whose authors are members of the GitHub organization, outside collaborators to the organization or repository, or contributors to that repository. > [!NOTE] > > If you are an Enterprise customer, please refer to the [Enterprise setup guide](/codereview/setup-guide-enterprise) for additional information. ## Questions? If you have questions about Augment Code Review or want to learn more about Enterprise features: * Visit our [Support Center](https://support.augmentcode.com/) * Join our [Subreddit](https://www.reddit.com/r/AugmentCodeAI/) * Contact Us [Augment Support](https://portal.usepylon.com/augment-code/forms/augment-support) ## Related Resources * [Code Review Overview](/codereview/overview) - Learn about Code Review features * [Fix with Augment](/codereview/fix-with-augment) - Automatically fix issues in your IDE * [Setup Guide for Enterprise](/codereview/setup-guide-enterprise) - Full setup instructions for Enterprise # Troubleshooting Source: https://docs.augmentcode.com/codereview/troubleshooting Common issues and solutions for Augment Code Review setup and configuration. ## Known issues and Remediations ### Stuck on Install button If you still see the "Install" button on the Augment Code Review Configuration page, then the Augment GitHub App installation failed. You will need to uninstall the Augment GitHub App from your organization and then reinstall it. Make sure the person installing the GitHub app has an Augment account and they see the "All set!" text after installing the app. **1. Navigate to the Augment GitHub App settings page on GitHub** Follow the steps on [GitHub Docs](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#navigating-to-the-github-app-you-want-to-review-or-modify) to modify the Augment GitHub App installation. **2. Uninstall the Augment GitHub App from your organization** In the Danger zone section, click on "Uninstall" **3. Reinstall the Augment GitHub App** Follow the steps in [Configure Repo Access](/codereview/setup-guide-enterprise#install-the-augment-github-app) again to install the app ### Unable to see the repositories from Organization just added If you are unable to see the repositories from an organization you just added, then the Augment GitHub App installation failed for that organization. You will need to uninstall the Augment GitHub App from your organization and then reinstall it. Make sure the GitHub administrator installing the GitHub app has an Augment account and they see the "All set!" text after installing the app. **1. Navigate to the Augment GitHub App settings page on GitHub** Follow the steps on [GitHub Docs](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#navigating-to-the-github-app-you-want-to-review-or-modify) to modify the Augment GitHub App installation. **2. Uninstall the Augment GitHub App from your organization** In the Danger zone section, click on "Uninstall" **3. Reinstall the Augment GitHub App** Follow the steps in [Configure Repo Access](/codereview/setup-guide-enterprise#install-the-augment-github-app) again to install the app ### "Installation Already Exists" error If you see "Installation Already Exists" with the message "Only Enterprise accounts can connect multiple GitHub organizations" when trying to install the Augment GitHub App on a second GitHub organization, this is expected behavior for self-serve plans. Self-serve plans are limited to a single GitHub organization. To use Augment Code Review across multiple GitHub organizations simultaneously, you'll need to upgrade to an Enterprise plan. See [Enterprise Features](/codereview/enterprise-features) for more information. **1. Navigate to the Augment GitHub App settings page on GitHub** Follow the steps on [GitHub Docs](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#navigating-to-the-github-app-you-want-to-review-or-modify) to modify the Augment GitHub App installation. **2. Uninstall the Augment GitHub App from your existing organization** In the Danger zone section, click on "Uninstall" **3. Reinstall the Augment GitHub App on the new organization** Follow the steps in [Configure Repo Access](/codereview/setup-guide-enterprise#install-the-augment-github-app) to install the app on your new organization # User Access Source: https://docs.augmentcode.com/codereview/user-access Manage which GitHub users can trigger Augment Code Review with Allowlist Mode and Deny List. ## User Access Enterprise Plan administrators can control which GitHub users can trigger automatic Augment Code Review using two complementary features: **Allowlist Mode** and **Deny List**. Administrators can manage permissions at [User Access for Code Review](https://app.augmentcode.com/settings/code-review/user-access). ## Allowlist Mode When Allowlist Mode is active, only users in the allowlist will be able to trigger Augment Code Review. Automatic and manual reviews will be disabled for all other users. This is useful for organizations that want to limit access to the feature to a select group of users. To enable Allowlist Mode: 1. Navigate to [User Access for Code Review](https://app.augmentcode.com/settings/code-review/user-access) 2. Toggle on **Allowlist Mode** 3. Add GitHub usernames to the allowlist by entering them in the input field (separated by commas or spaces) 4. Press Enter or click **Add** to add users to the list > [!NOTE] > > If you enable Allowlist Mode, you must add at least one user to the allowlist. Otherwise, no users will be able to trigger Augment Code Review. ## Deny List The Deny List allows administrators to prevent specific GitHub users from triggering Augment Code Review. Users on the Deny List will not trigger code reviews, regardless of allowlist settings. Manual reviews can still be triggered by users not on the Deny List for a PR that was opened by a user on the Deny List. This feature is useful for: * Excluding bot accounts from triggering reviews * Temporarily preventing specific users from triggering automatic reviews * Managing exceptions to your allowlist configuration To add users to the Deny List: 1. Navigate to [User Access for Code Review](https://app.augmentcode.com/settings/code-review/user-access) 2. Scroll to the **Deny List** section 3. Add GitHub usernames to the deny list by entering them in the input field (separated by commas or spaces) 4. Press Enter or click **Add** to add users to the list > [!NOTE] > > The Deny List takes precedence over the Allowlist. If a user is on both lists, they will not be able to trigger automatic code reviews. # Custom Client Source: https://docs.augmentcode.com/context-services/context-connectors/advanced/custom-client Build custom search clients for your applications > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. Build custom search clients to load indexes and provide search functionality for web apps, CLIs, or serverless functions. ## Basic Search Client **TypeScript** ```typescript theme={null} import { SearchClient, FilesystemStore } from "@augmentcode/context-connectors"; // Create a search client const client = new SearchClient({ store: new FilesystemStore({ basePath: "./indexes" }), indexName: "my-docs", }); // Initialize (loads index from store) await client.initialize(); // Search const { results } = await client.search("authentication"); console.log(results); // Ask a question about the search results const answer = await client.searchAndAsk( "authentication", "How does auth work?" ); console.log(answer); ``` **Python** ```python theme={null} from auggie_sdk.context import DirectContext import os class SearchClient: def __init__(self, index_name: str, store_path: str = None): self.index_name = index_name self.store_path = store_path self.context = None def initialize(self): # Load search-optimized state (smaller, no file list) search_file = os.path.join(self.store_path, self.index_name, 'search.json') self.context = DirectContext.import_from_file(search_file) def search(self, query: str): return self.context.search(query) def ask(self, search_query: str, prompt: str = None): return self.context.search_and_ask(search_query, prompt) # Usage client = SearchClient('my-docs', store_path='./indexes') client.initialize() results = client.search('authentication') answer = client.ask('authentication', 'How does auth work?') ``` > [!NOTE] > > Search clients load `search.json` which is optimized for search operations. > The full `state.json` file is only needed by indexers for incremental updates. ## Web Application **TypeScript (Express)** ```typescript theme={null} import express from "express"; import { SearchClient, FilesystemStore } from "@augmentcode/context-connectors"; const app = express(); app.use(express.json()); // Initialize client at startup const client = new SearchClient({ store: new FilesystemStore(), indexName: "my-docs", }); await client.initialize(); app.post("/api/search", async (req, res) => { const { query } = req.body; const { results } = await client.search(query); res.json({ results }); }); app.post("/api/ask", async (req, res) => { const { query, question } = req.body; const answer = await client.searchAndAsk(query, question); res.json({ answer }); }); app.listen(3000); ``` **Python (Flask)** ```python theme={null} from flask import Flask, request, jsonify app = Flask(__name__) client = SearchClient('my-docs') client.initialize() @app.post('/api/search') def search(): query = request.json['query'] results = client.search(query) return jsonify({'results': results}) @app.post('/api/ask') def ask(): query = request.json['query'] prompt = request.json.get('prompt') answer = client.ask(query, prompt) return jsonify({'answer': answer}) ``` ## CLI Client **TypeScript** ```typescript theme={null} import { program } from "commander"; import { SearchClient, FilesystemStore } from "@augmentcode/context-connectors"; program .command("search ") .option("-i, --index ", "Index name", "my-project") .action(async (query, options) => { const client = new SearchClient({ store: new FilesystemStore(), indexName: options.index, }); await client.initialize(); const { results } = await client.search(query); console.log(results); }); program .command("ask ") .option("-i, --index ", "Index name", "my-project") .option("-q, --question ", "Question to ask") .action(async (query, options) => { const client = new SearchClient({ store: new FilesystemStore(), indexName: options.index, }); await client.initialize(); const answer = await client.searchAndAsk(query, options.question); console.log(answer); }); program.parse(); ``` **Python** ```python theme={null} import click @click.group() def cli(): pass @cli.command() @click.argument('query') @click.option('--index', default='my-project') def search(query, index): client = SearchClient(index) client.initialize() print(client.search(query)) @cli.command() @click.argument('query') @click.option('--index', default='my-project') @click.option('--prompt') def ask(query, index, prompt): client = SearchClient(index) client.initialize() print(client.ask(query, prompt)) if __name__ == '__main__': cli() ``` ## Serverless Function **TypeScript (AWS Lambda)** ```typescript theme={null} import { SearchClient, S3Store } from "@augmentcode/context-connectors"; let client: SearchClient | null = null; async function getClient() { if (!client) { client = new SearchClient({ store: new S3Store({ bucket: "my-indexes" }), indexName: "my-docs", }); await client.initialize(); } return client; } export async function handler(event: any) { const body = JSON.parse(event.body || "{}"); const { query } = body; const client = await getClient(); const { results } = await client.search(query); return { statusCode: 200, body: JSON.stringify({ results }), }; } ``` **Python (AWS Lambda)** ```python theme={null} import json client = None def get_client(): global client if client is None: client = SearchClient('my-docs') client.initialize() return client def lambda_handler(event, context): body = json.loads(event.get('body', '{}')) query = body.get('query') client = get_client() results = client.search(query) return { 'statusCode': 200, 'body': json.dumps({'results': results}) } ``` ## Next Steps * [Custom Indexer](/context-services/context-connectors/advanced/custom-indexer) - Build custom indexers * [Custom Store](/context-services/context-connectors/advanced/custom-store) - Custom storage backends * [DirectContext API Reference](/context-services/sdk/api-reference) - Complete API docs # Custom Indexer Source: https://docs.augmentcode.com/context-services/context-connectors/advanced/custom-indexer Build a custom indexer for any data source using DirectContext > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. Build a custom indexer to fetch content from any source (API, database, CMS) and index it with DirectContext. ## Basic Example **TypeScript** ```typescript theme={null} import { Indexer, FilesystemStore } from "@augmentcode/context-connectors"; import type { Source, FileEntry, FileChanges, SourceMetadata, FileInfo } from "@augmentcode/context-connectors"; // Implement the Source interface for your data source class ApiSource implements Source { readonly type = "custom" as const; async fetchAll(): Promise { // Replace with your actual data source (API, database, CMS, etc.) const response = await fetch("https://api.example.com/docs"); const docs = await response.json(); return docs.map((doc: any) => ({ path: doc.path, contents: doc.content, })); } async fetchChanges(previous: SourceMetadata): Promise { // Return null to always do full re-index // Or implement incremental updates based on your data source return null; } async getMetadata(): Promise { return { type: "custom", identifier: "api-docs", ref: new Date().toISOString(), syncedAt: new Date().toISOString(), }; } async listFiles(directory?: string): Promise { const files = await this.fetchAll(); return files.map(f => ({ path: f.path, type: "file" as const })); } async readFile(path: string): Promise { const files = await this.fetchAll(); return files.find(f => f.path === path)?.contents ?? null; } } // Usage const source = new ApiSource(); const store = new FilesystemStore({ basePath: "./indexes" }); const indexer = new Indexer(); const result = await indexer.index(source, store, "my-docs"); console.log(`Indexed ${result.filesIndexed} files (${result.type})`); ``` **Python** ```python theme={null} from auggie_sdk.context import DirectContext, File import json import os from pathlib import Path class CustomIndexer: def __init__(self, store_path: str = None): self.store_path = store_path def fetch_files(self): """Fetch from your data source (API, database, CMS, etc.)""" # Replace with your actual data source return [ File(path='docs/intro.md', contents='# Introduction\n...'), File(path='docs/api.md', contents='# API Reference\n...'), ] def index(self, index_name: str): index_dir = os.path.join(self.store_path, index_name) state_file = os.path.join(index_dir, 'state.json') # Load existing or create new context if os.path.exists(state_file): context = DirectContext.import_from_file(state_file) else: context = DirectContext.create() # Fetch and index files files = self.fetch_files() # Handle incremental updates indexed_paths = set(context.get_indexed_paths()) current_paths = {f.path for f in files} paths_to_remove = [p for p in indexed_paths if p not in current_paths] if paths_to_remove: context.remove_from_index(paths_to_remove) context.add_to_index(files) # Export both full and search-only states full_state = context.export(mode='full') search_state = context.export(mode='search-only') # Save both files Path(index_dir).mkdir(parents=True, exist_ok=True) with open(os.path.join(index_dir, 'state.json'), 'w') as f: json.dump(full_state, f, indent=2) with open(os.path.join(index_dir, 'search.json'), 'w') as f: json.dump(search_state, f, indent=2) # Usage indexer = CustomIndexer(store_path='./indexes') indexer.index('my-docs') ``` > [!NOTE] > > **Index Layout:** The indexer saves two files: > > * `state.json` - Full state including file path list (for incremental indexing) > * `search.json` - Optimized state without file list (smaller, for search clients) > > Search clients should load `search.json`. Indexers need `state.json` for incremental updates. ## Data Source Examples **TypeScript** **REST API:** ```typescript theme={null} async fetchAll(): Promise { const response = await fetch("https://api.example.com/docs"); const docs = await response.json(); return docs.map((doc: any) => ({ path: doc.path, contents: doc.content })); } ``` **Database:** ```typescript theme={null} async fetchAll(): Promise { const docs = await db.query("SELECT path, content FROM documents"); return docs.map(doc => ({ path: doc.path, contents: doc.content })); } ``` **Python** **REST API:** ```python theme={null} def fetch_files(self): response = requests.get('https://api.example.com/docs') return [File(path=doc['path'], contents=doc['content']) for doc in response.json()] ``` **Database:** ```python theme={null} def fetch_files(self): docs = db.query('SELECT path, content FROM documents') return [File(path=doc.path, contents=doc.content) for doc in docs] ``` ## Automation **Cron (Node.js):** ```bash theme={null} 0 * * * * cd /path/to/project && npx tsx indexer.ts ``` **Cron (Python):** ```bash theme={null} 0 * * * * cd /path/to/project && python indexer.py ``` **GitHub Actions:** See [GitHub Actions Auto-Indexing](/context-services/context-connectors/quickstart/github-actions-indexing) ## Next Steps * [Custom Store](/context-services/context-connectors/advanced/custom-store) - Custom storage backends * [Custom Client](/context-services/context-connectors/advanced/custom-client) - Build search clients * [DirectContext API Reference](/context-services/sdk/api-reference) - Complete API docs # Custom Store Source: https://docs.augmentcode.com/context-services/context-connectors/advanced/custom-store Create custom storage backends for your indexes > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. Create custom storage backends to save and load DirectContext state from local filesystem, S3, or any storage system. ## Local Filesystem Store **TypeScript** ```typescript theme={null} import { promises as fs } from "node:fs"; import { join } from "node:path"; import type { IndexStore, IndexState, IndexStateSearchOnly } from "@augmentcode/context-connectors"; class LocalStore implements IndexStore { constructor(private basePath: string = "./indexes") {} async save(key: string, fullState: IndexState, searchState: IndexStateSearchOnly): Promise { const indexDir = join(this.basePath, key); await fs.mkdir(indexDir, { recursive: true }); // Full state for incremental indexing await fs.writeFile(join(indexDir, "state.json"), JSON.stringify(fullState, null, 2)); // Search-optimized state (smaller) await fs.writeFile(join(indexDir, "search.json"), JSON.stringify(searchState, null, 2)); } async loadState(key: string): Promise { try { const data = await fs.readFile(join(this.basePath, key, "state.json"), "utf-8"); return JSON.parse(data); } catch { return null; } } async loadSearch(key: string): Promise { try { const data = await fs.readFile(join(this.basePath, key, "search.json"), "utf-8"); return JSON.parse(data); } catch { return null; } } async delete(key: string): Promise { await fs.rm(join(this.basePath, key), { recursive: true, force: true }); } async list(): Promise { const entries = await fs.readdir(this.basePath, { withFileTypes: true }); return entries.filter(e => e.isDirectory()).map(e => e.name); } } ``` **Python** ```python theme={null} import json import os from pathlib import Path class LocalStore: def __init__(self, base_path: str = None): self.base_path = base_path def save(self, index_name: str, full_state, search_state): """Save both full state and search-optimized state.""" index_dir = os.path.join(self.base_path, index_name) Path(index_dir).mkdir(parents=True, exist_ok=True) # Full state for incremental indexing with open(os.path.join(index_dir, 'state.json'), 'w') as f: json.dump(full_state, f, indent=2) # Search-optimized state (smaller) with open(os.path.join(index_dir, 'search.json'), 'w') as f: json.dump(search_state, f, indent=2) def load_state(self, index_name: str): """Load full state for incremental indexing.""" state_path = os.path.join(self.base_path, index_name, 'state.json') if not os.path.exists(state_path): return None with open(state_path, 'r') as f: return json.load(f) def load_search(self, index_name: str): """Load search-optimized state for search operations.""" search_path = os.path.join(self.base_path, index_name, 'search.json') if not os.path.exists(search_path): return None with open(search_path, 'r') as f: return json.load(f) # Usage store = LocalStore(base_path='./indexes') context = DirectContext.create() context.add_to_index([File(path='file.py', contents='...')]) # Export both states full_state = context.export(mode='full') search_state = context.export(mode='search-only') store.save('my-project', full_state, search_state) ``` ## S3 Store **TypeScript** ```typescript theme={null} import { S3Client, GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3"; import type { IndexStore, IndexState, IndexStateSearchOnly } from "@augmentcode/context-connectors"; class S3Store implements IndexStore { private client: S3Client; constructor( private bucket: string, private prefix = "context-connectors/" ) { this.client = new S3Client({}); } async save(key: string, fullState: IndexState, searchState: IndexStateSearchOnly): Promise { await Promise.all([ this.client.send(new PutObjectCommand({ Bucket: this.bucket, Key: `${this.prefix}${key}/state.json`, Body: JSON.stringify(fullState, null, 2), ContentType: "application/json", })), this.client.send(new PutObjectCommand({ Bucket: this.bucket, Key: `${this.prefix}${key}/search.json`, Body: JSON.stringify(searchState, null, 2), ContentType: "application/json", })), ]); } async loadState(key: string): Promise { try { const response = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: `${this.prefix}${key}/state.json`, })); const body = await response.Body?.transformToString(); return body ? JSON.parse(body) : null; } catch { return null; } } async loadSearch(key: string): Promise { try { const response = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: `${this.prefix}${key}/search.json`, })); const body = await response.Body?.transformToString(); return body ? JSON.parse(body) : null; } catch { return null; } } // ... delete() and list() implementations } // Usage const store = new S3Store("my-bucket"); ``` **Python** ```python theme={null} import boto3 import json class S3Store: def __init__(self, bucket: str, prefix: str = 'context-connectors/'): self.s3 = boto3.client('s3') self.bucket = bucket self.prefix = prefix def save(self, index_name: str, full_state, search_state): """Save both full state and search-optimized state.""" state_key = f'{self.prefix}{index_name}/state.json' search_key = f'{self.prefix}{index_name}/search.json' self.s3.put_object( Bucket=self.bucket, Key=state_key, Body=json.dumps(full_state, indent=2) ) self.s3.put_object( Bucket=self.bucket, Key=search_key, Body=json.dumps(search_state, indent=2) ) def load_state(self, index_name: str): """Load full state for incremental indexing.""" key = f'{self.prefix}{index_name}/state.json' try: response = self.s3.get_object(Bucket=self.bucket, Key=key) return json.loads(response['Body'].read()) except self.s3.exceptions.NoSuchKey: return None def load_search(self, index_name: str): """Load search-optimized state for search operations.""" key = f'{self.prefix}{index_name}/search.json' try: response = self.s3.get_object(Bucket=self.bucket, Key=key) return json.loads(response['Body'].read()) except self.s3.exceptions.NoSuchKey: return None # Usage store = S3Store('my-bucket') store.save('my-project', full_state, search_state) ``` > [!NOTE] > > **Built-in S3 Store:** The `@augmentcode/context-connectors` package includes a built-in `S3Store` class. Use it directly: > > ```typescript theme={null} > import { S3Store } from "@augmentcode/context-connectors"; > const store = new S3Store({ bucket: "my-bucket" }); > ``` ## Other Storage Examples **TypeScript** **Redis:** ```typescript theme={null} import { createClient } from "redis"; import type { IndexStore, IndexState, IndexStateSearchOnly } from "@augmentcode/context-connectors"; class RedisStore implements IndexStore { constructor(private redis: ReturnType) {} async save(key: string, fullState: IndexState, searchState: IndexStateSearchOnly): Promise { await Promise.all([ this.redis.set(`context:${key}:state`, JSON.stringify(fullState)), this.redis.set(`context:${key}:search`, JSON.stringify(searchState)), ]); } async loadState(key: string): Promise { const data = await this.redis.get(`context:${key}:state`); return data ? JSON.parse(data) : null; } async loadSearch(key: string): Promise { const data = await this.redis.get(`context:${key}:search`); return data ? JSON.parse(data) : null; } // ... delete() and list() implementations } ``` **Python** **Redis:** ```python theme={null} class RedisStore: def save(self, index_name: str, full_state, search_state): self.redis.set(f'context:{index_name}:state', json.dumps(full_state)) self.redis.set(f'context:{index_name}:search', json.dumps(search_state)) def load_state(self, index_name: str): data = self.redis.get(f'context:{index_name}:state') return json.loads(data) if data else None def load_search(self, index_name: str): data = self.redis.get(f'context:{index_name}:search') return json.loads(data) if data else None ``` **Database:** ```python theme={null} class DatabaseStore: def save(self, index_name: str, full_state, search_state): self.db.execute(''' INSERT INTO indexes (name, full_state, search_state) VALUES (%s, %s, %s) ON CONFLICT (name) DO UPDATE SET full_state = %s, search_state = %s ''', [index_name, json.dumps(full_state), json.dumps(search_state), json.dumps(full_state), json.dumps(search_state)]) def load_state(self, index_name: str): row = self.db.query_one('SELECT full_state FROM indexes WHERE name = %s', [index_name]) return json.loads(row['full_state']) if row else None def load_search(self, index_name: str): row = self.db.query_one('SELECT search_state FROM indexes WHERE name = %s', [index_name]) return json.loads(row['search_state']) if row else None ``` ## Index File Layout Each index consists of two files: | File | Purpose | Size | Used By | | - | - | - | - | | `state.json` | Full state with file paths | Larger | Indexers (for incremental updates) | | `search.json` | Search-optimized state | Smaller | Search clients | The `search.json` file excludes the blobs array (list of indexed file paths), making it much smaller for search-only use cases. Indexers need the full `state.json` to determine which files have changed for incremental updates. ## Next Steps * [Custom Indexer](/context-services/context-connectors/advanced/custom-indexer) - Build custom indexers * [Custom Client](/context-services/context-connectors/advanced/custom-client) - Build search clients * [Store Indexes in S3](/context-services/context-connectors/quickstart/share-with-s3) - S3 storage guide # CLI Reference Source: https://docs.augmentcode.com/context-services/context-connectors/cli-reference Complete command-line reference for Context Connectors > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. ## Global Requirements All commands require authentication. Set the `AUGMENT_SESSION_AUTH` environment variable to the session JSON from `auggie token print`: ```bash theme={null} auggie token print # Get your session JSON export AUGMENT_SESSION_AUTH='' ``` ## Data Storage By default, indexes are stored at `~/.augment/context-connectors`. Override with `--store-path` or the `CONTEXT_CONNECTORS_STORE_PATH` environment variable. ## Commands ### `index` - Index a data source Index code from various sources using source-specific subcommands. ```bash theme={null} npx ctxc index [options] ``` #### Subcommands | Source | Description | | - | - | | `github` | Index a GitHub repository | | `gitlab` | Index a GitLab project | | `bitbucket` | Index a Bitbucket repository | | `website` | Crawl and index a website | *** #### `index github` ```bash theme={null} npx ctxc index github [options] ``` | Option | Description | Default | | - | - | - | | `-i, --index ` | Index name (required) | - | | `--owner ` | Repository owner (required) | - | | `--repo ` | Repository name (required) | - | | `--ref ` | Branch, tag, or commit | `HEAD` | **Environment:** Requires `GITHUB_TOKEN` with repo read access. *** #### `index gitlab` ```bash theme={null} npx ctxc index gitlab [options] ``` | Option | Description | Default | | - | - | - | | `-i, --index ` | Index name (required) | - | | `--project ` | Project ID or path (required) | - | | `--ref ` | Branch, tag, or commit | `HEAD` | | `--gitlab-url ` | GitLab base URL (self-hosted) | `https://gitlab.com` | **Environment:** Requires `GITLAB_TOKEN` with repo read access. *** #### `index bitbucket` ```bash theme={null} npx ctxc index bitbucket [options] ``` | Option | Description | Default | | - | - | - | | `-i, --index ` | Index name (required) | - | | `--workspace ` | Workspace slug (required) | - | | `--repo ` | Repository name (required) | - | | `--ref ` | Branch, tag, or commit | `HEAD` | | `--bitbucket-url ` | Bitbucket base URL (Server/Data Center) | `https://api.bitbucket.org/2.0` | **Environment:** Requires `BITBUCKET_TOKEN` with repo read access. *** #### `index website` ```bash theme={null} npx ctxc index website [options] ``` | Option | Description | Default | | - | - | - | | `-i, --index ` | Index name (required) | - | | `--url ` | Website URL to crawl (required) | - | | `--max-depth ` | Maximum crawl depth | `3` | | `--max-pages ` | Maximum pages to crawl | `100` | | `--include ` | URL patterns to include (glob) | - | | `--exclude ` | URL patterns to exclude (glob) | - | *** #### Store Options (all index subcommands) | Option | Description | Default | | - | - | - | | `--store ` | Store type: `filesystem`, `s3` | `filesystem` | | `--store-path ` | Store base path | Platform-specific | **S3 Configuration (environment variables):** | Variable | Description | | - | - | | `AWS_ACCESS_KEY_ID` | AWS access key (required for S3) | | `AWS_SECRET_ACCESS_KEY` | AWS secret key (required for S3) | | `CC_S3_BUCKET` | S3 bucket name | | `CC_S3_ENDPOINT` | Custom endpoint URL (for S3-compatible services) | | `CC_S3_FORCE_PATH_STYLE` | Use path-style URLs (`true`/`false`) | #### Examples ```bash theme={null} # Index GitHub repo export GITHUB_TOKEN='ghp_...' npx ctxc index github --owner facebook --repo react -i react # Index GitLab project export GITLAB_TOKEN='glpat-...' npx ctxc index gitlab --project mygroup/myrepo -i myrepo # Index Bitbucket repo export BITBUCKET_TOKEN='...' npx ctxc index bitbucket --workspace myws --repo myrepo -i myrepo # Index website npx ctxc index website --url https://docs.example.com -i docs # Index to S3 export CC_S3_BUCKET='my-team-indexes' npx ctxc index github --owner myorg --repo myrepo -i my-project \ --store s3 ``` *** ### `list` - List local indexes List all indexes in the local store. ```bash theme={null} npx ctxc list [options] ``` #### Optional Options | Option | Description | Default | | - | - | - | | `--store-path ` | Store path to list from | `~/.augment/context-connectors` | #### Examples ```bash theme={null} # List all local indexes npx ctxc list # List from custom store path npx ctxc list --store-path /data/indexes ``` *** ### `delete` - Delete a local index Delete an index from the local store. ```bash theme={null} npx ctxc delete [options] ``` #### Arguments | Argument | Description | | - | - | | `` | Name of the index to delete (required) | #### Optional Options | Option | Description | Default | | - | - | - | | `--store-path ` | Store path containing the index | `~/.augment/context-connectors` | #### Examples ```bash theme={null} # Delete an index npx ctxc delete my-project # Delete from custom store path npx ctxc delete my-project --store-path /data/indexes ``` *** ### `search` - Search indexed content Search indexed content and answer questions using an LLM. ```bash theme={null} npx ctxc search [options] ``` #### Arguments | Argument | Description | | - | - | | `` | Search query / question (required) | #### Required Options | Option | Description | | - | - | | `-i, --index ` | Index spec: `name`, `path:/path`, or `s3://bucket/key` | #### Optional Options | Option | Description | Default | | - | - | - | | `--raw` | Return raw search results instead of LLM answer | `false` | | `--max-chars ` | Maximum output characters (only with `--raw`) | - | #### Index Spec Formats | Format | Example | Description | | - | - | - | | Name | `my-project` | Index from default store path | | Path | `path:/data/indexes/proj` | Direct filesystem path | | S3 | `s3://bucket/prefix/proj` | S3 location | #### Examples ```bash theme={null} # Ask a question (uses LLM to answer) npx ctxc search "How does authentication work?" -i my-project # Raw search results (no LLM) npx ctxc search "authentication logic" -i my-project --raw # Search S3-stored index npx ctxc search "API routes" -i s3://my-bucket/indexes/my-project # Search from a specific path npx ctxc search "database queries" -i path:/data/indexes/my-project ``` *** ### `agent` - Interactive AI agent Run an interactive AI agent that can search and read your codebase. ```bash theme={null} npx ctxc agent [query] [options] ``` #### Arguments | Argument | Description | | - | - | | `[query]` | Optional initial query | #### Required Options | Option | Description | | - | - | | `-i, --index ` | Index spec(s): `name`, `path:/path`, or `s3://bucket/key` | | `--provider ` | LLM provider: `augment`, `openai`, `anthropic`, `google` | #### Optional Options | Option | Description | Default | | - | - | - | | `--print` | Non-interactive mode: print response and exit | `false` | | `--model ` | Model to use | Provider-specific default | | `--max-steps ` | Maximum agent steps | `10` | | `-v, --verbose` | Show tool calls | `false` | | `--search-only` | Disable file operations | `false` | **Environment:** Requires provider-specific API key: * Augment: Uses existing Augment credentials (via `augment login` or environment variables) * OpenAI: `OPENAI_API_KEY` * Anthropic: `ANTHROPIC_API_KEY` * Google: `GOOGLE_API_KEY` **Default Models:** * Augment: `claude-sonnet-4-5` * OpenAI: `gpt-5-mini` * Anthropic: `claude-haiku-4-5` * Google: `gemini-3-flash-preview` #### Examples ```bash theme={null} # Using Augment provider (uses your existing Augment credentials) npx ctxc agent -i my-project --provider augment # Interactive mode with initial query (continues interactively after response) export ANTHROPIC_API_KEY='sk-ant-...' npx ctxc agent -i my-project --provider anthropic "How does auth work?" # Non-interactive mode (prints response and exits) npx ctxc agent -i my-project --provider anthropic "How does auth work?" --print # Using OpenAI provider export OPENAI_API_KEY='sk-...' npx ctxc agent -i my-project --provider openai # Multiple indexes npx ctxc agent -i my-project -i s3://bucket/other-project --provider openai # Verbose mode npx ctxc agent -i my-project --provider openai --verbose ``` *** ### `mcp stdio` - Run as MCP server (stdio) Run as an MCP server using stdio transport for integration with MCP-compatible agents like Claude Desktop. ```bash theme={null} npx ctxc mcp stdio [options] ``` #### Optional Options | Option | Description | Default | | - | - | - | | `-i, --index ` | Index spec(s): `name`, `path:/path`, or `s3://bucket/key` | All indexes | | `--search-only` | Disable file operations | `false` | When no `--index` is specified, all indexes in the default store are exposed. #### Examples ```bash theme={null} # Expose a specific index npx ctxc mcp stdio -i my-project # Multiple indexes npx ctxc mcp stdio -i my-project -i other-project # From S3 npx ctxc mcp stdio -i s3://my-bucket/indexes/my-project # All indexes in default store npx ctxc mcp stdio ``` *** ### `mcp http` - Start MCP HTTP server Start an MCP server accessible over HTTP for remote clients. ```bash theme={null} npx ctxc mcp http [options] ``` #### Optional Options | Option | Description | Default | | - | - | - | | `-i, --index ` | Index spec(s): `name`, `path:/path`, or `s3://bucket/key` | All indexes | | `--port ` | Port to listen on | `3000` | | `--host ` | Host to bind to | `localhost` | | `--cors ` | CORS origins (comma-separated, or `*`) | - | | `--base-path ` | Base path for MCP endpoint | `/mcp` | | `--api-key ` | API key for authentication | - | | `--search-only` | Disable file operations | `false` | **Environment:** Can use `MCP_API_KEY` instead of `--api-key` flag. #### Examples ```bash theme={null} # Basic HTTP server npx ctxc mcp http -i my-project --port 8080 # With authentication and CORS npx ctxc mcp http -i my-project --port 8080 \ --api-key "secret" --cors "*" # Accept external connections npx ctxc mcp http -i my-project --host 0.0.0.0 --port 8080 # Search-only mode npx ctxc mcp http -i my-project --search-only # From S3 npx ctxc mcp http -i s3://my-bucket/indexes/my-project --port 8080 ``` *** ## Common Patterns ### Using S3 Storage All commands support S3 storage for team sharing: ```bash theme={null} # Set AWS credentials and S3 bucket export AWS_ACCESS_KEY_ID='your-key' export AWS_SECRET_ACCESS_KEY='your-secret' export CC_S3_BUCKET='my-team-indexes' # Index to S3 npx ctxc index github --owner myorg --repo myrepo -i my-project \ --store s3 # Search from S3 npx ctxc search "query" -i s3://my-team-indexes/my-project ``` ### Using S3-Compatible Services For MinIO, DigitalOcean Spaces, Cloudflare R2, etc.: ```bash theme={null} export CC_S3_BUCKET='my-bucket' export CC_S3_ENDPOINT='http://localhost:9000' export CC_S3_FORCE_PATH_STYLE='true' npx ctxc index github --owner myorg --repo myrepo -i my-project \ --store s3 ``` ### File Operations The `--search-only` flag controls whether file operations are available: * **Without `--search-only`**: Enables `search`, `listFiles`, and `readFile` tools * **With `--search-only`**: Only `search` tool is available *** ## Troubleshooting ### "Index not found" Make sure the index spec points to the correct location (name, path, or S3 URL). ### "AUGMENT\_SESSION\_AUTH is not set" Set the required environment variable: ```bash theme={null} auggie token print # Get your session JSON export AUGMENT_SESSION_AUTH='' ``` ### S3 Access Denied Verify your AWS credentials and bucket permissions: ```bash theme={null} export AWS_ACCESS_KEY_ID='your-key' export AWS_SECRET_ACCESS_KEY='your-secret' ``` ### GitHub/GitLab/BitBucket Authentication Make sure the appropriate token is set: ```bash theme={null} export GITHUB_TOKEN='ghp_...' export GITLAB_TOKEN='glpat-...' export BITBUCKET_TOKEN='...' ``` # How It Works Source: https://docs.augmentcode.com/context-services/context-connectors/how-it-works Architecture and data flow of Context Connectors Context Connectors is a pipeline that indexes your code and content for semantic search. Here's how the pieces fit together. ## Architecture Content flows through five components: **1. Source** Connect to your content: GitHub, GitLab, BitBucket, or website **2. Indexer** Discover files, filter, chunk, and send to Context Engine for embedding **3. Store** Persist index state (local filesystem or S3) for incremental updates **4. Context Engine** Augment's semantic search backend stores embeddings and handles queries **5. Client** Query via CLI, MCP server, or your own application ## Data Flow ### Indexing When you run `ctxc index`, here's what happens: 1. **Discover** - Source connector lists all files (respects `.gitignore`) 2. **Filter** - Skip binary files, large files, excluded patterns 3. **Hash** - Compute file hashes to detect changes 4. **Diff** - Compare with stored state to find new/modified/deleted files 5. **Index** - Send changed files to Context Engine for embedding 6. **Save** - Store new state for next incremental run ### Searching When you run `ctxc search` or query via MCP: 1. **Query** - User submits natural language query 2. **Embed** - Context Engine converts query to vector 3. **Match** - Find semantically similar code chunks 4. **Return** - Results with file paths, line numbers, and snippets ### File Reading (MCP/Agent) When an agent needs full file content (not just search snippets): 1. **Request** - Agent requests file by path 2. **Fetch** - MCP server reads from original source (filesystem or Git API) 3. **Return** - Full file content returned to agent This is why MCP servers need source credentials (e.g., `GITHUB_TOKEN`) - they read files on demand from the original source, not from the index. ## Incremental Updates Context Connectors tracks file state to avoid re-indexing unchanged files: | Scenario | What Happens | | - | - | | File unchanged | Skipped (hash matches) | | File modified | Re-indexed | | File deleted | Removed from index | | New file | Added to index | State is stored in your chosen store: * **Local filesystem** - Platform-specific directory (e.g., `~/.local/share/context-connectors` on Linux) * **S3** - `s3://bucket/index-name/` prefix This makes subsequent runs fast - only changed files are processed. # Overview Source: https://docs.augmentcode.com/context-services/context-connectors/overview An open-source library built on the Context Engine SDK that makes diverse sources searchable across agents and apps > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. **Build indexes** from Git repos (GitHub, GitLab, BitBucket) or documentation websites. Index code, documentation, runbooks, schemas, configs, and more. Use DirectContext in the Context Engine SDK for custom sources. **Store indexes** on your local filesystem for fast & simple access, or in S3 for persistent storage in production apps. **Search indexes** via interactive agent, MCP for AI integrations, CLI for quick searches, or DirectContext in the Context Engine SDK for custom implementations. ## Getting Started **New to Context Connectors?** Here's a suggested path: 1. **Index and search** → [Index and Search Code](/context-services/context-connectors/quickstart/index-git-repos) (3 min) 2. **Connect an agent** → [Local MCP Server](/context-services/context-connectors/quickstart/claude-desktop-integration) (3 min) 3. **Build an app** → [Store Indexes in S3](/context-services/context-connectors/quickstart/share-with-s3) (5 min) 4. **Automate updates** → [GitHub Actions Auto-Indexing](/context-services/context-connectors/quickstart/github-actions-indexing) (5 min) Or jump directly to any recipe below. ## Quickstart Recipes > **[Index and Search Code](/context-services/context-connectors/quickstart/index-git-repos)** > > Index a Git repository and search or chat with it (3 minutes) > **[Index Websites](/context-services/context-connectors/quickstart/index-website)** > > Crawl and index documentation sites (3 minutes) > **[Local MCP Server](/context-services/context-connectors/quickstart/claude-desktop-integration)** > > Add codebase search to Claude Desktop, Claude Code, Cursor, or another agent (3 minutes) > **[Remote MCP Server](/context-services/context-connectors/quickstart/remote-mcp-server)** > > Expose indexes via MCP over HTTP for remote clients (3 minutes) > **[Store Indexes in S3](/context-services/context-connectors/quickstart/share-with-s3)** > > Store indexes in S3 for persistent storage in production apps (5 minutes) > **[GitHub Actions Auto-Indexing](/context-services/context-connectors/quickstart/github-actions-indexing)** > > Automatically re-index on every push using GitHub Actions (5 minutes) > **[Auto-Index with Webhooks](/context-services/context-connectors/quickstart/auto-index-webhook)** > > Custom webhook server for auto-indexing (advanced, 10 minutes) ## Advanced Recipes > **[Custom Indexer](/context-services/context-connectors/advanced/custom-indexer)** > > Build a custom indexer for any data source using DirectContext > **[Custom Store](/context-services/context-connectors/advanced/custom-store)** > > Create custom storage backends (local, S3, or any storage) > **[Custom Client](/context-services/context-connectors/advanced/custom-client)** > > Build custom search clients for your applications ## Documentation > **[CLI Reference](/context-services/context-connectors/cli-reference)** > > Complete command-line reference # Auto-Index with Webhooks Source: https://docs.augmentcode.com/context-services/context-connectors/quickstart/auto-index-webhook Set up a custom webhook server to re-index on push (advanced) in 10 minutes > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. ## Prerequisites * A Vercel account (or Express server) * Augment API credentials * AWS credentials + S3 bucket * A GitHub repo you control ## Steps ### 1. Create a Vercel project ```bash theme={null} npx create-next-app@latest my-webhook --typescript --app cd my-webhook npm install @augmentcode/context-connectors @aws-sdk/client-s3 ``` ### 2. Create the webhook handler Create `app/api/webhook/route.ts`: ```typescript theme={null} import { createVercelHandler } from "@augmentcode/context-connectors/integrations/vercel"; import { S3Store } from "@augmentcode/context-connectors/stores"; const store = new S3Store({ bucket: process.env.INDEX_BUCKET! }); export const POST = createVercelHandler({ store, secret: process.env.GITHUB_WEBHOOK_SECRET!, shouldIndex: (event) => event.ref === "refs/heads/main", }); ``` ### 3. Set environment variables in Vercel ``` AUGMENT_SESSION_AUTH= GITHUB_WEBHOOK_SECRET=your-secret INDEX_BUCKET=my-indexes AWS_ACCESS_KEY_ID=your-key AWS_SECRET_ACCESS_KEY=your-secret ``` ### 4. Deploy ```bash theme={null} npx vercel --prod ``` Note the URL (e.g., `https://my-webhook.vercel.app`). ### 5. Configure GitHub webhook 1. Go to your repo → Settings → Webhooks → Add webhook 2. Payload URL: `https://my-webhook.vercel.app/api/webhook` 3. Content type: `application/json` 4. Secret: same as `GITHUB_WEBHOOK_SECRET` 5. Events: Just the push event 6. Click "Add webhook" ### 6. Test it Push a commit to main. Check Vercel logs for: ``` Indexed myorg/myrepo: 142 files indexed ``` ## Done! Your index updates automatically on every push to main. ## Also Works With | Instead of... | Try... | | - | - | | Vercel | Express: `createExpressHandler()` from `integrations/express` | | Vercel | Any framework: `createGitHubWebhookHandler()` + `verifyWebhookSignature()` | | Main branch only | Customize `shouldIndex` to match any branch pattern | | S3 storage | `FilesystemStore` for local/self-hosted setups | # Local MCP Server Source: https://docs.augmentcode.com/context-services/context-connectors/quickstart/claude-desktop-integration Add codebase search to Claude Desktop, Claude Code, Cursor, or another agent in 3 minutes > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. ## Prerequisites * Claude Desktop installed * An indexed project (see [Index and Search Code](/context-services/context-connectors/quickstart/index-git-repos)) * Augment API credentials ## Steps ### 1. Open Claude Desktop config **macOS** ```bash theme={null} open ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` **Windows** ``` %APPDATA%\Claude\claude_desktop_config.json ``` ### 2. Add MCP server config **Local Filesystem** ```json theme={null} { "mcpServers": { "my-project": { "command": "npx", "args": ["ctxc", "mcp", "stdio", "-i", "my-project"], "env": { "AUGMENT_SESSION_AUTH": "" } } } } ``` **GitHub** ```json theme={null} { "mcpServers": { "my-project": { "command": "npx", "args": ["ctxc", "mcp", "stdio", "-i", "my-project"], "env": { "AUGMENT_SESSION_AUTH": "", "GITHUB_TOKEN": "ghp_..." } } } } ``` **GitLab** ```json theme={null} { "mcpServers": { "my-project": { "command": "npx", "args": ["ctxc", "mcp", "stdio", "-i", "my-project"], "env": { "AUGMENT_SESSION_AUTH": "", "GITLAB_TOKEN": "glpat-..." } } } } ``` **BitBucket** ```json theme={null} { "mcpServers": { "my-project": { "command": "npx", "args": ["ctxc", "mcp", "stdio", "-i", "my-project"], "env": { "AUGMENT_SESSION_AUTH": "", "BITBUCKET_TOKEN": "..." } } } } ``` ### 3. Restart Claude Desktop Quit and reopen Claude Desktop. ### 4. Test it Ask Claude: > Search for authentication logic in my-project You should see Claude use the search tool and return code snippets. ## Done! Your agent can now search your codebase via the local MCP server. ## Works With Other Agents This same configuration works with any MCP-compatible agent: * **Claude Desktop** - Follow the steps above * **Claude Code** (VS Code extension) - Add to Claude Code's MCP settings * **Cursor** - Configure in Cursor's MCP settings * **GitHub Copilot** - Add to Copilot's MCP configuration * **Custom agents** - Any tool that supports MCP stdio protocol Each agent has its own config file location, but the MCP server configuration is the same. ## Also Works With | Instead of... | Try... | | - | - | | One repo | Add multiple entries to `mcpServers` for different projects | | Local index | S3-stored indexes with `--store s3` and `CC_S3_BUCKET` env var | | Search only | Add `--search-only` to disable file reading | # GitHub Actions Auto-Indexing Source: https://docs.augmentcode.com/context-services/context-connectors/quickstart/github-actions-indexing Automatically index your repository on every push using GitHub Actions in 5 minutes > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. ## Prerequisites * A GitHub repository * Augment API credentials ## Steps ### 1. Create the workflow file Create `.github/workflows/augment-index.yml` in your repository: ```yaml theme={null} name: Index Repository on: push: branches: - main workflow_dispatch: # Allow manual triggering jobs: index: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Restore index state uses: actions/cache@v4 with: path: .augment-index-state key: augment-index-${{ github.ref_name }}-${{ github.sha }} restore-keys: | augment-index-${{ github.ref_name }}- - name: Index repository run: | npx @augmentcode/context-connectors index github \ --owner ${{ github.repository_owner }} \ --repo ${{ github.event.repository.name }} \ --ref ${{ github.sha }} \ -i ${{ github.repository_owner }}/${{ github.event.repository.name }} env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} AUGMENT_SESSION_AUTH: ${{ secrets.AUGMENT_SESSION_AUTH }} ``` ### 2. Set up GitHub repository secrets Go to your repository **Settings → Secrets and variables → Actions** and add: | Secret Name | Value | | - | - | | `AUGMENT_SESSION_AUTH` | Your Augment session JSON (from `auggie token print`) | **How to get your credentials:** ```bash theme={null} # Login to Augment auggie login # Print your session JSON auggie token print ``` Copy the full session JSON output and use it as the value for `AUGMENT_SESSION_AUTH`. ### 3. Commit and push ```bash theme={null} git add .github/workflows/augment-index.yml git commit -m "Add Augment indexing workflow" git push ``` ### 4. Verify it's working Go to your repository's **Actions** tab. You should see the "Index Repository" workflow running. Once complete, you can search your index: ```bash theme={null} export AUGMENT_SESSION_AUTH='' # from auggie token print npx ctxc search "authentication logic" -i myorg/myrepo ``` ## Done! Your repository will now automatically re-index on every push to the main branch. The workflow uses GitHub Actions cache to store index state for efficient incremental updates. ## Also Works With | Instead of... | Try... | | - | - | | Main branch only | Edit the workflow to add more branches: `branches: [main, develop]` | | GitHub cache | Use S3 storage: add `--store s3` and set `CC_S3_BUCKET` env var | | Custom index name | Change the `-i` value to your preferred name | ## How It Works The workflow: 1. **Triggers** on every push to your main branch 2. **Restores** the previous index state from GitHub Actions cache 3. **Indexes** the repository using the GitHub API (no checkout needed for indexing) 4. **Caches** the new index state for the next run This approach is much faster than full re-indexing on every push. ## Advanced: Using S3 Storage For production use or team sharing, you can store indexes in S3 instead of GitHub cache: 1. Edit `.github/workflows/augment-index.yml` 2. Add S3 configuration to the command: ```yaml theme={null} - name: Index repository run: | npx @augmentcode/context-connectors index github \ --owner ${{ github.repository_owner }} \ --repo ${{ github.event.repository.name }} \ --ref ${{ github.sha }} \ -i ${{ github.repository_owner }}/${{ github.event.repository.name }} \ --store s3 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} AUGMENT_SESSION_AUTH: ${{ secrets.AUGMENT_SESSION_AUTH }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} CC_S3_BUCKET: my-team-indexes ``` 3. Add AWS credentials to repository secrets This allows multiple repositories or team members to share the same index. # Index and Search Code Source: https://docs.augmentcode.com/context-services/context-connectors/quickstart/index-git-repos Index a Git repository and search or chat with it in 3 minutes > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. ## Prerequisites * Node.js 18+ * Augment authentication (via `auggie login` or `AUGMENT_SESSION_AUTH` environment variable) * Git provider token with repo read access: * GitHub: `GITHUB_TOKEN` * GitLab: `GITLAB_TOKEN` * BitBucket: `BITBUCKET_TOKEN` * For chat: An LLM API key (OpenAI, Anthropic, or Google) ## Steps ### 1. Install ```bash theme={null} npm install @augmentcode/context-connectors ``` ### 2. Set credentials **GitHub** ```bash theme={null} export AUGMENT_SESSION_AUTH='' # from auggie token print export GITHUB_TOKEN='your-github-token' ``` **GitLab** ```bash theme={null} export AUGMENT_SESSION_AUTH='' # from auggie token print export GITLAB_TOKEN='your-gitlab-token' ``` **BitBucket** ```bash theme={null} export AUGMENT_SESSION_AUTH='' # from auggie token print export BITBUCKET_TOKEN='your-bitbucket-token' ``` ### 3. Index the repository **GitHub** ```bash theme={null} npx ctxc index github --owner facebook --repo react -i react ``` **GitLab** ```bash theme={null} npx ctxc index gitlab --project mygroup/myrepo -i myrepo ``` **Bitbucket** ```bash theme={null} npx ctxc index bitbucket --workspace myws --repo myrepo -i myrepo ``` You should see: ``` Fetching file tree from facebook/react... Indexing complete: 2847 files indexed, 156 skipped ``` ### 4. Search ```bash theme={null} npx ctxc search "How does the reconciliation algorithm work?" -i react ``` You should see an LLM-generated answer based on the codebase: ``` Answer: Based on the code in packages/react-reconciler/src/ReactFiberReconciler.js... ``` For raw search results without LLM processing, add `--raw`: ```bash theme={null} npx ctxc search "reconciliation" -i react --raw ``` ### 5. Chat (Optional) For an interactive AI agent that can search and read the codebase: ```bash theme={null} export OPENAI_API_KEY='your-openai-key' npx ctxc agent -i react --provider openai ``` You should see: ``` Agent ready. Type your question or 'exit' to quit. > ``` Ask questions interactively: ``` > How does React handle component updates? Searching: "component updates"... Reading: packages/react-reconciler/src/ReactFiberWorkLoop.js... Based on the code, React handles component updates by... ``` Type `exit` to quit. ## Done! You can now: * **Search** your codebase semantically with the `search` command * **Chat** with an AI agent that understands your code using the `agent` command No need to clone the repository locally - Context Connectors fetches files directly from the Git provider API. ## Also Works With | Instead of... | Try... | | - | - | | Default branch | `--ref main`, `--ref v1.0.0`, or `--ref abc123` for specific branch/tag/commit | | Local storage | `--store s3` with `CC_S3_BUCKET` for team sharing | | Manual updates | Set up [GitHub Actions](/context-services/context-connectors/quickstart/github-actions-indexing) to re-index on every push | | Interactive chat | `npx ctxc agent -i react --provider openai "your question" --print` for single-question mode | | OpenAI | `--provider anthropic` or `--provider google` for other LLM providers | | Code repos | [Index websites](/context-services/context-connectors/quickstart/index-website) to chat with documentation sites | # Index Website Source: https://docs.augmentcode.com/context-services/context-connectors/quickstart/index-website Crawl and index a static website for semantic search in 3 minutes > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. ## Prerequisites * Node.js 18+ * Augment API credentials * For chat: An LLM API key (OpenAI, Anthropic, or Google) ## Steps ### 1. Install ```bash theme={null} npm install @augmentcode/context-connectors ``` ### 2. Set credentials ```bash theme={null} export AUGMENT_SESSION_AUTH='' # from auggie token print ``` ### 3. Index the site ```bash theme={null} npx ctxc index website --url https://docs.example.com -i example-docs ``` You should see: ``` Crawling https://docs.example.com... Indexing complete: 87 pages indexed, 12 skipped ``` ### 4. Search ```bash theme={null} npx ctxc search "how to configure SSO" -i example-docs ``` You should see an LLM-generated answer based on the documentation: ``` Answer: Based on the documentation at https://docs.example.com/auth/sso, SSO can be configured by... ``` For raw search results without LLM processing, add `--raw`: ```bash theme={null} npx ctxc search "SSO" -i example-docs --raw ``` ### 5. Chat (Optional) For an interactive AI agent that can search and read the documentation: ```bash theme={null} export OPENAI_API_KEY='your-openai-key' npx ctxc agent -i example-docs --provider openai ``` You should see: ``` Agent ready. Type your question or 'exit' to quit. > ``` Ask questions interactively: ``` > How do I set up SSO with Okta? Searching: "SSO Okta setup"... Reading: https://docs.example.com/auth/sso-okta... Based on the documentation, to set up SSO with Okta you need to... ``` Type `exit` to quit. ## Done! You can now: * **Search** the documentation semantically with the `search` command * **Chat** with an AI agent that understands the docs using the `agent` command ## Limitations * Only static HTML is indexed. JavaScript-rendered content (SPAs) won't work. * Only pages linked from the starting URL are discovered. ## Also Works With | Instead of... | Try... | | - | - | | Single site | Index multiple sites with different `-i` names | | Local storage | `--store s3` with `CC_S3_BUCKET` for team sharing | | Interactive chat | `npx ctxc agent -i example-docs --provider openai "your question" --print` for single-question mode | | OpenAI | `--provider anthropic` or `--provider google` for other LLM providers | # Remote MCP Server Source: https://docs.augmentcode.com/context-services/context-connectors/quickstart/remote-mcp-server Expose your index via MCP over HTTP for remote clients in 3 minutes > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. > [!NOTE] > > **For local MCP integration** with Claude Desktop, Claude Code, Cursor, or other agents, see [Local MCP Server](/context-services/context-connectors/quickstart/claude-desktop-integration). ## Prerequisites * Node.js 18+ * Augment API credentials * An indexed project (see [Index and Search Code](/context-services/context-connectors/quickstart/index-git-repos)) ## Steps ### 1. Install ```bash theme={null} npm install @augmentcode/context-connectors @modelcontextprotocol/sdk ``` ### 2. Set credentials ```bash theme={null} export AUGMENT_SESSION_AUTH='' # from auggie token print ``` ### 3. Start the server ```bash theme={null} npx ctxc mcp http -i my-project --port 8080 --api-key "secret" ``` You should see: ``` MCP HTTP server running at http://localhost:8080/mcp ``` ### 4. Test with curl First, initialize a session: ```bash theme={null} curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer secret" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "curl-test", "version": "1.0.0" } } }' -i ``` Note the `mcp-session-id` header in the response. Use it for subsequent requests: ```bash theme={null} curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer secret" \ -H "mcp-session-id: " \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "search", "arguments": { "query": "authentication" } } }' ``` You should see JSON search results. ## Done! Your index is accessible via MCP over HTTP at `http://localhost:8080/mcp`. Remote clients can now search your codebase using the Model Context Protocol over HTTP. ## Also Works With | Instead of... | Try... | | - | - | | localhost only | `--host 0.0.0.0` to accept external connections | | No CORS | `--cors "*"` or `--cors "https://myapp.com"` for browser clients | | Full access | `--search-only` to disable file operations | | Local storage | `--store s3` with `CC_S3_BUCKET` for shared indexes | # Store Indexes in S3 Source: https://docs.augmentcode.com/context-services/context-connectors/quickstart/share-with-s3 Store indexes in S3 for team sharing or application data management in 5 minutes > [!WARNING] > > **Experimental API** - Context Connectors is experimental and subject to breaking changes. S3 storage enables two key use cases: * **Team Sharing**: Multiple team members can search the same index * **Application Data**: Build apps that manage per-user indexes in S3 ## Prerequisites * Node.js 18+ * Augment API credentials * AWS credentials with S3 read/write access * An S3 bucket ## Steps ### 1. Install ```bash theme={null} npm install @augmentcode/context-connectors @aws-sdk/client-s3 ``` ### 2. Set credentials ```bash theme={null} export AUGMENT_SESSION_AUTH='' # from auggie token print export AWS_ACCESS_KEY_ID='your-key' export AWS_SECRET_ACCESS_KEY='your-secret' ``` ### 3. Index to S3 ```bash theme={null} export CC_S3_BUCKET='my-team-bucket' npx ctxc index github --owner myorg --repo myrepo -i my-project \ --store s3 ``` You should see: ``` Fetching file tree from myorg/myrepo... Indexing complete: 142 files indexed, 0 skipped Stored to s3://my-team-bucket/context-connectors/my-project/ ``` ### 4. Search from S3 Anyone with AWS credentials can now search: ```bash theme={null} npx ctxc search "How does authentication work?" \ -i s3://my-team-bucket/context-connectors/my-project ``` > [!NOTE] > > Indexes are stored under a `context-connectors/` prefix in your bucket. Include this prefix when searching. ## Done! Your index is stored in S3 at `s3://my-team-bucket/context-connectors/my-project/`. Share the S3 URL with your team. ## Also Works With | Instead of... | Try... | | - | - | | AWS S3 | MinIO: set `CC_S3_ENDPOINT` and `CC_S3_FORCE_PATH_STYLE=true` | | AWS S3 | DigitalOcean Spaces, Backblaze B2, Cloudflare R2 (use `CC_S3_ENDPOINT`) | | Manual indexing | [Auto-index on push](/context-services/context-connectors/quickstart/auto-index-webhook) with GitHub webhooks | # Context Engine MCP Source: https://docs.augmentcode.com/context-services/mcp/overview Plug Context Engine into any agent via the Model Context Protocol ## What is the Context Engine? Every AI uses the same models. **Context is the difference.** Augment's Context Engine maintains a live understanding of your entire stack: * **Semantic understanding** — Not just grep. A full search engine for code that understands meaning, not just text. * **Relationship awareness** — Understands how files connect across repos, services, and architectures. * **More than code** — Indexes commit history, codebase patterns, external sources (docs, tickets), and tribal knowledge. * **Smart curation** — Retrieves only what matters and compresses context without losing information. ## Local vs Remote Server | Aspect | Local Server | Remote Server | | - | - | - | | **Best for** | Making edits, new features, active development | Adding to codebase, understanding/talking to code | | **What's indexed** | Working directory in real-time | Selected repos' default branches (chosen during GitHub App install) | | **Setup** | Run Auggie CLI locally | GitHub App + [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) | ### Local Server (Recommended for Active Development) * Run the Auggie CLI locally as an MCP server (stdio) * Your client accesses `codebase-retrieval` for your working directory * Indexes in real-time as you edit — no manual sync required ### Remote Server (Best for Adding/Understanding Code) * Connect to Augment-hosted Context Engine over HTTP * Integrates with Augment GitHub App * Best for: * Adding to an existing codebase * Talking to / understanding the codebase * Cross-repo context * CI/server environments without a local working tree ### Usage cost for MCP Context Engine MCP queries are billed under [token-based pricing](/models/token-based-pricing): LLM tokens at the provider's public API list price plus the 40% service fee on LLM usage. Cost per query varies based on the underlying costs and amount of retrieval required — in our experience, the average cost is roughly $0.03–$0.06 per query. ## How Indexing Works ### Local Indexing * Real-time indexing of your working directory * Picks up local file changes immediately * No manual sync required ### Remote Indexing * Repositories connected via the Augment GitHub App are automatically indexed * **What's indexed:** All selected repositories' default branches (selected during GitHub App installation) * **When it updates:** Automatically when commits are pushed to the default branch ## Connect to MCP 1. **Sign up** at [augmentcode.com](https://augmentcode.com) 2. **Get your configuration** at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) The configuration page provides ready-to-use setup instructions for your MCP client, including authentication details for both interactive (OAuth) and non-interactive (API key) use cases. ## Quickstart Guides Get started with Context Engine MCP in your favorite AI tool: > **[Claude Code](/context-services/mcp/quickstart-claude-code)** > > Set up Context Engine MCP with Claude Code > **[Codex](/context-services/mcp/quickstart-codex)** > > Set up Context Engine MCP with OpenAI Codex CLI > **[Cursor](/context-services/mcp/quickstart-cursor)** > > Set up Context Engine MCP with Cursor > **[Zed](/context-services/mcp/quickstart-zed)** > > Set up Context Engine MCP with Zed > **[GitHub Copilot](/context-services/mcp/quickstart-github-copilot)** > > Set up Context Engine MCP with GitHub Copilot > **[OpenCode](/context-services/mcp/quickstart-open-code)** > > Set up Context Engine MCP with OpenCode > **[Kilo Code](/context-services/mcp/quickstart-kilo)** > > Set up Context Engine MCP with Kilo Code > **[Kiro](/context-services/mcp/quickstart-kiro)** > > Set up Context Engine MCP with Kiro > **[AntiGravity](/context-services/mcp/quickstart-anti-gravity)** > > Set up Context Engine MCP with AntiGravity > **[Gemini CLI](/context-services/mcp/quickstart-gemini-cli)** > > Set up Context Engine MCP with Gemini CLI > **[Roo Code](/context-services/mcp/quickstart-roo-code)** > > Set up Context Engine MCP with Roo Code > **[Droid (Factory.AI)](/context-services/mcp/quickstart-droid)** > > Set up Context Engine MCP with Droid # AntiGravity Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-anti-gravity Get started with Augment Context Engine MCP in AntiGravity in minutes **Local Server** ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Configure the MCP server in AntiGravity * Click the MCP server icon ![MCP server icon](https://mintcdn.com/augment-mtje7p526w/bPUsQPriBJwiNgJV/images/anti-gravity-1.png?fit=max\&auto=format\&n=bPUsQPriBJwiNgJV\&q=85\&s=0435ca2c51f4e1ba08dfb960e831d1b5) * Click manage MCP server ![Manage MCP server](https://mintcdn.com/augment-mtje7p526w/bPUsQPriBJwiNgJV/images/anti-gravity-2.png?fit=max\&auto=format\&n=bPUsQPriBJwiNgJV\&q=85\&s=0ac8123bfce7dcbbc06cad295e83d5cd) * Click View raw config ![View raw config](https://mintcdn.com/augment-mtje7p526w/bPUsQPriBJwiNgJV/images/anti-gravity-3.png?fit=max\&auto=format\&n=bPUsQPriBJwiNgJV\&q=85\&s=aba540233efbcb11816383c6c1cf2fe0) Paste this configuration: ```json theme={null} { "mcpServers": { "augment-context-engine": { "command": "auggie", "args": ["--mcp", "--mcp-auto-workspace"] } } } ``` ### 4. Test the integration ``` Prompt: "What is this project? Please use codebase retrieval tool to get the answer." ``` AntiGravity should confirm it has access to the `codebase-retrieval` tool. ![AntiGravity test](https://mintcdn.com/augment-mtje7p526w/bPUsQPriBJwiNgJV/images/anti-gravity-4.png?fit=max\&auto=format\&n=bPUsQPriBJwiNgJV\&q=85\&s=a047aed452e06af1c7d41e2c2461e731) See [MCP Server Mode](/cli/reference#mcp-server-mode) for more options. **Remote Server** 1. Sign up at [augmentcode.com](https://augmentcode.com) 2. Follow the setup instructions at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) # Claude Code Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-claude-code Get started with Augment Context Engine MCP in Claude Code in minutes **Local Server** ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Configure the MCP server in Claude Code Add the MCP server to user scope (available in all projects): ```bash theme={null} claude mcp add-json auggie --scope user '{"type":"stdio","command":"auggie","args":["--mcp","--mcp-auto-workspace"]}' ``` Or add to project scope (only available in the current project): ```bash theme={null} claude mcp add-json auggie --scope project '{"type":"stdio","command":"auggie","args":["--mcp","--mcp-auto-workspace"]}' ``` ### 4. Test the integration ```bash theme={null} claude --print "Do you have access to the Augment codebase retrieval tool? Answer in one sentence." ``` Claude should confirm it has access to the `codebase-retrieval` tool. ## Advanced: Non-Interactive Setup For non-interactive environments like CI/CD pipelines, GitHub Actions, or automated scripts where you cannot run `auggie login` interactively, you can configure authentication using environment variables. ### 1. Get your authentication session details ```bash theme={null} auggie token print ``` This will output your session JSON. ### 2. Configure with environment variables ```bash theme={null} claude mcp add-json auggie --scope user '{"type":"stdio","command":"auggie","args":["--mcp","--mcp-auto-workspace"],"env":{"AUGMENT_SESSION_AUTH":""}}' ``` Replace `` with the full session JSON output from step 1. **Remote Server** 1. Sign up at [augmentcode.com](https://augmentcode.com) 2. Follow the setup instructions at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) # Codex Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-codex Get started with Augment Context Engine MCP in OpenAI Codex CLI in minutes **Local Server** ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Configure the MCP server in Codex Add the MCP server using the Codex CLI: ```bash theme={null} codex mcp add codebase-retrieval -- auggie --mcp --mcp-auto-workspace ``` The `--mcp-auto-workspace` flag automatically detects your workspace when using Codex. ### 4. Test the integration Run Codex and prompt it with: ``` "What is this project? Please use the codebase-retrieval tool to get the answer." ``` Codex should confirm it has access to the `codebase-retrieval` tool. ## Advanced: Non-Interactive Setup For non-interactive environments like CI/CD pipelines, GitHub Actions, or automated scripts where you cannot run `auggie login` interactively, you can configure authentication using environment variables. ### 1. Get your authentication session details ```bash theme={null} auggie token print ``` This will output your session JSON. ### 2. Configure with environment variables ```bash theme={null} codex mcp add codebase-retrieval --env AUGMENT_SESSION_AUTH='' -- auggie --mcp --mcp-auto-workspace ``` Replace `` with the full session JSON output from step 1. **Remote Server** 1. Sign up at [augmentcode.com](https://augmentcode.com) 2. Follow the setup instructions at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) # Cursor Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-cursor Get started with Augment Context Engine MCP in Cursor in minutes **Local Server** ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Configure the MCP server in Cursor * Go to settings (top right) ![Cursor settings](https://mintcdn.com/augment-mtje7p526w/bPUsQPriBJwiNgJV/images/cursor-1.png?fit=max\&auto=format\&n=bPUsQPriBJwiNgJV\&q=85\&s=d1195573e43bb2307721f576674e5aae) * Click on **Tools & MCP** on the left menu then **New MCP Server** ![Cursor MCP](https://mintcdn.com/augment-mtje7p526w/bPUsQPriBJwiNgJV/images/cursor-2.png?fit=max\&auto=format\&n=bPUsQPriBJwiNgJV\&q=85\&s=8db7b7e8d319f1cb1de18744f602a8bb) Paste this configuration: ```json theme={null} { "mcpServers": { "augment-context-engine": { "type": "local", "command": "auggie", "args": ["--mcp", "--mcp-auto-workspace"], "enabled": true } } } ``` ### 4. Test the integration ``` Prompt: "What is this project? Please use codebase retrieval tool to get the answer." ``` Cursor should confirm it has access to the `codebase-retrieval` tool. ![Cursor test](https://mintcdn.com/augment-mtje7p526w/bPUsQPriBJwiNgJV/images/cursor-3.png?fit=max\&auto=format\&n=bPUsQPriBJwiNgJV\&q=85\&s=a33dfe584f3b9439ea2ba8e4ad485717) See [MCP Server Mode](/cli/reference#mcp-server-mode) for more options. **Remote Server** 1. Sign up at [augmentcode.com](https://augmentcode.com) 2. Follow the setup instructions at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) # Droid Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-droid Get started with Augment Context Engine MCP in Droid in minutes **Local Server** ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Configure the MCP server in Droid Add the Augment Context Engine MCP server: ```bash theme={null} droid mcp add augment-code "auggie" --mcp --mcp-auto-workspace ``` ### 4. Test the integration ``` Prompt: "Do you have access to the Augment codebase retrieval tool?" ``` Droid should confirm it has access to the `codebase-retrieval` tool. ## Advanced: Non-Interactive Setup For non-interactive environments like CI/CD pipelines, GitHub Actions, or automated scripts where you cannot run `auggie login` interactively, you can configure authentication using environment variables. ### 1. Get your authentication session details ```bash theme={null} auggie token print ``` This will output your session JSON. ### 2. Configure with environment variables ```bash theme={null} droid mcp add augment-code "auggie" --mcp --mcp-auto-workspace --env AUGMENT_SESSION_AUTH='' ``` Replace `` with the full session JSON output from step 1. **Remote Server** 1. Sign up at [augmentcode.com](https://augmentcode.com) 2. Follow the setup instructions at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) # Gemini CLI Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-gemini-cli Get started with Augment Context Engine MCP in Gemini CLI in minutes **Local Server** ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Configure the MCP server in Gemini CLI Gemini CLI reads the MCP server configuration from a settings file. You can configure MCP servers at either the user level (applies to all projects) or project level (applies only to that specific project): **Configuration file locations:** * **User settings** (global): * macOS/Linux: `~/.gemini/settings.json` * Windows: `%USERPROFILE%\.gemini\settings.json` * **Project settings** (optional): `.gemini/settings.json` in your project's root directory Add the following configuration to your Gemini CLI settings file: ```json theme={null} { "mcpServers": { "augment-context-engine": { "command": "auggie", "args": ["--mcp", "--mcp-auto-workspace"] } } } ``` ### 4. Test the integration Prompt the Gemini CLI with: ``` Prompt: "What is this project? Please use codebase retrieval tool to get the answer." ``` Gemini CLI should confirm it has access to the `codebase-retrieval` tool. See [MCP Server Mode](/cli/reference#mcp-server-mode) for more options. **Remote Server** 1. Sign up at [augmentcode.com](https://augmentcode.com) 2. Follow the setup instructions at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) # GitHub Copilot Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-github-copilot Get started with Augment Context Engine MCP in GitHub Copilot in minutes **Local Server** ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Configure the MCP server in GitHub Copilot * Please create the following file **at the root** of your project: **.vscode/mcp.json** * Paste this content inside and **Save** ```json theme={null} { "servers": { "augmentcode": { "type": "stdio", "command": "auggie", "args": ["--mcp", "--mcp-auto-workspace"] } }, "inputs": [] } ``` ### 4. Test the integration Prompt this in **AGENT MODE**: "What is this project? Please use codebase retrieval tool to get the answer." Copilot should confirm it has access to the `codebase-retrieval` tool. ![Copilot test](https://mintcdn.com/augment-mtje7p526w/bPUsQPriBJwiNgJV/images/copilot-1.png?fit=max\&auto=format\&n=bPUsQPriBJwiNgJV\&q=85\&s=fab7a23aa375687de73dc5e7ee9b8e2d) See [MCP Server Mode](/cli/reference#mcp-server-mode) for more options. **Remote Server** 1. Sign up at [augmentcode.com](https://augmentcode.com) 2. Follow the setup instructions at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) # Kilo Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-kilo Get started with Augment Context Engine MCP in Kilo in minutes **Local Server** ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Configure the MCP server in Kilo * Click the MCP server icon ![Click the MCP server icon](https://mintcdn.com/augment-mtje7p526w/rIravLuzI7-HsY1h/images/kilo-1.png?fit=max\&auto=format\&n=rIravLuzI7-HsY1h\&q=85\&s=db01b02e473bc0d81b0bbc0335d36540) * Click Edit Global MCP ![Click Edit Global MCP](https://mintcdn.com/augment-mtje7p526w/rIravLuzI7-HsY1h/images/kilo-2.png?fit=max\&auto=format\&n=rIravLuzI7-HsY1h\&q=85\&s=c7c319402a8842930e170de74aa27154) Paste this configuration: ```json theme={null} { "mcpServers": { "augment-context-engine": { "command": "auggie", "type": "stdio", "args": ["--mcp", "--mcp-auto-workspace"], "disabled": false, "alwaysAllow": ["codebase-retrieval"] } } } ``` ### 4. Test the integration Prompt: "What is this project? Please use codebase retrieval tool to get the answer." Kilo should confirm it has access to the `codebase-retrieval` tool. ![Kilo test](https://mintcdn.com/augment-mtje7p526w/rIravLuzI7-HsY1h/images/kilo-3.png?fit=max\&auto=format\&n=rIravLuzI7-HsY1h\&q=85\&s=643074aad72151ee9dffcb93459abb2c) See [MCP Server Mode](/cli/reference#mcp-server-mode) for more options. **Remote Server** 1. Sign up at [augmentcode.com](https://augmentcode.com) 2. Follow the setup instructions at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) # Kiro Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-kiro Get started with Augment Context Engine MCP in Kiro in minutes **Local Server** ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Configure the MCP server in Kiro Open the command palette (`Cmd + Shift + P` on Mac, `Ctrl + Shift + P` on Windows/Linux) and select: * **Kiro: Open workspace MCP config (JSON)** - For workspace-level configuration * **Kiro: Open user MCP config (JSON)** - For user-level configuration Paste this configuration: ```json theme={null} { "mcpServers": { "Augment-Context-Engine": { "command": "auggie", "args": ["--mcp", "--mcp-auto-workspace"], "disabled": false, "autoApprove": ["codebase-retrieval"] } } } ``` ### 4. Test the integration ``` Prompt: "Do you have access to the Augment codebase retrieval tool?" ``` Kiro should confirm it has access to the `codebase-retrieval` tool. See [MCP Server Mode](/cli/reference#mcp-server-mode) for more options. **Remote Server** 1. Sign up at [augmentcode.com](https://augmentcode.com) 2. Follow the setup instructions at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) # OpenCode Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-open-code Get started with Augment Context Engine MCP in OpenCode in minutes **Local Server** ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Configure the MCP server in OpenCode * Go to Folder: \~/.config/opencode/ * Create a file named: opencode.json Paste this configuration: ```json theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "augment-context-engine": { "type": "local", "command": ["auggie", "--mcp", "--mcp-auto-workspace"], "enabled": true } } } ``` ### 4. Test the integration ``` Prompt: "What is this project? Please use codebase retrieval tool to get the answer." ``` OpenCode should confirm it has access to the `codebase-retrieval` tool. ![OpenCode test](https://mintcdn.com/augment-mtje7p526w/rIravLuzI7-HsY1h/images/open-code-1.png?fit=max\&auto=format\&n=rIravLuzI7-HsY1h\&q=85\&s=81963a81b49d6c14ef9822004c1425f8) See [MCP Server Mode](/cli/reference#mcp-server-mode) for more options. **Remote Server** 1. Sign up at [augmentcode.com](https://augmentcode.com) 2. Follow the setup instructions at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) # Roo Code Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-roo-code Get started with Augment Context Engine MCP in Roo Code in minutes ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Install from the MCP Marketplace 1. Open Roo Code and go to **Settings** 2. Click **MCP Servers** on the left side 3. Click **MCP Marketplace** 4. Search for **Augment Context Engine** 5. Click **Install** ### 4. Test the integration ``` Prompt: "What is this project? Please use codebase retrieval tool to get the answer." ``` Roo Code should confirm it has access to the `codebase-retrieval` tool. See [MCP Server Mode](/cli/reference#mcp-server-mode) for more options. # Zed Quickstart Source: https://docs.augmentcode.com/context-services/mcp/quickstart-zed Get started with Augment Context Engine MCP in Zed in minutes **Local Server** ### 1. Install Auggie CLI ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` ### 2. Sign in to Augment ```bash theme={null} auggie login ``` This will open a browser window for authentication. ### 3. Configure the MCP server in Zed * Click the ... then **Add Custom Server** ![Zed custom server](https://mintcdn.com/augment-mtje7p526w/UAXlZ5LOydH6Jt19/images/zed-1.png?fit=max\&auto=format\&n=UAXlZ5LOydH6Jt19\&q=85\&s=4f89d1d4023e5b63227eed394765069e) * Paste the config below ![Zed MCP](https://mintcdn.com/augment-mtje7p526w/UAXlZ5LOydH6Jt19/images/zed-2.png?fit=max\&auto=format\&n=UAXlZ5LOydH6Jt19\&q=85\&s=1a602d03518a7382c58c4694b680ecfc) ```json theme={null} { "Augment-Context-Engine": { "enabled": true, "command": "auggie", "args": ["--mcp", "--mcp-auto-workspace"], "env": {} } } ``` ### 4. Test the integration Prompt: "What is this project? Please use codebase retrieval tool to get the answer." Zed should confirm it has access to the `codebase-retrieval` tool. ![Zed test](https://mintcdn.com/augment-mtje7p526w/UAXlZ5LOydH6Jt19/images/zed-3.png?fit=max\&auto=format\&n=UAXlZ5LOydH6Jt19\&q=85\&s=5663fb0c0cc565f0b890f96e4f846eb8) See [MCP Server Mode](/cli/reference#mcp-server-mode) for more options. **Remote Server** 1. Sign up at [augmentcode.com](https://augmentcode.com) 2. Follow the setup instructions at [app.augmentcode.com/mcp/configuration](https://app.augmentcode.com/mcp/configuration) # API Reference Source: https://docs.augmentcode.com/context-services/sdk/api-reference Complete API documentation for the Context Engine SDK > [!WARNING] > > **Experimental API** - Context Engine SDK is experimental and subject to breaking changes. ## DirectContext This class provides explicit file indexing via API calls with the ability to import and export state to avoid re-indexing between sessions. *** ## Examples ### Example 1: Simple Usage Upload files and ask questions immediately: ```typescript TypeScript theme={null} import { DirectContext } from '@augmentcode/auggie-sdk'; async function simpleExample() { // Create context (authentication is automatic) const context = await DirectContext.create(); // Add files and wait for indexing (default behavior) const result = await context.addToIndex([ { path: 'src/auth.ts', contents: 'export function login(user, pass) { ... }' }, { path: 'src/user.ts', contents: 'export class User { constructor(id) { ... } }' }, { path: 'README.md', contents: '# My Project\nAuthentication system' } ]); console.log(`Newly uploaded: ${result.newlyUploaded.length}`); // Ask questions about the code - files are already indexed const answer = await context.searchAndAsk( 'How does the login system work?' ); console.log('Answer:', answer); } simpleExample().catch(console.error); ``` ```python Python theme={null} from auggie_sdk.context import DirectContext, File def simple_example(): # Create context (authentication is automatic) context = DirectContext.create() # Add files and wait for indexing (default behavior) result = context.add_to_index([ File(path='src/auth.py', contents='def login(user, password): ...'), File(path='src/user.py', contents='class User:\n def __init__(self, id): ...'), File(path='README.md', contents='# My Project\nAuthentication system') ]) print(f"Newly uploaded: {len(result.newly_uploaded)}") # Ask questions about the code - files are already indexed answer = context.search_and_ask( 'How does the login system work?' ) print('Answer:', answer) if __name__ == '__main__': simple_example() ``` ### Example 2: Persistent Index Persist state between sessions to avoid re-indexing. This is useful when you want to save the index state to disk and reload it later without having to re-upload and re-index all files. The saved state file contains metadata about which files are indexed, allowing you to resume from where you left off: ```typescript TypeScript theme={null} import { DirectContext } from '@augmentcode/auggie-sdk'; // First session: Upload and save async function uploadAndSave() { const context = await DirectContext.create(); // Upload files await context.addToIndex([ { path: 'src/auth.ts', contents: 'export function login() { ... }' }, { path: 'src/user.ts', contents: 'export class User { ... }' }, { path: 'src/database.ts', contents: 'export function connect() { ... }' } ]); // Save state for later use - this creates a JSON file containing the index metadata // so you can reload it later without re-indexing all files await context.exportToFile('./my-project-context.json'); console.log('Context saved!'); console.log('You can now reload this state in a future session using importFromFile()'); } // Second session: Load, update incrementally, and save again async function updateAndSave() { // Load previous state - this restores the index without re-uploading files const context = await DirectContext.importFromFile('./my-project-context.json'); console.log('Context loaded from previous session - no re-indexing needed!'); // Make incremental changes - remove old file and add new one await context.removeFromIndex(['src/user.ts']); await context.addToIndex([ { path: 'src/profile.ts', contents: 'export class Profile { /* profile logic */ }' }, { path: 'src/settings.ts', contents: 'export function updateSettings() { /* settings */ }' } ]); console.log('Index updated incrementally'); // Save updated state await context.exportToFile('./my-project-context.json'); console.log('Updated context saved!'); } // Third session: Load and search async function loadAndSearch() { // Load the updated state const context = await DirectContext.importFromFile('./my-project-context.json'); console.log('Updated context loaded'); // Search immediately - files are already indexed const answer = await context.searchAndAsk( 'What user management features are implemented?' ); console.log('Answer:', answer); } // Run the complete workflow: upload → update → search uploadAndSave() .then(() => updateAndSave()) .then(() => loadAndSearch()) .catch(console.error); ``` ```python Python theme={null} from auggie_sdk.context import DirectContext, File # First session: Upload and save def upload_and_save(): context = DirectContext.create() # Upload files context.add_to_index([ File(path='src/auth.py', contents='def login(): ...'), File(path='src/user.py', contents='class User: ...'), File(path='src/database.py', contents='def connect(): ...') ]) # Save state for later use - this creates a JSON file containing the index metadata # so you can reload it later without re-indexing all files context.export_to_file('./my-project-context.json') print('Context saved!') print('You can now reload this state in a future session using import_from_file()') # Second session: Load, update incrementally, and save again def update_and_save(): # Load previous state - this restores the index without re-uploading files context = DirectContext.import_from_file('./my-project-context.json') print('Context loaded from previous session - no re-indexing needed!') # Make incremental changes - remove old file and add new one context.remove_from_index(['src/user.py']) context.add_to_index([ File(path='src/profile.py', contents='class Profile: # profile logic'), File(path='src/settings.py', contents='def update_settings(): # settings') ]) print('Index updated incrementally') # Save updated state context.export_to_file('./my-project-context.json') print('Updated context saved!') # Third session: Load and search def load_and_search(): # Load the updated state context = DirectContext.import_from_file('./my-project-context.json') print('Updated context loaded') # Search immediately - files are already indexed answer = context.search_and_ask( 'What user management features are implemented?' ) print('Answer:', answer) # Run the complete workflow: upload → update → search if __name__ == '__main__': upload_and_save() update_and_save() load_and_search() ``` ### Example 3: Batch Upload Then Wait When you need to upload many files in multiple batches, you can optimize performance by uploading all files first without waiting for indexing, then waiting once at the end. This approach is faster than waiting for indexing after each batch: ```typescript TypeScript theme={null} import { DirectContext } from '@augmentcode/auggie-sdk'; async function batchExample() { const context = await DirectContext.create(); // Upload multiple batches without waiting for indexing await context.addToIndex([ { path: 'src/auth.ts', contents: 'export function login() { ... }' }, { path: 'src/user.ts', contents: 'export class User { ... }' } ], { waitForIndexing: false }); await context.addToIndex([ { path: 'src/database.ts', contents: 'export function connect() { ... }' }, { path: 'src/api.ts', contents: 'export function createServer() { ... }' } ], { waitForIndexing: false }); // Wait for all files to be indexed console.log('Waiting for indexing to complete...'); await context.waitForIndexing(); console.log('All files indexed!'); // Now search - all files are guaranteed to be indexed const answer = await context.searchAndAsk( 'How do the database and auth systems work together?' ); console.log('Answer:', answer); } batchExample().catch(console.error); ``` ```python Python theme={null} from auggie_sdk.context import DirectContext, File def batch_example(): context = DirectContext.create() # Upload multiple batches without waiting for indexing context.add_to_index([ File(path='src/auth.py', contents='def login(): ...'), File(path='src/user.py', contents='class User: ...') ], wait_for_indexing=False) context.add_to_index([ File(path='src/database.py', contents='def connect(): ...'), File(path='src/api.py', contents='def create_server(): ...') ], wait_for_indexing=False) # Wait for all files to be indexed print('Waiting for indexing to complete...') context.wait_for_indexing() print('All files indexed!') # Now search - all files are guaranteed to be indexed answer = context.search_and_ask( 'How do the database and auth systems work together?' ) print('Answer:', answer) if __name__ == '__main__': batch_example() ``` ### Example 4: Custom Prompts Use searchAndAsk with custom prompts for diverse tasks: ```typescript TypeScript theme={null} import { DirectContext } from '@augmentcode/auggie-sdk'; async function creativeExample() { const context = await DirectContext.create(); // Upload some code await context.addToIndex([ { path: 'src/auth.ts', contents: 'export function login(user, pass) { /* auth logic */ }' }, { path: 'src/database.ts', contents: 'export function connect() { /* db connection */ }' }, { path: 'README.md', contents: '# My App\nA secure authentication system' } ]); // Creative prompts with searchAndAsk const poem = await context.searchAndAsk( 'authentication system', 'Write a haiku about this authentication code' ); console.log('Haiku:', poem); // Generate documentation const docs = await context.searchAndAsk( 'database authentication flow', 'Write a brief user guide explaining how to use the database authentication flow' ); console.log('Documentation:', docs); // Code review style analysis const review = await context.searchAndAsk( 'authentication logic', 'Provide a code review focusing on security best practices' ); console.log('Code Review:', review); } creativeExample().catch(console.error); ``` ```python Python theme={null} from auggie_sdk.context import DirectContext, File def creative_example(): context = DirectContext.create() # Upload some code context.add_to_index([ File(path='src/auth.py', contents='def login(user, password): # auth logic'), File(path='src/database.py', contents='def connect(): # db connection'), File(path='README.md', contents='# My App\nA secure authentication system') ]) # Creative prompts with search_and_ask poem = context.search_and_ask( 'authentication system', 'Write a haiku about this authentication code' ) print('Haiku:', poem) # Generate documentation docs = context.search_and_ask( 'database authentication flow', 'Write a brief user guide explaining how to use the database authentication flow' ) print('Documentation:', docs) # Code review style analysis review = context.search_and_ask( 'authentication logic', 'Provide a code review focusing on security best practices' ) print('Code Review:', review) if __name__ == '__main__': creative_example() ``` ### Example 5: External LLM Integration Use search() results with external LLM APIs: ```typescript TypeScript theme={null} import { DirectContext } from '@augmentcode/auggie-sdk'; // import { Anthropic } from '@anthropic-ai/sdk'; // import OpenAI from 'openai'; async function externalLLMExample() { const context = await DirectContext.create(); // Upload code await context.addToIndex([ { path: 'src/api.ts', contents: 'export function handleRequest() { /* API logic */ }' }, { path: 'src/auth.ts', contents: 'export function authenticate() { /* auth */ }' }, { path: 'src/database.ts', contents: 'export function query() { /* db query */ }' } ]); // Get formatted search results for external LLMs const codeContext = await context.search('API request handling'); // codeContext is a formatted string ready to embed in prompts for // Anthropic, OpenAI, or other LLM APIs console.log('Code context for LLM:', codeContext); // Example: Use with Anthropic Claude (uncomment to use) // const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }); // const response = await anthropic.messages.create({ // model: 'claude-sonnet-4-5-20250929', // max_tokens: 1000, // messages: [{ // role: 'user', // content: `Based on this code:\n\n${codeContext}\n\nHow can I improve the error handling in the API?` // }] // }); // console.log('Claude response:', response.content[0].text); // Example: Use with OpenAI GPT-5.1 (uncomment to use) // const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); // const completion = await openai.chat.completions.create({ // model: 'gpt-5.1', // messages: [{ // role: 'user', // content: `Based on this code:\n\n${codeContext}\n\nSuggest performance optimizations for this API.` // }] // }); // console.log('GPT-5.1 response:', completion.choices[0].message.content); } externalLLMExample().catch(console.error); ``` ```python Python theme={null} from auggie_sdk.context import DirectContext, File # import anthropic # import openai def external_llm_example(): context = DirectContext.create() # Upload code context.add_to_index([ File(path='src/api.py', contents='def handle_request(): # API logic'), File(path='src/auth.py', contents='def authenticate(): # auth'), File(path='src/database.py', contents='def query(): # db query') ]) # Get formatted search results for external LLMs code_context = context.search('API request handling') # code_context is a formatted string ready to embed in prompts for # Anthropic, OpenAI, or other LLM APIs print('Code context for LLM:', code_context) # Example: Use with Anthropic Claude (uncomment to use) # client = anthropic.Anthropic(api_key=os.environ['ANTHROPIC_API_KEY']) # response = client.messages.create( # model='claude-sonnet-4-5-20250929', # max_tokens=1000, # messages=[{ # 'role': 'user', # 'content': f'Based on this code:\n\n{code_context}\n\nHow can I improve the error handling?' # }] # ) # print('Claude response:', response.content[0].text) # Example: Use with OpenAI GPT-5.1 (uncomment to use) # client = openai.OpenAI(api_key=os.environ['OPENAI_API_KEY']) # completion = client.chat.completions.create( # model='gpt-5.1', # messages=[{ # 'role': 'user', # 'content': f'Based on this code:\n\n{code_context}\n\nSuggest performance optimizations.' # }] # ) # print('GPT-5.1 response:', completion.choices[0].message.content) if __name__ == '__main__': external_llm_example() ``` *** ## API Reference ### DirectContext.create() Create and initialize a new DirectContext instance. ```typescript TypeScript theme={null} static async create(options?: DirectContextOptions): Promise interface DirectContextOptions { apiKey?: string; // Optional - falls back to env vars or session.json apiUrl?: string; // Optional - falls back to env vars or session.json debug?: boolean; // Enable debug logging (default: false) } ``` ```python Python theme={null} @classmethod def create( cls, *, api_key: Optional[str] = None, api_url: Optional[str] = None, debug: bool = False, ) -> DirectContext ``` **Parameters:** * `options` - Optional configuration object * `apiKey` - API key for authentication (optional) * `apiUrl` - API URL for your tenant (optional) * `debug` - Enable debug logging (optional, default: false) **Authentication Priority:** 1. `options.apiKey` / `options.apiUrl` (passed to create()) 2. `AUGMENT_SESSION_AUTH` environment variable (session JSON from `auggie token print`) 3. `~/.augment/session.json` (created by `auggie login`) **Usage:** See complete examples above for full implementation details. **Notes:** * The SDK is **source-agnostic** - you provide files as `{path, contents}` objects * Files larger than 1MB are rejected during indexing * All indexing operations are serialized to ensure consistency * State can be saved and loaded to avoid re-indexing *** ### DirectContext.importFromFile() / import\_from\_file() Create a DirectContext instance from a saved state file. ```typescript TypeScript theme={null} static async importFromFile( filePath: string, options?: DirectContextOptions ): Promise ``` ```python Python theme={null} @classmethod def import_from_file( cls, file_path: str, *, api_key: Optional[str] = None, api_url: Optional[str] = None, debug: bool = False, ) -> DirectContext ``` **Parameters:** * `filePath` / `file_path` - Path to the saved state file * `options` - Optional configuration object (same as `create()`) **Returns:** A DirectContext instance with restored state **Usage:** ```typescript TypeScript theme={null} // Load context from saved state const context = await DirectContext.importFromFile('./my-context.json'); // Files are already indexed, ready to search ``` ```python Python theme={null} # Load context from saved state context = DirectContext.import_from_file('./my-context.json') # Files are already indexed, ready to search ``` *** ### DirectContext.import() / import\_state() Create a DirectContext instance from a saved state object. ```typescript TypeScript theme={null} static async import( state: DirectContextState, options?: DirectContextOptions ): Promise ``` ```python Python theme={null} @classmethod def import_state( cls, state: DirectContextState, *, api_key: Optional[str] = None, api_url: Optional[str] = None, debug: bool = False, ) -> DirectContext ``` **Parameters:** * `state` - The state object to restore from * `options` - Optional configuration object (same as `create()`) **Returns:** A DirectContext instance with restored state **Usage:** ```typescript TypeScript theme={null} // Load context from state object const savedState = JSON.parse(stateJson); const context = await DirectContext.import(savedState); ``` ```python Python theme={null} import json # Load context from state object with open('state.json') as f: saved_state = DirectContextState.from_dict(json.load(f)) context = DirectContext.import_state(saved_state) ``` *** ## DirectContext Methods ### addToIndex() / add\_to\_index() Add files to the index. Files can come from any source - memory, disk, API, database, etc. ```typescript TypeScript theme={null} async addToIndex( files: File[], options?: { waitForIndexing?: boolean } ): Promise interface File { path: string; // Relative path (e.g., "src/main.ts") contents: string; // File contents as string } interface IndexingResult { newlyUploaded: string[]; // Paths that were uploaded and indexed alreadyUploaded: string[]; // Paths that were skipped (already on server) } ``` ```python Python theme={null} def add_to_index( self, files: List[File], wait_for_indexing: bool = True ) -> IndexingResult @dataclass class File: path: str # Relative path (e.g., "src/main.py") contents: str # File contents as string @dataclass class IndexingResult: newly_uploaded: List[str] # Paths that were uploaded and indexed already_uploaded: List[str] # Paths that were skipped (already on server) ``` **Parameters:** * `files` - Array/list of file objects with `path` and `contents` * `options` / `wait_for_indexing` - Optional configuration * `waitForIndexing` / `wait_for_indexing` - If true (default), waits for the newly added files to be indexed before returning **Returns:** `IndexingResult` object with details about what was indexed **Notes:** * Files larger than 1MB will throw an error * By default, waits for backend indexing to complete before returning (set `waitForIndexing: false` / `wait_for_indexing=False` to return immediately after upload) * If a file with the same path already exists, it will be updated * All operations are serialized to ensure consistency * The SDK optimizes uploads by checking which blobs the server already has and only uploading missing ones *** ### removeFromIndex() / remove\_from\_index() Remove files from the index by path. ```typescript TypeScript theme={null} async removeFromIndex(paths: string[]): Promise ``` ```python Python theme={null} def remove_from_index(self, paths: List[str]) -> None ``` **Parameters:** * `paths` - Array/list of file paths to remove *** ### clearIndex() / clear\_index() Clear the entire index, removing all files. ```typescript TypeScript theme={null} async clearIndex(): Promise ``` ```python Python theme={null} def clear_index(self) -> None ``` *** ### getIndexedPaths() / get\_indexed\_paths() Get the list of currently indexed file paths. ```typescript TypeScript theme={null} getIndexedPaths(): string[] ``` ```python Python theme={null} def get_indexed_paths(self) -> List[str] ``` **Returns:** Array/list of relative file paths that are currently indexed **Use Cases:** * Display indexed files to users * Verify which files are included in the index * Filter files for targeted searches *** ### search() Search the codebase and return formatted results as a string. ```typescript TypeScript theme={null} async search( query: string, options?: { maxOutputLength?: number } ): Promise ``` ```python Python theme={null} def search( self, query: str, max_output_length: Optional[int] = None ) -> str ``` **Parameters:** * `query` - Natural language search query * `options` / `max_output_length` - Optional search options * `maxOutputLength` / `max_output_length` - Maximum character length of the formatted output (default: 20000, max: 80000) **Returns:** Formatted string containing the search results, ready for LLM consumption **Notes:** * Returns a formatted string designed for use in LLM prompts * The format includes file paths, line numbers, and code content * Does NOT wait for indexing - ensure files are indexed before searching by either: * Using `addToIndex()` / `add_to_index()` with `waitForIndexing: true` / `wait_for_indexing=True` (default) * Calling `waitForIndexing()` / `wait_for_indexing()` explicitly before searching * Throws an error if the index is empty *** ### searchAndAsk() / search\_and\_ask() Search the indexed codebase and ask an LLM a question about the results. This is a convenience method that combines `search()` with an LLM call to answer questions about your codebase. ```typescript TypeScript theme={null} async searchAndAsk( searchQuery: string, prompt?: string ): Promise ``` ```python Python theme={null} def search_and_ask( self, search_query: str, prompt: Optional[str] = None ) -> str ``` **Parameters:** * `searchQuery` / `search_query` - The semantic search query to find relevant code (also used as the prompt if no separate prompt is provided) * `prompt` - Optional prompt to ask the LLM about the search results. If not provided, searchQuery is used as the prompt. **Returns:** The LLM's answer to your question **Notes:** * Does NOT wait for indexing - ensure files are indexed before searching by either: * Using `addToIndex()` / `add_to_index()` with `waitForIndexing: true` / `wait_for_indexing=True` (default) * Calling `waitForIndexing()` / `wait_for_indexing()` explicitly before searching * Requires authentication via `auggie login`, `AUGMENT_SESSION_AUTH` environment variable, or API credentials for LLM access **Use Cases:** * Quick Q\&A about your codebase * Building conversational interfaces * Automated code analysis and documentation *** ### waitForIndexing() / wait\_for\_indexing() Wait for all indexed files to be fully indexed on the backend. This method polls the backend until all files that have been added to the index are confirmed to be indexed and searchable. ```typescript TypeScript theme={null} async waitForIndexing(): Promise ``` ```python Python theme={null} def wait_for_indexing(self) -> None ``` **Returns:** Promise that resolves when all files are indexed **Notes:** * Throws an error if indexing times out (default: 10 minutes) * Only waits for files that have been added to the index * Useful when you want to control when to wait for indexing completion **Use Cases:** * Batch upload multiple files quickly, then wait for all to be indexed * Ensure search results include all recently added files * Control timing of indexing waits in complex workflows *** ### exportToFile() / export\_to\_file() Export the current state to a file. ```typescript TypeScript theme={null} async exportToFile(filePath: string): Promise ``` ```python Python theme={null} def export_to_file(self, file_path: str) -> None ``` **Parameters:** * `filePath` / `file_path` - Path to save the state file **Use Cases:** * Persist indexing state between sessions * Avoid re-indexing large codebases * Share indexing state across different processes *** ### export() Export the current state as an object (in-memory). ```typescript TypeScript theme={null} export(): DirectContextState interface DirectContextState { checkpointId?: string; addedBlobs: string[]; deletedBlobs: string[]; blobs: BlobEntry[]; // Array of [blobName, path] tuples } ``` ```python Python theme={null} def export(self) -> DirectContextState @dataclass class DirectContextState: checkpoint_id: Optional[str] added_blobs: List[str] deleted_blobs: List[str] blobs: List[Tuple[str, str]] # List of (blob_name, path) tuples ``` **Returns:** State object that can be serialized and stored *** ## FileSystemContext This class provides automatic indexing and search capabilities for a local directory. ### FileSystemContext.create() Create and initialize a new FileSystemContext instance. ```typescript TypeScript theme={null} static async create(options: FileSystemContextOptions): Promise interface FileSystemContextOptions { directory: string; // Path to the workspace directory to index auggiePath?: string; // Path to auggie executable (default: "auggie") debug?: boolean; // Enable debug logging (default: false) } ``` ```python Python theme={null} @classmethod def create( cls, directory: str, *, auggie_path: str = "auggie", debug: bool = False, ) -> FileSystemContext ``` **Parameters:** * `options` / positional args - Configuration * `directory` - Path to the workspace directory to index (required) * `auggiePath` / `auggie_path` - Path to auggie executable (optional, default: "auggie") * `debug` - Enable debug logging (optional, default: false) **Usage:** See DirectContext examples above for similar patterns. **Notes:** * Automatically indexes the directory on startup * Requires `auggie` CLI to be installed and accessible * Python supports context manager (`with` statement) for automatic cleanup *** ## FileSystemContext Methods ### search() Search the codebase and return formatted results as a string. ```typescript TypeScript theme={null} async search(query: string): Promise ``` ```python Python theme={null} def search(self, query: str) -> str ``` **Parameters:** * `query` - Natural language search query **Returns:** Formatted string containing the search results, ready for LLM consumption *** ### searchAndAsk() / search\_and\_ask() Search the indexed codebase and ask an LLM a question about the results. ```typescript TypeScript theme={null} async searchAndAsk( searchQuery: string, prompt?: string ): Promise ``` ```python Python theme={null} def search_and_ask( self, search_query: str, prompt: Optional[str] = None ) -> str ``` **Parameters:** * `searchQuery` / `search_query` - The semantic search query to find relevant code (also used as the prompt if no separate prompt is provided) * `prompt` - Optional prompt to ask the LLM about the search results. If not provided, searchQuery is used as the prompt. **Returns:** The LLM's answer to your question **Notes:** * Requires authentication via `auggie login`, `AUGMENT_SESSION_AUTH` environment variable, or API credentials for LLM access *** ### close() Close the connection and cleanup resources. ```typescript TypeScript theme={null} async close(): Promise ``` ```python Python theme={null} def close(self) -> None ``` **Notes:** * Always call `close()` when done to cleanup resources * Python: Use context manager (`with` statement) for automatic cleanup *** ## Types ### File Represents a file to be indexed (input type for `addToIndex()` / `add_to_index()`). ```typescript TypeScript theme={null} interface File { path: string; // Relative path (e.g., "src/main.ts") contents: string; // File contents as string } ``` ```python Python theme={null} @dataclass class File: path: str # Relative path (e.g., "src/main.py") contents: str # File contents as string ``` ### IndexingResult Result from `addToIndex()` / `add_to_index()` operation showing what was indexed. ```typescript TypeScript theme={null} interface IndexingResult { newlyUploaded: string[]; // Paths that were uploaded and indexed alreadyUploaded: string[]; // Paths that were skipped (already on server) } ``` ```python Python theme={null} @dataclass class IndexingResult: newly_uploaded: List[str] # Paths that were uploaded and indexed already_uploaded: List[str] # Paths that were skipped (already on server) ``` **Notes:** * `newlyUploaded` / `newly_uploaded`: Files that were uploaded to the server and indexed * `alreadyUploaded` / `already_uploaded`: Files that were skipped because: * They were already in the local cache with the same content, OR * The server already had the blob (detected via `find-missing` API) ### DirectContextOptions (TypeScript) / Keyword Arguments (Python) Options for configuring DirectContext. ```typescript TypeScript theme={null} interface DirectContextOptions { apiKey?: string; // API key for authentication apiUrl?: string; // API URL for your Augment tenant debug?: boolean; // Enable debug logging (default: false) } ``` ```python Python theme={null} # In Python, these are passed as keyword arguments to create(): DirectContext.create( api_key: Optional[str] = None, # API key for authentication api_url: Optional[str] = None, # API URL for your Augment tenant debug: bool = False, # Enable debug logging (default: False) ) ``` ### DirectContextState State for DirectContext that can be saved/loaded. ```typescript TypeScript theme={null} interface DirectContextState { checkpointId?: string; // Current checkpoint ID addedBlobs: string[]; // Blob names added (pending checkpoint) deletedBlobs: string[]; // Blob names deleted (pending checkpoint) blobs: BlobEntry[]; // List of blobs as [blobName, path] tuples } type BlobEntry = [blobName: string, path: string]; ``` ```python Python theme={null} @dataclass class DirectContextState: checkpoint_id: Optional[str] # Current checkpoint ID added_blobs: List[str] # Blob names added (pending checkpoint) deleted_blobs: List[str] # Blob names deleted (pending checkpoint) blobs: List[Tuple[str, str]] # List of (blob_name, path) tuples def to_dict(self) -> Dict[str, Any]: """Convert to JSON-serializable dict.""" ... @classmethod def from_dict(cls, data: Dict[str, Any]) -> DirectContextState: """Create from JSON dict (e.g., from imported state file).""" ... ``` **Serialization Example:** ```typescript TypeScript theme={null} // DirectContextState is a plain object, use JSON.parse/stringify const stateJson = JSON.stringify(context.export()); const restoredState = JSON.parse(stateJson); const newContext = await DirectContext.import(restoredState); ``` ```python Python theme={null} import json # Export state and serialize to JSON state = context.export() state_json = json.dumps(state.to_dict()) # Later: deserialize and import data = json.loads(state_json) restored_state = DirectContextState.from_dict(data) new_context = DirectContext.import_state(restored_state) ``` ### FileSystemContextOptions (TypeScript) / Keyword Arguments (Python) Options for FileSystem Context. ```typescript TypeScript theme={null} interface FileSystemContextOptions { directory: string; // Path to the workspace directory to index auggiePath?: string; // Path to auggie executable (default: "auggie") debug?: boolean; // Enable debug logging (default: false) } ``` ```python Python theme={null} # In Python, these are passed as arguments to create(): FileSystemContext.create( directory: str, # Path to the workspace directory to index auggie_path: str = "auggie", # Path to auggie executable (default: "auggie") debug: bool = False, # Enable debug logging (default: False) ) ``` *** ## Authentication The SDK automatically loads credentials from multiple sources in this priority order: 1. **Options/keyword arguments**: `apiKey`/`api_key` and `apiUrl`/`api_url` passed to `DirectContext.create()` 2. **Environment variable**: `AUGMENT_SESSION_AUTH` (session JSON from `auggie token print`) 3. **Session file**: `~/.augment/session.json` (created by `auggie login`) **To get credentials:** 1. Sign in to Augment using the CLI: `auggie login` 2. Your credentials will be stored in `~/.augment/session.json` 3. The SDK will automatically use them *** ## Error Handling The SDK exports specific error classes for better error handling: | Error Class | Description | | - | - | | `BlobTooLargeError` | File exceeds 1MB limit. Includes `path` and `size` properties. | | `APIError` | Network or API request failures. Includes `status` property. | ```typescript TypeScript theme={null} import { DirectContext, APIError, BlobTooLargeError } from '@augmentcode/auggie-sdk'; try { const context = await DirectContext.create(); await context.addToIndex([ { path: 'test.ts', contents: '...' } ]); const results = await context.search('query'); } catch (error) { if (error instanceof BlobTooLargeError) { console.error('File too large (max 1MB):', error.path); } else if (error instanceof APIError) { console.error('API request failed:', error.message); console.error('Status code:', error.status); } else if (error.message.includes('API key is required')) { console.error('Missing credentials'); } else if (error.message.includes('Index not initialized')) { console.error('No files indexed yet'); } else { console.error('Operation failed:', error); } } ``` ```python Python theme={null} from auggie_sdk.context import DirectContext, File, APIError, BlobTooLargeError try: context = DirectContext.create() context.add_to_index([ File(path='test.py', contents='...') ]) results = context.search('query') except BlobTooLargeError as error: print('File too large (max 1MB):', error) except APIError as error: print('API request failed:', error) except ValueError as error: if 'API key is required' in str(error): print('Missing credentials') elif 'Index not initialized' in str(error): print('No files indexed yet') else: print('Operation failed:', error) except Exception as error: print('Operation failed:', error) ``` # Examples Source: https://docs.augmentcode.com/context-services/sdk/examples Example applications using the Auggie SDK > [!WARNING] > > **Experimental API** - Context Engine SDK is experimental and subject to breaking changes. ## Available Examples > **[Direct Context](#direct-context)** > > API-based indexing and search > **[FileSystem Context](#filesystem-context)** > > Local directory search > **[File Search Server](#file-search-server)** > > REST API for code search > **[Prompt Enhancer Server](#prompt-enhancer-server)** > > Context-aware prompt enhancement > **[GitHub Action Indexer](#github-action-indexer)** > > CI/CD repository indexing *** ## Getting the Examples All example code is available in the Auggie repository. To access the examples: ```bash TypeScript theme={null} git clone https://github.com/augmentcode/auggie.git cd auggie/examples/typescript-sdk/context ``` ```bash Python theme={null} git clone https://github.com/augmentcode/auggie.git cd auggie/examples/python-sdk/context ``` Each example is a complete, runnable application demonstrating different use cases of the Auggie SDK. ## Prerequisites Before running the examples: 1. **Runtime** - One of the following: * **TypeScript:** Node.js 18+ * **Python:** Python 3.10+ 2. **Auggie CLI** - Required for FileSystem Context examples ```bash theme={null} npm install -g @augmentcode/auggie@latest ``` 3. **Authentication** - Required for all examples ```bash theme={null} auggie login ``` This creates a session file at `~/.augment/session.json` with your API token. Alternatively, set the `AUGMENT_SESSION_AUTH` environment variable to the session JSON: ```bash theme={null} auggie token print # Get your session JSON export AUGMENT_SESSION_AUTH='' ``` ## Setup Install dependencies: ```bash TypeScript theme={null} cd examples/typescript-sdk/context npm install ``` ```bash Python theme={null} cd examples/python-sdk/context pip install auggie-sdk ``` *** ## Simple Examples Get started quickly with these basic examples that demonstrate core SDK functionality. ### Direct Context Demonstrates indexing files from any source and performing semantic searches with AI-powered question answering. **Quick Start:** ```bash TypeScript theme={null} npm run direct-context ``` ```bash Python theme={null} python -m direct_context ``` **Or run directly:** ```bash TypeScript theme={null} npx tsx direct-context/index.ts ``` ```bash Python theme={null} python direct_context/main.py ``` *** ### FileSystem Context Shows how to search a local directory using automatic file discovery via the MCP protocol. **Prerequisites:** * Auggie CLI must be installed and in your PATH * Authentication via `auggie login` or `AUGMENT_SESSION_AUTH` environment variable * A `.gitignore` or `.augmentignore` file in the workspace directory to exclude `node_modules/` and other large directories **Important:** The FileSystem Context indexes all files in the workspace directory. To avoid timeouts when indexing large directories (like `node_modules/`), make sure you have a `.gitignore` or `.augmentignore` file that excludes them. **Quick Start:** ```bash TypeScript theme={null} npm run filesystem-context ``` ```bash Python theme={null} python -m filesystem_context ``` **Or run directly:** ```bash TypeScript theme={null} npx tsx filesystem-context/index.ts ``` ```bash Python theme={null} python filesystem_context/main.py ``` *** ## Developer Tools Build production-ready applications with these server examples. ### File Search Server A REST API server that provides semantic file search with AI-powered summarization. **Prerequisites:** Auggie CLI must be installed and in your PATH. **Quick Start:** ```bash TypeScript theme={null} npm run file-search-server [workspace-directory] ``` ```bash Python theme={null} python -m file_search_server [workspace-directory] ``` Then query the API: ```bash theme={null} curl "http://localhost:3000/search?q=typescript" ``` **Or run directly:** ```bash TypeScript theme={null} npx tsx file-search-server/index.ts . ``` ```bash Python theme={null} python file_search_server/main.py . ``` *** ### Prompt Enhancer Server An HTTP server that automatically enriches user prompts with relevant codebase context. **Prerequisites:** Auggie CLI must be installed and in your PATH. **Quick Start:** ```bash TypeScript theme={null} npm run prompt-enhancer-server [workspace-directory] ``` ```bash Python theme={null} python -m prompt_enhancer_server [workspace-directory] ``` Then enhance prompts: ```bash theme={null} curl -X POST http://localhost:3001/enhance \ -H "Content-Type: application/json" \ -d '{"prompt": "fix the login bug"}' ``` **Or run directly:** ```bash TypeScript theme={null} npx tsx prompt-enhancer-server/index.ts . ``` ```bash Python theme={null} python prompt_enhancer_server/main.py . ``` *** ## CI/CD Integration Integrate the SDK into your continuous integration workflows. ### GitHub Action Indexer Automatically index your GitHub repositories with **zero-question setup** and incremental updates. Perfect for CI/CD workflows and keeping your codebase searchable. **Key Features:** * 🔄 **Incremental indexing** - Only processes changed files for efficiency * 💾 **Smart caching** - Persists index state between runs * 🚀 **30-second setup** - From zero to running GitHub Action **Installation:** ```bash TypeScript theme={null} # Install directly into your repository cd /path/to/your/repository npx @augment-samples/github-action-indexer install # Add your API secrets to GitHub repository settings # Push to trigger automatic indexing on every commit ``` ```bash Python theme={null} # From the auggie repo, install into your target repository cd examples/python-sdk/context python -m github_action_indexer install /path/to/your/repository # Add your API secrets to GitHub repository settings # Push to trigger automatic indexing on every commit ``` **What It Does:** 1. **Indexes** your codebase automatically on every push 2. **Updates** incrementally using GitHub's Compare API 3. **Caches** index state for fast subsequent runs 4. **Handles** large repositories with optimized performance settings **Perfect For:** * Keeping your codebase searchable and up-to-date * CI/CD workflows that need codebase understanding * Teams wanting automatic repository indexing * Projects with frequent commits (incremental updates are fast) **Try It Locally First:** ```bash TypeScript theme={null} cd github-action-indexer npm install export AUGMENT_SESSION_AUTH='' export GITHUB_TOKEN="your-github-token" export GITHUB_REPOSITORY="owner/repo" export GITHUB_SHA="$(git rev-parse HEAD)" npm run index npm run search "authentication functions" ``` ```bash Python theme={null} cd examples/python-sdk/context pip install -r github_action_indexer/augment_indexer/requirements.txt export AUGMENT_SESSION_AUTH='' export GITHUB_TOKEN="your-github-token" export GITHUB_REPOSITORY="owner/repo" export GITHUB_SHA="$(git rev-parse HEAD)" python -m github_action_indexer index python -m github_action_indexer search "authentication functions" ``` 📖 **Complete Setup Guides:** * [TypeScript GitHub Action Indexer →](https://github.com/augmentcode/auggie/tree/main/examples/typescript-sdk/context/github-action-indexer) * [Python GitHub Action Indexer →](https://github.com/augmentcode/auggie/tree/main/examples/python-sdk/context/github_action_indexer) *** ## Troubleshooting ### MCP Timeout in FileSystem Context **Problem:** The FileSystem Context example times out during indexing. **Cause:** The workspace directory contains too many files (e.g., `node_modules/` with 45,000+ files). **Solution:** Create a `.gitignore` or `.augmentignore` file in the workspace directory to exclude large directories: ```bash theme={null} # .gitignore or .augmentignore node_modules/ dist/ __pycache__/ .venv/ *.log .DS_Store ``` The auggie CLI respects both `.gitignore` and `.augmentignore` patterns and will skip excluded files during indexing. ### Authentication Errors **Problem:** `Error: API key is required for searchAndAsk()` or `ValueError: API credentials are required` **Cause:** The SDK cannot find your authentication credentials. **Solution:** Run `auggie login` to authenticate, or set the `AUGMENT_SESSION_AUTH` environment variable to the session JSON from `auggie token print`. *** ## Next Steps > **[API Reference](/context-services/sdk/api-reference)** > > Complete API documentation > **[Quick Start](/context-services/sdk/overview)** > > Back to quick start guide # Quickstart Source: https://docs.augmentcode.com/context-services/sdk/overview Get started with the Augment Context Engine SDK in minutes > [!WARNING] > > **Experimental API** - Context Engine SDK is experimental and subject to breaking changes. ## Installation ```bash TypeScript theme={null} npm install -g @augmentcode/auggie@latest && npm install @augmentcode/auggie-sdk ``` ```bash Python theme={null} npm install -g @augmentcode/auggie@latest pip install auggie-sdk ``` ## Getting Credentials Sign in to Augment using the CLI: ```bash theme={null} auggie login ``` Your credentials will be stored in `~/.augment/session.json` and the SDK will automatically use them. Alternatively, for automation or non-interactive environments, set the `AUGMENT_SESSION_AUTH` environment variable to the session JSON: ```bash theme={null} auggie token print # Get your session JSON export AUGMENT_SESSION_AUTH='' ``` > [!NOTE] > > The session JSON includes both your access token and tenant URL, so no separate URL variable is needed. Run `auggie token print` after logging in to get the full session JSON. ## Direct Context Explicitly index files from any source (APIs, databases, memory, disk) with full control over what gets indexed and the ability to save/load state: ```typescript TypeScript theme={null} import { DirectContext } from '@augmentcode/auggie-sdk'; async function main() { // Authentication is automatic via: // 1. Options parameters (apiKey, apiUrl passed to create()) // 2. AUGMENT_SESSION_AUTH environment variable (session JSON from `auggie token print`) // 3. ~/.augment/session.json (created by `auggie login`) const context = await DirectContext.create(); // Add files to index const result = await context.addToIndex([ { path: 'src/main.ts', contents: 'export function main() { ... }' }, { path: 'src/auth.ts', contents: 'export function authenticate() { ... }' } ]); console.log(`Newly uploaded: ${result.newlyUploaded.length}`); console.log(`Already uploaded: ${result.alreadyUploaded.length}`); // Search - returns formatted string ready for LLM use or display const results = await context.search('authentication logic'); console.log(results); // Or use searchAndAsk for one-step Q&A const answer = await context.searchAndAsk( 'How does authentication work?' ); console.log(answer); // Save state to avoid re-indexing await context.exportToFile('/tmp/state.json'); } main(); ``` ```python Python theme={null} from auggie_sdk.context import DirectContext, File def main(): # Authentication is automatic via: # 1. Options parameters (api_key, api_url passed to create()) # 2. AUGMENT_SESSION_AUTH environment variable (session JSON from `auggie token print`) # 3. ~/.augment/session.json (created by `auggie login`) context = DirectContext.create() # Add files to index result = context.add_to_index([ File(path='src/main.py', contents='def main(): ...'), File(path='src/auth.py', contents='def authenticate(): ...') ]) print(f"Newly uploaded: {len(result.newly_uploaded)}") print(f"Already uploaded: {len(result.already_uploaded)}") # Search - returns formatted string ready for LLM use or display results = context.search('authentication logic') print(results) # Or use search_and_ask for one-step Q&A answer = context.search_and_ask( 'How does authentication work?' ) print(answer) # Save state to avoid re-indexing context.export_to_file('/tmp/state.json') if __name__ == '__main__': main() ``` ## FileSystem Context Automatically index and search a local directory - just point to a directory path and start searching, perfect for local development and testing: ```typescript TypeScript theme={null} import { FileSystemContext } from '@augmentcode/auggie-sdk'; async function main() { const context = await FileSystemContext.create({ directory: '/path/to/workspace', }); // Search the directory const results = await context.search('authentication logic'); console.log(results); // Or ask a question const answer = await context.searchAndAsk( 'How does authentication work?' ); console.log(answer); // Clean up await context.close(); } main(); ``` ```python Python theme={null} from auggie_sdk.context import FileSystemContext def main(): # Use context manager for automatic cleanup with FileSystemContext.create('/path/to/workspace') as context: # Search the directory results = context.search('authentication logic') print(results) # Or ask a question answer = context.search_and_ask( 'How does authentication work?' ) print(answer) if __name__ == '__main__': main() ``` ## Next Steps > **[Examples](/context-services/sdk/examples)** > > See more example applications > **[API Reference](/context-services/sdk/api-reference)** > > Explore the complete API # Agent Integrations Source: https://docs.augmentcode.com/jetbrains/setup-augment/agent-integrations Configure integrations for Augment Agent to access external services like GitHub, Linear, Jira, Confluence, and Notion. ## About Agent Integrations Augment Agent can access external services through integrations to add additional context to your requests and take actions on your behalf. These integrations allow Augment Agent to seamlessly work with your development tools without leaving your editor. Once set up, Augment Agent will automatically use the appropriate integration based on your request context. Or, you can always mention the service in your request to use the integration. ## Setting Up Integrations To set up integrations with Augment Agent in JetBrains IDEs, follow these steps: 1. Click the Augment icon in the bottom right of your IDE and select Tools Settings 2. Click "Connect" for the integration you want to set up ![Set up integrations in the settings page](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/integration-settings.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=8e1cb7e476ff72baf79853e1a396061a) You'll be redirected to authorize the integration with the appropriate service. After authorization, the integration will be available for use with Augment Agent. ## Easy MCP Integrations > **New:** Easy MCP launched ONLY July 30, 2025, providing one-click access to popular developer tools. Easy MCP transforms complex MCP server setup into a single click. Available integrations include: * **CircleCI** - Build logs, test insights, and flaky-test detection * **MongoDB** - Data exploration, database management, and context-aware code generation * **Redis** - Keyspace introspection, TTL audits, and migration helpers For detailed setup instructions and examples, see [Configure MCP servers](/jetbrains/setup-augment/mcp). ## Native Integrations ## GitHub Integration Add additional context to your requests and take actions. Pull in information from a GitHub Issue, make the changes to your code (or have Agent do it for you), and open a Pull Request all without leaving your editor. ### Examples * "Implement Issue #123 and open up a pull request" * "Find all issues assigned to me" * "Check the CI status of my latest commit" For authorization details, see [GitHub documentation](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party). ## Linear Integration Read, update, comment on, and resolve your Linear issues within your IDE. ### Examples * "Fix TES-1" * "Create Linear tickets for these TODOs" * "Help me triage these new bug reports" For authorization details, see [Linear documentation](https://linear.app/docs/third-party-application-approvals). ## Jira Integration Work on your Jira issues, create new tickets, and update existing ones. ### Examples * "Show me all my assigned Jira tickets" * "Create a Jira ticket for this bug" * "Create a PR to fix SOF-123" * "Update the status of PROJ-123 to 'In Progress'" For authorization details, see [Jira documentation](https://support.atlassian.com/jira-software-cloud/docs/allow-oauth-access/). ## Confluence Integration Query existing documentation or update pages directly from your IDE. Ensure your team's knowledge base stays current without any context switching. ### Examples * "Summarize our Confluence page on microservice architecture" * "Find information about our release process in Confluence" * "Update our onboarding docs to explain how we use Bazel" For authorization details, see [Confluence documentation](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/). ## Notion Integration Search and retrieve information from your team's knowledge base - access documentation, meeting notes, and project specifications. This integration is currently READ-ONLY. ### Examples * "Find Notion pages about our API documentation" * "Show me the technical specs for the payment system" * "What outstanding tasks are left from yesterday's team meeting?" For authorization details, see [Notion documentation](https://www.notion.so/help/add-and-manage-connections-with-the-api#install-from-a-developer). ## Glean Integration > **Note:** The Glean integration is in early access and thus is a little different from other integrations. > > * It is currently only available to enterprise customers. > * It does not appear in the list of integrations in the settings panel. The Glean integration lets the agent retrieve information from your team's internal data sources leveraging Glean's powerful search engine. **To Enable the Glean Integration:** You'll need to be have administrator access to Augment and Glean. Follow the instructions on [https://app.augmentcode.com/gleanConfig](https://app.augmentcode.com/gleanConfig) and your agent will be ready to use Glean! ### Examples * "Search Glean for past related incidents and how they were resolved" * "Search Glean for why we're migrating to a new payment processor" ## Next Steps * [Configure additional tools with Easy MCP or advanced MCP setup](/jetbrains/setup-augment/mcp) * Explore one-click integrations for CircleCI, MongoDB, and Redis through Easy MCP # Install Augment for JetBrains IDEs Source: https://docs.augmentcode.com/jetbrains/setup-augment/install-jetbrains-ides Are you ready for your new superpowers? Augment brings agent and chat into your favorite JetBrains IDE. > [!NOTE] > > Augment requires version `2024.3` or above for all JetBrains IDEs. [See > JetBrains documentation](https://www.jetbrains.com/help/) on how to update > your IDE. > **[Get the Augment Plugin](https://plugins.jetbrains.com/plugin/24072-augment)** > > Install Augment for JetBrains IDEs ## About Installation Installing [Augment for JetBrains IDEs](https://plugins.jetbrains.com/plugin/24072-augment) is easy and will take you less than a minute. Augment is compatible with all JetBrains IDEs, including WebStorm, PyCharm, and IntelliJ. You can find the Augment plugin in the JetBrains Marketplace and install it following the instructions below. ![Augment plugin in JetBrains Marketplace](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/jetbrains-plugin.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=fb1192b9ebe85582db42bf74930e5db7) ## Installing Augment for JetBrains IDEs > [!NOTE] > > For these instructions we'll use *JetBrains IntelliJ* as an example, anywhere > you see *IntelliJ* replace the name of the JetBrains IDE you're using. > > In the case of Android Studio, which is based on IntelliJ, please ensure that your installation > uses a runtime with JCEF. Go to Help > Find Action, type Choose Boot Java Runtime for the IDE > and press Enter. Ensure the current runtime ends with `-jcef`; if not, select one **with JCEF** from the options > below. **1. Make sure you have the latest version of your IDE installed** You can download the latest version of JetBrains IDEs from the [JetBrains](https://www.jetbrains.com/ides/#choose-your-ide) website. If you already have IntelliJ installed, you can update to the latest version by going to IntelliJ IDEA > Check for Updates.... **2. Open the Plugins settings in your IDE** From the menu bar, go to IntelliJ IDEA > Settings..., or use the keyboard shortcut Cmd/Ctrl , to open the Settings window. Select Plugins from the sidebar. **3. Search for Augment in the marketplace** Using the search bar in the Plugins panel, search for Augment. **4. Install the extension** Click Install to install the extension. Then click OK to close the Settings window. **5. Sign into Augment and get coding** Sign in to by clicking Sign in to Augment in the Augment panel. If you do not see the Augment panel, use the shortcut Cmd/Ctrl L or click the Augment icon ![](https://mintcdn.com/augment-mtje7p526w/OQGzHw_wD-n9a1ch/images/augment-icon-simple.svg?fit=max\&auto=format\&n=OQGzHw_wD-n9a1ch\&q=85\&s=94af0dcc2ce5458f2ff3e86126115b5a) in the side bar of your IDE. See more details in [Sign In](/setup-augment/sign-in). ## Installing Beta versions of Augment for JetBrains IDEs In order to get a specific bug fix or feature, sometimes you may need to *temporarily* install a beta version of Augment for JetBrains IDEs. To do this, follow the steps below: **1. Download an archive of the beta version** You can download the latest beta version of Augment from [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/24072-augment/versions/beta?noRedirect=true) website. Please click Download on the latest version and save the archive to disk. **2. Open the Plugins settings in your IDE** From the menu bar, go to IntelliJ IDEA > Settings..., or use the keyboard shortcut Cmd/Ctrl , to open the Settings window. Select Plugins from the sidebar. **3. Install Augment from the downloaded archive** Click on the gear icon next to Installed tab and click Install plugin from disk.... Select the archive you downloaded in the previous step and click OK. # Keyboard Shortcuts for JetBrains IDEs Source: https://docs.augmentcode.com/jetbrains/setup-augment/jetbrains-keyboard-shortcuts Augment integrates with your IDE to provide keyboard shortcuts for common actions. Use these shortcuts to quickly accept suggestions, write code, and navigate your codebase. ## About keyboard shortcuts Augment is deeply integrated into your IDE and utilizes many of the standard keyboard shortcuts you are already familiar with. These shortcuts allow you to quickly accept suggestions, write code, and navigate your codebase. We also suggest updating a few keyboard shortcuts to make working with code suggestions even easier. **MacOS** To update keyboard shortcuts, use one of the following: | Method | Action | | :- | :- | | Keyboard | Cmd , select Keymap | | Menu bar | IntelliJ IDEA > Settings > Keymap | ## General | Action | Default shortcut | | :- | :- | | Open Augment panel | Cmd Option I | ## Chat | Action | Default shortcut | | :- | :- | | Focus or open Chat panel | Cmd Option I | ## Completions | Action | Default shortcut | | :- | :- | | Accept entire suggestion | Tab | | Accept word-by-word | Option Right | | Reject suggestion | Esc | | Toggle automatic completions | Cmd Option 9 | **Windows/Linux** To update keyboard shortcuts, use one of the following: | Method | Action | | :- | :- | | Keyboard | Ctrl , then select Keymap | | Menu bar | File > Settings > Keymap | ## General | Action | Default shortcut | | :- | :- | | Open Augment panel | Ctrl Alt I | ## Chat | Action | Default shortcut | | :- | :- | | Focus or open Chat panel | Ctrl Alt I | ## Completions | Action | Default shortcut | | :- | :- | | Accept entire suggestion | Tab | | Accept word-by-word | Ctrl Right | | Reject suggestion | Esc | | Toggle automatic completions | Ctrl Alt 9 | # Setup Model Context Protocol servers Source: https://docs.augmentcode.com/jetbrains/setup-augment/mcp Use Model Context Protocol (MCP) servers with Augment to expand Augment's capabilities with external tools and data sources. ## About Model Context Protocol servers Augment Agent can utilize external integrations through Model Context Protocol (MCP) to access external systems for information and integrate tools to take actions. MCP is an open protocol that provides a standardized way to connect AI models to different data sources and tools. MCP servers can be used to access local or remote databases, run automated browser testing, send messages to Slack or even play music on Spotify. ## Easy MCP: One-Click Integrations > **New:** Easy MCP launched on July 30, 2025, making it easier than ever to connect popular developer tools to Augment Code. Easy MCP is a new feature in the Augment Code extension that transforms complex MCP server setup into a single click. Instead of manually configuring servers, hunting for GitHub repos, or editing JSON files, you can now connect popular developer tools with just an API token or OAuth approval. ### Available Easy MCP Integrations Easy MCP provides one-click access to these popular developer tools: #### CircleCI * **Context:** Build logs, test insights, flaky-test detection * **Sample prompt:** "Find the latest failed pipeline on my branch and surface the failing tests." * **Setup:** Click "+", paste your CircleCI API token, and you're connected. #### MongoDB * **Context:** Data exploration, database management, and context-aware code generation * **Sample prompt:** "Analyze my user collection schema and suggest optimizations for our new search feature." * **Setup:** One-click OAuth connection to your MongoDB instance. #### Redis * **Context:** Keyspace introspection, TTL audits, and migration helpers * **Sample prompt:** "Generate a migration script to move expiring session keys to the new namespace." * **Setup:** Connect with your Redis credentials in seconds. ### Getting Started with Easy MCP 1. Open the Augment Code extension in your JetBrains IDE 2. Navigate to the Easy MCP pane in the settings 3. Click the "+" button next to your desired integration 4. Paste an API token or approve OAuth 5. Start using the integration immediately in your Agent conversations ![](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/EasyMCP.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=c02010664a36e319631e3f5367f5f00e) From that moment on, Augment Code streams your tool's live context into every suggestion and autonomous Agent run. ## Advanced Configuration: Settings Panel For developers who need custom MCP server configurations or want to use servers not available through Easy MCP, you can configure MCP servers manually using the Augment Settings Panel. To access the settings panel, select the gear icon in the upper right of the Augment panel. Once the settings panel is open, you will see a section for MCP servers. ![](https://mintcdn.com/augment-mtje7p526w/IEgTogsPIebDB-Bu/images/settings-panel-mcp.png?fit=max\&auto=format\&n=IEgTogsPIebDB-Bu\&q=85\&s=f34e3682127f6e6ba2dfc5a4ae7fd8a5) Fill in the `name` and `command` fields. The `name` field must be a unique name for the server. The `command` field is the command to run the server. Environment variables have their own section and no longer need to be specified in the command. ![](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/mcp-env.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=20d9ffa2c683194ec1d66afe390f6f9d) To add additional servers, click the `+` button next to the `MCP` header. To edit a configuration or to delete a server, click the `...` button next to the server name. ### Add a Remote MCP server If your MCP server runs remotely (for example, a hosted service), click the "+ Add remote MCP" button in the MCP section. Remote MCP connections support both HTTP and SSE (Server‑Sent Events). ![](https://mintcdn.com/augment-mtje7p526w/IEgTogsPIebDB-Bu/images/settings-panel-mcp-remote.png?fit=max\&auto=format\&n=IEgTogsPIebDB-Bu\&q=85\&s=21086d1c640c6e20975aa7207532be78) * Connection Type: choose HTTP or SSE * Name: a unique display name for the server * URL: the base URL to your MCP server (e.g., [https://api.example.com](https://api.example.com)) Remote MCP servers appear alongside your local MCP servers in the list. You can edit or remove them using the "..." menu next to the server name. ## MCP Tool Search By default, every tool from every configured MCP server is exposed to Augment Agent up front. With many MCP servers configured, this can consume a significant portion of the agent's context window before a conversation starts. MCP Tool Search changes this by hiding individual MCP tools from the agent and exposing two meta-tools instead: * **`find-tool`** — the agent describes what it wants to do, and a lightweight model returns the best matching MCP tool. * **`execute-tool`** — the agent calls this with the tool name returned by `find-tool` to invoke the underlying MCP tool. The agent only pays the context cost for tools it actually needs, rather than for every tool on every configured server. ### Enable MCP Tool Search MCP Tool Search is disabled by default. To enable it, open the Augment Settings Panel, go to the MCP section, and toggle **MCP Tool Search** on. The change takes effect immediately; no restart is required. Using VS Code or the Auggie CLI? See [MCP Tool Search in VS Code](/setup-augment/mcp#mcp-tool-search) or [MCP Tool Search on the CLI](/cli/integrations#mcp-tool-search). ### Permissions MCP Tool Search doesn't change how permissions are evaluated. Permission rules still match against the underlying MCP tool names invoked by `execute-tool`, so existing permission configurations continue to apply. ### Billing When MCP Tool Search is enabled, `find-tool` calls appear as a separate **Tool Search** activity in your usage dashboard. Tool invocations made through `execute-tool` are billed as part of normal agent usage. ## Server compatibility Not all MCP servers are compatible with Augment's models. The MCP standard, implementation of specific servers, and Augment's MCP support are frequently being updated, so check compatibility frequently. # Index your workspace Source: https://docs.augmentcode.com/jetbrains/setup-augment/workspace-indexing When your workspace is indexed, Augment can provide tailored code suggestions and answers based on your unique codebase, best practices, coding patterns, and preferences. You can always control what files are indexed. ## About indexing your workspace When you open a workspace with Augment enabled, your codebase will be automatically uploaded to Augment's secure cloud. You can control what files get indexed using `.gitignore` and `.augmentignore` files. Indexing usually takes less than a minute but can take longer depending on the size of your codebase. ## Security and privacy Augment stores your code securely and privately to enable our powerful context engine. We ensure code privacy through a proof-of-possession API and maintain strict internal data minimization principles. [Read more about our security](https://www.augmentcode.com/security). ## What gets indexed Augment will index all the files in your workspace, except for the files that match patterns in your `.gitignore` file and the `.augmentignore` file. ## Ignoring files with .augmentignore The `.augmentignore` file is a list of file patterns that Augment will ignore when indexing your workspace. Create an `.augmentignore` file in the root of your workspace. You can use any glob pattern that is supported by the [gitignore](https://git-scm.com/docs/gitignore) file. ## Including files that are .gitignored If you have a file or directory in your `.gitignore` that you want to indexed, you can add it to your `.augmentignore` file using the `!` prefix. For example, you may want your `node_modules` indexed to provide Augment with context about the dependencies in their project, but it is typically included in their `.gitignore`. Add `!node_modules` to your `.augmentignore` file. ```bash .augmentignore theme={null} # Include .gitignore excluded files with ! prefix !node_modules # Exclude other files with .gitignore syntax data/test.json ``` ```bash .gitignore theme={null} # Exclude dependencies node_modules # Exclude secrets .env # Exclude build artifacts out build ``` # Using Agent Source: https://docs.augmentcode.com/jetbrains/using-augment/agent Use Agent to complete simple and complex tasks across your workflow–implementing a feature, upgrade a dependency, or writing a pull request. ## About Agent Augment Agent is a powerful tool that can help you complete software development tasks end-to-end. From quick edits to complete feature implementation, Agent breaks down your requests into a functional plan and implements each step all while keeping you informed about what actions and changes are happening. Powered by Augment's Context Engine and powerful LLM architecture, Agent can write, document, and test like an experienced member of your team. ## Accessing Agent To access Agent, simply open the Augment panel and select one of the Agent modes from the drop down in the input box. ![Augment Agent](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/agent-selector-jetbrains.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=a67bcc5b41dca6b0a5e7d2f7eec8a2fa) ### Choosing a model Use the model dropdown in the Augment panel to switch between Claude Sonnet 4 and GPT-5. Your selection applies only to Agent for the current workspace and can be changed at any time. See [Available Models](/models/available-models) for details. ## Using Agent To use Agent, simply type your request into the input box using natural language and click the submit button. You will see the default context including your current workspace and file. You can add additional context by clicking and selecting files or folder, or add an image as context by clicking the paperclip. Agent can create, edit, or delete code across your workspace and can use tools like the terminal and external integrations through MCP to complete your request. ### Enhancing your prompt You can improve the quality of your changes by starting with a well crafted prompt. You can start with a quick or incomplete prompt and use the prompt enhancer to add relevant references, structure, and conventions from your codebase to improve the prompt before it is sent. 1. Write your prompt in the prompt input box 2. Click the Enhance Prompt ✨ button 3. Review and edit the enhanced prompt 4. Submit your prompt ### Reviewing changes You can review every change Agent makes by clicking on the action to expand the view. Review diffs for file changes, see complete terminal commands and output, and the results of external integration calls. ![Augment Agent](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/agent-expand-jetbrains.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=b31d72511c15bceaa95ed2d6b42f6815) ### Checkpoints Checkpoints are automatically saved snapshots of your workspace as Agent implements the plan allowing you to easily revert back to a previous step. This enables Agent to continue working while you review code changes and commands results. To revert to a previous checkpoint, click the reverse arrow to restore your code. ![Augment Agent](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/agent-checkpoint-jetbrains.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=f3eb8fca517586641c2ca2c14137ca7a) ### Agent vs Agent Auto By default, Agent will pause work when it needs to execute a terminal command or access external integrations. After reviewing the suggested action, click the blue play button to have Agent execute the command and continue working. You tell Agent to skip a specific action by clicking on the three dots and then Skip. ![Augment Agent](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/agent-approval.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=5c528efde3b96da6711dcecdda312294) In Agent Auto, Agent will act more independently. It will edit files, execute terminal commands, and access tools like MCP servers automatically. ### Stop or guide the Agent You can interrupt the Agent at any time by clicking Stop. This will pause the action to allow you to correct something you see the agent doing incorrectly. While Agent is working, you can also prompt the Agent to try a different approach which will automatically stop the agent and prompt it to correct its course. ![Stopping the agent](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/agent-stop.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=3c195714aa08f74acb9d63a354acdc99) ### Quick Ask Mode Quick Ask Mode is a toggle button in the agent chat interface that restricts the AI to read-only tools only. When activated, it adds a visual badge to the message and focuses the AI on information gathering without making any changes to your codebase. ![Quick Ask Mode toggle and usage](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/ask-mode.gif?s=c2c554fd010bb15d8267de15ad4f9dc5) ### Comparison to Chat Agent takes Chat to the next level by allowing Augment to do things for you-that is create and make modifications directly to your codebase. Chat can explain code, create plans, and suggest changes which you can smartly apply one-by-one, but Agent takes it a step further by automatically implementing the entire plan and all code changes for you. | What are you trying to do? | Chat | Agent | | :- | :-: | :-: | | Ask questions about your code | ☑️ | ✅ | | Get advice on how to refactor code | ☑️ | ✅ | | Add new features to selected lines of code | ☑️ | ✅ | | Add new feature spanning multiple files | | ✅ | | Document new features | | ✅ | | Queue up tests for you in the terminal | | ✅ | | Open Linear tickets or start a pull request | | ✅ | | Start a new branch in GitHub from recent commits | | ✅ | | Automatically perform tasks on your behalf | | ✅ | ### Use cases Use Agent to handle various aspects of your software development workflow, from simple configuration changes to complex feature implementations. Agent supports your daily engineering tasks like: * **Make quick edits** - Create a pull request to adjust configuration values like feature flags from FALSE to TRUE * **Perform refactoring** - Move functions between files while maintaining coding conventions and ensuring bug-free operation * **Start a first draft for new features** - Start a pull request (PR) with implementing entirely new functionality straight from a GitHub Issue or Linear Ticket * **Branch from GitHub** - Open a PR from GitHub based on recent commits that creates a new branch * **Query Supabase tables directly** - Ask Agent to view the contents of a table * **Start tickets in Linear or Jira** - Open tickets and ask Agent to suggest a plan to address the ticket * **Add Pull Request descriptions** - Merge your PR into a branch then tell the agent to explain what the changes are and why they were made * **Create test coverage** - Generate unit tests for your newly developed features * **Generate documentation** - Produce comprehensive documentation for your libraries and features * **Start a README** - Write a README for a new feature or updated function that you just wrote * **Track development progress** - Review and summarize your recent Git commits for better visibility with the GitHub integration ## Next steps * [Configure Agent Integrations](/jetbrains/setup-augment/agent-integrations) # Using Chat Source: https://docs.augmentcode.com/jetbrains/using-augment/chat Use Chat to explore your codebase, quickly get up to speed on unfamiliar code, and get help working through a technical problem. ## About Chat Chat is a new way to work with your codebase using natural language. Chat will automatically use the current workspace as context and you can [provide focus](/jetbrains/using-augment/chat-context) for Augment by selecting specific code blocks, files, folders, or external documentation. Details from your current chat, including the additional context, are used to provide more relevant code suggestions as well. ![Augment Chat](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/chat-explain.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=d375d6ded40f6ed3353e002a9d9fa7a0) ## Accessing Chat Access the Chat sidebar by clicking the Augment icon ![](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/augment-icon-chat.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=5a70e197b4ab16c79e9612aac74015cf) in the sidebar or the status bar. You can also open Chat by using one of the keyboard shortcuts below. **Keyboard Shortcuts** | Platform | Shortcut | | :- | :- | | MacOS | Cmd L | | Windows/Linux | Ctrl L | ## Using Chat To use Chat, simply type your question or command into the input field at the bottom of the Chat panel. You will see the currently included context which includes the workspace and current file by default. Use Chat to explain your code, investigate a bug, or use a new library. See [Example Prompts for Chat](/jetbrains/using-augment/chat-prompts) for more ideas on using Chat. ### Enhancing your prompt You can improve the quality of your chats by starting with a well crafted prompt. You can start with a quick or incomplete prompt and use the prompt enhancer to add relevant references, structure, and conventions from your codebase to improve the prompt before it is sent. 1. Write your prompt in the prompt input box 2. Click the Enhance Prompt ✨ button 3. Review and edit the enhanced prompt 4. Submit your prompt ### Conversations about code To get the best possible results, you can go beyond asking simple questions or commands, and instead have a back and forth conversation with Chat about your code. For example, you can ask Chat to explain a specific function and then ask follow-up questions about possible refactoring options. Chat can act as a pair programmer, helping you work through a technical problem or understand unfamiliar code. ### Starting a new chat You should start a new Chat when you want to change the topic of the conversation since the current conversation is used as part of the context for your next question. To start a new chat, open the Augment panel and click the new chat icon at the top-right of the Chat panel. ### Previous chats You can continue a chat by clicking the chevron iconat the top-left of the Chat panel. Your previous chats will be listed in reverse chronological order, and you can continue your conversation where you left off. ### Deleting a chat You can delete a previous chat by clicking the chevron iconat the top-left of the Chat panel to show the list of previous chats. Click the delete icon next to the chat you want to delete. You will be asked to confirm that you want to delete the chat. # Using Actions in Chat Source: https://docs.augmentcode.com/jetbrains/using-augment/chat-actions Actions let you take common actions on code blocks without leaving Chat. Explain, improve, or find everything you need to know about your codebase. ![Augment Chat Actions](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/chat-actions.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=db5e93308abefb7782a8684ad79e2a50) ## Using actions in Chat To use a quick action, you an use a / command or click the up arrow iconto show the available actions. For explain, fix, and test actions, first highlight the code in the editor and then use the command. | Action | Usage | | :- | :- | | /find | Use natural language to find code or functionality | | /explain | Augment will explain the hightlighted code | | /fix | Augment will suggest improvements or find errors in the highlighted code | | /test | Augment will suggest tests for the highlighted code | Augment will typically include code blocks in the response to the action. See [Applying code blocks from Chat](/jetbrains/using-augment/chat-apply) for more details. # Applying code blocks from Chat Source: https://docs.augmentcode.com/jetbrains/using-augment/chat-apply Use Chat to explore your codebase, quickly get up to speed on unfamiliar code, and get help working through a technical problem. ![Augment Chat Apply](https://mintcdn.com/augment-mtje7p526w/r-azeXhOS4FbEUi5/images/chat-apply.png?fit=max\&auto=format\&n=r-azeXhOS4FbEUi5\&q=85\&s=b461dba46612cb6cc46db000bebb7566) ## Using code blocks from within Chat Whenever Chat responds with code, you will have the option to add the code to your codebase. The most common option will be shown as a button and you can access the other options by clicking the overflow menu iconat the top-right of the code block. You can use the following options to apply the code: * **Copy** the code from the block to your clipboard * **Create** a new file with the code from the block * **Apply** the code from the block intelligently to your file # Focusing Context in Chat Source: https://docs.augmentcode.com/jetbrains/using-augment/chat-context You can specify context from files, folders, and external documentation in your conversation to focus your chat responses. ## About Chat Context Augment intelligently includes context from your entire workspace based on the ongoing conversation–even if you don't have the relevant files open in your editor–but sometimes you want Augment to prioritize specific details for more relevant responses.