PHP 8.4 agent runtime for terminal, CI, editors, and apps

KosmoKrator

A terminal-first coding agent with the same runtime available headlessly through CLI commands, Lua, MCP, ACP, and an embeddable PHP SDK.

Get Started Read SDK Docs GitHub
  • Interactive TUI or ANSI terminal
  • Headless JSON and stream-json execution
  • OpenCompany integrations, MCP, and Lua
  • ACP for non-PHP UI wrappers
  • SDK parity with the headless CLI
terminal
headless
sdk
acp
$ kosmokrator
You > Fix the failing tests and explain the risky changes.

  phase: exploring
  tool: php vendor/bin/phpunit
  tool: grep pattern="PaymentService"
  subagents: 3 running, 1 waiting

$ kosmokrator -p "Review this branch" \
    --mode plan \
    --output stream-json

$ kosmokrator integrations:plane search_issues --json
$ kosmokrator mcp:call github search_repositories \
    '{"query":"kosmokrator"}'

$agent = AgentBuilder::create()
    ->forProject($repo)
    ->withMode('edit')
    ->build()
    ->collect('Add tests for the billing edge cases');
~50MBruntime footprint
40+LLM providers
10parallel subagents by default
1:1headless and SDK runtime parity
Runtime Surface

One agent core, several integration points

The terminal UI is only one way to use KosmoKrator. The same session builder, tools, permissions, subagents, integrations, MCP runtime, Lua runtime, and context system are available to automation and external applications.

Terminal Agent

Interactive TUI with ANSI fallback, slash commands, approvals, model switching, sessions, memories, and live subagent monitoring.

/docs/getting-started

Headless CLI

Use `kosmokrator -p`, JSON output, stream-json events, settings commands, provider credentials, and agent-friendly helper commands in scripts.

/docs/headless

Integrations, MCP, and Lua

Call OpenCompany integrations and MCP tools directly from CLI or Lua while preserving read/write permissions and credential handling.

/docs/integrations

SDK and ACP

Embed the headless runtime in PHP applications, or wrap KosmoKrator from non-PHP apps through ACP plus KosmoKrator extension events.

/docs/sdk
Install

Install the way your environment expects

Use a zero-dependency binary, a small PHAR, a source checkout, or Termux on Android. Every path lands on the same CLI and headless runtime.

Recommended

Static binary

Self-contained release binary. No local PHP, Composer, Node, or Python runtime required.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

kosmokrator setup
kosmokrator
Small package

PHAR

Single PHP archive for machines that already have PHP 8.4+ installed.

sudo curl -fSL https://github.com/OpenCompanyApp/kosmokrator/releases/latest/download/kosmokrator.phar \
  -o /usr/local/bin/kosmokrator
sudo chmod +x /usr/local/bin/kosmokrator

kosmokrator setup
Development

Source checkout

Best when contributing, testing branches, or building a custom PHAR.

git clone https://github.com/OpenCompanyApp/kosmokrator.git
cd kosmokrator
composer install

bin/kosmokrator setup
Android

Termux

Run KosmoKrator on Android with Termux. Use ANSI renderer for the most predictable mobile terminal UX.

pkg update
pkg install php composer git curl

curl -fSL https://github.com/OpenCompanyApp/kosmokrator/releases/latest/download/kosmokrator.phar \
  -o $PREFIX/bin/kosmokrator
chmod +x $PREFIX/bin/kosmokrator

Headless provider setup

kosmokrator providers:configure openai \
  --api-key-env OPENAI_API_KEY \
  --model gpt-5.4-mini \
  --global --json

kosmokrator -p "Summarize this repo" \
  --mode ask \
  -o json

Full installation docs

Manual platform binaries, PHP extension requirements, update paths, PHAR builds, and troubleshooting live in the installation guides.

kosmokrator --version
kosmokrator setup
kosmokrator
Installation Docs Termux Docs
Control

Permissions are explicit in both UI and headless mode

Guardian, Argus, and Prometheus govern native tools. Integration and MCP read/write policies apply in headless runs too, with force flags reserved for trusted automation.

Guardian
Smart approval
Safe reads and known-safe commands can proceed; writes and uncertain actions ask first.
Argus
Ask for everything
Every governed tool call requires explicit approval. Useful for audits and sensitive projects.
Prometheus
Trusted automation
Run without approval prompts for CI, scripts, and controlled environments.
Architecture

Built around a reusable headless session

`AgentSessionBuilder` wires the LLM client, tools, permissions, context manager, renderer, subagents, integrations, MCP, and Lua. Terminal, CLI, SDK, and ACP entry points all run through that same shape.

CLI / SDK / ACP
→
AgentSessionBuilder
→
AgentLoop
→
Tools + Integrations + MCP