Claude Code Integration

Claude Code is Anthropic's official CLI tool that brings Claude's AI capabilities directly to your terminal. Plexus can monitor your Claude Code sessions, tracking AI interactions, tool usage, and costs across all your projects.

What is Claude Code?

Claude Code is a command-line interface for interacting with Claude, Anthropic's AI assistant. It's designed for developers who prefer working in the terminal. Key features include:

• Direct Terminal Access - Run Claude directly from your command line
• Agentic Capabilities - Claude can read files, write code, run commands, and search your codebase
• Multi-Turn Conversations - Maintain context across multiple prompts in a session
• Tool Integration - Built-in tools for file operations, bash commands, web search, and more
• Hook System - Customizable scripts that run at specific lifecycle points

Claude Code supports various tools including Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, and MCP (Model Context Protocol) servers.

How Plexus Integrates with Claude Code

Plexus monitors Claude Code through its native hook system. Hooks are automated scripts that execute at specific points in Claude Code's workflow:

┌─────────────────────────────────────────────────┐
│                  Claude Code                     │
│                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │   Read   │  │  Write   │  │   Bash   │      │
│  │          │  │   Edit   │  │          │      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘      │
│       │             │             │             │
│       └─────────────┼─────────────┘             │
│                     ▼                           │
│  ┌──────────────────────────────────────────┐  │
│  │           Claude Code Hooks              │  │
│  │   (PreToolUse, PostToolUse, Stop, etc.)  │  │
│  └──────────────────────────────────────────┘  │
│                     │                           │
└─────────────────────┼───────────────────────────┘
                      ▼
              ┌───────────────┐
              │    Plexus     │
              │   Dashboard   │
              └───────────────┘

Monitored Events

Setting Up the Integration

Automatic Setup

When you first launch Plexus with Claude Code installed, the integration can be configured automatically:

1. Launch Plexus from your Applications folder
2. Go to Settings > Agents > Claude Code
3. Click Install Hooks
4. Restart your terminal and Claude Code session

Manual Hook Setup

If automatic setup doesn't work, you can configure hooks manually by editing Claude Code's settings file.

Settings File Location

Claude Code uses JSON settings files at three levels:

For Plexus integration, edit your user settings file:

# Create the .claude directory if it doesn't exist
mkdir -p ~/.claude

# Edit the settings file
nano ~/.claude/settings.json

Basic Hook Configuration

Add the following configuration to ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/Plexus.app/Contents/Resources/hooks/claude-code-hook.sh post-tool-use"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/Plexus.app/Contents/Resources/hooks/claude-code-hook.sh notification"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/Plexus.app/Contents/Resources/hooks/claude-code-hook.sh stop"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/Plexus.app/Contents/Resources/hooks/claude-code-hook.sh session-start"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/Plexus.app/Contents/Resources/hooks/claude-code-hook.sh session-end"
          }
        ]
      }
    ]
  }
}

Understanding Matchers

The matcher field determines which tools trigger a hook:

For Plexus, we recommend using "*" to capture all tool usage.

Verifying the Integration

After configuring hooks, verify the connection:

1. Open a new terminal session
2. Run claude to start Claude Code
3. Execute a simple command like "list files in this directory"
4. Check the Plexus dashboard - a new Claude Code session should appear

You can also verify hooks are loaded by running:

claude --debug

Or use Claude Code's built-in hook inspector:

# Inside a Claude Code session, type:
/hooks

Hook Event Details

PreToolUse

Executes before Claude uses a tool. Can be used to:

• Log upcoming actions
• Validate tool inputs
• Block dangerous operations

Input data received:

{
  "session_id": "abc123",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm install"
  }
}

PostToolUse

Executes after a tool completes. Ideal for:

• Tracking tool results
• Measuring execution time
• Formatting code after edits

Input data received:

{
  "session_id": "abc123",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.ts",
    "content": "..."
  },
  "tool_response": "File written successfully"
}

Notification

Triggers when Claude Code sends notifications:

• permission_prompt - Claude needs permission for an action
• idle_prompt - Claude is waiting for input (60+ seconds)

