CodeHero

The Developer That Never Rests
Powered by Claude AI

This is not an AI that answers questions. It builds software.

Instead of chatting back and forth, this AI works inside a real development environment. Describe what you want, and it plans the project, writes code, and tracks its own progress — like a developer on your team.

What makes it different is control. It understands your whole project, uses only the files it needs, avoids loops, and stops itself when something goes wrong.

For beginners, it removes complexity. For developers, it removes noise.

Download it. Let it build.

True Autonomy - Works While You Sleep

Unlike chat-based AI tools that require constant prompting, this system runs unattended for hours or even days. Create your tickets, describe what you want, and walk away. Come back to find completed features, fixed bugs, and working code.

Queue multiple tasks across projects
AI works through them one by one
Built-in failsafe prevents runaway sessions
Wake up to progress, not prompts

Control Everything from Your Phone

Work from anywhere with two-way Telegram integration. No need to open a laptop.

Get instant alerts when Claude needs your input or something fails
Reply to continue - just reply to any notification to give Claude new instructions
Ask quick questions - start with ? to get status updates without triggering work
Never lose time - respond from the bus, the coffee shop, or your bed

📱 Notification: "Task completed - awaiting review"
     ↓
💬 You reply: "add error handling too"
     ↓
🤖 Claude continues working

Screenshots

Dashboard - Real-time overview of projects, tickets, and usage statistics

Tickets Tickets - Track all development tasks across projects

Projects - Manage multiple projects with isolated environments

Ticket Detail - Claude's response with code and conversation history

Console Console - Real-time view of Claude working on tickets

Why CodeHero?

Challenge	Solution
"AI tools need constant prompting"	Set it and forget it - Claude works for hours unattended
"I want to code more, but time is limited"	Multiply your output - wake up to completed features
"Chat-based AI feels like extra work"	True autonomy - describe once, Claude figures out the rest
"I need my code to stay private"	Self-hosted - your code never leaves your infrastructure
"I want to think bigger, not type more"	Master from above - architect solutions, let AI build them

Key Features

Intelligent AI Features

SmartContext - Intelligent Context Management

Claude automatically understands your project structure without being told:

Auto-detects framework, language, and architecture
Finds relevant files based on the task at hand
Builds minimal context - only includes what's needed
Learns patterns from your codebase conventions
Reduces token usage by up to 70% vs. sending entire codebase

AI Failsafe (Watchdog)

Built-in protection against runaway AI sessions:

Monitors all active tickets every 30 minutes
Detects stuck patterns: repeated errors, circular behavior, no progress
Auto-pauses problematic tickets before excessive token usage
Telegram notifications when issues detected
Explains why it stopped in the conversation

AI Project Manager (Blueprint Planner)

Let Claude design and build your entire project from a single description:

How it works:

Describe what you want to build
CodeHero Manager creates the plan (tech stack, features, database)
Creates the project and tickets automatically
You just wait - wake up to working code

"Plan with AI" button on Projects page
Guided questionnaire - Claude asks about requirements
Auto-creates project with correct paths and settings
Auto-creates tickets with dependencies and sequences
Choose execution mode - autonomous, semi-autonomous, or supervised

Claude Assistant

Interactive Claude terminal with full control:

AI Model Selection: Choose Opus, Sonnet, or Haiku per session
Popup Window: Open in separate window for multi-monitor setups
Direct Access: Chat with Claude outside of ticket workflow
Full Terminal: Real PTY with color support

Execution Modes

Control how Claude runs your tickets with three security levels:

Mode	Description	Best For
Autonomous	Full access, no permission prompts	Trusted tasks, experienced users
Semi-Autonomous	Smart sandbox with automatic rules (recommended)	Most projects
Supervised	Asks permission for all write operations	Sensitive projects, learning

Semi-Autonomous Mode (New!) - The smart middle ground:

✅ Auto-allows: File operations within project, running tests, builds, linting
⚠️ Asks permission: Package installs (npm install, pip install), git commits, database migrations
🚫 Blocks: System files, /etc, .git folder modifications, dangerous commands
🔄 "Approve Similar": Approve once, auto-approve similar operations

Set per-ticket or project-wide - override defaults as needed

Dependency Modes

Control how tickets progress and close:

Strict (default) - User reviews and closes tickets manually
Relaxed - AI reviewer automatically closes completed tickets
Useful for chained tasks - Keep work flowing without manual intervention

