Coqui is your personal operating system for AI work: a lightweight, hackable agent runtime for coding, research, automation, and long-running projects.

Built on php-agents, it gives you a REPL, persistent memory, background tasks, schedules, artifacts, and runtime-extensible toolkits in one PHP 8.4 runtime you can inspect, modify, and self-host.

Start with Installation, Getting Started, Features, or browse coqui.space.

Coqui is a WIP and under rapid development. Be careful when running this tool. Always test in a safe environment.

Join the Discord community to follow along, ask questions, and share your creations!

Why Coqui?

• No build or compile steps — clone, composer install, run. That’s it.
• Hackable and readable — plain PHP 8.4, strict types, one class per file. Read it, change it, own it.
• Fast load times — cold boot in ~78 ms with OPcache and JIT.
• Low memory footprint — 10–30 MB per process, even with dozens of tools loaded.
• Scheduled tasks & background processes — cron-style automation and isolated long-running agents that work while you don’t.
• Project management built in — projects, sprints, todos, versioned artifacts, and multi-iteration loops for structured work of any kind.

Why PHP?

• Low resources, fast, fault tolerant — single-process, no garbage collector pauses, battle-tested in production for decades.
• Friendly language — readable syntax with a massive ecosystem and community.
• Easy to read and understand — approachable even for non-programmers who want to inspect or modify agent behavior.
• Easy to host — runs anywhere PHP runs: shared hosting, VPS, Docker, serverless. More hosting providers than any other runtime.
• Self-hosting friendly — no complex infrastructure, no cluster, no cloud dependency.

Features

• 🤖 Multi-Model Orchestration — route tasks to the right model with automatic failover
• 🔀 Agent Delegation — spawn specialized agents (coder, researcher, planner, reviewer, muse, philosopher) with role-appropriate models
• 🧠 Memory Persistence — cross-session memory with SQLite, FTS5, and optional vector embeddings
• 📦 Runtime Extensibility — install Composer toolkits at runtime; browse coqui.space
• 🔐 Credential Management — declarative .env-based secrets with hot-reload and automatic guards
• 📋 Skills System — teach Coqui any workflow with plain Markdown files — no code required
• ⏰ Scheduled Tasks — cron-style automation with circuit breakers
• 📨 Channels — Signal-backed external messaging with API-managed inbound and outbound delivery
• 🏗️ Background Tasks — isolated processes for long-running work
• 🔁 Loops — fully automated multi-iteration workflows chaining roles in sequence
• 🧩 Cognitive Flexibility — creative muse and philosopher roles, diverge-converge loops, sketch/hypothesis artifacts
• 🗂️ Artifacts & Plans — versioned plan artifacts with draft→review→final lifecycle
• 🔧 Toolkit Visibility — 3-tier model (enabled/stub/disabled) to reduce token usage
• 🛡️ Layered Safety — 5-layer security: sandbox → sanitizer → blacklist → approval → audit
• 🌐 HTTP API — async REST + SSE server for dashboards and headless automation
• 💾 Persistent Sessions — SQLite-backed conversations that survive restarts
• 👁️ Vision Analysis — analyze images from URLs, files, or base64 data
• 🪶 Soul — customizable orchestrator identity via prompts/soul.md

See docs/FEATURES.md for the full feature reference with usage examples and token efficiency strategies.

Platform Support

For the best experience on Windows, use the WSL2 installer path first. Docker remains a containerized alternative when you do not want a WSL-based workflow.

Requirements

• PHP 8.4 or later
• Core extensions: dom, mbstring, pdo_sqlite, xml
• Recommended extensions: curl, readline, zip
• Optional extensions: gd for bundled image previews, pcntl and posix on Linux or macOS for background task management
• Ollama (recommended for local inference)

Or use Docker — no local PHP required. The Docker image includes the default batteries-included extension set. See Docker below.

Installation

The installer detects your OS, installs PHP 8.4+ and required extensions if missing, downloads the latest Coqui release, verifies the SHA-256 checksum, and adds coqui to your PATH — no Git or Composer required.

Linux / macOS / WSL2

curl -fsSL https://coquibot.org/install | bash

Windows (WSL2 Bootstrap)

Run the Windows bootstrap in PowerShell. It checks for WSL2, offers to install Ubuntu when needed, and then runs the standard Coqui installer inside WSL.

irm https://raw.githubusercontent.com/AgentCoqui/coqui-installer/main/install.ps1 | iex

Update

Re-run the same install command. The installer detects an existing installation and updates it automatically.

