OpenClaudia

Open-source universal agent harness — Claude Code-like coding workflows for many AI providers.

OpenClaudia is a Rust-based CLI that transforms any LLM into an agentic coding assistant with tools, memory, hooks, and multi-provider support.

Features

• Behavioral Modes — Three-axis model (agency, quality, scope) with 8 presets and 6 modifiers for fine-grained control over AI behavior
• Multi-Provider Support — Anthropic, OpenAI, Google Gemini, DeepSeek, Qwen, Z.AI/GLM, Kimi/Moonshot, MiniMax, Ollama, and any OpenAI-compatible server
• Local LLM Support — Run with Ollama, LM Studio, LocalAI, or any OpenAI-compatible endpoint
• Auto-Detect Provider — Pass -m gemini-3.5-flash and the provider is detected automatically
• 30+ Agentic Tools — Bash, file ops, LSP, web search, notebooks, task tracking, plan mode, worktrees, cron scheduling, MCP resources
• Tool Execution Loop — Multi-turn tool calling with automatic result feedback (works across all providers)
• Web Search — Free DuckDuckGo/Bing browser scraping in default builds; no search API key required
• Auto-Learning Memory — Automatically captures coding patterns, error resolutions, file relationships, and user preferences across sessions
• Background Shells — Run long-running processes, check output, and kill them on demand
• Thinking Mode — Extended reasoning for Anthropic, OpenAI GPT-5/o1/o3/o4, Gemini 3.x/2.5, DeepSeek V4, Qwen QwQ, Z.AI/GLM, and MiniMax-M3
• VDD Adversarial Review — Verification-Driven Development: a separate adversary model reviews code for bugs/vulnerabilities
• Hooks System — Run custom scripts at key moments (session start, tool use, prompt submit, etc.)
• Guardrails — Configurable code quality gates, blast radius limiting, and diff size monitoring
• Plan Mode — Toggle between Build and Plan modes; plan mode restricts destructive tools
• Permissions — Granular tool-level allow/deny rules with glob patterns
• Task Management — Built-in task tracking with dependencies and status workflow
• LSP Integration — Language Server Protocol support for go-to-definition, find-references, hover, and more
• Subagent System — Spawn autonomous agents from the agent loop; coordinator infrastructure is experimental and not wired into the default TUI yet
• ACP Server — Agent Control Protocol server for agent interoperability via stdin/stdout
• Git Worktrees — Create, list, and safely remove isolated git worktrees without mutating the process CWD
• Cron Scheduling — Create, list, and delete cron schedule metadata for external schedulers
• Skills System — Load and invoke reusable prompt skills from markdown files
• Cross-Platform — Windows, macOS, Linux with Git Bash for consistent shell behavior
• Interactive TUI — Rich terminal interface with keybindings, themes, and session management
• Context Compaction — Automatic summarization when conversations get long
• Notebook Support — Read and edit Jupyter notebooks
• MCP Integration — Browse and read resources from MCP servers
• Plugin System — Install, manage, and extend with plugins (commands, hooks, MCP servers)
• OAuth Support — Use your Claude Max subscription via built-in OAuth proxy

Prerequisites

Required

• Rust — Install via rustup
• Git Bash (Windows only) — Comes with Git for Windows
• OpenClaudia uses Git Bash on Windows for Unix command compatibility
• Ensure Git is in your PATH

Installation

# Clone the repository
git clone https://github.com/dollspace-gay/openclaudia.git
cd openclaudia

# Build release version (includes browser/web search support by default)
cargo build --release

# Build without browser feature (lighter binary, no headless Chrome)
cargo build --release --no-default-features

# The binary is at target/release/openclaudia

Quick Start

# Set your API key (choose your provider)
export ANTHROPIC_API_KEY="your-key-here"
# or: export OPENAI_API_KEY="your-key-here"
# or: export GOOGLE_API_KEY="your-key-here"
# or: export DEEPSEEK_API_KEY="your-key-here"

# Initialize configuration in your project
openclaudia init

# Start chatting (uses default provider from config)
openclaudia

# Use a specific model (provider auto-detected from model name)
openclaudia -m gemini-3.5-flash
openclaudia -m gpt-5.5
openclaudia -m claude-sonnet-4-6

# Start with a behavioral mode
openclaudia --mode create     # Autonomous architect — build from scratch
openclaudia --mode safe       # Collaborative minimal — surgical precision
openclaudia --mode debug      # Investigation-first debugging

Configuration

Environment Variables