Mode	Ticket Closing	Best For
Strict	User closes manually	Critical tasks, review needed
Relaxed	AI auto-closes	Batch work, trusted workflows

Visual Verification - "See With Your Eyes"

Claude can see exactly what you see:

Screenshot capture - Claude takes screenshots using Playwright
Visual analysis - Describes layout, styling, and UI issues
No more explaining - Just click "👁️ See" and Claude sees the problem
Automatic when needed - Mention visual issues and Claude uses Playwright automatically

Monaco Editor with LSP Support

VS Code-quality code editing right in your browser:

Monaco Editor - The same editor that powers VS Code
Intelligent Autocomplete - Context-aware suggestions as you type
Hover Documentation - See function docs by hovering
Go to Definition - Ctrl+Click to jump to definitions
Real-time Diagnostics - Errors and warnings as you type
Multi-language Support - Python, JavaScript, TypeScript, PHP, Java, C#, Kotlin, HTML, CSS, JSON
Optional LSP Servers - Install only what you need with setup_lsp.sh

Git Version Control

Automatic version control for every project:

Auto-commit - When AI completes work, changes are committed automatically
Commit Messages - Format: [TICKET-NUM] Title with full metadata
Git History Page - View all commits with timeline and diff viewer
Rollback - Restore any previous version with one click (preserves history)
Smart .gitignore - Auto-generated based on project type (PHP, Python, Node, .NET)
AI Context - Claude sees recent commits and can self-correct based on history
Initialize Existing - Add Git to existing projects from the web UI

Telegram - Work from Your Phone

Full two-way communication via Telegram. Control your AI developer from anywhere:

Instant Notifications - Get alerts when tasks complete, fail, or get stuck
Reply to Execute - Reply to any notification and Claude starts working
Quick Questions - Add ? to get instant status updates via AI
Never Wait - Respond immediately from your phone, no laptop needed
Easy Setup - One-click configuration from Settings panel (⚙️)

Core AI Features

Autonomous AI Agent - Claude AI works on tickets independently, writing real code
Multi-Project Management - Handle multiple projects with isolated databases
Parallel Execution - Process tickets from different projects simultaneously
Real-Time Console - Watch Claude write code live in your browser
Interactive Chat - Guide Claude or ask questions during execution
Voice Input - Speak instead of typing in ticket chat (auto-stops after 10s silence)

Ticket Management

Ticket Workflow - Structured flow: Open → In Progress → Awaiting Input → Done
Kill Switch - Instant control while Claude is working:
- /stop command or Stop button - Pause immediately and wait for correction
Message Queue - Messages sent during execution are read when Claude finishes
Auto-Close - Tickets auto-close after 7 days in awaiting input
Search - Search across tickets, projects, and history

Web Terminal

Full Linux terminal in your browser:

Real shell access via WebSocket
Popup support for multi-monitor setups
Full sudo access for system administration
256-color support with xterm.js

Backup & Restore

Auto Backup on Close - Project automatically backed up when ticket completes
Manual Backup - Create backup anytime from project page
Restore - Restore project files to any previous backup point
Export Project - Download complete project as ZIP

Project Migration

Move projects between servers with all data intact:

Export for Migration - Full backup with tickets, conversations, and database
Export Full - Complete backup including conversation history
Export Light - Smaller backup without conversations
Import Migration - Restore on any CodeHero server
Simple Import - Import files + database only (no tickets)

File Management

File Upload - Upload files directly to project via web interface
File Editor - Edit project files in browser with syntax highlighting
File Browser - Navigate project directory structure

Project Features

Auto Database Provisioning - MySQL database auto-created per project
phpMyAdmin Integration - Full database management with auto-login (port 9454)
Voice Input - Speak to create projects and tickets (name, description fields)
Project Archive/Reopen - Archive completed projects, reopen when needed
Global Context - Server environment info shared with all projects
Tech Stack Detection - Knows installed tools (Node.js, PHP, Java, etc.)

Monitoring & Analytics

Real-Time Usage Tracking - Tokens, API requests, and work duration tracked in real-time
Per-Project Stats - See exactly how much each project costs
Per-Ticket Stats - Know the cost of every feature or fix
Time-Based Reports - Daily, weekly, and monthly usage summaries
Session History - View all Claude sessions with full output
Daemon Status - Monitor background worker status

Infrastructure

Web Dashboard - Beautiful dark-theme admin panel
SSL Encryption - All traffic encrypted via Nginx
Self-Hosted - Complete control over your data
CLI Tool - Manage projects and tickets from terminal

