Meerkat

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

Quick Start • Capabilities • Surfaces • Architecture • Docs

Why Meerkat?

Meerkat is a library-first, modular agent harness — a set of composable Rust crates that handle the hard parts of building agentic systems: state machines, retries, budgets, streaming, tool execution, MCP, 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.

How it compares

Those tools excel at interactive development with rich terminal UIs. Meerkat has no TUI — the CLI is a thin, scriptable surface — but you still get first-class features like hooks, skills, semantic memory, and rich session management. Meerkat is for automated pipelines, embedded agents, multi-agent systems, and anywhere you need programmatic control.

Quick Start

As a Library

[dependencies]
meerkat = "0.1"
tokio = { version = "1", features = ["full"] }

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let result = meerkat::with_anthropic(std::env::var("ANTHROPIC_API_KEY")?)
        .model("claude-sonnet-4-5")
        .system_prompt("You are a helpful assistant.")
        .run("What is the capital of France?")
        .await?;

    println!("{}", result.text);
    Ok(())
}

As a CLI

cargo install rkat

export ANTHROPIC_API_KEY=sk-...
rkat run "What is the capital of France?"
rkat run --model gpt-5.2 "Write a haiku about Rust"
rkat run --model gemini-3-flash-preview "Explain async/await"

Core Capabilities

Modularity

Pick only what you need:

# Minimal: just the agent loop + one provider
meerkat = { version = "0.1", default-features = false, features = ["anthropic"] }

# Add persistence and compaction
meerkat = { version = "0.1", features = ["anthropic", "session-store", "session-compaction"] }

# Everything
meerkat = { version = "0.1", features = ["all-providers", "session-store", "session-compaction", "memory-store-session"] }

Disabled capabilities return typed errors (SessionError::PersistenceDisabled, etc.) — no panics, no silent degradation.

Surfaces

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

Architecture

                        ┌──────────────────┐
                        │   Your Surface   │  CLI / REST / RPC / MCP / SDK
                        └────────┬─────────┘
                                 │
                        ┌────────▼─────────┐
                        │     meerkat      │  Facade crate
                        └────────┬─────────┘
                                 │
     ┌───────────┬───────┬───────┼───────┬───────────┬───────────┐
     │           │       │       │       │           │           │
┌────▼────┐ ┌───▼───┐ ┌─▼───┐ ┌─▼─────┐ ┌───▼───┐ ┌─────▼─────┐
│ client  │ │session│ │store│ │ mcp   │ │ tools │ │  memory   │
├─────────┤ ├───────┤ ├─────┤ ├───────┤ ├───────┤ ├───────────┤
│Anthropic│ │Service│ │JSONL│ │Router │ │ Reg.  │ │ HNSW      │
│ OpenAI  │ │Compact│ │ redb│ │Stdio  │ │ Valid.│ │ redb      │
│ Gemini  │ │Events │ │     │ │HTTP   │ │       │ │           │
└─────────┘ └───────┘ └─────┘ └───────┘ └───────┘ └───────────┘
                                 │
                         ┌───────▼───────┐
                         │  meerkat-core │  Traits, state machine
                         │  No I/O deps  │  Pure logic
                         └───────────────┘

Crates

Examples

Custom Tools

use meerkat::{AgentToolDispatcher, ToolCallView, ToolDef, ToolResult};
use meerkat::error::ToolError;
use async_trait::async_trait;
use serde_json::json;
use std::sync::Arc;

struct Calculator;

#[async_trait]
impl AgentToolDispatcher for Calculator {
    fn tools(&self) -> Arc<[Arc<ToolDef>]> {
        vec![Arc::new(ToolDef {
            name: "add".into(),
            description: "Add two numbers".into(),
            input_schema: json!({
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"}
                },
                "required": ["a", "b"]
            }),
        })].into()
    }

    async fn dispatch(&self, call: ToolCallView<'_>) -> Result<ToolResult, ToolError> {
        #[derive(serde::Deserialize)]
        struct AddArgs { a: f64, b: f64 }

        match call.name {
            "add" => {
                let args: AddArgs = call.parse_args()
                    .map_err(|e| ToolError::InvalidArguments(e.to_string()))?;
                Ok(ToolResult::success(call.id, (args.a + args.b).to_string()))
            }
            _ => Err(ToolError::not_found(call.name)),
        }
    }
}

Streaming

let (tx, mut rx) = mpsc::channel(100);

tokio::spawn(async move {
    while let Some(event) = rx.recv().await {
        if let AgentEvent::TextDelta { delta } = event {
            print!("{}", delta);
        }
    }
});

agent.run_with_events("Write a poem".into(), tx).await?;

See the full documentation for more: MCP tools, session lifecycle, structured output, hooks, sub-agents, skills, and multi-agent comms.

Configuration

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

# .rkat/config.toml or ~/.rkat/config.toml
[agent]
model = "claude-opus-4-6"
max_tokens = 4096

See the configuration guide for the full reference.

Documentation

Full documentation is available at docs.rkat.ai.

Development

cargo build --workspace             # Build
cargo rct                           # Fast tests (unit + integration-fast)
cargo unit                          # Unit tests only
cargo int                           # Integration-fast only
cargo int-real                      # Integration-real (ignored by default)
cargo e2e                           # E2E tests (ignored; requires API keys)

Contributing

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

License

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