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](screenshots/dashboard.png)
*Dashboard - Real-time overview of projects, tickets, and usage statistics*

![Tickets](screenshots/tickets.png)
*Tickets - Track all development tasks across projects*

![Projects](screenshots/projects.png)
*Projects - Manage multiple projects with isolated environments*

![Ticket Detail](screenshots/ticket-detail.png)
*Ticket Detail - Claude's response with code and conversation history*

![Console](screenshots/console.png)
*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 wit

[truncated…]