Supported Application Types

CodeHero supports multiple project types with intelligent context and tooling:

Web Development

PHP / WordPress - Full PHP-FPM integration with Nginx
Static HTML/CSS/JS - Served directly via Nginx
API Projects - REST and GraphQL endpoints

.NET / ASP.NET Core

Full .NET 8 SDK support with automatic configuration
Auto Nginx Proxy - Each .NET app gets its own reverse proxy route
Systemd Services - Apps run as managed services with auto-restart
Port Management - Automatic port allocation (5001+)
PowerShell, Mono, Wine - Windows development tools available

Mobile Development (Android)

Android Emulator with Web Visualization

Run and test Android apps directly from your browser:

Server-based Emulator - Redroid (Android in Docker)
Live Screen Mirror - See and control the emulator via ws-scrcpy
ADB Integration - Install APKs, view logs, capture screenshots
Framework Support - Capacitor.js, React Native, Flutter, Native Android

📱 Your Browser → ws-scrcpy (HTTPS:8443) → Redroid Container
                         ↓
                   Live Android Screen
                   Touch/Keyboard Input

Remote ADB Device

Connect to physical Android devices or remote emulators:

Remote ADB - Connect to any device via IP:PORT
Same Commands - Install, debug, and test seamlessly
No Local Setup - Everything runs on the server

Backend / API

Node.js - Full Node 22.x with npm
Python - Python 3 with Flask, Django support
Java - GraalVM 24 with Gradle

Optional Setup Scripts

After initial installation, run these scripts based on your needs:

