ccremote

<div align="center">
    <h1>ccremote</h1>
    <p><strong>Claude Code Remote</strong></p>
</div>

<p align="center">
    <a href="https://npmjs.com/package/ccremote"><img src="https://img.shields.io/npm/v/ccremote?color=yellow" alt="npm version" /></a>
    <a href="https://packagephobia.com/result?p=ccremote"><img src="https://packagephobia.com/badge?p=ccremote" alt="install size" /></a>
</p>

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

### 1. Install and Initialize

```bash
# 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

```bash
# 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

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

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

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

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

### Required Settings

```bash
# 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

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

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

```bash
# 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

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](https://atyourservice.ai/?utm_source=github&utm_medium=sponsorship&utm_campaign=ccremote)

<div>
  <a href="https://atyourservice.ai/?utm_source=github&utm_medium=sponsorship&utm_campaign=ccremote">
    <img src="https://atyourservice.ai/ogimage.png?utm_source=github&utm_medium=sponsorship&utm_campaign=ccremote" alt="AI@YourService" width="300" />
  </a>
</div>

## Acknowledgements

Big thanks to the authors and maintainers of:

- **[Claude-Code-Remote](https://github.com/JessyTsui/Claude-Code-Remote)** - Demonstrated that remote control was possible and provided valuable insights into different approaches for remote notifications
- **[ccusage](https://github.com/ryoppippi/ccusage)** - Great tool that inspired package and repository structure patterns

## License

MIT