How to Configure CodeGPT's Agent Mode to Safely Execute Multi-Step File Operations and Terminal Commands

Software developers frequently face a painful trade-off with AI coding assistants: manually copying and pasting diffs across dozens of files is tedious and prone to human error, but handing full autonomy to an AI agent raises immediate concerns about accidental file deletion, corrupted git trees, or rogue terminal commands.

In CodeGPT (for Visual Studio Code and JetBrains IDEs), developers do not have to choose between total manual labor and reckless automation. By configuring Agent Mode alongside its underlying Internal Tools, you can harness autonomous multi-step planning while locking down sensitive file modifications and shell execution behind explicit permission gates.

Here is a practical guide on how CodeGPT's agent architecture works, how to configure its safety permissions, and how to execute multi-file refactoring and command sequences without risking your codebase.

1. The Interaction Modes: Selecting the Right Profile

CodeGPT structures IDE interactions through three distinct profile modes available from the profile selector at the bottom of the chat panel. Selecting the right profile is your first defense against unintended system side-effects:

To initiate agentic workflows, open the CodeGPT chat interface, click the profile selector dropdown, and switch from Chat or Search Mode to Agent Mode.

2. Model Compatibility: The Function-Calling Requirement

Before configuring permissions, ensure your active model supports tool calling. CodeGPT's internal tools rely strictly on native function calling.

• Compatible Providers & Models: Anthropic (Claude 3.5 / 3.7 Sonnet), OpenAI (GPT-4o, o-series), Google (Gemini 1.5 / 2.0 / 2.5 Flash & Pro), DeepSeek, Mistral, and compatible models routed through OpenRouter or Bedrock.
• Incompatible Models: If you choose a model from a provider without function-calling capabilities, CodeGPT disables internal tool execution entirely, downgrading the agent to pure text responses.

3. Configuring Tool Permissions: Manual Approval vs. Auto-Approve

CodeGPT gives developers granular control over eight built-in internal tools:

1. Code Search: Semantically queries the codebase for symbols and logic patterns.
2. Read File: Retrieves content from designated files.
3. View Folder Structure: Maps project file hierarchies.
4. Create File/Folder: Generates new project directories and source files.
5. Edit File: Applies targeted patches and modifications to existing files.
6. Delete File: Permanently removes files from the workspace.
7. Run Terminal Command: Spawns shell processes for package installation, test execution, or builds.
8. Update ToDo List: Maintains real-time task planning and progress tracking.

Step-by-Step Configuration Steps

1. In the CodeGPT extension panel, open the Settings menu (gear icon ⚙️).
2. Navigate to the Tools configuration section.
3. Review the available tools and configure each tool's execution behavior:
   • Enabled (Manual Approval): The agent pauses before taking action, presents a preview (such as a diff of file changes or the exact command line string), and requires you to click Approve or Reject.
   • Auto-Approve: The agent executes the tool autonomously whenever its planning loop determines it is needed, without waiting for developer input.

CodeGPT's Hard Safety Threshold

To prevent uncontrolled runaway loops (such as an agent entering an infinite error-fix cycle and spamming shell commands or file rewrites), CodeGPT enforces a hard safety limit: a maximum of 20 consecutive auto-approvals for potentially dangerous operations (Create File/Folder, Edit File, Delete File, and Run Terminal Command).

Once the agent hits 20 automated operations, it automatically halts and requires manual developer confirmation before continuing.

4. The Recommended Security Policy for Engineering Teams

For everyday software engineering, a blanket "Auto-Approve All" policy creates severe operational hazards. Instead, adopt a layered permission tier based on tool risk:

flowchart TD
    A[CodeGPT Agent Mode Prompt] --> B{Tool Request Type}
    
    B -->|Read: Code Search, Read File, View Folder| C[Auto-Approve: Instant Execution]
    B -->|Planning: Update ToDo List| D[Auto-Approve: Live Visual Checklist]
    
    B -->|Mutation: Create File / Edit File| E{Diff Inspection}
    E -->|Safe Scaffolding / Low Risk| F[Optional Auto-Approve or Manual Approval]
    
    B -->|High Risk: Delete File| G[Strict Manual Approval Required]
    B -->|High Risk: Run Terminal Command| H[Strict Manual Approval Required]
    
    G --> I[Developer Review & Sign-Off]
    H --> I
    I --> J[Apply to Disk or Shell]

Tier 1: Read-Only & Planning Tools (Safe for Auto-Approve)

