ccremote

ccremote

Claude Code Remote

Claude Code Remote

• Approve prompts from Discord Approve Claude Code prompts (file edits, shell commands) from Discord, so sessions don't stall when you're away.

• Continue sessions after quota resets Detect when a session stops due to quota limits, wait until the 5-hour window resets, then automatically continue.

• Align quota windows with your workday Schedule an early dummy command (e.g. 5 AM) so quota windows align with your workday → effectively 3 usable windows instead of 2.

• Get notified when tasks complete Receive Discord notifications when Claude finishes a task and is ready for new input (no more checking back every few minutes).

• Remote session monitoring View current session output directly in Discord with the /output command - see what Claude is working on from anywhere.

Quick Start

1. Install and Initialize

# Install globally (recommended)
npm install -g ccremote

# Initialize configuration interactively
ccremote init

# Keep ccremote up to date
npm update -g ccremote

Note: ccremote automatically checks for updates once per day and displays a notification if a newer version is available.

2. Start Monitoring

# Start with auto-attach to Claude Code
ccremote

# Or with custom session name
ccremote start --name "my-session"

💡 Pro tip: ccremote without arguments is the same as ccremote start - just replace claude with ccremote in your workflow!

That's it! You'll be automatically attached to a Claude Code session with monitoring active.

Quick Setup

• Initialize Configuration:

  ccremote init                    # Interactive setup (creates ~/.ccremote.env by default)
  

  The interactive setup will:

  • Ask whether to create global (~/.ccremote.env) or local (./ccremote.env) config
  • Guide you through creating a Discord app and bot (only for you)
  • Help you find your Discord bot token and user ID
  • Generate a complete configuration file

• Start a Monitored Session:

  ccremote start --name "my-session"
  

  This automatically:

  • Creates a tmux session with Claude Code running
  • Shows session details for 5 seconds
  • Attaches you directly to the Claude Code session

• Work Normally:

  • Use Claude Code as usual in the attached session
  • ccremote monitors in the background and will automatically continue when limits reset
  • Get Discord notifications about session status

Usage

# Initialize configuration (interactive)
ccremote init                            # Interactive setup (global by default)

# Start a new monitored session
ccremote                                 # Default command (same as 'ccremote start')
ccremote start                           # Auto-generated name
ccremote start --name "my-session"       # Custom name

# Schedule daily quota window alignment
ccremote schedule --time "5:00"          # Schedule daily 5 AM quota window
ccremote schedule --time "7:30am"        # Schedule daily 7:30 AM quota window

# Resume sessions
ccremote resume --session ccremote-1     # Resume a specific session
ccremote resume --dry-run               # Preview what would be resumed

# Manage sessions
ccremote list                            # List sessions for current project
ccremote list --all                      # List sessions from all projects
ccremote status --session ccremote-1     # Show session details
ccremote stop --session ccremote-1       # Stop session
ccremote stop --session ccremote-1 --force  # Force stop even if active

# Maintenance commands
ccremote clean                           # Clean up current project's dead sessions
ccremote clean --all                     # Clean up dead sessions from all projects
ccremote clean --dry-run                 # Preview what would be cleaned
ccremote setup-tmux                      # Configure tmux settings for ccremote

# Manual tmux access (if needed)
tmux attach -t ccremote-1                # Attach to existing session
tmux list-sessions                       # List all tmux sessions

How It Works

• Smart Monitoring: ccremote polls your tmux session every 2 seconds, analyzing output for Claude Code limit messages
• Auto-Continuation: When a usage limit is detected, ccremote waits for the limit to reset (typically 5 hours) and automatically continues your session
• Discord Notifications: Get real-time updates about your sessions:
  • 🚫 Usage limit reached
  • ✅ Session automatically continued
  • ❓ Approval requests (Claude Code confirmation dialogs)
  • ✅ Task completion notifications (when Claude is ready for new input)
  • ❌ Errors or session ended
• Seamless Integration: Works with your existing Claude Code workflow - the start command automatically attaches you to the session

Features

• 🔄 Automatic Continuation: Automatically continue your Claude Code sessions when usage limits reset
• 💬 Discord Integration: Real-time notifications and approval handling via Discord DM or private channels
• ✅ Task Completion Notifications: Get alerted when Claude finishes tasks and is ready for new input
• 📺 Remote Output Viewing: View current session output directly in Discord with /output command
• 🧹 Smart Cleanup: Automatic cleanup of orphaned Discord channels and session files
• 📱 Session Management: Create, list, monitor, and stop multiple sessions
• 🖥️ Tmux Integration: Seamless tmux session management with proper cleanup
• 🎯 Pattern Detection: Intelligent detection of usage limits, errors, and continuation opportunities
• ⚡ Smart Polling: Efficient monitoring with configurable intervals and retry logic
• 🔒 Secure: Environment-based configuration, no hardcoded credentials

