<p align="center">
  <img src="docs/assets/logo.png" alt="OpenAkita Logo" width="200" />
</p>

<h1 align="center">OpenAkita</h1>

<p align="center">
  <strong>Your Loyal and Reliable AI Companion</strong>
</p>

<p align="center">
  <a href="https://github.com/openakita/openakita/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" />
  </a>
  <a href="https://www.python.org/downloads/">
    <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python Version" />
  </a>
  <a href="https://github.com/openakita/openakita/releases">
    <img src="https://img.shields.io/github/v/release/openakita/openakita?color=green" alt="Version" />
  </a>
</p>

<p align="center">
  <a href="#philosophy">Philosophy</a> •
  <a href="#features">Features</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#architecture">Architecture</a> •
  <a href="#multi-agent">Multi-Agent</a>
</p>

<p align="center">
  <a href="README_CN.md">中文文档</a>
</p>

---

## What is OpenAkita?

OpenAkita is a **self-evolving AI assistant** — your loyal and reliable companion in the digital world.

Like the Akita dog it's named after, OpenAkita embodies:
- 🤝 **Loyal Companion** — Always by your side, ready to help whenever you need
- 🧠 **Grows With You** — Remembers your preferences and becomes more helpful over time
- 💪 **Reliable Partner** — Commits to completing tasks, never gives up easily
- 🛡️ **Trustworthy** — Keeps your data safe and respects your privacy

OpenAkita is more than a tool — it's a partner that remembers you, understands you, and stands by you through every challenge.

## Philosophy

### 1. Human-Centered

OpenAkita's core is **serving people**, not showcasing technology. We focus on:

- **Understanding Intent**: Not just executing commands, but understanding what you really want
- **Proactive Communication**: Asks when encountering problems, rather than guessing or failing
- **Privacy Respect**: Your data belongs to you, never misused

### 2. Continuous Evolution

OpenAkita can **learn and evolve**:

- **Memory System**: Remembers your preferences, habits, common operations
- **Skill Extension**: Automatically searches or generates new capabilities for new needs
- **Experience Accumulation**: Learns from each task, becomes more efficient

### 3. Reliable Execution

Once a task is assigned to OpenAkita:

- **Persistent Completion**: Won't give up due to minor errors
- **Smart Retry**: Analyzes failure reasons, tries different approaches
- **Progress Saving**: Long tasks support checkpoint recovery

### 4. Multi-Platform Collaboration

Through **Multi-Agent architecture** for efficient parallelism:

- **Master-Worker Architecture**: Master coordinates, Workers execute
- **Smart Scheduling**: Allocates resources based on task complexity
- **Fault Recovery**: Automatic detection and restart of failed nodes

## Features

### Basic Capabilities

| Feature | Description |
|---------|-------------|
| **Smart Dialogue** | Multi-turn contextual conversation |
| **Task Execution** | Shell commands, file operations, network requests |
| **Code Abilities** | Write, debug, explain code |
| **Knowledge Retrieval** | Search web, GitHub, local documents |

### Advanced Capabilities

| Feature | Description |
|---------|-------------|
| **Plan Mode** | Intelligent multi-step task planning and execution |
| **Skill System** | Extensible skill library, supports customization |
| **MCP Integration** | Connect browsers, databases, external services |
| **Scheduled Tasks** | Set reminders, periodic tasks |
| **User Profile** | Learn your preferences, personalized service |

### Plan Mode (Multi-Step Task Management)

For complex tasks requiring multiple steps, OpenAkita automatically activates **Plan Mode** to ensure reliable execution:

#### How It Works