• Code Search: Auto-Approve.
• Read File: Auto-Approve.
• View Folder Structure: Auto-Approve.
• Update ToDo List: Auto-Approve. Rationale: These operations inspect files or update internal planning state without modifying persistent workspace files or external environments.

Tier 2: File Creation and Editing (Selective Auto-Approve or Manual)

• Create File/Folder: Auto-Approve in clean feature branches; Manual Approval in sensitive modules.
• Edit File: Keep on Enabled (Manual Approval) during initial planning. Once you observe that the agent generates accurate structural patches, you can switch to Auto-Approve for repetitive boilerplate updates. Rationale: Code modifications should always be validated against git diffs to prevent regression bugs or erased comments.

Tier 3: Destructive Actions & Command Execution (Strictly Manual)

• Delete File: Enabled (Manual Approval Only).
• Run Terminal Command: Enabled (Manual Approval Only). Rationale: Shell execution can trigger network calls, database migrations, package installations, or irreversible filesystem changes (rm, git reset, chmod). Always inspect the terminal command string and arguments before approving execution.

5. IDE Nuances: VS Code vs. JetBrains

While CodeGPT provides core feature parity across platforms, developers should account for distinct IDE environment behaviors:

Visual Studio Code

• Profile Selector: Located in the chat footer bar for rapid switching between Chat, Search, and Agent profiles.
• Diff Previews: File changes proposed via Edit File leverage VS Code's native inline diff viewer, enabling developers to inspect changes side-by-side prior to approval.
• Configuration: Settings can be tuned at the user level or scoped per workspace in .vscode/settings.json.

JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm)

• Installation: Installed via the JetBrains Marketplace or manually using Install Plugin from Disk.
• Companion Service Port: CodeGPT runs an internal background service requiring local port 54112 or 54113 to communicate with the IDE. Ensure firewall rules or local processes do not block these ports.
• Approval Dialogs: File operations and terminal executions prompt through JetBrains modal or tool window notifications. Terminal executions run within JetBrains' integrated terminal instances.

6. Safe Multi-Step Execution Workflow in Practice

To execute a non-trivial refactor—such as migrating an API module, extracting shared types, and validating test suites—follow this 5-step operational protocol:

Step 1: Ensure Clean Version Control

Before launching Agent Mode, run git status. Ensure your working branch has no uncommitted changes, or check out an isolated branch (feature/codegpt-refactor). If an autonomous sequence produces unexpected outputs, git reset --hard or git checkout . serves as your immediate fail-safe.

Step 2: Probe with Search Mode First

Before granting write permissions, switch to Search Mode. Ask the model to map dependencies:

"Analyze how UserService interacts with DatabaseClient and list all files that will be impacted if we migrate to the new async driver."

Search Mode gathers project context and outlines the scope of work using read-only tools, eliminating token churn and premature file writes.

Step 3: Switch to Agent Mode with a Planning Constraint

Switch the profile to Agent Mode. Provide a prompt that instructs the model to leverage Update ToDo List before mutating code:

"Switch to Agent Mode. Refactor the authentication middleware to use JWT verification across all controller files. First, construct a detailed step-by-step ToDo list. Break the tasks down: 1) create the new token utility, 2) update the middleware, 3) adjust existing tests. Do not delete any files without asking."

The agent generates a structured, visual checklist, allowing you to monitor progress in real time.

Step 4: Validate Inline Diffs and Commands

As CodeGPT executes the plan, review each proposed modification:

• For Edit File: Inspect the diff view to verify that only target logic was modified.
• For Run Terminal Command: Verify that the command runs read-only test runners (e.g., npm test -- auth.test.ts or pytest tests/auth/) rather than destructive deployment scripts.

Step 5: Final Sanity Check and Commit

Once all items in the ToDo list are marked complete, run the project build and comprehensive test suite manually in your terminal. Inspect your git diff, verify test passes, and commit your verified code.

Summary

CodeGPT's Agent Mode transforms the IDE assistant from a passive text prompter into an active pair programmer capable of multi-file updates and environment operations. By keeping Delete File and Run Terminal Command set to manual confirmation, utilizing the Search Mode → Agent Mode progressive workflow, and relying on CodeGPT's built-in 20-operation safety threshold, developers achieve high-speed autonomous coding without compromising repository safety.

References

• Internal Tools | CodeGPT
• Profile Modes | CodeGPT
• 🛠️ Features | CodeGPT
• CodeGPT Chat | CodeGPT
• 👋 Welcome | CodeGPT