Configuration

ccremote supports multiple configuration methods with the following priority (highest to lowest):

• Environment variables (prefixed with CCREMOTE_)
• Project config: ./ccremote.env
• Project config: ./.env
• Global config: ~/.ccremote.env

Required Settings

# Required: Discord Bot Configuration  
CCREMOTE_DISCORD_BOT_TOKEN=your_discord_bot_token
CCREMOTE_DISCORD_OWNER_ID=your_discord_user_id

# Optional: Additional authorized users (comma-separated)
CCREMOTE_DISCORD_AUTHORIZED_USERS=user_id1,user_id2

# Optional: Monitoring Configuration
CCREMOTE_MONITORING_INTERVAL=2000    # Polling interval in milliseconds
CCREMOTE_MAX_RETRIES=3               # Max retry attempts on error  
CCREMOTE_AUTO_RESTART=true           # Auto-restart monitoring on failure

Privacy Model

• Per-user bots: Each user should create their own Discord bot for privacy
• Per-project bots: For client work, create separate bots per project/organization
• Project-specific config: Use ccremote.env in each project directory
• Global config: Use ~/.ccremote.env for personal/default settings

Discord Setup

• Create Bot: Go to Discord Developer Portal → New Application → Bot

• Enable Intent: In Bot section, enable "Message Content Intent" (required for approval commands)

• Get Token: Copy the bot token from the Bot section

• Get User ID: Enable Developer Mode in Discord → Right-click your profile → Copy User ID

• Invite Bot: Use OAuth2 → URL Generator to create invite link with these permissions:

  • Administrator (recommended - for full channel management)

  OR for minimal permissions:

  • Manage Channels (to create private session channels)
  • Manage Roles (to set channel permissions)
  • Send Messages (to send notifications)
  • Read Message History (to see approval responses)

  💡 Note: If your bot lacks Manage Channels permission, ccremote will gracefully fall back to DMs

Discord Commands

Once your bot is set up and sessions are running, you can interact with ccremote through Discord:

In Session Channels:

• /output or output - View current session output (last 50 lines, formatted in code blocks)
• status - Show session status information
• 1, 2, 3 - Respond to approval dialogs with numbered options

Session Channels:

• Each monitored session gets its own private Discord channel (e.g., #ccremote-session-1)
• Channels are automatically created when sessions start
• Only you (and other authorized users) can see these channels
• Channels are archived when sessions end or via the clean command

Requirements

• Node.js 20.19.4 or higher
• tmux (for session management) - Important: macOS ships with tmux 3.3a which has a critical bug causing crashes when mouse mode is enabled. Install the latest version: brew install tmux
• Discord bot (for notifications)

Development

# Clone and install
git clone <repo>
cd ccremote
bun install

# Development commands
bun run dev start --name test       # Run in development mode
bun run check                       # Run all checks (lint + typecheck + test + build)
bun run build                       # Build for production
bun run test                        # Run tests with vitest
bun run lint                        # Lint code with ESLint
bun run typecheck                   # Type check with TypeScript
bun run format                      # Format code (lint --fix)
bun run release                     # Full release workflow (check + version bump)
bun run release:test                 # Test package without releasing

# Global development installation (recommended approach)
bun run release:test                 # Build, package, and install globally

# After making changes, simply run:
bun run release:test                 # Rebuilds, repackages, and reinstalls globally

Release Process

Key Principles

• Test before merging: Test features (npm pack + local install) on feature branches
• Publish from main: Only publish to npm from main branch after PR merge
• Tag releases: Create git tags for published versions

Workflow

• Merge features: All features merged to main via GitHub PRs
• Release: On main branch, run bun run release
  • Validates you're on main branch
  • Runs all checks (lint, typecheck, tests, build)
  • Creates and tests package locally
  • Interactive version bump
  • Publishes to npm and creates git tag
• Bug fixes: If issues found, fix via PR then re-run bun run release

Sponsors

• AI@YourService

Acknowledgements

Big thanks to the authors and maintainers of:

• Claude-Code-Remote - Demonstrated that remote control was possible and provided valuable insights into different approaches for remote notifications
• ccusage - Great tool that inspired package and repository structure patterns

License

MIT