```
┌─────────────────────────────────────────────────────────────┐
│                       Plan Mode                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   User Request                                               │
│        ↓                                                     │
│   ┌─────────────────────────────────────────────────────┐   │
│   │  Multi-Step Detection                                │   │
│   │  • 5+ action words (complex task)                    │   │
│   │  • 3+ actions + connectors ("then", "after")         │   │
│   │  • Compound task type                                │   │
│   └─────────────────────────────────────────────────────┘   │
│        ↓                                                     │
│   ┌─────────────────────────────────────────────────────┐   │
│   │  create_plan → Execute Steps → update_plan_step     │   │
│   │       ↓              ↓                ↓             │   │
│   │  Plan Created   Tool Calls    Progress Tracked      │   │
│   │       ↓              ↓                ↓             │   │
│   │  User Notified  Real-time     Status Updates        │   │
│   └─────────────────────────────────────────────────────┘   │
│        ↓                                                     │
│   complete_plan → Summary Report                             │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

#### Features

| Feature | Description |
|---------|-------------|
| **Auto Detection** | Automatically identifies multi-step tasks |
| **Plan First** | Forces plan creation before execution |
| **Progress Tracking** | Real-time status updates for each step |
| **User Notification** | Sends progress to IM channels |
| **Persistent Plans** | Saves plans as Markdown files |
| **Step Dependencies** | Supports step dependency chains |

#### Example

```
User: "Open Baidu, search for weather, and take a screenshot"

📋 Task Plan: Search weather on Baidu and screenshot
├─ 1. Launch browser and navigate to Baidu
├─ 2. Enter search keyword
├─ 3. Click search button
└─ 4. Take screenshot and send

Execution:
✅ [1/4] Launch browser - Done
✅ [2/4] Enter keyword - Done  
✅ [3/4] Click search - Done
✅ [4/4] Screenshot - Done

🎉 Task completed! 4/4 steps successful.
```

#### Plan Tools

| Tool | Description |
|------|-------------|
| `create_plan` | Create execution plan with steps |
| `update_plan_step` | Update step status (pending/in_progress/completed/failed) |
| `get_plan_status` | Get current plan progress |
| `complete_plan` | Mark plan as completed, generate summary |

### Self-Maintenance System

OpenAkita's "sleep cycle" — automatic maintenance during quiet hours:

| Feature | Schedule | Description |
|---------|----------|-------------|
| **Memory Consolidation** | 03:00 AM | Consolidate daily conversations into long-term memory |
| **Self-Check & Repair** | 04:00 AM | Analyze errors, auto-fix tool issues, generate reports |
| **Task Retrospection** | After long tasks | Review execution, extract lessons learned |
| **Loop Detection** | Real-time | Prevent infinite loops |

#### How It Works

```
┌─────────────────────────────────────────────────────────────┐
│                   Self-Maintenance System                    │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────┐    ┌─────────────────┐                 │
│  │  Log System     │    │  Memory System  │                 │
│  │  • File rotation│    │  • Consolidation│                 │
│  │  • Auto cleanup │    │  • Deduplication│                 │
│  │  • Error filter │    │  • Vector search│                 │
│  └────────┬────────┘    └────────┬────────┘                 │
│           │                      │                           │
│           └──────────┬───────────┘                           │
│                      ▼                                       │
│           ┌─────────────────────┐                            │
│           │   Daily Self-Check  │                            │
│           │   • Analyze errors  │                            │
│           │   • LLM diagnosis   │                            │
│           │   • Auto-fix tools  │                            │
│           │   • Generate report │                            │
│           └─────────────────────┘                            │
│                                                              │
│  Error Types:                                                │
│  • Core (Brain/Memory/Scheduler) → Report only, no auto-fix │
│  • Tool (Shell/File/Web/MCP)     → Auto-fix, self-test      │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

#### Configuration

```bash
# Log settings
LOG_LEVEL=INFO
LOG_DIR=logs
LOG_RETENTION_DAYS=30

# Self-check (system tasks, cannot be deleted, can be disabled)
# Runs at 03:00 (memory) and 04:00 (self-check) daily
```

### Multi-Platform Support

| Platform | Status | Supported Message Types |
|----------|--------|------------------------|
| **CLI** | ✅ Full Support | Text |
| **Telegram** | ✅ Full Support | Text, Voice, Image, File |
| **Feishu** | ✅ Full Support | Text, Voice, Image, File |
| **WeCom** | ⚠️ Implemented, Not Tested | - |
| **DingTalk** | ⚠️ Implemented, Not Tested | - |
| **QQ** | ⚠️ Implemented, Not Tested | - |

