codehero

<p align="center"> <img src="assets/hero-icon.svg" width="80" height="96" alt="CodeHero"> </p> <h1 align="center">CodeHero</h1> <p align="center"> <strong>The Developer That Never Rests</strong><br> <em>Powered by Claude AI</em> </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Dual-blue.svg" alt="License"></a> <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-2.83.5-green.svg" alt="Version"></a> <img src="https://img.shields.io/badge/Ubuntu-22.04%20|%2024.04-orange.svg" alt="Ubuntu"> <a href="https://anthropic.com"><img src="https://img.shields.io/badge/Powered%20by-Claude%20AI-blueviolet.svg" alt="Claude AI"></a> <a href="https://github.com/fotsakir/codehero/stargazers"><img src="https://img.shields.io/github/stars/fotsakir/codehero?style=social" alt="Stars"></a> </p>

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 - Track all development tasks across projects

Projects - Manage multiple projects with isolated environments

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

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:

1. Describe what you want to build
2. CodeHero Manager creates the plan (tech stack, features, database)
3. Creates the project and tickets automatically
4. 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 encry