Skip to main content
An agent is a folder. The only required file is its instructions; everything else is additive and optional.

​
The smallest possible app

my-app/
└── CLAUDE.md      # agent instructions - that's a complete app
CLAUDE.md
# Beans - Karta Coffee Co. support assistant

You are Beans, the friendly support assistant for Karta Coffee Co.
Help with orders, shipping, our roasts, returns, and brewing tips.
Keep replies short - 1-3 sentences unless asked for more.
Run it: 
from karta import Karta
print(Karta().send_sync("What roasts do you have?").text)

​
A fuller Claude Code app

my-app/
├── CLAUDE.md                  # shared context / instructions (required)
├── .claude/
│   ├── agents/                # one specialist agent per .md file
│   │   ├── billing.md
│   │   └── shipping.md
│   ├── skills/                # reusable capabilities
│   │   └── order-lookup/
│   │       └── SKILL.md
│   └── settings.json          # harness settings: tools, permissions, MCP
├── karta.toml                # agent name, deploy gate, build hints
└── karta.jsonc               # Karta CLI/harness/runtime settings (optional)
PathOwned byPurpose
CLAUDE.mdharnessShared instructions and context for every agent.
.claude/agents/*.mdharnessSpecialist agents, discovered automatically.
.claude/skills/harnessSkills agents can invoke.
.claude/settings.jsonharnessTools, permissions, MCP servers - standard Claude Code config.
karta.tomlKartaThe agent’s name, deploy gate, and build hints - its local identity.
karta.jsoncKartaCLI, harness, and runtime settings.
The files under .claude/ are standard Claude Code - nothing Karta-specific. That’s the design: examples from the harness’s own docs work unchanged, and Karta reads your definitions rather than asking you to restate them.

​
The OpenCode equivalent

my-app/
├── AGENTS.md                  # shared context
├── .opencode/
│   ├── agents/*.md            # specialist agents
│   ├── skills/<name>/SKILL.md # skills
│   └── opencode.jsonc         # harness config (incl. default_agent)
├── karta.toml
└── karta.jsonc
Karta detects the harness from the layout - .claude//CLAUDE.md → Claude Code, .opencode/ → OpenCode.

​
Multiple agents in one repo

One repo can hold several agents - each a folder with its own CLAUDE.md and its own karta.toml: 
my-agents/
├── support-bot/
│   ├── CLAUDE.md
│   └── karta.toml            # name = "support-bot", deploy = true
└── billing-bot/
    ├── CLAUDE.md
    └── karta.toml            # name = "billing-bot", deploy = true
Each agent’s karta.toml carries its own name and deploy = true. One karta deploy (or git push karta) builds every enabled agent in the tree, each from its own subdirectory. See karta.toml and the deploy loop.

​
Run it locally

karta dev runs the folder behind the consumer session API, with a chat REPL and hot reload: 
cd my-app && karta dev
See the CLI overview for the full CLI.

Define agents

The frontmatter format for specialist agents.

karta.toml

Build hints for publishing a release.