bots-n-cats Documentation
Everything you need to know about making your code purr
Introduction
bots-n-cats is a GitHub App that transforms your development activity into a live, ambient soundtrack. Each commit, pull request, merge, deploy, and test result generates unique musical patterns, creating an audio representation of your codebase's heartbeat.
How it works: GitHub webhooks trigger our audio engine, which generates real-time musical compositions using Tone.js synthesis. Each event type has unique musical characteristics that reflect its meaning.
Installation
Step 1: Install the GitHub App
- Visit the GitHub App installation page
- Choose which repositories to enable (specific repos or all repositories)
- Click "Install" to authorize the app
- You'll be redirected to the success page
Step 2: Grant Permissions
bots-n-cats requires the following GitHub permissions:
- Read access to repository events (push, pull request, issues)
- Read access to workflows (for CI/CD events)
- Webhook subscriptions for real-time event processing
Privacy Note: bots-n-cats only reads event metadata (event type, timestamp, repository name). We never access your source code or commit contents.
Configuration
Repository Settings
After installation, configure your repository settings:
- Enable/Disable Audio: Turn soundtrack generation on or off per repository
- Volume Settings: Adjust base volume for event sounds
- Event Filters: Choose which events trigger sounds
- Sharing: Generate public or private stream URLs
Team Access
Share your repository's soundtrack with your team:
- Open the bots-n-cats dashboard
- Select your repository
- Click "Share Stream"
- Copy the stream URL and send to team members
Event Types
bots-n-cats supports 6 core event types, each with unique musical characteristics:
🟢 Code Push
Triggered when commits are pushed to any branch
Bass synth arpeggio (like a purr)
120 BPM, C minor pentatonic
🔵 Pull Request
Triggered when PRs are opened, updated, or reviewed
Sustained chord progression
100 BPM, F major
🟣 Merge
Triggered when PRs are merged or branches are merged
Resolution cadence (major key)
110 BPM, G major
🟠 Deploy
Triggered by deployment workflows (production/staging)
Dramatic transition with reverb
130 BPM, D mixolydian
✅ Test Pass
Triggered when CI tests complete successfully
Bright major chord (happy chirp)
140 BPM, A major
❌ Test Fail
Triggered when CI tests fail
Dissonant cluster (warning)
90 BPM, E diminished
Musical Mapping
bots-n-cats uses sophisticated musical algorithms to map development activity to audio:
Emotion Categories
🔴 Tension
Failures, conflicts → minor key, dissonance
💚 Resolution
Merges, fixes → major key, consonance
⚡ Activity
Commits, comments → increased rhythm
📈 Growth
New features → layering, complexity
Parameter Mapping
- Commit frequency → BPM (tempo)
- Lines changed → Duration and complexity
- Programming language → Instrument type
- Test pass/fail → Effects intensity
- Time of day → Ambient texture layers
Usage
Listening to Your Soundtrack
- Open the bots-n-cats dashboard
- Select your repository from the list
- Click "Play Stream" to start listening
- Adjust volume and enable/disable specific events
- Share the stream URL with your team
Best Practices
- Play your soundtrack in the background during work hours
- Use headphones for immersive experience
- Enable desktop notifications for important events
- Share streams during standup meetings for team awareness
- Archive notable soundtracks as development milestones
Troubleshooting
No sound is playing
- Check that the app is installed on your repository
- Verify webhooks are enabled in repository settings
- Ensure your browser allows audio playback
- Check volume settings in the dashboard
Events are not triggering
- Check GitHub App permissions
- Verify webhook deliveries in GitHub settings
- Look for failed webhook requests in GitHub
- Contact support if issues persist
Audio is choppy or laggy
- Check your internet connection
- Close other browser tabs using audio
- Try a different browser (Chrome recommended)
- Reduce volume or disable some event types
Frequently Asked Questions
Is bots-n-cats free?
Yes! bots-n-cats is free for personal projects and open source repositories. Team plans with additional features coming soon.
Can I use real cat sounds instead of synthesized ones?
Real cat sound integration is coming in a future update! We're currently curating a library of pitch-tuned cat samples.
Does this slow down my GitHub workflows?
No. bots-n-cats processes webhooks asynchronously and does not affect your CI/CD pipeline performance.
Can I customize the musical mappings?
Custom mappings are planned for a future release. For now, you can enable/disable specific events and adjust volume.
Is my code data secure?
Yes. bots-n-cats only reads event metadata (type, timestamp, repo name). We never access your source code or commit contents.
Can I record or download my soundtrack?
Recording and download features are planned for premium tiers. Currently, soundtracks are live-streamed only.
Need More Help?
Our team is here to help you get the most out of bots-n-cats