A modular, high-performance agent harness built in Rust.

Quick Start • Capabilities • Surfaces • Examples • Docs

Meerkat is a library-first, modular agent harness -- composable Rust crates that handle the hard parts of building agentic systems: state machines, retries, budgets, streaming, tool execution, MCP integration, and multi-agent coordination.

It is designed to be stable (deterministic state machine, typed errors, compile-time guarantees) and fast (<10ms cold start, ~20MB memory, single 5MB binary).

The library comes first; surfaces come second. The CLI, REST API, JSON-RPC server, MCP server, Python SDK, and TypeScript SDK are all thin layers over the same engine. Pick the entry point that fits your architecture.

Those tools excel at interactive development with rich terminal UIs. Meerkat is for automated pipelines, embedded agents, multi-agent systems, and anywhere you need programmatic control over the agent lifecycle.

cargo install rkat
export ANTHROPIC_API_KEY=sk-...

Run a one-off prompt with any provider:

rkat run "What is the capital of France?"
rkat run --model gpt-5.2 "Explain async/await"

Give it tools and let it work. Enable shell access and mob orchestration, then let the agent coordinate delegated work through mob members and flows:

rkat run --enable-builtins --enable-shell --enable-mob \
  "Create a small mob to inspect src/ for functions longer than 50 lines. \
   Ask the members to suggest refactors, then collect and summarize the results."

Extract structured data with schema validation and budget controls:

rkat run --model claude-sonnet-4-5 --enable-builtins --enable-shell \
  --output-schema '{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"description":{"type":"string"}},"required":["file","severity","description"]}}},"required":["issues"]}' \
  --max-tokens 4000 \
  "Audit the last 20 commits for security issues. Check each changed file."

The agent loops autonomously -- calling tools, reading results, reasoning, calling more tools -- until the task is done or the budget runs out. All three examples use the same binary; provider is inferred from the model name.

Providers and streaming. Anthropic, OpenAI, and Gemini through a unified streaming interface. Provider is inferred from the model name -- switch models with a flag, not a code change.

Sessions and memory. Persistent sessions (JSONL or redb), automatic context compaction for long conversations, and semantic memory with HNSW indexing for recall across sessions.

Tools and integration. Custom tool dispatchers, native MCP client for connecting external tool servers, JSON-schema-validated structured output, and built-in tools for task management, utility edits like apply_patch, shell access, and more. Live tool scoping lets you add, remove, or filter tools mid-session without restarting the agent.

Hooks and skills. Eight hook points (pre/post LLM, pre/post tool, turn boundary, run lifecycle) with observe, rewrite, and guardrail semantics. Skills are composable knowledge packs that inject context and capabilities.

Multi-agent. Sub-agents with budget and tool isolation. Peer-to-peer inter-agent messaging with cryptographic identity. Mobs for orchestrating teams of agents with role-based coordination, shared task boards, and DAG-based flows. Portable mob artifacts (.mobpack) support reproducible deploys via CLI and browser-target web bundles.

Packaging and targets. Build once as a signed .mobpack, then choose runtime target: direct deploy, embedded native binary, optimized compile, or browser WASM bundle.

Modularity. Every subsystem is opt-in via Cargo features. Default: three providers and nothing else. Add session-store, mcp, comms, or skills as needed. Disabled features return typed errors, not panics. See the capability matrix for the full feature map.

All surfaces share the same SessionService lifecycle and AgentFactory construction pipeline.

graph TD
    subgraph surfaces["Surfaces"]
        CLI["rkat CLI"]
        REST["REST API"]
        RPC["JSON-RPC"]
        MCPS["MCP Server"]
        RUST["Rust SDK"]
        PY["Python SDK"]
        TS["TypeScript SDK"]
    end

    SS["SessionService"]
    AF["AgentFactory"]

    CLI --> SS
    REST --> SS
    RPC --> SS
    MCPS --> SS
    RUST --> SS
    PY -->|via rkat-rpc| SS
    TS -->|via rkat-rpc| SS

    SS --> AF

    subgraph core["meerkat-core  (no I/O deps)"]
        AGENT["Agent loop + state machine"]
        TRAITS["Trait contracts"]
    end

    AF --> AGENT

    CLIENT["Providers\nAnthropic / OpenAI / Gemini"]
    TOOLS["Tools\nRegistry / MCP / Built-ins"]
    SESSION["Sessions\nPersistence / Compaction"]
    MEMORY["Memory\nHNSW semantic index"]
    COMMS["Comms\nP2P messaging"]
    HOOKS["Hooks\nObserve / Rewrite / Guard"]

    AGENT --> CLIENT
    AGENT --> TOOLS
    AGENT --> SESSION
    AGENT --> MEMORY
    AGENT --> COMMS
    AGENT --> HOOKS