## Quick Start

> ⚠️ **Early Stage Project**: This project is in early development. For faster deployment, we recommend using AI coding assistants like [Cursor](https://cursor.sh/), [Claude](https://claude.ai/), or [GitHub Copilot](https://github.com/features/copilot) to help with setup and troubleshooting.

### Requirements

- Python 3.11+
- LLM API Key (Anthropic, OpenAI-compatible, or other providers)

### Recommended Models

| Model | Provider | Notes |
|-------|----------|-------|
| `claude-sonnet-4-5-*` | Anthropic | Default, balanced |
| `claude-opus-4-5-*` | Anthropic | Most capable |
| `qwen3-max` | Alibaba | Strong Chinese support |
| `minimax-2.1` | MiniMax | Good for dialogue |
| `kimi-2.5` | Moonshot | Long-context capability |

> 💡 **Tip**: Enable "extended thinking" mode for complex tasks. Set model to `*-thinking` variant (e.g., `claude-opus-4-5-20251101-thinking`) for better reasoning.

### Quick Install (Recommended)

**One-line install with interactive setup wizard:**

```bash
# Install from PyPI
pip install openakita

# Run setup wizard (interactive configuration)
openakita init
```

The setup wizard will guide you through:
- LLM API configuration (API key, model selection)
- IM channel setup (optional: Telegram, Feishu, etc.)
- Memory system configuration
- Directory structure creation

**Or use the quick start script:**

```bash
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/openakita/openakita/main/scripts/quickstart.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/openakita/openakita/main/scripts/quickstart.ps1 | iex
```

### Manual Installation

```bash
# Clone repository
git clone https://github.com/openakita/openakita.git
cd openakita

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install
pip install -e .

# Run setup wizard
openakita init

# Or configure manually
cp examples/.env.example .env
# Edit .env, fill in your API keys
```

### Run

```bash
# Interactive CLI
openakita

# Execute single task
openakita run "Write a Python calculator"

# Service mode (IM channels only)
openakita serve

# Check status
openakita status
```

### Basic Configuration

```bash
# .env file

# Required
ANTHROPIC_API_KEY=your-api-key

# Optional: Custom API endpoint
ANTHROPIC_BASE_URL=https://api.anthropic.com

# Optional: Enable Telegram
TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=your-bot-token

# Optional: Enable Multi-Agent
ORCHESTRATION_ENABLED=true
```

## Architecture

### Overall Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                              OpenAkita                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│    ┌──────────────────────── Identity Layer ──────────────────────┐     │
│    │                                                               │     │
│    │   SOUL.md      AGENT.md      USER.md      MEMORY.md          │     │
│    │   (Values)     (Behavior)    (Profile)    (Memory)           │     │
│    │                                                               │     │
│    └───────────────────────────────────────────────────────────────┘     │
│                               │                                          │
│                               ▼                                          │
│    ┌──────────────────────── Core Layer ──────────────────────────┐     │
│    │                                                               │     │
│    │   ┌─────────┐    ┌──────────┐    ┌───────────────┐           │     │
│    │   │  Brain  │    │ Identity │    │    Memory     │           │     │
│    │   │  (LLM)  │    │  (Self)  │    │   (System)    │           │     │
│    │   └─────────┘    └──────────┘    └───────────────┘           │     │
│    │                                                               │     │
│    └───────────────────────────────────────────────────────────────┘     │
│                               │                                          │
│                               ▼                                          │
│    ┌──────────────────────── Tool Layer ──────────────────────────┐     │
│    │                                                               │     │
│    │   ┌───────┐  ┌───────┐  ┌───────┐  ┌───────┐                │     │
│    │   │ Shell │  │ File  │  │  Web  │  │  MCP  │                │     │
│    │   └───────┘  └───────┘  └───────┘  └───────┘                │     │
│    │                                                               │     │
│    │   ┌───────────┐  ┌────────────┐  ┌─────────────┐             │     │
│    │   │  Skills   │  │  Scheduler │  │  Evolution  │             │     │
│    │   └───────────┘  └────────────┘  └─────────────┘             │     │
│    │                                                               │     │
│    └───────────────────────────────────────────────────────────────┘     │
│                               │                                          │
│                               ▼                                          │
│    ┌──────────────────────── Channel Layer ───────────────────────┐     │
│    │                                                               │     │
│    │   ┌─────┐  ┌──────────┐  ┌────────┐  ┌──────────┐  ┌────┐   │     │
│    │   │ CLI │  │ Telegram │  │ Feishu │  │ DingTalk │  │ QQ │   │     │
│    │   └─────┘  └──────────┘  └────────┘  └──────────┘  └────┘   │     │
│    │                                                               │     │
│    └───────────────────────────────────────────────────────────────┘     │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

### Core Components

| Component | Description |
|-----------|-------------|
| **Brain** | LLM interaction layer, supports multi-endpoint failover |
| **Identity** | Identity system, loads SOUL/AGENT/USER/MEMORY |
| **Memory** | Vector memory system, supports semantic retrieval |
| **Skills** | Skill system, supports dynamic loading and extension |
| **Scheduler** | Scheduled task scheduler |
| **Channels** | Multi-platform message channels |

## Multi-Agent

When `ORCHESTRATION_ENABLED=true` is set, OpenAkita enters Multi-Agent collaboration mode:

### Architecture

```
┌────────────────────────────────────────────────────────────────┐
│                       Main Process                              │
│                                                                 │
│   ┌─────────┐    ┌──────────┐    ┌───────────┐                 │
│   │   CLI   │    │ Gateway  │    │ Scheduler │                 │
│   │(Command)│    │(IM Chan.)│    │  (Tasks)  │                 │
│   └────┬────┘    └────┬─────┘    └─────┬─────┘                 │
│        │              │                │                        │
│        └──────────────┼────────────────┘                        │
│                       ▼                                         │
│              ┌────────────────┐                                 │
│              │  MasterAgent   │                                 │
│              │ (Coordinator)  │                                 │
│              │                │                                 │
│              │ • Task Routing │                                 │
│              │ • Worker Mgmt  │                                 │
│              │ • Health Check │                                 │
│              │ • Fault Recov. │                                 │
│              └───────┬────────┘                                 │
│                      │                                          │
│              ┌───────┴────────┐                                 │
│              │   AgentBus     │                                 │
│              │  (ZMQ Comm.)   │                                 │
│              └───────┬────────┘                                 │
│                      │                                          │
│              ┌───────┴────────┐                                 │
│              │ AgentRegistry  │                                 │
│              │  (Registry)    │                                 │
│              └────────────────┘                                 │
│                                                                 │
└────────────────────────────────────────────────────────────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
   ┌────────────┐ ┌────────────┐ ┌────────────┐
   │  Worker 1  │ │  Worker 2  │ │  Worker N  │
   │  (Process) │ │  (Process) │ │  (Process) │
   │            │ │            │ │            │
   │ • Execute  │ │ • Execute  │ │ • Execute  │
   │ • Heartbeat│ │ • Heartbeat│ │ • Heartbeat│
   │ • Return   │ │ • Return   │ │ • Return   │
   └────────────┘ └────────────┘ └────────────┘
```

### Features

| Feature | Description |
|---------|-------------|
| **Smart Routing** | Simple tasks local, complex tasks to Workers |
| **Stateless Workers** | Session history via messages, flexible scheduling |
| **Shared Memory** | All Workers use same memory storage |
| **Fault Recovery** | Heartbeat + automatic Worker restart |
| **Dynamic Scaling** | Auto-adjust Worker count based on load |

### Configuration

```bash
# Enable Multi-Agent
ORCHESTRATION_ENABLED=true

# Worker count
ORCHESTRATION_MIN_WORKERS=1
ORCHESTRATION_MAX_WORKERS=5

# Heartbeat interval (seconds)
ORCHESTRATION_HEARTBEAT_INTERVAL=5

# ZMQ addresses
ORCHESTRATION_BUS_ADDRESS=tcp://127.0.0.1:5555
ORCHESTRATION_PUB_ADDRESS=tcp://127.0.0.1:5556
```

### CLI Commands

```bash
# View Agent status
/agents

# View collaboration stats
/status
```

## Project Structure

```
openakita/
├── identity/                 # Identity configs
│   ├── SOUL.md               # Values
│   ├── AGENT.md              # Behavior rules
│   ├── USER.md               # User profile
│   └── MEMORY.md             # Working memory
├── src/openakita/
│   ├── core/                 # Core modules
│   │   ├── agent.py          # Agent main class
│   │   ├── brain.py          # LLM interaction
│   │   ├── identity.py       # Identity system
│   │   └── ralph.py          # Task loop
│   ├── orchestration/        # Multi-Agent
│   │   ├── master.py         # MasterAgent
│   │   ├── worker.py         # WorkerAgent
│   │   ├── registry.py       # Registry
│   │   ├── bus.py            # ZMQ communication
│   │   └── monitor.py        # Monitoring
│   ├── tools/                # Tool layer
│   ├── skills/               # Skill system
│   ├── channels/             # Message channels
│   ├── memory/               # Memory system
│   └── scheduler/            # Scheduled tasks
├── skills/                   # Skills directory
├── data/                     # Data storage
└── docs/                     # Documentation
```

## Documentation

| Document | Description |
|----------|-------------|
| [Quick Start](docs/getting-started.md) | Installation and basic usage |
| [Configuration](docs/configuration.md) | All configuration options |
| [Skill System](docs/skills.md) | Creating and using skills |
| [MCP Integration](docs/mcp-integration.md) | Connecting external services |
| [IM Channels](docs/im-channels.md) | Telegram/Feishu/DingTalk setup |
| [Deployment](docs/deploy_en.md) | Production deployment |

## Contributing

Contributions welcome! See [Contributing Guide](CONTRIBUTING.md).

```bash
# Development environment
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Code check
ruff check src/
mypy src/
```

## Community

Join our community for help, discussions, and updates!

### Instant Communication

<table>
  <tr>
    <td align="center">
      <img src="docs/assets/wechat_group.jpg" width="200" alt="WeChat Group QR Code" /><br/>
      <b>WeChat Group</b><br/>
      <sub>Scan to join (Chinese)</sub>
    </td>
    <td>
      <b>💬 WeChat</b> - Chinese community chat<br/><br/>
      <b>🎮 Discord</b> - <a href="https://discord.gg/Mkpd3rsm">Join Discord</a><br/><br/>
      <b>🐦 X (Twitter)</b> - <a href="https://x.com/openakita">@openakita</a><br/><br/>
      <b>📧 Email</b> - <a href="mailto:zacon365@gmail.com">zacon365@gmail.com</a>
    </td>
  </tr>
</table>

### Project Resources

- 📖 [Documentation](docs/) - Complete guides
- 🐛 [Issues](https://github.com/openakita/openakita/issues) - Bug reports & feature requests
- 💬 [Discussions](https://github.com/openakita/openakita/discussions) - Q&A and ideas
- ⭐ [Star us](https://github.com/openakita/openakita) - Show your support

## Acknowledgments

- [Anthropic Claude](https://www.anthropic.com/claude) — LLM Engine
- [browser-use](https://github.com/browser-use/browser-use) — AI browser automation
- [AGENTS.md Standard](https://agentsmd.io/) — Agent behavior specification
- [ZeroMQ](https://zeromq.org/) — Inter-process communication

## License

MIT License - See [LICENSE](LICENSE)

---

<p align="center">
  <strong>OpenAkita — Your Loyal and Reliable AI Companion</strong>
</p>