Script	What it installs
`setup_android.sh`	Docker, Redroid emulator, ws-scrcpy, ADB, Flutter, Gradle
`setup_windows.sh`	.NET 8 SDK, PowerShell, Wine, Mono, NuGet
`setup_devtools.sh`	Node.js, Java (GraalVM), multimedia tools (ffmpeg, ImageMagick, tesseract)
`setup_lsp.sh`	Language servers for code editor (Python, JS/TS, PHP, Java, C#, Kotlin, HTML/CSS)

# Android development (emulator + mobile frameworks)
sudo /opt/codehero/scripts/setup_android.sh

# Windows/.NET development
sudo /opt/codehero/scripts/setup_windows.sh

# Development tools (Node.js, Java, multimedia)
sudo /opt/codehero/scripts/setup_devtools.sh

# Code editor LSP (optional - for autocomplete, hover docs, etc.)
sudo /opt/codehero/scripts/setup_lsp.sh

Perfect For

Solo Developers - Multiply your productivity with an AI coding partner
Small Teams - Offload routine development tasks to AI
Agencies - Manage multiple client projects efficiently
Startups - Ship faster with AI-assisted development
Learning - See how AI approaches coding problems
Mobile Developers - Test Android apps without local emulator setup

Quick Start

One-Click Install (Recommended)

No technical knowledge required! Works on Windows, macOS, and Linux.

🪟 Windows - Open PowerShell as Admin, paste:

irm https://raw.githubusercontent.com/fotsakir/codehero/main/multipass/install-windows.ps1 | iex

🍎 macOS - Open Terminal, paste:

curl -sL https://raw.githubusercontent.com/fotsakir/codehero/main/multipass/install-macos.command | bash

🐧 Linux - Open Terminal, paste:

curl -sL https://raw.githubusercontent.com/fotsakir/codehero/main/multipass/install-linux.sh | bash

Paste → Enter → Wait 15 minutes → Done! Full guide →

After installation:

Dashboard: https://VM_IP:9453 (login: admin / admin123)
Change passwords: sudo /opt/codehero/scripts/change-passwords.sh

Manual Install (Ubuntu Server)

Requirements

Ubuntu 22.04 or 24.04 LTS (server or desktop)
2GB+ RAM recommended
Root/sudo access
Internet connection

One-Command Install

# Install required tools
apt-get update && apt-get install -y unzip wget net-tools

# Download and extract
cd /root
wget https://github.com/fotsakir/codehero/releases/latest/download/codehero-2.83.5.zip
unzip codehero-2.83.5.zip
cd codehero

# Run setup
chmod +x setup.sh && ./setup.sh

# Find your IP address
ifconfig

# Then install Claude Code CLI
/opt/codehero/scripts/install-claude-code.sh

The installer automatically sets up:

MySQL 8.0 database
Nginx web server with SSL and PHP-FPM
Python Flask application
Claude Code CLI
Background daemon service
All required dependencies

Upgrading from Previous Version

# Download new version
cd /root
unzip codehero-2.83.5.zip
cd codehero

# Preview changes (recommended)
sudo ./upgrade.sh --dry-run

# Run upgrade
sudo ./upgrade.sh

# Or auto-confirm all prompts
sudo ./upgrade.sh -y

The upgrade script will:

Create automatic backup of current installation
Apply any database migrations
Update all application files
Restart services
Show what changed in the new version

Access Your Dashboard

Service	URL	Default Login
Admin Panel	`https://YOUR_IP:9453`	admin / admin123
Web Projects	`https://YOUR_IP:9867`	-
phpMyAdmin	`https://YOUR_IP:9454`	auto-login from project

Claude Activation

CodeHero requires Claude to be activated before it can work on tickets. You have two activation methods and can use either the Web Terminal or Linux Terminal.

Method 1: Claude Subscription (Pro/Max)

If you have a Claude Pro or Claude Max subscription at claude.ai, you can use it directly.

Via Web Terminal (Dashboard)

Go to Dashboard → Click "Activate Claude" button (or "License Active")
Click "Open Terminal" in the Subscription section
In the terminal, type:
```
claude
```
Once Claude starts, type:
```
/login
```
Claude will display a URL - copy it (right-click → Copy)
Open the URL in your browser and authorize access
Copy the authorization code from the browser
Paste it back in the terminal (right-click → Paste)
Done! Claude is now activated with your subscription

Via Linux Terminal (SSH)

SSH into your server or open a terminal
Switch to the claude user:
```
sudo su - claude
```
Run Claude and login:
```
claude
```
Type /login and follow the same authorization flow as above

Method 2: Anthropic API Key

If you have an API key from console.anthropic.com, you can use it instead of a subscription.

Via Dashboard

Go to Dashboard → Click "Activate Claude" button
Select the "API Key" section
Paste your API key (starts with sk-ant-api...)
Click Save

Via Linux Terminal

SSH into your server

Create or edit the environment file:

sudo mkdir -p /home/claude/.claude
sudo nano /home/claude/.claude/.env

Add your API key:

ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

Save and set permissions:

sudo chown claude:claude /home/claude/.claude/.env
sudo chmod 600 /home/claude/.claude/.env

Verify Activation

After activation, the "Activate Claude" button in the dashboard will change to "License Active" (green).

You can also verify from terminal:

sudo su - claude
claude --version

Deactivate License

To deactivate (e.g., to switch methods):

Dashboard → Click "License Active" → "Deactivate License"

Or via terminal:

rm /home/claude/.claude/.credentials.json
rm /home/claude/.claude/.env

How It Works

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Create    │     │   Daemon    │     │  Claude AI  │     │    Code     │
│   Ticket    │ ──► │   Picks Up  │ ──► │   Works     │ ──► │  Delivered  │
│             │     │   Ticket    │     │   On Task   │     │             │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
       │                                       │
       │            ┌─────────────┐            │
       └───────────►│  You Watch  │◄───────────┘
                    │  Real-Time  │
                    └─────────────┘

Create a ticket - Describe what you need built
Daemon assigns it - Background service picks up open tickets
Claude works - AI writes code, creates files, runs commands
You review - Watch in real-time or review when complete
Iterate - Send messages to refine, or close when satisfied

Ticket Workflow

┌──────┐     ┌─────────────┐     ┌─────────────────┐     ┌──────┐
│ open │ ──► │ in_progress │ ──► │ awaiting_input  │ ──► │ done │
└──────┘     └─────────────┘     └────────┬────────┘     └──────┘
                                          │
                              Send Message │ (refine/continue)
                                          ▼
                                    ┌──────────┐
                                    │   open   │
                                    └──────────┘

Tickets auto-close after 7 days in awaiting_input if no action taken.

Architecture

                    ┌────────────────────────────────┐
                    │           INTERNET             │
                    └───────┬───────────┬────────────┘
                            │           │
                       Port 9453   Port 9867
                      Admin Panel  Web Projects
                            │           │
                    ┌───────┴───────────┴────────┐
                    │          Nginx             │
                    │    (SSL Termination)       │
                    └───────┬───────────┬────────┘
                            │           │
                    ┌───────┴───┐ ┌─────┴───────┐
                    │   Flask   │ │  PHP-FPM    │
                    │  Web App  │ │  Projects   │
                    └───────┬───┘ └─────────────┘
                            │
                    ┌───────┴───────┐
                    │    Daemon     │──── Claude Code CLI
                    │  (Background) │
                    └───────┬───────┘
                            │
                    ┌───────┴───────┐
                    │    MySQL      │
                    │   Database    │
                    └───────────────┘

CLI Commands

# Create a project
claude-cli project add --name "My E-Commerce" --code SHOP

# Create a ticket
claude-cli ticket add --project SHOP --title "Build user authentication" --priority high

# Check system status
claude-cli status

# Control daemon
claude-cli daemon start|stop|status

Configuration

Edit /etc/codehero/system.conf:

# Database connection
DB_HOST=localhost
DB_NAME=claude_knowledge
DB_USER=claude_user
DB_PASSWORD=your-secure-password

# Parallel processing (how many tickets at once)
MAX_PARALLEL_PROJECTS=3

# Auto-close tickets after N days
REVIEW_DEADLINE_DAYS=7

Tech Stack

Backend: Python 3, Flask, Flask-SocketIO
Database: MySQL 8.0
Web Server: Nginx with PHP-FPM
AI: Claude AI via Claude Code CLI
OS: Ubuntu 22.04 / 24.04 LTS

Documentation

Document	Description
One-Click Install	Easiest install for Windows, macOS, Linux
User Guide	How to use the admin panel (with screenshots)
Migration Guide	Move projects between servers
Domain & SSL Setup	Configure domains with Let's Encrypt SSL
2FA Setup	Enable Two-Factor Authentication with Google Authenticator
WAF Setup	ModSecurity Web Application Firewall with OWASP rules
LSP Setup	Install language servers for code editor features
Telegram Setup	Get instant alerts on your phone
VM Installation	Install on VMware, Hyper-V, VirtualBox, UTM, Parallels
Installed Packages	All tools & packages (ffmpeg, ImageMagick, OCR, etc.)
INSTALL.md	Detailed installation guide
CLAUDE_OPERATIONS.md	System management & troubleshooting
CHANGELOG.md	Version history
CLAUDE.md	Development workflow for contributors

Important Notice

Warning: This system runs Claude AI with unrestricted access to your server. Claude can execute commands, create/modify/delete files, access databases, and perform any operation the system user can do.

Use at your own risk. The authors and contributors are not responsible for any damage, data loss, security issues, or other consequences resulting from the use of this software. Always run on isolated/dedicated servers and maintain proper backups.

Security

Self-hosted: Your code stays on your server
SSL encryption: All web traffic encrypted
Isolated databases: Each project gets its own MySQL database
Configurable access: Restrict admin panel to trusted IPs

Two-Factor Authentication (2FA)

Optional TOTP-based 2FA for enhanced login security:

Google Authenticator Support - Works with any TOTP app (Authy, Microsoft Authenticator, etc.)
Account Lockout - Automatic 30-minute lockout after 5 failed login attempts
Remember Device - Skip 2FA on trusted devices until end of month
Terminal Management - Enable/disable 2FA from command line

# Manage 2FA settings
sudo /opt/codehero/scripts/manage-2fa.sh

# Direct commands
sudo /opt/codehero/scripts/manage-2fa.sh enable    # Enable 2FA
sudo /opt/codehero/scripts/manage-2fa.sh disable   # Disable 2FA
sudo /opt/codehero/scripts/manage-2fa.sh unlock    # Unlock after failed attempts
sudo /opt/codehero/scripts/manage-2fa.sh status    # Check current status

See 2FA Setup Guide for detailed instructions.

Change Passwords

After installation, change default passwords:

sudo /opt/codehero/scripts/change-passwords.sh

Contributing

Contributions are welcome!

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

See CLAUDE.md for development guidelines.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions

License

This project uses a Dual License - free for personal use and small businesses, commercial license required for larger organizations. See LICENSE for details.

Built with Claude AI
_{If you find this useful, please star the repository!}

Author

Fotios Tsakiridis (@fotsakir)

Smartnav Telematic Services Cyprus Ltd

Keywords

claude-ai anthropic ai-coding-assistant autonomous-agent code-generation ai-developer self-hosted ticket-system project-management flask mysql nginx ubuntu devops automation open-source php python human-ai-collaboration future-of-programming proof-of-concept ai-pair-programming agentic-ai

codehero

Links

README