Getting Started

Five minutes from zero to your first AI-assisted code change. This guide covers the essentials: install, configure, and start using KosmoKrator in your project. For detailed installation options, see the Installation page.

Prerequisites

You need a terminal and an API key from at least one LLM provider (Anthropic, OpenAI, Google, Mistral, or any of the 40+ supported providers). That's it.

If you use the static binary, no PHP installation is required — the runtime is bundled. If you prefer the PHAR or source install, check your PHP version:

php -v

You need PHP 8.4 or newer for the PHAR and source methods. The static binary has no PHP requirement at all.

Install in 30 Seconds

Pick your preferred method below. For detailed instructions, platform-specific notes, and troubleshooting, see Installation.

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

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

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

First Run

Launch the setup wizard to configure your LLM provider:

kosmokrator setup

The wizard walks you through three steps:

1. Pick a provider — Choose from 40+ supported providers (Anthropic, OpenAI, Google, Mistral, local endpoints, and more).
2. Authenticate — Most providers accept an API key entered directly. OAuth-based providers (like Codex) use a browser or device flow instead — the wizard opens a link for you to authorize. Credentials are stored locally at ~/.kosmokrator/config.yaml and never sent anywhere except the provider's own API.
3. Pick a model — Select a default model. You can override this per-session or change it in the config later.

Once setup is complete, start KosmoKrator in your project directory:

cd your-project
kosmokrator

Your First Task

Once KosmoKrator is running, you'll see the interactive prompt. Here are three ways to put it to work immediately:

Ask a question

Type a natural-language question about your codebase. KosmoKrator will read relevant files and explain what's going on.

You > Explain how the routing works in this project

The agent searches your project, reads the relevant files, and responds with a clear explanation — no file edits, just understanding.

Make a change

Describe what you want done in plain language. The agent plans the change, reads the files it needs, and writes the code.

You > Add a /health endpoint to the API controller

Depending on your permission mode, file writes may ask for your approval before they land. In Prometheus mode they go through automatically; in Guardian mode you review each one.

Use a power command

Power commands (prefixed with :) activate specialized agent behaviors with a single instruction.

You > :review src/Controller/UserController.php

This launches a focused code review of the specified file. The agent reads the file, analyzes it for bugs, style issues, and improvements, and presents its findings.

Dispatch a skill

Use the $ prefix to dispatch a named skill directly:

You > $phpstan src/Controller/UserController.php

This invokes the phpstan skill on the specified file. Skills are specialized, reusable workflows you can define in your project config. See Commands for details.

Switch Modes

KosmoKrator operates in one of three modes that control what the agent can do. Switch modes at any time with a slash command:

For the complete list of slash commands, power commands, and keyboard shortcuts, see the Commands reference.

CLI Essentials

Subcommands

Beyond the interactive session, KosmoKrator ships with several subcommands:

Useful CLI options

Project-level config

Global config lives at ~/.kosmokrator/config.yaml. For per-project settings, create .kosmokrator/config.yaml in your project root. Project config overrides global values — perfect for team-shared defaults, model preferences, or custom skills. See Configuration for the full reference.

Next Steps

You're set up and productive. Dive deeper into the topics below to get the most out of KosmoKrator.