> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puzld.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic Mode

> LLMs explore your codebase and propose edits

Agentic mode gives LLMs tools to explore your codebase, then propose file edits with permission prompts — like Claude Code, but for any LLM.

## Usage

The TUI runs in agentic mode by default. Just type your task:

```bash theme={null}
fix the bug in src/utils.ts
add error handling to api/routes.ts
create a hello world script
```

Set the agent for your tasks:

```bash theme={null}
/agent claude    # Use Claude
/agent gemini    # Use Gemini
/agent ollama    # Use local Ollama
```

> [!TIP]
>
> See [Model Selection](https://docs.puzld.cc/features/models.md) to configure which model each agent uses.

## Available Tools

| Tool | Description |
| - | - |
| `view` | Read file contents with line numbers |
| `glob` | Find files by pattern (e.g., `**/*.ts`) |
| `grep` | Search file contents with regex |
| `bash` | Execute shell commands |
| `write` | Create or overwrite files |
| `edit` | Search and replace in files |

## Approval Modes

Control how permissions and file edits are handled with `/approval-mode`:

| Mode | Permissions | File Edits | Use Case |
| - | - | - | - |
| **Default** | Ask for each | Diff review | Normal development |
| **Plan** | Ask for each | Show plan only | Planning/reviewing |
| **Accept** | Ask for each | Auto-apply | Faster iteration |
| **YOLO** | Auto-approve | Auto-apply | Full trust, max speed |

## Permission Prompts

In Default and Plan modes, every tool call shows a permission prompt:

* **Allow** — Execute this tool call
* **Allow from directory** — Auto-approve reads from this directory
* **Allow all reads** — Auto-approve all file reads
* **Allow all edits** — Auto-approve all file writes for this session
* **Deny** — Skip this tool call
* **Esc** — Cancel entire operation

> [!TIP]
>
> "Allow all edits" persists across messages in the same session — useful when you trust the agent to make multiple changes.

## Trust Management

Pre-approve directories so the agent can read files without prompts:

```bash theme={null}
/trusted                  # List trusted directories
/trusted add ./src        # Trust the src folder
/trusted add .            # Trust current directory
/trusted remove ./src     # Remove trust
```

Files in trusted directories are auto-approved for read operations.

## Live Tool Activity

When the LLM uses tools, you see:

* **●** Green = completed
* **●** Yellow = running
* **●** Red = error
* **●** Gray = pending

Press `Ctrl+S` to expand/collapse full output.

## How It Works

**1. Describe the task**

Type your request in the TUI

**2. LLM explores**

The LLM uses view, glob, grep to understand your codebase

**3. Permission prompts**

Each tool call shows a prompt — you approve or deny

**4. LLM proposes edits**

The LLM uses write/edit to propose changes

**5. Review diff**

You see a diff preview and approve or reject each change

**6. Apply changes**

Approved changes are written to disk

## Consensus → Agentic Workflow

Run consensus first, then continue with the agent:

```bash theme={null}
/consensus claude,gemini "best approach for auth"
# Choose "Continue"
# Type your follow-up — has consensus context
```

The consensus result is automatically injected as context.

## Agent Support

| Agent | Agentic Support |
| - | - |
| Claude | Full support — uses our tool system |
| Ollama | Full support — uses our tool system |
| Gemini | Partial — auto-reads files (bypasses read prompts) |
| Codex | Safe mode — backup/rollback for file changes |
| Mistral | Experimental — inconsistent tool support |

### Codex Safe Mode

Codex runs in "safe mode" by default. Since Codex's exec mode writes files directly (bypassing our tool system), PuzldAI:

1. **Backs up** source files before Codex runs
2. **Runs Codex** with `workspace-write` sandbox
3. **Detects changes** by comparing files after execution
4. **Applies approval mode**:
   * Plan mode → rolls back all changes
   * Accept/YOLO → keeps changes
   * Default → shows notification, keeps changes

> [!WARNING]
>
> Codex changes are applied immediately, then rolled back if rejected. This differs from Claude/Ollama where you approve *before* changes are written.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.