Inspect before running

• Linux / macOS / WSL2: install.sh
• Windows bootstrap: install.ps1

Development Install

Clone the repository and install dependencies manually. Requires PHP 8.4+, Composer 2.x, and Git.

git clone https://github.com/AgentCoqui/coqui.git
cd coqui
composer install

Alternatively, use the --dev flag with the installer to clone and set up in one step:

# Linux / macOS
./install.sh --dev
 
# Windows
.\install.ps1 -Dev

Quick Start

./bin/coqui

./bin/coqui is the main entry point. It starts the launcher-managed app: REPL in the foreground plus the API server in the background on port 3300.

Use ./bin/coqui-launcher when you want the explicit launcher name. Both entry points share the same launcher-managed behavior.

The launcher-managed app handles:

• Clean exit (exit code 0) — /quit stops the launcher and all background services
• Restart (exit code 10) — /restart or the restart_coqui tool triggers an immediate relaunch
• Crash recovery — unexpected exits auto-relaunch up to 3 consecutive times
• Service management — ./bin/coqui status, stop, and cleanup to manage background services and reclaim stale Coqui-owned processes

If a previous session left stale Coqui processes behind, run:

./bin/coqui cleanup

cleanup only targets stale or conflicting Coqui-owned processes for this checkout. It does not blindly kill unrelated PHP processes.

 Coqui v0.1.0

 Session  a3f8b2c1
 Model    ollama/glm-4.7-flash:latest
 Project  /home/you/projects/my-app
 Workspace /home/you/.coqui/.workspace

 Type /help for commands, /quit to exit.

 You > Summarize the README.md file
 ▸ Using: read_file(path: "README.md")
 ✓ Done

 The README describes a PHP application that...

Make sure Ollama is running: ollama serve and a model is pulled: ollama pull glm-4.7-flash

Getting Started

Once you’re in the REPL:

1. Have a conversation — ask questions, request code changes, or describe a task
2. Try a different role — /role coder for focused coding, /role plan for structured planning
3. Extend with toolkits — browse coqui.space, install with /space install ‹package›, then restart Coqui to activate newly discovered tools and toolkit-provided REPL commands
4. Run API-only mode when needed — coqui --api-only or ./bin/coqui-launcher --api-only
5. Explore models — map roles to models in openclaw.json for cost-optimized routing

See docs/ROLES.md for all built-in roles and docs/COMMANDS.md for the full command reference.

CLI Options

See docs/COMMANDS.md for the full CLI reference including api, setup, and doctor subcommands.

REPL Commands

See docs/COMMANDS.md for the full command reference with examples.

Providers & OpenClaw Config

Coqui uses an openclaw.json config file for centralized model routing. The format is fully compatible with OpenClaw — you can drop in your existing OpenClaw config and it works without any changes. Coqui-specific extensions (workspace, mounts, shell access control) live under agents.defaults and are safely ignored by other OpenClaw-compatible tools.

Config changes require a restart to take effect. Use /restart in the REPL or restart the process after editing openclaw.json.

For the full config reference, see docs/CONFIGURATION.md.

Supported Providers

OpenAI Responses API — use openai-responses for Codex models (e.g. openai/codex-mini). Standard OpenAI models use openai-completions.

Any OpenAI-compatible provider can be added by specifying openai-completions as the API protocol.

Provider Setup

// Ollama (local — no API key needed)
"ollama": {
    "baseUrl": "http://localhost:11434/v1",
    "apiKey": "ollama-local",
    "api": "openai-completions"
}
 
// OpenAI
"openai": {
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "your-openai-api-key",
    "api": "openai-completions"
}
 
// Anthropic
"anthropic": {
    "baseUrl": "https://api.anthropic.com/v1",
    "apiKey": "your-anthropic-api-key",
    "api": "anthropic"
}
 
// xAI (Grok)
"xai": {
    "baseUrl": "https://api.x.ai/v1",
    "apiKey": "your-xai-api-key",
    "api": "openai-completions"
}

Set your API keys as environment variables or directly in openclaw.json:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export XAI_API_KEY="xai-..."

Role-Based Model Routing

The real power is in role-to-model mapping. Assign the best model for each job:

{
    "agents": {
        "defaults": {
            "model": {
                "primary": "ollama/glm-4.7-flash:latest",
                "fallbacks": ["ollama/qwen3-coder:latest"]
            },
            "roles": {
                "orchestrator": "openai/gpt-4.1",
                "coder": "anthropic/claude-opus-4-6",
                "reviewer": "openai/gpt-4o-mini"
            }
        }
    }
}

