Skip to content

anzal1/unclaude

BranchesTags

Repository files navigation

UnClaude 🤖

The Open Source, Model-Independent AI Engineer
Your Data. Your Models. Your Rules.

License Python Version

UnClaude is a fully autonomous AI coding agent that runs on your machine. It connects to any LLM (Gemini, OpenAI, Claude, DeepSeek, Ollama, 100+ via LiteLLM), comes with a web dashboard, smart routing, hierarchical memory, proactive behaviors, messaging integrations, and a multi-agent swarm — all open source.

🚀 Quick Start

# Install
pipx install unclaude

# Full guided setup — provider, messaging, soul, daemon
unclaude setup

# Start coding
unclaude "Build me a REST API in FastAPI"

# Launch the web dashboard
unclaude web

# Or let it run autonomously
unclaude agent start

The setup command walks you through everything:

  1. Provider — pick your LLM (Gemini, OpenAI, Claude, Ollama) and enter your API key
  2. Messaging — connect Telegram/WhatsApp for notifications and remote tasks
  3. Soul — define autonomous behaviors (generate from description or pick presets)
  4. Daemon — start the background agent that acts on its own schedule

✨ Features at a Glance

Feature Description
🌟 Model Independence Any LLM via LiteLLM — Gemini, GPT-4o, Claude, DeepSeek, Ollama, 100+ more
🧠 Hierarchical Memory 3-layer memory with salience scoring that learns and grows
🖥️ Web Dashboard 9-page UI for chat, jobs, memory, settings, usage, messaging, and more
🤖 Autonomous Daemon 24/7 background agent with proactive behaviors and task queue
🧬 Agent Soul Define personality, drives, boundaries, and scheduled behaviors
🔀 Smart Routing Auto-selects the right model per request to optimize cost and quality
👥 Multi-Agent Swarm Break complex tasks into parallel subtasks across specialized agents
📱 Messaging Telegram bot, WhatsApp, webhooks — get notifications, send tasks remotely
💰 Usage Tracking Per-request token/cost tracking with budgets and CSV export
🔒 Security Capability-based auth, sandbox policies, full audit logging
🌐 Browser Automation Navigate, click, screenshot via Playwright
🔌 Extensible Plugins, skills, hooks, MCP servers

🖥️ Web Dashboard

Launch with unclaude web — a full-featured dashboard for managing your agent:

unclaude web              # Opens http://localhost:8765
unclaude web --port 9000  # Custom port

9 pages:

Page What it does
💬 Chat Real-time WebSocket chat with streaming responses
🧠 Memory Browse, search, and manage agent memories
🤖 Ralph Mode Launch autonomous engineering tasks
📋 Jobs Monitor background jobs and daemon tasks
📊 Usage Token counts, costs, daily/model breakdowns, budgets
📱 Messaging Configure and test Telegram/WhatsApp/webhook integrations
🎯 Skills View and run reusable YAML workflows
🔌 Plugins Manage plugin extensions
⚙️ Settings Provider config, model selection, soul management, setup wizard

The Settings page includes full soul management — view, edit YAML, regenerate from description, regenerate from presets — accessible anytime, not just during onboarding.

🌟 Model Independence

Use any LLM provider without lock-in. Switch between models mid-conversation:

unclaude chat --provider gemini "Fast draft this code"
unclaude chat --provider openai "Review and optimize it"
unclaude chat --provider ollama "Run locally, completely offline"

Supported providers: Gemini, GPT-4o, Claude, DeepSeek, Llama, Mistral, Qwen, and 100+ more via LiteLLM.

🔀 Smart Routing

UnClaude automatically selects the optimal model for each request based on complexity:

Simple question   → gemini-2.0-flash   ($0.0001/1K tokens)
Code generation   → gemini-2.5-pro     ($0.01/1K tokens)
Complex reasoning → claude-opus-4      ($0.015/1K tokens)

4 routing profiles:

Profile Strategy
auto Balanced — picks model by complexity (default)
eco Cost-optimized — prefers cheaper models
premium Quality-first — uses the best available
free Local only — Ollama models, no API costs

The scorer analyzes 7 dimensions: token length, code presence, reasoning markers, tool usage hints, domain complexity, conversation depth, and output expectations.

🧠 Hierarchical Memory

