Looking for the karta command? The public CLI is @karta.sh/cli (npm install -g @karta.sh/cli). This package is karta-runtime - the internal engine that CLI bootstraps for karta dev, and the data plane the platform serves (RFC 0013, docs/rfcs/0013-unified-cli.md). Its own CLI verbs are internal (see CLI); use it directly as a Python SDK/library, exactly as documented below.

Why Karta

Agent frameworks like LangGraph, CrewAI, AutoGen, and the OpenAI Agents SDK build agents from scratch — defining their own tool systems, context management, memory, and execution loops.

Karta takes the opposite approach. Agent harnesses like Claude Code and OpenCode already solved the hard problems — tools, MCP servers, context management, memory, skills, and agentic execution. They're battle-tested, deeply integrated with real development workflows, and improving fast.

Karta builds on top of these harnesses in two tiers: a thin core that delegates all agent execution and conversation persistence to the harness, plus a platform layer that adds the multi-tenant SaaS machinery production applications need. Together they provide multi-user sessions, multi-agent routing, participant-aware messaging, cross-instance communication, HTTP deployment, multi-tenancy with durable tenant isolation, BYOK key management, usage metering, policy enforcement, and lifecycle hooks — without reinventing agent capabilities from scratch.

┌──────────────────────────────────────────────────────────┐
│  Other frameworks          │  Karta                      │
│                            │                              │
│  Build agents from scratch │  Build ON existing harnesses │
│  Own tool system           │  Harness tools (MCP, etc.)   │
│  Own memory/context        │  Harness memory/context      │
│  Own execution loop        │  Harness execution loop      │
│  + Multi-agent orchestr.   │  + Multi-user sessions       │
│                            │  + Multi-agent routing       │
│                            │  + Gateway & fan-out         │
│                            │  + Multi-tenancy             │
│                            │  + HTTP API & CLI            │
│                            │  + Hooks & policies          │
└──────────────────────────────────────────────────────────┘

What Karta provides

Install

pip install karta-runtime

With optional backends:

pip install karta-runtime[postgres]   # PostgreSQL sessions
pip install karta-runtime[s3]         # S3 sessions

You also need a coding agent harness installed:

• Claude Code: npm install -g @anthropic-ai/claude-code (docs)
• OpenCode: curl -fsSL https://opencode.ai/install | bash (docs)

Quickstart

Zero-config hello world

from karta import Karta

app = Karta()
response = app.send_sync("Hello!")
print(response.text)

Karta auto-detects your harness from the project directory (.claude/ → Claude Code, .opencode/ → OpenCode).

Multi-turn sessions

from karta import Karta

app = Karta()

session = app.session(metadata={"customer_id": "abc123"})
response = session.send_sync("I need help with my order")
response = session.send_sync("Order #12345")

# Resume later by looking up the session
session = app.session(metadata={"customer_id": "abc123"})
response = session.send_sync("Any updates?")

Multi-agent routing

Define specialist agents in your harness's native format (.claude/agents/*.md or .opencode/agents/*.md), then route:

from karta import Karta

app = Karta()

# Route to a specific agent
response = app.send_sync("Audit my billing", agent="billing-specialist")

# Agent handoff within a session
session = app.session(metadata={"customer_id": "abc123"})
session.send_sync("I need help with my order")         # → default agent
session.current_agent = app.agents["billing"]           # handoff
session.send_sync("Check invoice #789")                 # → billing agent

Multi-participant sessions

from karta import Karta, HumanAgent

app = Karta()
session = app.session()

alice = HumanAgent(name="alice", display_name="Alice Chen")
bob = HumanAgent(name="bob", display_name="Bob Park")

# Messages are attributed to the sending participant
session.send_sync("I need help with deployment", participant=alice)
session.send_sync("I can help — what's the error?", participant=bob)

Streaming

import asyncio
from karta import Karta

async def main():
    app = Karta()
    async for event in app.stream("Explain quicksort"):
        if event.type == "text":
            print(event.text, end="", flush=True)

asyncio.run(main())

HTTP API

from karta import Karta
from karta.server import create_fastapi_app
import uvicorn

app = Karta()
fastapi_app = create_fastapi_app(app)
uvicorn.run(fastapi_app, host="0.0.0.0", port=8000)

