Meerkat Platform Guide

Meerkat (rkat) is a minimal, high-performance agent harness for LLM-powered applications. It provides the core execution loop, tool dispatch, session management, and multi-agent coordination without opinions about prompts or output formatting.

Surfaces

Meerkat exposes the same agent engine through multiple surfaces. All share the same underlying AgentFactory::build_agent() pipeline.

For full API reference for each surface including method signatures, parameters, and complex multi-step examples, load: references/api_reference.md

Quick Start

CLI

rkat run "What is Rust?"
rkat run "Create a todo app" --enable-builtins --enable-shell --stream -v
rkat resume sid_abc123 "Now add error handling"

Python SDK

from meerkat import MeerkatClient

client = MeerkatClient()
await client.connect()
result = await client.create_session("What is Rust?")
print(result.text)

# Streaming
async with client.create_session_streaming("Write a poem") as stream:
    async for event in stream:
        if event["type"] == "text_delta":
            print(event["delta"], end="", flush=True)
    result = stream.result

await client.close()

TypeScript SDK

import { MeerkatClient } from "@meerkat/sdk";
const client = new MeerkatClient();
await client.connect();
const result = await client.createSession({ prompt: "What is Rust?" });
await client.close();

Rust SDK

use meerkat::{AgentFactory, AgentBuildConfig};
use meerkat_core::Config;

let config = Config::load().await?;
let factory = AgentFactory::new(".rkat/sessions").builtins(true).shell(true);
let build = AgentBuildConfig::new("claude-sonnet-4-5");
let mut agent = factory.build_agent(build, &config).await?;
let result = agent.run("What is Rust?".into()).await?;

Configuration

Configuration loads from .rkat/config.toml (project) or ~/.rkat/config.toml (global). API keys come from environment variables only.

[agent]
model = "claude-sonnet-4-5"
max_tokens_per_turn = 8192

[budget]
max_tokens = 100000
max_duration = "30m"
max_tool_calls = 50

[shell]
timeout_secs = 120

[comms]
mode = "inproc"  # or "tcp" with address = "0.0.0.0:4200"

[skills]
enabled = true
max_injection_bytes = 32768
inventory_threshold = 12

Environment variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY.

Core Features

Sessions

Sessions persist conversation state across turns. Lifecycle: create -> turn -> turn -> ... -> archive.

Streaming

Real-time event streaming: text_delta, tool_call_requested, tool_result_received, turn_completed, run_completed. Python SDK provides create_session_streaming() and start_turn_streaming() with async context manager pattern.

Skills

Domain-specific knowledge injection. Activated via /skill-ref in messages, skill_references wire param, or preload_skills at session creation. Sources: filesystem, git, HTTP, embedded. Configure in .rkat/skills.toml.

Hooks

8 lifecycle hook points (RunStarted, PreLlmRequest, PostLlmResponse, PreToolExecution, PostToolExecution, TurnBoundary, RunCompleted, RunFailed) for policy enforcement, logging, and content modification.

Sub-Agents

Hierarchical agent spawning with tools: agent_spawn, agent_fork, agent_status, agent_cancel, agent_list. Budget-isolated with configurable model inheritance.

Inter-Agent Communication

Encrypted peer-to-peer messaging via send_message, send_request, send_response, list_peers. Host mode keeps agent alive listening for messages.

Memory

Semantic memory indexes conversation history for cross-session retrieval via memory_search tool. Uses HNSW vectors backed by redb.

Structured Output

JSON schema-based extraction with automatic retry on validation failure. Pass output_schema on any surface.

Reference

For complete API reference with all method signatures, parameters, return types, and complex multi-feature examples across all surfaces, load: references/api_reference.md