See the architecture reference for the full crate structure, state machine diagram, and extension points.

Use an agent as a processing component in your service -- typed output, budget-limited, no subprocess.

let mut agent = AgentBuilder::new()
    .model("claude-sonnet-4-5")
    .system_prompt("You are an incident triage system.")
    .output_schema(OutputSchema::new(triage_schema)?)
    .budget(BudgetLimits::default().with_max_tokens(2000))
    .build(llm, tools, store)
    .await;

let result = agent.run(raw_alert_text.into()).await?;
let output = result.structured_output.ok_or("schema validation returned no output")?;
let triage: TriageReport = serde_json::from_value(output)?;
route_to_oncall(triage).await;

The agent returns validated JSON matching your schema, enforced by budget limits. This runs in-process in your Rust binary -- no HTTP roundtrip, no subprocess management.

Drive an agent from your Python backend. The agent coordinates mob members to parallelize work across providers.

from meerkat import MeerkatClient

client = MeerkatClient()
await client.connect()

result = await client.create_session(
    f"Analyze these CI failures. For each failing test, create a small mob "
    f"member task (use gemini-3-flash-preview for speed) to investigate the root cause by "
    f"reading the relevant source files. Collect results and return structured JSON.\n\n"
    f"{ci_log}",
    model="claude-sonnet-4-5",
    enable_shell=True,
    enable_mob=True,
    output_schema={
        "type": "object",
        "properties": {
            "failures": {"type": "array", "items": {"type": "object", "properties": {
                "test": {"type": "string"},
                "root_cause": {"type": "string"},
                "suggested_fix": {"type": "string"}
            }, "required": ["test", "root_cause", "suggested_fix"]}}
        }, "required": ["failures"]
    },
)

# Structured output -- parse directly, feed into your pipeline
return json.loads(result.structured_output)["failures"]

The orchestrator agent delegates investigation to fast mob members, collects their findings, and synthesizes a structured report. Budget controls prevent runaway cost.

Mobs are tool-driven -- the agent uses mob_* tools to create a team, spawn members, and coordinate work. Define the team structure in TOML and let the agent orchestrate:

# audit-team.toml
[profiles.analyst]
model = "claude-sonnet-4-5"
system_prompt = "You analyze code for error handling gaps, security issues, and test coverage."
tools = { shell = true, builtins = true }

[profiles.writer]
model = "gpt-5.2"
system_prompt = "You produce clear, actionable remediation plans from analysis findings."

[wiring]
mesh = [{ a = "analyst", b = "writer" }]

rkat run --enable-builtins --enable-shell \
  "Use a mob with the definition in audit-team.toml to audit the payments module. \
   The analyst should examine error handling and edge cases. The writer should \
   produce a prioritized remediation plan. Use the mob_* tools to coordinate."

The orchestrating agent reads the definition, creates the mob via mob_create, spawns members via mob_spawn, and the team communicates via signed peer-to-peer messages with a shared task board. See the mobs guide for DAG-based flows and built-in prefabs (coding_swarm, code_review, research_team, pipeline).

Build once, run in multiple environments with a portable .mobpack:

rkat mob pack ./mobs/release-triage -o ./dist/release-triage.mobpack
rkat mob deploy ./dist/release-triage.mobpack "triage latest regressions" --trust-policy strict

Browser target from the same artifact:

cargo install wasm-pack
export PATH="$HOME/.cargo/bin:$PATH"
rkat mob web build ./dist/release-triage.mobpack -o ./dist/release-triage-web

See full guide: Mobpack and Web Deployment.

export ANTHROPIC_API_KEY=sk-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=...

# .rkat/config.toml (project) or ~/.rkat/config.toml (user)
[agent]
model = "claude-sonnet-4-5"
max_tokens = 4096

See the configuration guide for the full reference.

Full documentation at docs.rkat.ai.

cargo build --workspace             # Build
cargo rct                           # Fast tests (unit + integration-fast)
make ci                             # Full CI pipeline

1. Run cargo rct to verify all checks pass
2. Add tests for new functionality
3. Submit PRs to main

Licensed under either of Apache-2.0 or MIT, at your option.