> ## Documentation Index > Fetch the complete documentation index at: https://docs.karta.sh/llms.txt > Use this file to discover all available pages before exploring further. # Agent structure > Lay out an agent file by file - the one required file, plus optional sub-agents, skills, and Karta config. 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. ```bash theme={null} karta create my-agent --harness claude-code cd my-agent karta dev karta setup --enable ``` ## The smallest possible agent project ```text theme={null} my-agent/ `-- CLAUDE.md # agent instructions - a complete agent project ``` ```markdown CLAUDE.md theme={null} # 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: ```python theme={null} from karta import Karta print(Karta().send_sync("What roasts do you have?").text) ``` ## A fuller Claude Code agent project ```text theme={null} 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](/build/defining-agents), discovered automatically. | | `.claude/skills/` | harness | [Skills](/build/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](/build/karta-toml) - its local deployment identity. | | `karta.jsonc` | Karta | [CLI, harness, and runtime settings](/build/configuration). | 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`](/build/configuration): 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 ```text theme={null} my-agent/ |-- AGENTS.md # shared context |-- .opencode/ | |-- agents/*.md # sub-agents | |-- skills//SKILL.md # skills | `-- opencode.jsonc # harness config, including default_agent |-- karta.toml `-- karta.jsonc ``` ## DeepAgents, Goose, and Codex CLI equivalents ```text DeepAgents theme={null} 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 ``` ```text Goose theme={null} 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 ``` ```text Codex CLI theme={null} 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](/concepts/harness-applications#harness-detection) 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`: ```text theme={null} 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](/build/karta-toml) and [the deploy loop](/deploy/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: ```bash theme={null} 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: ```bash theme={null} cd my-agent && karta dev ``` See the [CLI overview](/cli/overview) for the full CLI. The frontmatter format for harness sub-agents. Build hints for publishing a release.