Input data received:

{
  "session_id": "abc123",
  "hook_event_name": "Notification",
  "notification_type": "permission_prompt",
  "message": "Claude wants to run: npm test"
}

Stop

Executes when Claude finishes responding. Useful for:

• Running tests after code changes
• Formatting modified files
• Logging session summaries

SessionStart / SessionEnd

Track session lifecycle for analytics and monitoring.

Advanced Configuration

Timeout Settings

Set a custom timeout for hook execution (default: 60 seconds):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "plexus-hook post-tool-use",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Environment Variables

Plexus hooks receive these environment variables:

Multiple Hooks Per Event

You can configure multiple hooks for the same event:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_PROJECT_DIR"
          },
          {
            "type": "command",
            "command": "plexus-hook post-tool-use"
          }
        ]
      }
    ]
  }
}

Permissions Configuration

Control Claude Code's tool permissions alongside hooks:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)"
    ]
  },
  "hooks": {
    "...": "..."
  }
}

Disabling Hooks Temporarily

To disable all hooks for debugging:

{
  "disableAllHooks": true
}

Troubleshooting

Claude Code Sessions Not Appearing

If sessions don't appear in Plexus:

1. Verify Plexus is running - Check your system tray/menu bar for the Plexus icon
2. Check hook configuration - Run /hooks inside Claude Code to see registered hooks
3. Verify hook path - Ensure the Plexus hook script path is correct
4. Check permissions - The hook script must be executable:

   chmod +x /Applications/Plexus.app/Contents/Resources/hooks/claude-code-hook.sh

5. Restart terminal - Close and reopen your terminal after editing settings

Hooks Not Executing

If hooks aren't triggering:

1. Check JSON syntax - Validate your settings.json:

   cat ~/.claude/settings.json | jq .

2. Verify matcher syntax - Tool matchers are case-sensitive
3. Check debug output - Run claude --debug to see hook execution details
4. Look for conflicts - Project settings override user settings

Settings Not Loading

If Claude Code ignores your settings:

1. Check file location - Ensure the file is at ~/.claude/settings.json
2. Validate JSON format - Use a JSON validator
3. Check precedence - Project-level settings take priority over user settings:
   • Enterprise policies (highest)
   • Command line arguments
   • .claude/settings.local.json
   • .claude/settings.json
   • ~/.claude/settings.json (lowest)

Hook Errors

If hooks error during execution:

1. Check hook script exists - Verify the script path is correct
2. Check exit codes:
   • Exit code 0: Success
   • Exit code 2: Blocking error (prevents tool execution)
   • Other codes: Non-blocking error
3. Review stderr output - Errors are logged in verbose mode
4. Test hook manually:

   echo '{"session_id":"test"}' | /path/to/plexus-hook.sh post-tool-use

Permission Denied Errors

If you see permission errors:

1. Make hook executable:

   chmod +x /path/to/hook-script.sh

2. Check directory permissions - The .claude directory should be readable
3. Verify Plexus has disk access - Grant Full Disk Access in System Preferences if needed

Delayed Updates in Dashboard

If session updates are delayed:

1. Check that Plexus and Claude Code can communicate via local socket
2. Verify no firewall is blocking local connections
3. Restart both Plexus and Claude Code

Best Practices

Organize Project-Level Hooks

For team projects, use .claude/settings.json for shared hooks:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run format"
          }
        ]
      }
    ]
  }
}

Keep personal Plexus hooks in ~/.claude/settings.json.

Monitor Token Usage

Plexus tracks token consumption per session. To optimize costs:

1. Review the Costs tab in session details
2. Identify expensive operations
3. Use Claude Code's built-in /compact command to reduce context when needed

Team Workflows

For teams using Claude Code:

1. Configure Slack/Discord notifications for waiting states
2. Use the History feature to review AI interactions
3. Track costs by project for budget management

Next Steps

• Set up Webhook Notifications for team alerts
• Explore Keyboard Shortcuts for faster navigation
• Check Configuration Options for advanced settings