The orchestrator runs on a cost-effective model for routing and simple tasks, then delegates to expensive models only when needed — keeping costs low while maintaining quality where it counts.

Model Aliases

Define short aliases for quick reference:

{
    "models": {
        "ollama/qwen3:latest": { "alias": "qwen" },
        "anthropic/claude-opus-4-6": { "alias": "opus" },
        "openai/gpt-4.1": { "alias": "gpt4.1" }
    }
}

Built-in Tools

Coqui ships with a rich set of tools organized into toolkits:

Toolkits from Coqui Space and local workspace packages add more: GitHub, Brave Search, browser automation, Canva, Cloudflare, image generation, and more.

Extending Coqui

Coqui auto-discovers toolkits from installed Composer packages. Create a package that implements ToolkitInterface, register it in composer.json, and Coqui picks it up automatically — including credentials and gated operations.

Toolkit-provided REPL commands follow the same boot-time discovery path. After /space install ‹package› or a manual Composer install, restart Coqui to activate newly discovered tools and slash commands.

See docs/TOOLKITS.md for the full walkthrough with examples.

Performance

Coqui is optimized for low-latency agent loops. Key design decisions:

OPcache & JIT

Coqui ships with a tuned conf.d/coqui.ini that enables OPcache and JIT (tracing mode 1255, 128MB buffer). The installer and coqui doctor check for proper OPcache/JIT configuration.

For best performance in a non-debug CLI, ensure your PHP CLI has OPcache enabled and JIT available:

opcache.enable_cli=1
opcache.jit=1255
opcache.jit_buffer_size=128M

If you keep xdebug or pcov loaded in your everyday local CLI, disable JIT locally instead of trying to silence the startup warning. Those extensions make JIT unavailable anyway.

opcache.enable_cli=1
opcache.jit=0
opcache.jit_buffer_size=0

On Homebrew PHP this is usually easiest as a late-loading override such as /opt/homebrew/etc/php/8.4/conf.d/zz-local-no-jit.ini.

Benchmarking

Run the built-in benchmark command to measure performance on your system:

coqui benchmark
coqui benchmark --json          # Machine-readable output
coqui benchmark -i 500          # Custom iteration count

SQLite Tuning

Coqui configures SQLite for CLI workloads: WAL journal mode, synchronous=NORMAL, 8MB page cache, and in-memory temp storage. These PRAGMAs reduce fsync overhead and improve query throughput for the single-user agent use case.

Docker

Docker is the supported containerized alternative on Windows when you do not want to use WSL2. GPU passthrough and some terminal features may still behave differently. Please report issues.

Run Coqui in a container with zero host dependencies. The Docker setup uses php:8.4-cli with all required extensions and Composer.

The image includes the default batteries-included extension set: dom, curl, gd, mbstring, pdo_sqlite, readline, xml, zip, and pcntl.

Quick Start (Docker)

# Build the image
make docker-build
 
# Start REPL + API
make docker-start

Pass API keys from your host environment:

OPENAI_API_KEY=sk-... make docker-start

Or copy .env.example to .env and fill in your keys:

cp .env.example .env

Connect to Ollama

Coqui connects to Ollama on your host machine via host.docker.internal. Make sure Ollama is running:

ollama serve

Toolkit Discovery In Docker

Coqui discovers Composer-installed toolkits and toolkit-provided REPL commands on boot inside the container just like it does natively. After installing a toolkit with /space install ‹package› or a workspace Composer command, restart the REPL or API container so the new tools and slash commands are registered.

Useful Commands

Configuration

Pass a config file via the main entry point or the explicit launcher name:

# Native
./bin/coqui --config openclaw.json
 
# Docker
docker compose run --rm -v ./openclaw.json:/app/openclaw.json:ro coqui

File Overview

Documentation

Community

We’re building a community where people share agents, ask for help, and collaborate on new toolkits.

• Discord — Join us for support, discussions, and sharing your toolkits
• GitHub — AgentCoqui/coqui for issues, PRs, and source code

Contributing

We’d love your help making Coqui even mightier:

• Build new toolkits — create Composer packages that implement ToolkitInterface
• Add loops & background tasks — automate multi-iteration workflows and long-running processes
• Improve tools — enhance existing tools or add new ones in src/Tool/
• Write tests — expand coverage in tests/Unit/
• Fix bugs & improve docs — every contribution counts

See AGENTS.md for code conventions and architecture guidelines.

License

MIT