Skip to main content

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.

karta.jsonc is an optional file that tunes Karta’s behavior without touching your agent definitions. It’s JSONC (JSON with comments and trailing commas). Every key is optional, and the file defaults to ./karta.jsonc (override with karta dev --config).

​
Full example

karta.jsonc
{
  // How the CLI renders and gates a turn
  "cli": {
    "hidden_event_types": ["system", "step_start"],
    "input_required_policy": "prompt",
    "input_required_hidden_policy": "deny"
  },

  // Harness-specific settings
  "harness": {
    "claude": {
      "idle_timeout_seconds": 600,
      "thinking_budget_tokens": 10000,
      "permission_intercept": false,
      "agent_command": false
    }
  },

  // Deployment runtime behavior
  "runtime": {
    "permission_mode": "interactive"
  },

  // CLI user profile
  "profile": {
    "name": "alice",
    "display_name": "Alice Chen"
  }
}

​
cli

​
cli.hidden_event_types
string[]
Event types the CLI should not render — e.g. ["system", "step_start"]. Useful to quiet noisy harness internals.
​
cli.input_required_policy
string
default:"prompt"
How the CLI handles input_required approval prompts: prompt, deny, approve_once, approve_session, or error.
​
cli.input_required_hidden_policy
string
default:"deny"
The auto-decision applied to approval prompts that are hidden (so the user isn’t asked for events they can’t see).

​
harness.claude

​
harness.claude.idle_timeout_seconds
integer
default:"600"
How long the Claude SDK subprocess may stay idle before it’s shut down.
​
harness.claude.thinking_budget_tokens
integer
Optional extended-thinking budget for turns that request reasoning.
​
harness.claude.permission_intercept
boolean
default:"false"
Whether Karta intercepts the harness’s approval prompts (vs. letting the harness handle them).
​
harness.claude.agent_command
boolean
default:"false"
Enables the agent command surface.

​
runtime

​
runtime.permission_mode
string
default:"interactive"
How a deployed app treats approvals. interactive prompts (maps to the prompt policy); autonomous auto-approves for the session (maps to approve_session). Set this for unattended/headless deployments.

​
profile

​
profile.name
string
The default human participant name for CLI sessions.
​
profile.display_name
string
A friendly display name for that participant. Falls back to your OS user if unset.
karta.jsonc governs run-time behavior; karta.toml governs publish/build. OpenCode’s own harness config lives separately in .opencode/opencode.jsonc.