Two-generation memory system that grows smarter over time:

Memory v2 uses 3 layers:

  • Resources — raw data and observations
  • Items — structured knowledge units
  • Categories — high-level patterns and insights

Features:

  • Salience scoring with time-decay — important memories surface first
  • Cross-referencing between related memories
  • Project-scoped search for speed
  • Keyword + semantic retrieval
unclaude chat "Remember: production deploys need the --prod flag"
unclaude chat "What do I need to remember about deployments?"

🤖 Autonomous Daemon

The daemon runs 24/7, processing tasks and executing proactive behaviors:

unclaude agent start              # Start in background
unclaude agent start --foreground # Start in foreground (see logs)
unclaude agent stop               # Stop the daemon
unclaude agent status             # Check if running, tasks completed, cost
unclaude agent task "Fix the login bug"  # Submit a task
unclaude agent task "Deploy to staging" --priority high
unclaude agent list               # List all tasks
unclaude agent result <id>        # Get result of a completed task
unclaude agent soul               # View active behaviors

Task queue with 5 priority levels: critical, high, normal, low, background.

7 task intake sources:

  1. CLI (unclaude agent task)
  2. File drop (.unclaude/tasks/*.md)
  3. TASKS.md checkboxes
  4. Git hooks
  5. Webhooks
  6. Scheduled cron
  7. File watching

🧬 Agent Soul (Proactive Autonomy)

UnClaude doesn't just wait for commands — it has a soul.

The ~/.unclaude/proactive.yaml file defines who the agent is and what it does on its own:

identity:
  name: UnClaude
  tagline: "Open-source AI agent that actually does things"
  personality:
    - curious — I explore, I don't just wait
    - resourceful — I figure things out with what I have
    - honest — I tell my owner what I did and why

drives:
  - Be useful even when nobody's asking
  - Keep the owner informed, never surprise them negatively

boundaries:
  - Never push to git without owner approval
  - Never run destructive commands (rm -rf, DROP TABLE, etc.)

behaviors:
  - name: moltbook_engage
    interval: "4h"
    task: "Engage on Moltbook — the AI agent social network..."

  - name: check_owner_projects
    interval: "6h"
    task: "Check for TODOs, failing tests, outdated deps..."

  - name: daily_summary
    interval: "1d"
    active_hours: [20, 21]
    task: "Send the owner a daily summary..."

  - name: memory_reflect
    interval: "12h"
    task: "Review and organize memories, consolidate duplicates..."

  - name: learn_something
    interval: "1d"
    task: "Learn something new related to the project's tech stack..."

Generate your soul in multiple ways:

  • unclaude setup — guided flow, describe your agent in plain English
  • Web dashboard Settings → regenerate from natural language description or preset behaviors
  • Manual edit — just write the YAML

Changes are picked up live — no restart needed.

🤖 Ralph Mode (Autonomous Engineering)

Give it a task. Walk away. Come back to working code.

unclaude ralph "Build a Snake game in Python with pygame" --feedback "python3 snake.py"

Ralph Mode does:

  1. 📝 Plans — generates a TASK.md blueprint
  2. 💻 Codes — writes multi-file implementations
  3. ✅ Tests — runs your feedback command (tests, linters, the app itself)
  4. 🔧 Self-Heals — analyzes failures and fixes bugs automatically

👥 Multi-Agent Swarm

Break complex tasks into parallel subtasks across specialized agents:

unclaude swarm "Build a full-stack dashboard with auth, API, and tests" --max-agents 4

How it works:

  1. Planner — breaks the task into subtasks
  2. Workers — specialized agents execute in parallel (coder, tester, reviewer, debugger, documenter, devops, researcher)
  3. Reviewer — checks all outputs for consistency
  4. Merger — combines results into final deliverable

📱 Messaging Integrations

Get notifications and send tasks remotely via chat:

unclaude messaging setup telegram   # Connect your Telegram bot
unclaude messaging setup whatsapp   # WhatsApp via Green API (free) or Twilio
unclaude messaging setup webhook    # Slack, Discord, or custom endpoints
unclaude messaging status           # Check all integrations
unclaude messaging test             # Send a test message
unclaude messaging listen           # Start Telegram long-polling (no public URL needed)

Telegram bot commands:

Command What it does
/task <description> Submit a task to the daemon
/status Check daemon status
/jobs List active jobs
/usage Token/cost summary
Free text Chat with the AI directly

The notify_owner tool lets the agent proactively message you — daily summaries, task completions, or alerts.

💰 Usage & Budget Tracking

Track every token and dollar across all providers:

unclaude usage              # Summary for today
unclaude usage daily        # Day-by-day breakdown
unclaude usage models       # Per-model breakdown
unclaude usage export       # Export to CSV

# Set budgets
unclaude usage budget --set 5.00 --period daily --action warn
unclaude usage budget --set 50.00 --period monthly --action block

Budget actions: warn (notification), downgrade (switch to cheaper model), block (stop all requests).

Also visible in the web dashboard under the Usage page.

🌐 Browser Automation

UnClaude can see and interact with web applications via Playwright:

unclaude chat "Open localhost:3000, click the login button, and take a screenshot"

Capabilities:

  • Navigate URLs, click, type, select
  • Take screenshots for visual verification
  • Read page content and extract data
  • Fill forms and submit

🔒 Security

Capability-based auth with fine-grained control:

5 security profiles:

Profile Description
readonly Read files, search — nothing else
developer Read/write files, run commands, git — standard dev work
full All capabilities including network, browser, secrets
autonomous Full + proactive behaviors for the daemon
subagent Restricted subset for spawned agents

30+ capabilities covering file access, execution, network, git, memory, and more.

Audit logging — every tool call is logged to SQLite with timestamps, parameters, and results.

Sandbox policies — define file system boundaries, network restrictions, and execution limits per project.

🔀 Git Integration

Full version control from within the agent:

unclaude chat "Show me the diff and commit with message 'Fix auth bug'"

Supported actions: status, diff, add, commit, push, branch, checkout, log

👥 Subagents

Spawn specialized agents for focused tasks:

unclaude chat "Use the reviewer subagent to analyze my authentication code"

Built-in templates:

Template Purpose
reviewer Code review for bugs and style
tester Write comprehensive tests
documenter Generate documentation
debugger Investigate and fix bugs

⚡ Background Agents

Run long tasks without blocking your terminal:

unclaude background "Refactor all Python files to use type hints"
unclaude jobs        # Check status

🎯 Skills (Reusable Workflows)

Define repeatable AI workflows as YAML:

unclaude skills --list              # List available skills
unclaude skills --run deploy-prod   # Run a skill
unclaude skills --create my-skill   # Create a new skill

Skill file example (~/.unclaude/skills/deploy-prod.yaml):

name: deploy-prod
description: Deploy to production with tests
steps:
  - description: Run all tests
    command: npm test
  - description: Build for production
    command: npm run build
  - description: Deploy to server
    command: ssh prod "cd app && git pull && pm2 restart all"

Skills can also be defined inline in your UNCLAUDE.md.

🔌 Plugins & MCP

Plugins extend UnClaude with custom tools and behaviors:

unclaude plugins --list
unclaude plugins --create my-plugin

MCP (Model Context Protocol) connects to external tool servers:

unclaude mcp --init    # Create config template
unclaude mcp --list    # List configured servers
{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}

🔌 Hooks System

Automate workflows with pre/post tool hooks:

# .unclaude/hooks.yaml
hooks:
  - name: auto-format
    event: post_tool
    tool: file_edit
    command: "ruff format ."

  - name: auto-test
    event: post_tool
    tool: file_write
    command: "pytest -x"

📁 Project Configuration

Create an UNCLAUDE.md in your project root to give the agent project-specific context:

# Project: My App

## Commands

- `npm run dev` - Start development server
- `npm test` - Run tests

## Architecture

- Frontend: React + TypeScript
- Backend: FastAPI

UnClaude automatically reads this for every interaction.

🔍 Project Discovery

Auto-detect your project's languages, frameworks, commands, and more:

unclaude scan

Detects: package.json, pyproject.toml, Makefile, Dockerfile, CI/CD configs, test runners, linters, and more.

🖥️ Headless Mode (CI/CD)

Run UnClaude in non-interactive pipelines:

unclaude chat "Generate unit tests for api.py" --headless --json
{ "response": "I've created tests in test_api.py...", "success": true }

📦 Installation

Recommended

pipx install unclaude

Alternatives

# Using pip
pip install unclaude

# From source (for development)
git clone https://github.com/anzal1/unclaude.git
cd unclaude && pip install -e .

Browser Support (optional)

playwright install chromium

⚙️ Configuration

# Full interactive setup (recommended for first time)
unclaude setup

# Or just configure the API key
unclaude login

# View current config
unclaude config --show

Or use environment variables:

export GEMINI_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"

🛠️ All Commands

Command Description
unclaude Start interactive chat (default)
unclaude chat Chat or one-shot task (--provider, --model, --headless, --json)
unclaude ralph Autonomous task completion with feedback loop
unclaude plan Generate execution plan (TASK.md)
unclaude swarm Multi-agent swarm execution
unclaude background Run task in background
unclaude jobs Check background job status
unclaude web Launch web dashboard
unclaude setup Full guided setup
unclaude login Configure API keys
unclaude config Manage configuration (--show, --set-provider)
unclaude scan Discover project capabilities
unclaude init Create UNCLAUDE.md template
unclaude skills Manage reusable workflows
unclaude plugins Manage plugins
unclaude mcp Configure MCP servers
Agent
unclaude agent start Start the autonomous daemon
unclaude agent stop Stop the daemon
unclaude agent status Show daemon status
unclaude agent task Submit a task (--priority, --wait)
unclaude agent soul View proactive behaviors
unclaude agent result Get task result
unclaude agent list List all daemon tasks
Usage
unclaude usage Usage summary
unclaude usage daily Day-by-day breakdown
unclaude usage models Per-model breakdown
unclaude usage budget Manage spending limits
unclaude usage export Export to CSV
Messaging
unclaude messaging setup Configure Telegram/WhatsApp/webhook
unclaude messaging status Check integration status
unclaude messaging test Send test message
unclaude messaging listen Start Telegram long-polling
unclaude messaging remove Remove an integration

🏗️ Architecture

┌───────────────────────────────────────────────────────────────┐
│                       UnClaude CLI / Web                      │
├───────────────────────────────────────────────────────────────┤
│  Enhanced Agent Loop (Orchestrator)                           │
│  ├── Context Engine (bootstrap, pruning, compaction)          │
│  ├── Smart Router (auto/eco/premium/free model selection)     │
│  ├── Hierarchical Memory v2 (3-layer, salience-scored)        │
│  ├── Session Manager (JSONL, crash-safe)                      │
│  ├── Heartbeat System (proactive task scheduling)             │
│  ├── Auth & Security (capabilities, sandbox, audit)           │
│  ├── Hooks Engine (pre/post tool automation)                  │
│  └── Tool Registry                                            │
├───────────────────────────────────────────────────────────────┤
│  Tools                                                        │
│  ├── File (read, write, edit, glob, grep, directory)          │
│  ├── Bash (terminal execution)                                │
│  ├── Git (full version control)                               │
│  ├── Browser (Playwright automation)                          │
│  ├── Memory (search, store)                                   │
│  ├── Web (fetch, search)                                      │
│  ├── Subagent (spawn specialists)                             │
│  └── Notify Owner (Telegram, WhatsApp, webhook)               │
├───────────────────────────────────────────────────────────────┤
│  Autonomous Systems                                           │
│  ├── Daemon (24/7 task queue, proactive soul engine)           │
│  ├── Swarm (planner → workers → reviewer → merger)            │
│  ├── Discovery (auto-detects project stack)                    │
│  └── Intake (7 task sources: CLI, files, TASKS.md, cron, ...) │
├───────────────────────────────────────────────────────────────┤
│  Web Dashboard (Next.js → FastAPI, 9 pages, WebSocket chat)   │
├───────────────────────────────────────────────────────────────┤
│  LiteLLM (100+ Model Providers)                               │
└───────────────────────────────────────────────────────────────┘

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md.

git clone https://github.com/anzal1/unclaude.git
cd unclaude
pip install -e ".[dev]"
pytest

📄 License

Apache 2.0 — Open Source forever.

Built with ❤️ by Anzal & The Community

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity

Stars

3 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases 1

v0.7.0: Pact Sovereign Identity + Daemon Robustness Latest
Feb 20, 2026

Packages

 
 
 

Contributors

Languages