ACP

KosmoKrator can run as an Agent Client Protocol server for editors and IDEs that speak ACP:

kosmokrator acp

ACP mode is a protocol surface over the same runtime used by the terminal UI and headless CLI. It reuses provider credentials, sessions, permissions, built-in tools, Lua, integrations, MCP, memory, tasks, and subagents.

Clients that only understand ordinary ACP can ignore the extra frames. Rich wrappers can opt into KosmoKrator’s native model by reading the advertised kosmokratorCapabilities and subscribing to namespaced kosmokrator/* notifications on the same JSON-RPC connection.

Quick Start

kosmokrator setup
kosmokrator acp
kosmokrator acp --cwd /path/to/project --mode edit --permission-mode guardian
kosmokrator acp --yolo

ACP uses newline-delimited JSON-RPC over stdin/stdout. Stdout is reserved for protocol frames; logs and diagnostics go to stderr.

Editor Configuration

Zed

{
  "agent_servers": {
    "kosmokrator": {
      "command": "kosmokrator",
      "args": ["acp"]
    }
  }
}

JetBrains

{
  "agents": {
    "kosmokrator": {
      "command": "kosmokrator",
      "args": ["acp"]
    }
  }
}

Neovim / CodeCompanion

acp_providers = {
  kosmokrator = {
    command = "kosmokrator",
    args = { "acp" }
  }
}

Capabilities

ACP Feature	Status	Notes
Initialize	Supported	Advertises KosmoKrator version, prompt support, sessions, and auth method.
New session	Supported	Creates a normal persisted KosmoKrator session for the requested cwd.
Prompt	Supported	Streams assistant text and tool updates through session/update.
Load / resume	Supported	Loads existing persisted sessions by ID.
List sessions	Supported	Lists workspace sessions without requiring an LLM provider call.
Cancel	Supported	Cancels the active turn and subagents where the underlying operation honors cancellation.
Permissions	Supported	Guardian/Argus prompts are bridged to ACP session/request_permission.
Config options	Supported	Model, agent mode, and permission mode are exposed through session/set_config_option.
Legacy model switch	Supported	session/set_model is accepted for clients that still use the draft model endpoint.
Client MCP servers	Supported for stdio	ACP mcpServers become runtime-only MCP overlays for that active session and appear in app.mcp.*.
Client filesystem / terminal delegation	Planned	File and shell tools currently execute through KosmoKrator’s local tool layer.
KosmoKrator extension events	Supported	Native UI events are emitted as kosmokrator/* notifications for wrappers that need terminal-grade state.
Direct integration calls	Supported	ACP clients can list, describe, and call headless integrations without going through an LLM turn.
Direct MCP calls	Supported	ACP clients can list servers/tools, inspect schemas, call MCP tools, and execute MCP Lua workflows.
Lua execution	Supported	Lua can run against the integration runtime, the MCP runtime, or the combined integration runtime.

KosmoKrator Extensions

The extension layer keeps ACP compatibility while exposing the full KosmoKrator runtime to non-PHP applications. Extension events are JSON-RPC notifications whose method names start with kosmokrator/. Every event includes:

• protocolVersion — extension protocol version.
• type — event type without the namespace.
• sessionId — KosmoKrator session ID.
• runId — stable ID for the current prompt turn, when available.
• timestamp — Unix timestamp with fractional seconds.

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": 1
  },
  "id": 1
}

The response includes:

{
  "protocolVersion": 1,
  "agentInfo": {
    "name": "KosmoKrator",
    "version": "..."
  },
  "kosmokratorCapabilities": {
    "protocolVersion": 1,
    "uiEvents": true,
    "textDeltas": true,
    "thinkingDeltas": true,
    "toolLifecycle": true,
    "permissions": true,
    "subagentTree": true,
    "subagentDashboard": true,
    "integrations": true,
    "mcp": true,
    "lua": true,
    "runtimeConfig": true,
    "sessions": true,
    "permissionModes": true
  }
}

Native Event Stream

Notification	Purpose
kosmokrator/session_update	Prompt run started, completed, or cancelled.
kosmokrator/phase_changed	Agent phase changed.
kosmokrator/text_delta	Assistant response text delta.
kosmokrator/thinking_delta	Reasoning or thought delta when available.
kosmokrator/tool_started	Tool call was created.
kosmokrator/tool_progress	Tool execution status changed.
kosmokrator/tool_completed	Tool call completed or failed.
kosmokrator/permission_requested	KosmoKrator is asking the ACP client to approve a governed operation.
kosmokrator/permission_resolved	The client answered or the request was denied/cancelled.
kosmokrator/subagent_spawned	One or more subagents were spawned.
kosmokrator/subagent_running	Subagent batch execution started.
kosmokrator/subagent_tree	Live subagent tree snapshot for hierarchical UIs.
kosmokrator/subagent_completed	Subagent batch completed.
kosmokrator/subagent_dashboard	Aggregated subagent dashboard state.
kosmokrator/usage_updated	Token and cost counters changed.
kosmokrator/runtime_changed	Mode, model, provider, or permission selection changed.
kosmokrator/integration_event	Direct integration or Lua operation lifecycle.
kosmokrator/mcp_event	Direct MCP operation lifecycle.
kosmokrator/error	Agent/runtime error message.

{
  "jsonrpc": "2.0",
  "method": "kosmokrator/tool_started",
  "params": {
    "protocolVersion": 1,
    "type": "tool_started",
    "sessionId": "01j...",
    "runId": "run_1",
    "timestamp": 1777478400.123,
    "toolCallId": "tool_0",
    "tool": "file_read",
    "args": {
      "path": "README.md"
    },
    "kind": "read",
    "title": "Read README.md"
  }
}

Subagent Trees

Rich clients should build their tree from subagent_spawned and refresh it from subagent_tree. Tree nodes are plain JSON and include stable IDs, status, type, task, elapsed time, tool counts, errors, queue reason, last tool, message preview, retry timing, and children.

{
  "jsonrpc": "2.0",
  "method": "kosmokrator/subagent_tree",
  "params": {
    "type": "subagent_tree",
    "sessionId": "01j...",
    "runId": "run_1",
    "tree": [
      {
        "id": "docs-audit",
        "type": "explore",
        "task": "Audit docs",
        "status": "running",
        "elapsed": 4.2,
        "toolCalls": 3,
        "children": []
      }
    ]
  }
}

Sessions

ACP session IDs are KosmoKrator session IDs. A session created in an editor can be resumed from the CLI, and a terminal-created session can be loaded by an ACP client:

kosmokrator --session <id>
kosmokrator --resume

Permissions

ACP follows the same permission modes as the terminal UI:

• Guardian auto-approves safe operations and asks for risky ones.
• Argus asks for every governed tool operation.
• Prometheus auto-approves governed prompts while hard policy denies still apply.

When the policy asks, KosmoKrator sends an ACP permission request with allow once, allow always, reject once, and reject always options. If the client cancels or fails to answer, KosmoKrator denies the operation.

If the client sends session/cancel during a prompt turn, KosmoKrator requests cancellation from the active LLM call, cancels running subagents, and returns stopReason: "cancelled" for the turn. Operations that are already inside a non-interruptible local process may still emit final tool updates before the cancelled response is returned.

ACP MCP Servers

ACP clients can pass MCP servers in session/new, session/load, or session/resume. KosmoKrator adds those servers as runtime overlays for the active ACP session: they are available to that session but are not written to project .mcp.json. Switching between loaded ACP sessions refreshes the runtime overlay so session-specific MCP servers do not leak into the next prompt turn.

{
  "cwd": "/path/to/project",
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "env": []
    }
  ]
}

Attached servers are available in Lua through the same namespace as configured MCP servers:

app.mcp.filesystem.list_allowed_directories({})

Headless Configuration

ACP mode does not have its own credential store. Configure KosmoKrator once with normal headless commands:

printf %s "$OPENAI_API_KEY" | \
  kosmokrator providers:configure openai --api-key-stdin --json

kosmokrator settings:set agent.mode edit --global --json
kosmokrator settings:doctor --json

Direct Runtime Methods

These methods are for applications that need the same headless integration, MCP, Lua, and runtime surfaces as the CLI. They require a loaded ACP session so project root, session MCP overlays, permissions, and credentials match the active agent.

Runtime Selection

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "kosmokrator/runtime/set",
    "params": {
      "sessionId": "01j...",
      "provider": "openai",
      "mode": "edit",
      "model": "openai/gpt-5.4-mini",
      "permissionMode": "guardian"
  }
}

Settings And Credentials

{
  "jsonrpc": "2.0",
  "id": 18,
  "method": "kosmokrator/settings/set",
  "params": {
    "sessionId": "01j...",
    "scope": "project",
    "path": "kosmokrator.tools.default_permission_mode",
    "value": "guardian"
  }
}

{
  "jsonrpc": "2.0",
  "id": 19,
  "method": "kosmokrator/providers/configure",
  "params": {
    "sessionId": "01j...",
    "scope": "global",
    "provider": "openai",
    "model": "gpt-5.4-mini",
    "apiKey": "..."
  }
}

Provider responses never echo secret values. They report whether an API key or base URL was configured.

Integrations

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "kosmokrator/integrations/list",
  "params": {
    "sessionId": "01j...",
    "query": "plane",
    "limit": 20
  }
}

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "kosmokrator/integrations/describe",
  "params": {
    "sessionId": "01j...",
    "function": "plane.list_issues"
  }
}

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "kosmokrator/integrations/call",
  "params": {
    "sessionId": "01j...",
    "function": "plane.list_issues",
    "account": "work",
    "args": {
      "project_id": "..."
    },
    "force": false,
    "dryRun": false
  }
}

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "kosmokrator/integrations/configure",
  "params": {
    "sessionId": "01j...",
    "integration": "plane",
    "account": "work",
    "scope": "project",
    "credentials": {
      "api_key": "...",
      "workspace_slug": "..."
    },
    "enabled": true,
    "permissions": {
      "read": "allow",
      "write": "ask"
    }
  }
}

Integration credentials are stored in the global account credential store used by the headless integration CLI. The scope field controls the integration’s enabled state and read/write permission policy.

Integration calls follow configured read/write policy. Set force: true only for trusted automation that intentionally bypasses integration permission checks.

MCP

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "kosmokrator/mcp/list_servers",
  "params": {
    "sessionId": "01j..."
  }
}

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "kosmokrator/mcp/list_tools",
  "params": {
    "sessionId": "01j...",
    "server": "filesystem",
    "force": false
  }
}

{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "kosmokrator/mcp/call_tool",
  "params": {
    "sessionId": "01j...",
    "function": "filesystem.list_allowed_directories",
    "args": {},
    "force": false,
    "dryRun": false
  }
}

{
  "jsonrpc": "2.0",
  "id": 21,
  "method": "kosmokrator/mcp/add_stdio_server",
  "params": {
    "sessionId": "01j...",
    "scope": "project",
    "name": "filesystem",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
    "env": {},
    "enabled": true,
    "trust": true,
    "permissions": {
      "read": "allow",
      "write": "ask"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "kosmokrator/mcp/set_secret",
  "params": {
    "sessionId": "01j...",
    "server": "github",
    "key": "env.GITHUB_TOKEN",
    "value": "..."
  }
}

MCP direct calls honor project trust and read/write policy. Set force: true to bypass trust and policy for one trusted automation call.

Lua

{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "kosmokrator/lua/execute",
  "params": {
    "sessionId": "01j...",
    "runtime": "integrations",
    "code": "dump(app.integrations.plane.list_issues({project_id = '...'}))",
    "options": {
      "cpuLimit": 2.0,
      "memoryLimit": 67108864
    },
    "force": false
  }
}

Use runtime: "integrations" for the combined integration Lua environment, including app.integrations.* and available app.mcp.* namespaces. Use runtime: "mcp" for an MCP-only Lua environment.

Protocol Notes

• Transport is newline-delimited JSON-RPC over stdio.
• Stdout is reserved for JSON-RPC frames.
• Session IDs are the normal KosmoKrator persisted session IDs.
• Supported base ACP methods include initialize, authenticate, session/new, session/load, session/resume, session/list, session/prompt, session/cancel, session/close, session/set_mode, session/set_model, and session/set_config_option.
• Supported KosmoKrator methods include kosmokrator/capabilities, kosmokrator/runtime/set, kosmokrator/settings/set, kosmokrator/providers/configure, kosmokrator/integrations/list, kosmokrator/integrations/describe, kosmokrator/integrations/configure, kosmokrator/integrations/call, kosmokrator/mcp/list_servers, kosmokrator/mcp/list_tools, kosmokrator/mcp/schema, kosmokrator/mcp/add_stdio_server, kosmokrator/mcp/set_secret, kosmokrator/mcp/call_tool, and kosmokrator/lua/execute.
• Tool calls are streamed as ACP tool_call and tool_call_update events.
• Assistant text is streamed as agent_message_chunk.
• Reasoning/notices use agent_thought_chunk.
• HTTP and SSE MCP transports are not advertised yet; stdio MCP servers are supported.