# Troubleshooting Guide

> If something isn't working, please create a GitHub issue with all relevant context.

- Skill: `tools-only/troubleshooting-guide-22` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/troubleshooting-guide-22`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/troubleshooting-guide-22/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/troubleshooting-guide-22

---

# 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.

```bash
# 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:

```bash
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:
```bash
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`:
```toml
[logs]
max_size_mb = 1
max_lines = 2000
```

### Global Search Not Working

Check config:
```toml
[global_search]
enabled = true
```

Also verify `~/.claude/projects/` exists and has content.

## Debugging

Enable debug logging:
```bash
AGENTDECK_DEBUG=1 agent-deck
```

Check session logs:
```bash
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:

```bash
# 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:

```markdown
## 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]
```

</details>

<details>
<summary>Config (sanitized)</summary>

```toml
[paste sanitized config]
```

</details>

<details>
<summary>Logs</summary>

```
[paste relevant log lines]
```

</details>
```

### Step 4: Follow Up

- Check for responses on your issue
- Test any suggested fixes
- Update issue with results

## Recovery

### Session Metadata Lost

Backups at:
```bash
~/.agent-deck/profiles/default/sessions.json.bak
~/.agent-deck/profiles/default/sessions.json.bak.1
~/.agent-deck/profiles/default/sessions.json.bak.2
```

Restore:
```bash
cp ~/.agent-deck/profiles/default/sessions.json.bak \
   ~/.agent-deck/profiles/default/sessions.json
```

### tmux Sessions Lost

Session logs preserved:
```bash
tail -500 ~/.agent-deck/logs/agentdeck_<session>_*.log
```

### Profile Corrupted

Create fresh:
```bash
agent-deck profile create fresh
agent-deck profile default fresh
```

## Critical Warnings

**NEVER run these commands - they destroy ALL agent-deck sessions:**

```bash
# DO NOT RUN
tmux kill-server
tmux ls | grep agentdeck | xargs tmux kill-session
```

**Recovery impossible** - metadata backups exist but tmux sessions are gone.