Claude Code Connection

CrewHub connects to Claude Code by watching the ~/.claude/projects/ directory for live JSONL session files. This requires no extra configuration — just have Claude Code installed.

How It Works

When a Claude Code session starts, it writes a JSONL log to ~/.claude/projects/<hash>/<session-id>.jsonl. CrewHub watches these files in real-time using inotify (Linux) or FSEvents (macOS) and streams updates to the dashboard.

• No polling — file system events trigger instant updates
• Reads tool calls, messages, token counts, and cost in real-time
• Works with any number of simultaneous sessions
• Interactive mode allows sending messages back to the agent

Auto-Detection

At startup, CrewHub searches common locations for the Claude CLI:

# Checked in order:
/usr/local/bin/claude
/opt/homebrew/bin/claude
~/.local/bin/claude
# Also checks: which claude

The onboarding wizard shows a green checkmark if Claude Code is found. If it's in a non-standard location, you can configure the path manually.

Manual Path Configuration

If Claude Code is installed in a custom location, set the path in CrewHub's settings:

1. Open CrewHub at http://localhost:5181
2. Go to Settings → Connections → Claude Code
3. Enter the full path to your claude binary
4. Click Test Connection to verify

Or set via environment variable:

CLAUDE_BIN=/custom/path/claude ./scripts/start.sh

Interactive vs Read-Only Mode

Feature	Interactive (local)	Read-Only (Docker)
View session activity	✅	✅
Send messages to agent	✅	❌
Start meetings	✅	❌
Run tasks with agent	✅	❌
Generate meeting summaries	✅	❌

Troubleshooting

No sessions appearing

• Make sure at least one Claude Code session is running: claude --print "hello"
• Check that ~/.claude/projects/ exists and contains .jsonl files
• Verify the path in Settings → Connections

Session shows as "stale"

Sessions are marked stale after 30 minutes of inactivity. Start a new message to the agent to bring it back online.

Permissions error on Linux

chmod -R 755 ~/.claude/projects/