/agent-deck

Troubleshooting Guide

Common issues and solutions for agent-deck.

Quick Fixes

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

1. Check if attached: agent-deck mcp attached <session>
2. Restart session: agent-deck session restart <session>
3. 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:

1. What did you try? (exact command or TUI action)
2. What happened? (error message, unexpected behavior)
3. What did you expect? (correct behavior)
4. 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.