tools-only Troubleshooting Guide
Common issues and solutions for agent-deck.
Quick Fixes
| Issue | Solution |
|---|---|
Session shows ✕ error |
agent-deck session start <name> |
| MCPs not loading | agent-deck session restart <name> |
| CLI changes not in TUI | Press Ctrl+R to refresh |
| Flag not working | Put flags BEFORE arguments |
| Fork fails | Check session has valid Claude session ID |
| Status stuck | Wait 2 seconds or press u to mark unread |
Common Issues
Flags Ignored
Problem: Flags after positional arguments are silently ignored.
# WRONG - message not sent
agent-deck session start my-project -m "Hello"
# CORRECT
agent-deck session start -m "Hello" my-project
MCP Not Available
- Check if attached:
agent-deck mcp attached <session> - Restart session:
agent-deck session restart <session> - Verify in config:
agent-deck mcp list
Session ID Not Detected
Claude session ID needed for fork/resume. Check:
agent-deck session show <name> --json | jq '.claude_session_id'
If null, restart session and interact with Claude.
High CPU Usage
With many sessions: Normal if batched updates. Check:
agent-deck status # Should show ~0.5% CPU when idle
With active session: Normal (live preview updates).
Log Files Too Large
Add to ~/.agent-deck/config.toml:
[logs]
max_size_mb = 1
max_lines = 2000
Global Search Not Working
Check config:
[global_search]
enabled = true
Also verify ~/.claude/projects/ exists and has content.
Debugging
Enable debug logging:
AGENTDECK_DEBUG=1 agent-deck
Check session logs:
tail -100 ~/.agent-deck/logs/agentdeck_<session>_*.log
Report a Bug
If something isn't working, please create a GitHub issue with all relevant context.
Step 1: Gather Information
Run these commands and save output:
# Version info
agent-deck version
# Current status
agent-deck status --json
# Session details (if session-related)
agent-deck session show <session-name> --json
# Config (sanitized - removes secrets)
cat ~/.agent-deck/config.toml | grep -v "KEY\|TOKEN\|SECRET\|PASSWORD"
# Recent logs (if error occurred)
tail -100 ~/.agent-deck/logs/agentdeck_<session>_*.log 2>/dev/null
# System info
uname -a
echo "tmux: $(tmux -V 2>/dev/null || echo 'not installed')"
Step 2: Describe the Issue
Prepare clear answers to:
- What did you try? (exact command or TUI action)
- What happened? (error message, unexpected behavior)
- What did you expect? (correct behavior)
- Can you reproduce it? (steps to trigger)
Step 3: Create GitHub Issue
Go to: https://github.com/asheshgoplani/agent-deck/issues/new
Use this template:
## Description
[Brief description of the issue]
## Steps to Reproduce
1. [First step]
2. [Second step]
3. [What happened]
## Expected Behavior
[What should have happened]
## Environment
- agent-deck version: [output of `agent-deck version`]
- OS: [macOS/Linux/WSL]
- tmux version: [output of `tmux -V`]
## Debug Output
<details>
<summary>Status JSON</summary>
```json
[paste agent-deck status --json]
[paste sanitized config]
[paste relevant log lines]
Step 4: Follow Up
- Check for responses on your issue
- Test any suggested fixes
- Update issue with results
Recovery
Session Metadata Lost
Backups at:
~/.agent-deck/profiles/default/sessions.json.bak
~/.agent-deck/profiles/default/sessions.json.bak.1
~/.agent-deck/profiles/default/sessions.json.bak.2
Restore:
cp ~/.agent-deck/profiles/default/sessions.json.bak \
~/.agent-deck/profiles/default/sessions.json
tmux Sessions Lost
Session logs preserved:
tail -500 ~/.agent-deck/logs/agentdeck_<session>_*.log
Profile Corrupted
Create fresh:
agent-deck profile create fresh
agent-deck profile default fresh
Critical Warnings
NEVER run these commands - they destroy ALL agent-deck sessions:
# DO NOT RUN
tmux kill-server
tmux ls | grep agentdeck | xargs tmux kill-session
Recovery impossible - metadata backups exist but tmux sessions are gone.