Claude Code Remote

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.

Quick Start

$3

``bash


Install globally (recommended)

`bash


Start with auto-attach to Claude Code

💡 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

1. Initialize Configuration:
`bash
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:
`bash
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

Usage

`bash


Initialize configuration (interactive)

- 🔄 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):

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

$3

`bash


Required: Discord Bot Configuration

- 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

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

$3

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

`bash


Clone and install

- 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

$3

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`

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