Config File

Configuration is stored in .openclaudia/config.yaml:

proxy:
  port: 8080
  host: "127.0.0.1"
  # Provider: anthropic, openai, google/gemini, deepseek, qwen/alibaba,
  # zai/glm/zhipu, kimi/moonshot, minimax, ollama, local, lmstudio,
  # localai, text-generation-webui
  target: anthropic

providers:
  anthropic:
    base_url: https://api.anthropic.com
    thinking:
      enabled: false
      reasoning_effort: "high"    # Claude Opus 4.8/4.7/Fable/Mythos adaptive effort
      # budget_tokens: 10000      # Manual-thinking Claude models only
  openai:
    base_url: https://api.openai.com
    thinking:
      reasoning_effort: "medium"  # OpenAI GPT-5/o1/o3/o4: none, low, medium, high, xhigh
  google:
    base_url: https://generativelanguage.googleapis.com
    thinking:
      budget_tokens: 10000        # Google Gemini thinking budget
  zai:
    base_url: https://api.z.ai/api/coding/paas/v4
  deepseek:
    base_url: https://api.deepseek.com
  qwen:
    base_url: https://dashscope.aliyuncs.com/compatible-mode
  kimi:
    base_url: https://api.moonshot.ai/v1
  minimax:
    base_url: https://api.minimax.io/v1
  # Ollama for local LLM inference
  ollama:
    base_url: http://localhost:11434
  # Any OpenAI-compatible local server (LM Studio, LocalAI, text-generation-webui, etc.)
  local:
    base_url: http://localhost:1234/v1
  lmstudio:
    base_url: http://localhost:1234/v1
  localai:
    base_url: http://localhost:8080/v1
  text-generation-webui:
    base_url: http://localhost:5000/v1

session:
  timeout_minutes: 30
  persist_path: .openclaudia/session
  max_turns: 0  # 0 = unlimited agentic loop iterations; set nonzero to cap tool loops

# Verification-Driven Development (VDD) - Adversarial code review
# vdd:
#   enabled: true
#   mode: advisory           # advisory (single pass) or blocking (loop until clean)
#   adversary:
#     provider: google       # Must differ from proxy.target
#     model: gemini-3.5-flash

# Granular tool permissions
# permissions:
#   enabled: true
#   default_allow:
#     - "git status"
#     - "src/**"
#   mcp:
#     filesystem: ["read_file", "list_directory"]

# Legacy line REPL keybindings (`openclaudia --tui-mode`)
keybindings:
  ctrl-x n: new_session
  ctrl-x x: export
  tab: toggle_mode
  escape: cancel

CLI Commands

openclaudia                    # Start full-screen interactive TUI (default)
openclaudia -m <model>         # Use specific model (auto-detects provider)
openclaudia -v                 # Verbose logging
openclaudia --resume           # Resume last session
openclaudia --session-id <id>  # Resume specific session
openclaudia --coordinator --tui-mode  # Legacy REPL coordinator prompt mode
openclaudia --tui-mode         # Legacy line-oriented REPL
openclaudia --mode <preset>    # Start with a behavioral mode preset
openclaudia --print "prompt"   # Send one prompt, print the response, and exit

openclaudia init               # Initialize config in current directory
openclaudia init --force       # Overwrite existing config

openclaudia auth               # Authenticate with Claude Max (OAuth)
openclaudia auth --status      # Check auth status
openclaudia auth --logout      # Clear native OAuth session cache

openclaudia start              # Start as proxy server
openclaudia start -p 9090      # Custom port
openclaudia start -t openai    # Target specific provider

openclaudia acp                # Start ACP server on stdin/stdout
openclaudia acp -m <model>     # ACP with specific model

openclaudia loop               # Start iteration mode with Stop hooks
openclaudia loop -n 10         # Max 10 iterations

openclaudia config             # Show current configuration
openclaudia doctor             # Check connectivity and API keys

Slash Commands (Default TUI)

The default full-screen TUI intentionally exposes a focused slash-command set. The legacy line-oriented REPL (openclaudia --tui-mode) has additional commands; type /help there for that registry.

TUI Core

TUI Sessions

TUI Diagnostics

TUI Skills

TUI Shell & Files

Keyboard Shortcuts (Default TUI)

The keybindings: config map customizes the legacy line-oriented REPL (openclaudia --tui-mode). The default full-screen TUI currently uses the shortcuts above.

Available Tools

Core Tools

Code Intelligence

Planning and Task Tools