This exposes:

• POST /v1/send — send a message, get a response
• POST /v1/stream — send a message, get SSE stream
• POST /v1/sessions — create a session
• GET /v1/sessions — list/lookup sessions
• POST /v1/sessions/{id}/messages — send within a session
• POST /v1/sessions/{id}/input/respond — respond to approval prompts
• POST /v1/gateway/submit — submit a gateway event
• POST /v1/gateway/deliver — deliver to a local participant
• GET /healthz — health check

Multi-tenancy

from karta import KartaHub

hub = KartaHub("/path/to/karta-root")

# Each tenant/user gets an isolated workspace
session = hub.session("acme", "alice", metadata={"topic": "billing"})
response = session.send_sync("Help with invoice")

Lifecycle hooks

app = Karta()

@app.on("message.completed")
async def log_response(event):
    print(f"Session {event.session.id}: {event.message.text}")

@app.on("agent.handoff")
async def track_handoff(event):
    print(f"Handoff: {event.payload['from']} → {event.payload['to']}")

CLI (internal)

The customer-facing CLI is @karta.sh/cli; this package's verbs are internal (local platform dev, self-host):

karta-runtime dev <path>         # Hot-reload REPL against a folder
karta-runtime dev-serve <path>   # Serve a folder behind the consumer session API
                                 # (what the unified CLI's `karta dev` spawns)
karta-runtime serve              # The platform serve plane (self-host / dev-infra)

This package installs no karta script at all - that name belongs to the unified CLI (npm install -g @karta.sh/cli). It was dropped rather than shimmed: karta-python never shipped to PyPI, so there is no installed base to point anywhere.

Architecture

                 External Clients / Other Karta Instances
                              │
                    ┌─────────▼──────────┐
                    │     Gateway         │  event ingestion, fan-out delivery
                    │  Local · HTTP       │  cross-instance messaging
                    └─────────┬──────────┘
                              │
                    ┌─────────▼──────────┐
                    │   Client Layer      │  HTTP API · CLI · Python SDK
                    └─────────┬──────────┘
                              │
                    ┌─────────▼──────────┐
                    │   Multi-Tenancy     │  KartaHub → WorkspaceManager
                    └─────────┬──────────┘
                              │
                    ┌─────────▼──────────┐
                    │    Karta Core       │  sessions, agents, policies,
                    │                     │  hooks, participants
                    └─────────┬──────────┘
                              │
                    ┌─────────▼──────────┐
                    │   Harness Layer     │  Claude Code (SDK) or
                    │                     │  OpenCode (CLI subprocess)
                    └─────────┬──────────┘
                              │
                    ┌─────────▼──────────┐
                    │   Coding Agent      │  tools, MCP, context,
                    │                     │  memory, skills
                    └──────────────────────┘

Design principles

• Convention over configuration — follows your harness's folder conventions
• Progressive disclosure — start with 3 lines, add features as you need them
• Harness-native — agents are defined in .claude/agents/*.md or .opencode/agents/*.md, not reinvented
• Zero abstraction tax — examples from harness docs work as-is inside Karta

Progressive examples

The examples/ directory walks through increasing levels of complexity:

Configuration

Karta uses your harness's native agent definitions as the source of truth. Optional Karta-specific settings go in karta.jsonc:

{
  "cli": {
    "hidden_event_types": ["system"],
    "input_required_policy": "prompt"
  },
  "harness": {
    "claude": {
      "idle_timeout_seconds": 600,
      "permission_intercept": false
    }
  }
}

See examples/configurations/ for copy-ready templates.

Supported harnesses

Adding a new harness means implementing one HarnessAdapter class.

Documentation

Design documents and implementation specs live in dev/:

• Architecture — system architecture reference
• Design document — architecture and design philosophy
• Implementation spec — detailed implementation reference
• CLI spec — CLI commands and options
• HTTP API spec — REST endpoint reference
• Gateway implementation plan — gateway system design
• Multi-tenancy architecture — workspace isolation deep dive
• Phase status — implementation progress tracking

Development

# Install dependencies
poetry install --all-extras

# Run tests
poetry run pytest

# Lint
poetry run ruff check src/ tests/

# Type check
poetry run mypy src/karta/

License

This project is licensed under the MIT License — see the LICENSE file for details.