Configuration Reference
All options for ~/.agent-deck/config.toml.
Table of Contents
- Top-Level
- [claude] Section
- [logs] Section
- [updates] Section
- [global_search] Section
- [mcp_pool] Section
- [mcps.*] Section
- [tools.*] Section
Top-Level
default_tool = "claude" # Pre-selected tool when creating sessions[claude] Section
Claude Code integration settings.
[claude]
config_dir = "~/.claude-work" # Path to Claude config directory
dangerous_mode = true # Enable --dangerously-skip-permissions| Key | Type | Default | Description |
|---|---|---|---|
config_dir |
string | ~/.claude |
Claude config directory. Override with CLAUDE_CONFIG_DIR env. |
dangerous_mode |
bool | false |
Skip Claude permission dialogs. Required for automation. |
[logs] Section
Session log file management.
[logs]
max_size_mb = 10 # Max size before truncation
max_lines = 10000 # Lines to keep when truncating
remove_orphans = true # Delete logs for removed sessions| Key | Type | Default | Description |
|---|---|---|---|
max_size_mb |
int | 10 |
Max log file size in MB. |
max_lines |
int | 10000 |
Lines to keep after truncation. |
remove_orphans |
bool | true |
Clean up logs for deleted sessions. |
Logs location: ~/.agent-deck/logs/agentdeck_<session>_<id>.log
[updates] Section
Auto-update settings.
[updates]
auto_update = false # Auto-install updates
check_enabled = true # Check on startup
check_interval_hours = 24 # Check frequency
notify_in_cli = true # Show in CLI commands| Key | Type | Default | Description |
|---|---|---|---|
auto_update |
bool | false |
Install updates without prompting. |
check_enabled |
bool | true |
Enable startup update checks. |
check_interval_hours |
int | 24 |
Hours between checks. |
notify_in_cli |
bool | true |
Show updates in CLI (not just TUI). |
[global_search] Section
Search across all Claude conversations.
[global_search]
enabled = true # Enable global search
tier = "auto" # "auto", "instant", "balanced"
memory_limit_mb = 100 # Max RAM for index
recent_days = 90 # Limit to last N days (0 = all)
index_rate_limit = 20 # Files/second for indexing| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | true |
Enable G key global search. |
tier |
string | "auto" |
Strategy: instant (fast, more RAM), balanced (LRU cache). |
memory_limit_mb |
int | 100 |
Max memory for balanced tier. |
recent_days |
int | 90 |
Only search recent conversations. |
index_rate_limit |
int | 20 |
Indexing speed (reduce for less CPU). |
[mcp_pool] Section
Share MCP processes across sessions via Unix sockets.
[mcp_pool]
enabled = false # Enable socket pooling
auto_start = true # Start pool on launch
pool_all = false # Pool ALL MCPs
exclude_mcps = [] # Exclude from pool_all
fallback_to_stdio = true # Fallback if socket fails
show_pool_status = true # Show 🔌 indicator| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | false |
Master switch for pooling. |
pool_all |
bool | false |
Pool all available MCPs. |
exclude_mcps |
array | [] |
MCPs to exclude when pool_all=true. |
fallback_to_stdio |
bool | true |
Use stdio if socket unavailable. |
Benefits: 30 sessions x 5 MCPs = 150 processes -> 5 shared processes (90% memory savings).
Socket location: /tmp/agentdeck-mcp-{name}.sock
[mcps.*] Section
Define MCP servers. One section per MCP.
STDIO MCPs (Local)
[mcps.exa]
command = "npx"
args = ["-y", "exa-mcp-server"]
env = { EXA_API_KEY = "your-key" }
description = "Web search via Exa AI"| Key | Type | Required | Description |
|---|---|---|---|
command |
string | Yes | Executable (npx, docker, node, python). |
args |
array | No | Command arguments. |
env |
map | No | Environment variables. |
description |
string | No | Help text in MCP Manager. |
HTTP/SSE MCPs (Remote)
[mcps.remote]
url = "https://api.example.com/mcp"
transport = "http" # or "sse"
description = "Remote MCP server"Common MCP Examples
# Web search
[mcps.exa]
command = "npx"
args = ["-y", "@anthropics/exa-mcp"]
env = { EXA_API_KEY = "xxx" }
# GitHub
[mcps.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_xxx" }
# Filesystem
[mcps.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
# Sequential thinking
[mcps.thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
# Playwright
[mcps.playwright]
command = "npx"
args = ["-y", "@anthropics/playwright-mcp"]
# Memory
[mcps.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"][tools.*] Section
Define custom AI tools.
[tools.my-ai]
command = "my-ai-assistant"
icon = "🧠"
busy_patterns = ["thinking...", "processing..."]| Key | Type | Required | Description |
|---|---|---|---|
command |
string | Yes | Command to run. |
icon |
string | No | Emoji for TUI (default: 🐚). |
busy_patterns |
array | No | Strings indicating busy state. |
Built-in icons: claude=🤖, gemini=✨, opencode=🌐, codex=💻, cursor=📝, shell=🐚
Complete Example
default_tool = "claude"
[claude]
config_dir = "~/.claude-work"
dangerous_mode = true
[logs]
max_size_mb = 10
max_lines = 10000
remove_orphans = true
[updates]
check_enabled = true
check_interval_hours = 24
[global_search]
enabled = true
tier = "auto"
recent_days = 90
[mcp_pool]
enabled = false
[mcps.exa]
command = "npx"
args = ["-y", "exa-mcp-server"]
env = { EXA_API_KEY = "your-key" }
description = "Web search"
[mcps.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_xxx" }
description = "GitHub access"Environment Variables
| Variable | Purpose |
|---|---|
AGENTDECK_PROFILE |
Override default profile |
CLAUDE_CONFIG_DIR |
Override Claude config dir |
AGENTDECK_DEBUG=1 |
Enable debug logging |