Documentation

Security & Guardrails

Codinel assumes you can read the diff. These guardrails keep the agent inside the projects you have open, stop destructive actions for your approval regardless of permission level, and check the contents of scripts it runs rather than trusting the command line alone. Where a check cannot prove something is safe, it asks you instead of guessing.

To be clear about what this is: these are guardrails against agent mistakes and overreach, not a security sandbox. An approved command runs with your full user permissions.

Agent Permission Levels
Configure how much autonomy the AI agent has when performing state-changing operations. Each mode balances automation speed against developer control. Permission levels are now configured per-chat in the Chat Input Area (Agent Config dropdown), not at the workspace level.
Strict Mode
Requires explicit approval for any state-changing action. Every file write, search/replace edit, terminal command, and tool execution is presented to the developer for manual authorization before execution. Selected per-chat via the Agent Config dropdown in the Chat Input Area.
Balanced Mode
Auto-writes files and performs search/replace edits with automatic truncation safeguards, but requires confirmation for terminal commands and database queries. The recommended default for a smooth development experience. Selected per-chat via the Agent Config dropdown in the Chat Input Area.
Autonomous Mode
Executes routine tools without prompting - maximum speed with no interruptions for ordinary work. It is not a bypass: the Destructive Command Policy still applies in full, so deleting a branch, reaching outside your loaded projects, or running a script that cannot be verified will still stop and ask. Selected per-chat via the Agent Config dropdown in the Chat Input Area.
Destructive Command Policy
Guardrails that apply at every permission level, autonomous included. The permission level controls how much routine work you supervise; it is not standing consent to delete a branch or write outside your loaded projects. These checks run before the tool executes, and each approval prompt names the specific rule that fired so you know what you are approving.
Git Branch Deletion
Deleting a branch always stops for approval - via git branch -d/-D/--delete, git push --delete, or direct ref manipulation such as update-ref -d and reflog expiry. Unpushed commits exist nowhere else, and Codinel's snapshot undo covers files, not refs. The vcs_action tool refuses branch deletion outright and says where the decision actually lives, so the agent does not route around it through the terminal.
Escalates at every level
Out-of-Project Containment
Every path a command touches is resolved and checked against your loaded project roots before the shell sees it - including relative climbs like ../../.., absolute paths, and shell redirection targets that never appear as an argument. All loaded projects count, so monorepo work across sibling projects is unaffected. Anything landing outside stops for approval, and the prompt shows the resolved destination rather than the raw string.
Escalates at every level
Script Content Scanning
Closes the bypass where the agent writes a script inside your project (an ordinary file edit) and then runs it (a command pointing safely inside your project). When a file is executed through node, python, bash, PowerShell or any other interpreter, its contents are scanned for path literals that reach outside your projects. Hardcoded external paths escalate to approval.
Escalates at every level
Unprovable Cases Escalate
Static analysis of a dynamic language cannot be complete, and Codinel does not pretend otherwise. Scripts that build paths at runtime from environment variables, the home directory, or computed values escalate - as do inline -e code, interpreter REPLs, and any script that cannot be read. Commands containing shell variables or substitutions escalate for the same reason. The system fails to a prompt rather than to silence.
Fails closed
Working Directory Containment
A command's working directory is validated against the project root before execution. Without this, a relative workingDir could relocate the shell outside your project and every path check would be describing a command that was never the one that ran.
Host-Termination Refusals
A small set of commands are refused outright with no approval option, because consent does not make them safe: anything that force-kills the Electron process hosting the IDE would end the turn mid-stream with no record of what happened. Matching is on the whole command line, since the dangerous part is often an npm lifecycle hook the agent never typed. Refusals explain the cause and name a safe alternative, so the agent redirects instead of rephrasing and retrying.
Always refused
Approval Integrity
Approvals are single-use and bound to the exact tool and arguments that were held, so a replayed approval cannot execute an action twice and an approved action cannot be swapped for a different one. Per-chat tool exclusions are re-checked on the approved path as defense in depth.
Tool Exclusions
Granular per-chat toggles in the Chat Input Area to completely remove specific tools from the AI agent's system prompt, preventing it from even attempting certain categories of operations.
Terminal Command Toggle
Removes the terminal tool from the LLM system prompt entirely (allowTerminalCommand), and rejects it at the approval gate as well - so a model that names the tool anyway still cannot run it. Covers shell, PowerShell, and bash commands. Toggled per-chat in the Chat Input Area.
Database Query Toggle
Prevents the agent from attempting any database queries (allowDbQuery). The execute_db_query tool is excluded from the system prompt. Toggled per-chat in the Chat Input Area.
File Deletion Toggle
Blocks the delete_file tool from AI access (allowFileDeletion). The agent cannot permanently delete files from the project, ensuring accidental or unwanted file removal is impossible. Toggled per-chat in the Chat Input Area.
Local File History & Rollback
Automatic snapshot system that preserves historical copies of files before any modification or deletion, enabling point-in-time diff inspection and full rollback.
Rolling FIFO Snapshots
Keeps historical copies of files before each modification or deletion. Uses a first-in-first-out rolling buffer so recent snapshots are always available for comparison.
Configurable Snapshot Limit
Default snapshot limit is 50, configurable from 0 to 1000. Higher values retain deeper point-in-time rollback points in Local File History.
Default: 50 Range: 0–1000
Snapshot-based Undo Tool
Full rollback capability for any automated change. The undo tool restores the previous file snapshot, instantly reversing AI modifications.
Quality Control Thresholds
Automated guardrails that alert the developer when AI conversations exceed safe context parameters, preventing runaway token costs and error cascades.
Max Tokens Per Chat
Monitors cumulative token usage in long runs. Default threshold is 120,000 tokens to prevent degraded model reasoning quality from context window pressure.
Default: 120,000 tokens
Max Mistakes Per Chat
Alerts when the AI encounters too many rejected edits or tool failures. Default threshold is 10 mistakes to prevent infinite retry loops.
Default: 10 mistakes
Automated Chat Migration Prompt
When quality control thresholds are reached, the AI summarizes progress and offers to migrate to a fresh chat context with all staged files and synopsis preserved.
Ignore Max Tokens During Pipelines
Toggle to ignore the max token threshold during agent pipelines, so long-running multi-phase runs are not interrupted by the token guardrail.
Ignore Max Mistakes During Pipelines
Toggle to ignore the max session mistakes/errors threshold during agent pipelines, so multi-phase runs are not halted by the mistake guardrail.
Agentic QA Validation
Multi-layered quality assurance system that validates AI-generated code changes through automated test execution and LLM-powered code review before marking tasks as complete.
validate_implementation Gate
Forces QA validation on code changes. Analyzes git diffs, executes test suites, and invokes the Validation LLM connection to return a PASS or FAIL review.
project: string task: object
Unit Test QA Gate
Executes unit test suites automatically as a QA gate, ensuring new changes do not break existing module functionality.
Integration Test QA Gate
Runs API and integration test suites as part of the QA pipeline, verifying cross-module communication and contracts.
Playwright Browser E2E QA
Automates browser end-to-end testing via Playwright. Simulates user interactions to verify UI behavior after automated edits.
Acceptance Criteria Analysis
The Validation LLM checks code changes against specific acceptance criteria defined for the task before granting a PASS verdict.