An intelligent master agent that orchestrates Claude Code sessions 24/7
PerpetualCC acts like an experienced human developer - understanding project context, making informed decisions about tool permissions, answering Claude Code's questions automatically, and knowing when to escalate to a real human.
When Claude Code hits its token limit, PerpetualCC automatically detects the reset time and resumes your session the moment tokens are available again. No more forgetting to come back, no more lost momentum.
Claude Code often asks questions like "Should I proceed?" or "Which approach do you prefer?" PerpetualCC automatically answers these questions using:
- Rule-based patterns - No AI needed, handles common questions instantly
- Gemini API - Context-aware responses for complex decisions
- Local LLM (Ollama) - Privacy-focused, works offline with DeepSeek or other models
You stay focused on high-level decisions while PerpetualCC handles the routine interactions.
- Autonomous Operation - Runs Claude Code sessions unattended, handling permissions and questions automatically
- Auto-Resume on Token Reset - Detects rate limits, saves session state, and automatically resumes when tokens are available
- Smart Question Answering - Multiple brain options (rule-based, Gemini, Ollama) to answer Claude Code's questions
- Risk-Based Permissions - Auto-approves safe operations, asks brain for medium-risk, escalates dangerous ones to human
- Multi-Session Management - Run and monitor multiple concurrent sessions
- Human Bridge - macOS notifications when human input is needed
- Project Understanding - RAG-powered codebase knowledge (optional)
- Learning System - Improves decisions over time (optional)
The easiest way to install PerpetualCC is with pipx, which installs the pcc command globally in an isolated environment:
# Install pipx if you don't have it
brew install pipx # macOS
# or: python -m pip install --user pipx
# Install PerpetualCC
pipx install perpetualcc
# Verify installation
pcc --version
# Install with optional features (e.g., Gemini brain)
pipx install 'perpetualcc[gemini]'
# Install with all features
pipx install 'perpetualcc[all]'# Install from PyPI
pip install perpetualcc
# Or install with optional features
pip install 'perpetualcc[all]'# Clone the repository
git clone https://github.com/yourusername/perpetualcc.git
cd perpetualcc
# Create virtual environment with uv (recommended)
uv venv .venv
source .venv/bin/activate
# Install with development dependencies
uv pip install -e ".[dev]"
# Or install with all optional features
uv pip install -e ".[all,dev]"| Install Command | Features Added |
|---|---|
uv pip install -e ".[gemini]" |
Gemini API brain |
uv pip install -e ".[ollama]" |
Local LLM brain via Ollama |
uv pip install -e ".[knowledge]" |
RAG + code understanding |
uv pip install -e ".[memory]" |
SQLite learning persistence |
uv pip install -e ".[all]" |
All optional features |
# Simple task
pcc start ./your-project --task "Build a REST API with authentication"
# With requirements file
pcc start ./your-project --requirements requirements.md
# Run in background
pcc start ./your-project --task "Refactor the auth module" --detach# List all sessions
pcc list
# Check detailed status
pcc status <session-id>
# Attach to live session
pcc attach <session-id># View pending decisions
pcc pending
# Respond to a question
pcc respond 1 "Use PostgreSQL"
# Interactive response
pcc respond 1 --interactive┌─────────────────────────────────────────────────────────────────┐
│ PerpetualCC │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Claude Code Session ──▶ Event Stream ──▶ Master Agent │
│ │ │
│ ┌──────────────────┼──────────────┐│
│ │ │ ││
│ ▼ ▼ ▼│
│ ┌──────────┐ ┌──────────┐ ┌─────┴│
│ │ Decision │ │ Brain │ │Human ││
│ │ Engine │ │ (answer) │ │Bridge││
│ └────┬─────┘ └────┬─────┘ └──────┘│
│ │ │ │
│ LOW risk: Auto-approve │ │
│ MED risk: Use brain ───────┘ │
│ HIGH risk: Escalate to human ─────────────────│
│ │
└─────────────────────────────────────────────────────────────────┘
| Risk Level | Examples | Action |
|---|---|---|
| LOW | Read any file, Glob/Grep, Write to src/tests/ | Auto-approve |
| MEDIUM | Git commands, config files, network requests | Ask brain |
| HIGH | rm -rf, sudo, .env files, --force flags | Escalate to human |
| Type | Setup | Best For |
|---|---|---|
| Rule-Based | Default, no setup | Simple projects, predictable workflows |
| Gemini | Set GEMINI_API_KEY |
Context-aware decisions, complex questions |
| Ollama | Run ollama serve locally |
Privacy-focused, offline operation |
Configuration is stored at ~/.perpetualcc/config.toml. Key settings:
# Configure brain
pcc config brain gemini # Use Gemini API
pcc config brain ollama # Use local Ollama
pcc config brain none # Rule-based only
# View configuration
pcc config show| Variable | Purpose |
|---|---|
ANTHROPIC_API_KEY |
Required for Claude Code sessions |
GEMINI_API_KEY |
Optional, for Gemini brain |
Create a requirements.md to give PerpetualCC context:
# Project: My API
## Overview
REST API for user management.
## Preferences
- Database: PostgreSQL
- ORM: Prisma
- Auth: JWT with refresh tokens
- Test framework: Vitest
## Tasks
- [ ] Set up project structure
- [ ] Create user registration
- [ ] Implement authentication
- [ ] Write tests| Command | Description |
|---|---|
pcc start <path> |
Start a new session |
pcc list |
List all sessions |
pcc status <id> |
Show session details |
pcc attach <id> |
Attach to live session |
pcc pause <id> |
Pause a session |
pcc resume <id> |
Resume a session |
pcc add <id> "task" |
Add task to queue |
pcc pending |
List pending human decisions |
pcc respond <n> |
Respond to escalation |
pcc config |
Configure settings |
pcc logs <id> |
View session logs |
# Run all tests
pytest
# Run with coverage
pytest --cov=perpetualcc
# Run specific test file
pytest tests/unit/test_risk_classifier.py# Lint
ruff check perpetualcc/
# Format
ruff format perpetualcc/perpetualcc/
├── perpetualcc/
│ ├── cli.py # CLI commands (typer)
│ ├── claude/ # Claude Agent SDK integration
│ ├── core/ # Decision engine, session management
│ ├── brain/ # Question answering (rule-based, Gemini, Ollama)
│ ├── knowledge/ # RAG + code understanding (optional)
│ ├── memory/ # Learning systems (optional)
│ └── human/ # Notifications + escalation
├── tests/
│ ├── unit/
│ └── integration/
├── ARCHITECTURE.md # Detailed design document
└── CLAUDE.md # Context for Claude Code sessions
| Phase | Component | Status |
|---|---|---|
| 1 | CLI + Claude Adapter | Done |
| 2 | Decision Engine | Done |
| 3 | Brain (Rule-Based) | Done |
| 4 | Rate Limit + Checkpoint | Done |
| 5 | Session Manager | Done |
| 6 | Master Agent | Done |
| 7 | Knowledge Engine | Planned |
| 8 | Memory Systems | Planned |
| 9 | Human Bridge | Planned |
Contributions are welcome! Please read the Architecture Document to understand the system design.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
pytest) - Commit (
git commit -m 'feat: add amazing feature') - Push (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with the Claude Agent SDK
- CLI powered by Typer and Rich