Agent structure

An agent project is a folder an agent harness can run. The only required file is its instructions; everything else is additive and optional. Use karta create for a new folder. Use karta setup when the folder already contains an agent and you want to name it, set the deploy gate, or choose the delivery method.

karta create my-agent --harness claude-code
cd my-agent
karta dev
karta setup --enable

The smallest possible agent project

my-agent/
`-- CLAUDE.md      # agent instructions - a complete agent project

CLAUDE.md

# Beans - Karta Coffee Co. support agent

You are Beans, the support agent for Karta Coffee Co.
Help with orders, shipping, our roasts, returns, and brewing tips.
Keep replies short - 1-3 sentences unless asked for more.

Try it through Karta’s local wrapper:

from karta import Karta
print(Karta().send_sync("What roasts do you have?").text)

A fuller Claude Code agent project

my-agent/
|-- CLAUDE.md                  # shared context / instructions (required)
|-- .claude/
|   |-- agents/                # one sub-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 method/gate, build hints
`-- karta.jsonc                # Karta CLI/harness/runtime settings (optional)

Path	Owned by	Purpose
`CLAUDE.md`	harness	Shared instructions and context for every agent.
`.claude/agents/*.md`	harness	Sub-agent files, discovered automatically.
`.claude/skills/`	harness	Skills agents can invoke.
`.claude/settings.json`	harness	Tools, permissions, MCP servers - standard Claude Code config.
`karta.toml`	Karta	The agent’s name, deploy method/gate, and build hints - its local deployment identity.
`karta.jsonc`	Karta	CLI, harness, and runtime settings.

The files under .claude/ are standard Claude Code. Karta reads those definitions rather than asking you to restate them in a Karta-specific format.

Permissions and bounded authority

.claude/settings.json is where you bound what the agent can do. Its permissions.allow list is the agent’s authority: list the tools and commands the app actually needs (for example "Bash(python validate.py:*)") and keep it tight. Anything not on the list pauses the turn for approval instead of running. In a deployed session, an off-allowlist tool call surfaces as a tool-permission prompt the end user answers over the API (approve_once, approve_session, or deny) - it does not silently fail. How a deployment treats those prompts is set by runtime.permission_mode: the default prompts for approval; autonomous auto-approves for the session. Two habits keep the allowlist honest:

Prefer a deterministic entrypoint over an improvised pipeline. When a task is a fixed sequence (build, lint, package, verify), ship a checked-in script the agent runs as one allowlisted command rather than a pipeline of many commands that each need approval.
Treat the allowlist as a guardrail, not a sandbox. The matcher works on command prefixes; a compound command is checked per segment, and a construct like a heredoc can carry a body past prefix matching. Your isolation boundary is the per-instance sandbox, not the allowlist.

When you run the agent locally with karta dev, an interactive terminal lets you answer each prompt. A non-interactive run (piped input or no TTY) has no one to answer, so an off-allowlist tool is denied and the turn stalls. Allow the tools the app needs in .claude/settings.json up front, run karta dev interactively, or set runtime.permission_mode for unattended runs.

The OpenCode equivalent

my-agent/
|-- AGENTS.md                  # shared context
|-- .opencode/
|   |-- agents/*.md            # sub-agents
|   |-- skills/<name>/SKILL.md # skills
|   `-- opencode.jsonc         # harness config, including default_agent
|-- karta.toml
`-- karta.jsonc

DeepAgents, Goose, and Codex CLI equivalents

DeepAgents

my-agent/
|-- AGENTS.md                  # shared context
|-- .deepagents/
|   |-- agents/                # sub-agents, one .md each
|   `-- karta.jsonc            # Karta's native marker/config bridge
|-- karta.toml
`-- karta.jsonc

Goose

my-agent/
|-- AGENTS.md                  # shared context
|-- .goose/
|   |-- agents/                # sub-agents, one .md each
|   `-- karta.jsonc            # Karta's native marker/config bridge
|-- karta.toml
`-- karta.jsonc

Codex CLI

my-agent/
|-- AGENTS.md                  # shared context
|-- .codex/
|   |-- agents/                # optional Karta-discovered roles
|   `-- config.toml            # Codex project config / Karta marker
|-- karta.toml
`-- karta.jsonc

Karta detects the harness from the layout: .claude/ or CLAUDE.md means Claude Code, .opencode/ means OpenCode, .deepagents/ means DeepAgents, .goose/ means Goose, and .codex/config.toml means Codex CLI. karta create --harness deepagents, karta create --harness goose, and karta create --harness codex-cli write the AGENTS.md and marker files for you.

Multiple agents in one repo

One repo can hold several agents - each a folder with its own harness-native instruction file 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
`-- research-bot/
    |-- AGENTS.md
    |-- .deepagents/
    `-- karta.toml            # name = "research-bot", deploy = true

Each agent’s karta.toml carries its own name, deploy gate, and deploy_method. Deploy them independently from their folders; selecting one never builds its siblings. See karta.toml and the deploy loop. karta setup scans for folders with karta.toml, CLAUDE.md, .claude/, .opencode/, .deepagents/, .goose/, or .codex/ markers. If a repo contains several agent folders, pass the folder explicitly:

karta setup ./support-bot --enable --method git
karta setup ./billing-bot --enable --method folder
karta deploy --dir ./support-bot

Exercise the Karta surface locally

Author and test the agent in the harness workflow you already use. When you want to see how it behaves through Karta’s session API, karta dev runs the project locally with a chat REPL and hot reload:

cd my-agent && karta dev

See the CLI overview for the full CLI.

Sub-agent files

The frontmatter format for harness sub-agents.

karta.toml

Build hints for publishing a release.

Get started

Concepts

Agent project

The CLI

Deploy

Platform

Security

Enterprise

Tutorials

Agent structure

The smallest possible agent project

A fuller Claude Code agent project

Permissions and bounded authority

The OpenCode equivalent

DeepAgents, Goose, and Codex CLI equivalents

Multiple agents in one repo

Exercise the Karta surface locally

Sub-agent files

karta.toml

​The smallest possible agent project

​A fuller Claude Code agent project

​Permissions and bounded authority

​The OpenCode equivalent

​DeepAgents, Goose, and Codex CLI equivalents

​Multiple agents in one repo

​Exercise the Karta surface locally

Sub-agent files

karta.toml

The smallest possible agent project

A fuller Claude Code agent project

Permissions and bounded authority

The OpenCode equivalent

DeepAgents, Goose, and Codex CLI equivalents

Multiple agents in one repo

Exercise the Karta surface locally