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

# Permission System

> Configure what Lukan can and cannot do in your project.

## Permission Modes

| Mode      | Behavior                                        | Indicator           |
| --------- | ----------------------------------------------- | ------------------- |
| `manual`  | Asks permission for every tool call             | `[manual]` (yellow) |
| `auto`    | Auto-approves safe tools + allowed patterns     | `[auto]` (green)    |
| `skip`    | Fully automatic, deny list still applies        | `[skip]` (cyan)     |
| `planner` | Generates implementation plans before executing | `[planner]`         |

Toggle mode with **Shift+Tab** during a session. The cycle is: manual -> auto -> skip -> planner -> manual.

## Project Configuration

Initialize with `lukan init`, creates `.lukan/config.json`:

```json theme={null}
{
  "permissionMode": "manual",
  "permissions": {
    "deny": [],
    "ask": ["Bash(git push:*)", "Bash(git commit:*)", "Bash(rm:*)", "Bash(sudo:*)"],
    "allow": ["Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(npm:*)", "Bash(bun:*)"]
  },
  "trusted": false,
  "allowedPaths": []
}
```

### Pattern Syntax

* `Bash(git:*)` - Any git command
* `ReadFiles(**/.env)` - .env files anywhere (recursive glob)
* `ReadFiles` - Any ReadFiles call (no args = match all)

### Decision Flow (auto mode)

1. **Deny list** - Reject immediately
2. **Safe tools** - Auto-approve (ReadFiles, Grep, Glob, WebFetch, Explore, TaskAdd, TaskList, TaskUpdate, LoadSkill, PlannerQuestion, SubmitPlan)
3. **Ask list** - Prompt user
4. **Allow list** - Auto-approve
5. **Default** - Prompt user

### Planner Mode

In planner mode, only read-only and planning tools are allowed:

* ReadFiles, Grep, Glob, WebFetch, Explore
* TaskAdd, TaskList, TaskUpdate
* PlannerQuestion, SubmitPlan, LoadSkill

No execution tools (Bash, WriteFile, EditFile, etc.) are permitted.

## Project-Level Permissions

Run `lukan init` in your project directory to create a `.lukan/config.json` file. This file controls what Lukan can do in that specific project.

The permissions are granular:

* Control which commands can run
* Restrict access to sensitive files
* Set up auto-approval for safe operations

### Trusted Projects

Set `"trusted": true` in your project config to reduce permission prompts for known safe workspaces.

### Allowed Paths

Use `allowedPaths` to grant the agent access to directories outside the project root:

```json theme={null}
{
  "allowedPaths": ["~/shared-libs", "/opt/data"]
}
```

Paths support `~` expansion.

## Trusted Directories

For WhatsApp and Email channels (plugins), you can restrict file operations to specific directories:

```json theme={null}
{
  "plugins": {
    "overrides": {
      "whatsapp": {
        "allowedDirs": ["/home/user/projects"],
        "skipDirRestrictions": false
      }
    }
  }
}
```

Hidden files like `.env`, `.git/`, etc. are always blocked.

## Best Practices

1. Start with `manual` mode to understand what Lukan needs
2. Gradually move to `auto` mode for routine tasks
3. Use the deny list to block dangerous operations
4. Keep sensitive directories out of allowed paths
5. Use `planner` mode for complex tasks to review the plan before execution