Home / Docs / Role Configuration

Role Configuration

Overview #

Roles are per-project permission profiles stored in Thurbox's SQLite database. When a session starts, its assigned role determines the Claude CLI flags passed at spawn time:

bash

claude --permission-mode <mode> \
       --allowed-tools "<tool1> <tool2>" \
       --disallowed-tools "<tool3>" \
       --append-system-prompt "<text>"

Roles can also carry environment variables ( env ) injected into the session's tmux pane at spawn time.

Permission Modes #

Mode	Description
`default`	Claude asks the user before running tools (standard behavior)
`plan`	Claude can only plan; no tool execution until user approves
`acceptEdits`	Auto-approve file edits; ask for everything else
`dontAsk`	Auto-approve all tool calls without prompting
`bypassPermissions`	Skip all permission checks (use with caution)

Allow / Ask / Deny Semantics #

Tier	Behavior	Configured via
Allow	Tool runs without asking the user	`allowed_tools`
Ask	User is prompted before tool runs	(default for unlisted tools)
Deny	Tool is completely blocked	`disallowed_tools`

If a tool appears in both allowed_tools and disallowed_tools , the deny takes precedence.

Tool Name Format #

Simple tool names

Tool	Description
`Read`	Read files
`Edit`	Edit files
`Write`	Write/create files
`Bash`	Execute shell commands
`Glob`	Find files by pattern
`Grep`	Search file contents
`WebFetch`	Fetch web content
`WebSearch`	Search the web
`Task`	Launch sub-agents
`NotebookEdit`	Edit Jupyter notebooks

Scope patterns

Bash commands can be scoped using Bash(specifier) syntax:

examples

Bash(git:*)         # All git subcommands
Bash(npm run *)     # npm run with any script name
Bash(cargo:*)       # All cargo subcommands
Bash(docker:*)      # All docker subcommands
Read(.env*)          # Read .env files
Edit(src/**)        # Edit files in src/

Field Reference #

RoleInput fields

Field	Type	Required	Default	Description
`name`	string	Yes	—	Role identifier, unique per project. 1-64 chars.
`description`	string	Yes	—	Human-readable summary of the role's purpose.
`permission_mode`	string \| null	No	`null`	One of the permission modes .
`allowed_tools`	string[]	No	`[]`	Tools that auto-approve.
`disallowed_tools`	string[]	No	`[]`	Tools that are blocked entirely.
`tools`	string \| null	No	`null`	Restrict available tool set.
`append_system_prompt`	string \| null	No	`null`	Text appended to Claude's system prompt.
`env`	object	No	`{}`	Environment variables passed to sessions.

Common Patterns #

Developer — full access with git auto-approve

JSON

{
  "name": "developer",
  "description": "Full development access with git auto-approved",
  "permission_mode": "acceptEdits",
  "allowed_tools": ["Bash(git:*)", "Bash(cargo:*)"],
  "disallowed_tools": []
}

Reviewer — read-only code review

JSON

{
  "name": "reviewer",
  "description": "Read-only access for code review",
  "permission_mode": "plan",
  "allowed_tools": ["Read", "Grep", "Glob"],
  "disallowed_tools": ["Edit", "Write", "Bash"]
}

CI Runner — build and test only

JSON

{
  "name": "ci-runner",
  "description": "Run builds and tests, no file modifications",
  "permission_mode": "default",
  "allowed_tools": ["Read", "Grep", "Glob", "Bash(cargo:*)", "Bash(npm:*)"],
  "disallowed_tools": ["Edit", "Write"]
}

Auditor — read everything, change nothing

JSON

{
  "name": "auditor",
  "description": "Full read access for security audits",
  "permission_mode": "plan",
  "allowed_tools": ["Read", "Grep", "Glob", "WebFetch"],
  "disallowed_tools": ["Edit", "Write", "Bash", "NotebookEdit"],
  "append_system_prompt": "You are performing a security audit. Report findings but do not modify any files."
}

API Worker — with environment variables

JSON

{
  "name": "api-worker",
  "description": "API development with custom environment",
  "permission_mode": "acceptEdits",
  "allowed_tools": ["Read", "Edit", "Bash(cargo:*)"],
  "env": {
    "API_KEY": "sk-test-123",
    "DATABASE_URL": "postgres://localhost/dev",
    "RUST_LOG": "debug"
  }
}

Integration #

From the Admin session

The Admin session has thurbox-mcp auto-configured. Use natural language to manage roles:

Admin session

"Set up developer and reviewer roles for the my-app project."

From the TUI

Press Ctrl+E to edit a project. Navigate to the Roles field to add, edit, or delete roles using the built-in role editor.

From Claude Code CLI

Configure thurbox-mcp in .mcp.json and use the set_roles and list_roles tools directly. See MCP Server > CLI Integration .