claude-code-toolkit is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install claude-code-toolkit

It will make the claude-code-toolkit command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall claude-code-toolkit uninstalls.

Adding `claude_code_toolkit` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add claude-code-toolkit

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

claude-code-toolkit = "0.3.1"

The claude_code_toolkit library will be automatically available globally. Read the claude_code_toolkit library documentation.

Back to the crate overview.

Readme

claude-code-toolkit

Part of the GoodieBag collection of tools and libraries

Claude Code management tool for automatic credential synchronization to GitHub, session monitoring, and daemon service management.

Features

🔄 Automatic Credential Sync: Syncs Claude Code credentials to GitHub organization/repository secrets
⏰ Smart Scheduling: Monitors token expiry and syncs 1 minute after new token generation
🎯 Multi-Target Support: Sync to multiple GitHub organizations and repositories simultaneously
📊 Session Monitoring: Real-time session timer and status tracking with desktop notifications
🔧 Systemd User Service Integration: Runs as a background daemon with automatic startup
🚀 High Performance: Written in Rust for minimal resource usage and maximum reliability

Installation

Option 1: Cargo Install (Recommended)

# Install from crates.io
cargo install claude-code-toolkit

# Ensure ~/.cargo/bin is in your PATH
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Option 2: From Source

# Clone the repository
git clone https://github.com/deepbrainspace/goodiebag
cd goodiebag/packages/claude-code-toolkit

# Build and install
cargo install --path .

Important: The binary must remain in a stable location for the daemon service to work. If you move the binary after installing the service, run claude-code-toolkit service install again.

Prerequisites

Rust 2024 Edition (rustc 1.80+)
GitHub CLI (gh) installed and authenticated
GitHub Personal Access Token with appropriate permissions (see setup below)
Claude Code installed and authenticated
Linux/macOS with systemd (for daemon functionality)

GitHub Setup

1. Install GitHub CLI

# Ubuntu/Debian
sudo apt install gh

# macOS
brew install gh

# Or download from https://cli.github.com/

2. Create GitHub Personal Access Token

Go to GitHub Settings > Developer Settings > Personal Access Tokens > Fine-grained tokens
Create a new token with these permissions:
- Repository access: Select specific repositories OR all repositories (depending on your needs)
- Repository permissions:
  - Secrets: Write (required for updating repository secrets)
  - Metadata: Read (required for basic repository access)
- Organization permissions (if syncing to organizations):
  - Organization secrets: Write (required for updating organization secrets)
  - Members: Read (required for organization access)

3. Authenticate GitHub CLI

# Login using your PAT
gh auth login

# Or set token directly
export GITHUB_TOKEN="your_github_pat_here"
gh auth login --with-token <<< "$GITHUB_TOKEN"

# Verify authentication
gh auth status

Quick Start

Install and Configure:

# Add GitHub organization
claude-code-toolkit org add your-org-name

# Add GitHub repository
claude-code-toolkit repo add owner/repository

# Install and start daemon
claude-code-toolkit service install

Check Status:

claude-code-toolkit status

Real-time Session Timer:

claude-code-toolkit timer

Commands

Session Management

claude-code-toolkit status - Show comprehensive session and sync status
claude-code-toolkit timer - Real-time session timer with progress bar

Organization Management

claude-code-toolkit org add <name> [--secret-name NAME] - Add GitHub organization
claude-code-toolkit org remove <name> - Remove organization
claude-code-toolkit org list - List configured organizations with availability

Repository Management

claude-code-toolkit repo add <owner/repo> [--secret-name NAME] - Add repository
claude-code-toolkit repo remove <owner/repo> - Remove repository
claude-code-toolkit repo list - List configured repositories

Sync Operations

claude-code-toolkit sync now - Force immediate credential sync
claude-code-toolkit sync status - Show detailed sync status for all targets
claude-code-toolkit sync logs [--lines N] - View daemon logs

Service Management

claude-code-toolkit service install - Install and start systemd user daemon
claude-code-toolkit service uninstall [--keep-config] - Uninstall daemon
claude-code-toolkit service start/stop/restart - Control daemon
claude-code-toolkit service enable/disable - Control auto-start on login

Configuration

claude-code-toolkit configure - Interactive configuration wizard (coming soon)

Configuration

Command-Line Configuration

You can configure targets using the CLI commands:

# Add organizations
claude-code-toolkit org add my-org --secret-name CLAUDE_TOKEN
claude-code-toolkit org add another-org --secret-name CUSTOM_CLAUDE_TOKEN

# Add repositories
claude-code-toolkit repo add owner/repo --secret-name CLAUDE_CODE_TOKEN
claude-code-toolkit repo add owner/special-repo --secret-name CUSTOM_TOKEN

