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

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

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

4. 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).

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

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

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

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

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

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

# 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

1. Smart Monitoring: ccremote polls your tmux session every 2 seconds, analyzing output for Claude Code limit messages
2. Auto-Continuation: When a usage limit is detected, ccremote waits for the limit to reset (typically 5 hours) and automatically continues your session
3. 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
4. Seamless Integration: Works with your existing Claude Code workflow - the start command automatically attaches you to the session

• 🔄 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

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

1. Environment variables (prefixed with CCREMOTE_)
2. Project config: ./ccremote.env
3. Project config: ./.env
4. Global config: ~/.ccremote.env

# 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

• 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

1. Create Bot: Go to Discord Developer Portal → New Application → Bot

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

3. Get Token: Copy the bot token from the Bot section

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

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

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

• 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)

# 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

• 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

1. Merge features: All features merged to main via GitHub PRs
2. 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
3. Bug fixes: If issues found, fix via PR then re-run bun run release

• AI@YourService

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

MIT