php-claw

A minimal personal AI agent in the spirit of OpenClaw / NanoClaw, built entirely on PHP TrueAsync. You chat with it; it runs a Claude (or DeepSeek / any OpenAI-compatible) agent loop that can take real actions on the host (run shell commands, read and write files) and replies in the same conversation. "Claude Code whose terminal is your chat."

This is a learning project. Its purpose is to teach, and to show off, asynchronous PHP built into the engine (TrueAsync): a whole agent (concurrent HTTP, subprocesses, timers) in one process, with plain-looking code that never blocks. It is intentionally small and readable, not a production product. Not affiliated with Anthropic, OpenClaw or NanoClaw.

The design is documented step by step in ARCHITECTURE.md and, as a narrative tutorial, in tutorial/ru/ (Russian).

How it works

The core is the agentic loop (ReAct): a user message goes to the agent; the agent either replies with text or asks to run tools; tools run, their results go back to the agent, and it continues until a final answer. Everything the agent does is I/O-bound (HTTP to the model, HTTP to the chat, bash subprocesses), so under TrueAsync it all awaits and costs no CPU while suspended: hundreds of conversations run concurrently in a single thread, no callbacks.

Layers: Chat (the messenger; a console gateway today), Agent (decides the next move; pluggable backend with cause-aware retries), Tool (runs real actions, gated later by a security layer), and the Session that glues them with the loop.

Requirements

• A PHP TrueAsync build (PHP 8.6+) with the true_async, curl and pdo extensions.
• Composer (for the dev tooling and autoloader).

Quick start (console)

composer install
cp .env.example .env      # then set an API key (e.g. DeepSeek or Anthropic) and CLAW_ALLOWED_CHATS
php bin/claw              # type a message, Ctrl+D to exit

.env configures the backend (CLAW_AGENT = claude | openai-compatible | gemini), the model, the API key, and the sandbox working directory. Secrets stay in memory and are never exposed to the bash tool's environment.

Run with Docker

The image builds on the official TrueAsync PHP image, so you do not need a local TrueAsync build.

docker build -t php-claw .
docker run --rm -it \
  -v "$PWD/.env:/app/.env" \
  -v "$PWD/workspace:/app/workspace" \
  php-claw

The .env holds your secrets and is never baked into the image, so mount it at run time. Mounting workspace is optional; it lets the file and bash tools act on a directory you can see on the host.

Development

Run everything under the TrueAsync PHP binary:

php vendor/bin/testo            # tests (Testo)
php vendor/bin/phpstan analyse  # static analysis (level 8)
php vendor/bin/php-cs-fixer fix # coding style

Composer shortcuts: composer test, composer analyse, composer cs, composer cs-fix, composer qa (all three).

Status

Console agent that runs end to end (Config, async HTTP with cause-aware retry, Claude & DeepSeek backends, bash / read_file / write_file tools, the session loop, a periodic scheduler). Next: the security/permission middleware layer, per-session persistence, and a Telegram channel.