# List current configuration
claude-code-toolkit org list
claude-code-toolkit repo list

Direct YAML Configuration

Alternative: You can directly edit the configuration file at ~/.goodiebag/claude-code/config.yml:

daemon:
  log_level: info # debug, info, warn, error
  sync_delay_after_expiry: 60 # seconds to wait after token expiry

github:
  organizations:
    - name: deepbrainspace
      secret_name: CLAUDE_CODE_TOKEN # Custom secret name (optional)
    - name: another-org
      secret_name: CLAUDE_ACCESS_TOKEN
    - name: simple-org # Uses default secret name

  repositories:
    - repo: user/special-repo
      secret_name: CUSTOM_CLAUDE_TOKEN
    - repo: owner/another-repo # Uses default secret name

notifications:
  session_warnings: [30, 15, 5] # Warning times (minutes before expiry)
  sync_failures: true # Notify on sync failures

Configuration Notes:

If secret_name is omitted, defaults to CLAUDE_CODE_TOKEN
Restart the daemon after editing YAML: claude-code-toolkit service restart
Validate configuration: claude-code-toolkit status
The CLI commands automatically update the YAML file

Daemon Installation Details

The claude-code-toolkit service install command:

Creates Systemd Service: Installs ~/.config/systemd/user/claude-code-sync.service
References Current Binary: Uses the exact path of the currently running binary (no copying)
User Service: Runs as a user service (no root privileges required)
Auto-Start: Enables automatic startup on user login
Security Sandboxing: Runs with restricted file system access

Service Location: ~/.config/systemd/user/claude-code-sync.service Service Command: {binary_path} daemon Service Type: User service (systemctl --user)

Manual Service Management

# View service status
systemctl --user status claude-code-sync

# Control service directly
systemctl --user start/stop/restart claude-code-sync

# View logs
journalctl --user -u claude-code-sync -f

# Remove service manually
systemctl --user stop claude-code-sync
systemctl --user disable claude-code-sync
rm ~/.config/systemd/user/claude-code-sync.service
systemctl --user daemon-reload

How It Works

Credential Monitoring: Daemon monitors ~/.claude/.credentials.json for changes
Smart Timing: When token expires, waits 60 seconds for Claude Code to refresh it
Automatic Sync: Detects new token and syncs to all configured GitHub targets
Startup Recovery: Performs reconciliation check on startup to catch missed syncs
Status Tracking: Maintains detailed sync status and error information per target

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Claude Code    │───▶│  claude-code     │───▶│  GitHub Secrets │
│  Credentials    │    │  Daemon          │    │  (Orgs & Repos) │
│  ~/.claude/     │    │  (Systemd)       │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                               │
                               ▼
                       ┌──────────────────┐
                       │  Configuration   │
                       │  ~/.goodiebag/   │
                       │  claude-code/    │
                       └──────────────────┘

Development

Building

# Check code
cargo check

# Run tests
cargo test

# Build optimized binary
cargo build --release

# Run with NX
nx build claude-code-toolkit
nx test claude-code-toolkit
nx lint claude-code-toolkit

Testing

The project includes comprehensive test coverage:

Unit Tests: Core functionality testing
Integration Tests: End-to-end workflow testing
Property Tests: Edge case validation

# Run all tests
cargo test

# Run tests with coverage
cargo test --all-features

# Run specific test module
cargo test config::tests

Code Quality

# Lint with clippy
cargo clippy -- -D warnings

# Format code
cargo fmt

# Check formatting
cargo fmt --check

Troubleshooting

Check Daemon Status

claude-code-toolkit status
systemctl --user status claude-code-sync

View Detailed Logs

claude-code-toolkit sync logs --lines 100
journalctl --user -u claude-code-sync -f

Manual Sync

claude-code-toolkit sync now

Reset Configuration

claude-code-toolkit service uninstall
rm -rf ~/.goodiebag/claude-code
claude-code-toolkit service install

Performance

Binary Size: ~3.5MB (optimized)
Memory Usage: ~5-10MB runtime
CPU Usage: Near-zero when idle
Startup Time: <100ms
Sync Time: ~2-5 seconds per target

Security

Credential Security: Read-only access to local Claude credentials
GitHub Authentication: Uses authenticated gh CLI for all operations
Audit Trail: All operations logged with timestamps and outcomes
Systemd Sandboxing: Runs with minimal file system permissions
No Network Storage: All data stored locally in user directories

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

MIT License - see LICENSE for details.

Support

Issues: GitHub Issues
Documentation: This README and inline code documentation
Community: Discussions in the repository

Installing the command-line executable

Adding claude_code_toolkit library as a dependency

Adding `claude_code_toolkit` library as a dependency