). Mirrors\n \u003chttps://opencode.ai/docs/tools/\u003e and\n \u003chttps://opencode.ai/docs/custom-tools/\u003e.\n\u003c/reference\u003e\n\n\u003creference path=\".kortix/opencode/skills/kortix-system/references/opencode/plugins.md\"\u003e\n Plugin hooks (`tool.execute.before`, `session.idle`, `shell.env`,\n `experimental.session.compacting`, etc.), npm vs local loading,\n TypeScript types, examples (notifications, .env protection, custom\n tools, compaction). Mirrored from \u003chttps://opencode.ai/docs/plugins/\u003e.\n\u003c/reference\u003e\n\n\u003creference path=\".kortix/opencode/skills/kortix-system/references/opencode/mcp-servers.md\"\u003e\n Local + remote MCP servers, OAuth handling, the `mcp` config key,\n glob-based tool gating, per-agent enablement, common examples\n (Sentry, Context7, Grep). Mirrored from\n \u003chttps://opencode.ai/docs/mcp-servers/\u003e.\n\u003c/reference\u003e\n\n\u003creference path=\".kortix/opencode/skills/kortix-system/references/opencode/permissions.md\"\u003e\n The `permission` config — global `*`, per-tool, pattern-based bash\n rules, `external_directory`, defaults (including `.env` deny),\n per-agent overrides, what \"ask\" actually does. Mirrored from\n \u003chttps://opencode.ai/docs/permissions/\u003e.\n\u003c/reference\u003e\n\n\u003creference path=\".kortix/opencode/skills/kortix-system/references/opencode/rules.md\"\u003e\n `AGENTS.md` — the project-wide instructions file OpenCode auto-loads.\n Project vs global, Claude Code (`CLAUDE.md`) compatibility, precedence\n rules, the `instructions` config key for referencing external files.\n Mirrored from \u003chttps://opencode.ai/docs/rules/\u003e.\n\u003c/reference\u003e\n\n\u003creference path=\".kortix/opencode/skills/kortix-system/references/opencode/models.md\"\u003e\n Model selection (`/models`), recommended models, default config,\n per-provider options, custom variants, model loading priority order.\n Mirrored from \u003chttps://opencode.ai/docs/models/\u003e.\n\u003c/reference\u003e\n\n\u003c/references\u003e\n\n\u003cgotchas\u003e\nThings that surprise people:\n\n- **The workspace IS global — sessions are not.** A Kortix project is\n one big GitHub repo everyone shares. Persistent changes happen by\n committing to the session branch and **opening a change request**\n that merges back to `main`. Every session — even thousands running\n concurrently — gets its own isolated sandbox + ephemeral branch.\n Branches can `git pull` from `main` to pick up the latest. Merging\n back to `main` is how anything becomes persistent, and the *only*\n sanctioned path is `kortix cr open` → user review → merge.\n- **Merging to `main` is a CR — there is no other path.** Direct\n pushes to `main` from inside the sandbox skip the user-review\n contract and surprise the user. If an agent has changes worth\n keeping, the next move is *always* `kortix cr open`, never a force\n push, never asking the user to copy files out. See the\n `\u003cchange-requests\u003e` section above.\n- **Triggers live in `kortix.toml`, not as files.** Old Kortix shipped\n triggers under `.opencode/triggers/\u003cslug\u003e.md` — that's gone.\n Centralized in the manifest now, parsed as `[[triggers]]`.\n- **Kortix-owned files live in `.kortix/` at the repo root.** The\n `Dockerfile` and `opencode/` config dir sit under there to keep the\n root clean. Both paths are declared in `kortix.toml`\n (`[sandbox] dockerfile`, `[opencode] config_dir`) — relocate freely.\n- **OpenCode primitives are never platform-special.** The platform\n doesn't read them; OpenCode does. Adding a new agent/skill/command/\n tool/plugin is purely an OpenCode config change.\n- **Manifest schema is versioned.** `kortix_version` lets the platform\n evolve safely. A manifest declaring a higher version than the platform\n knows about is rejected outright — better than silent misread.\n- **`[env].required` is advisory, not enforced.** The platform surfaces\n `required` to the dashboard so the user knows what to set, but session\n bootstrap won't block on missing values today. Treat `required` as a\n contract with the user, not the platform.\n- **`[[apps]]` is experimental.** Gated behind\n `KORTIX_APPS_EXPERIMENTAL`. When off, entries are parsed but never\n acted on.\n\u003c/gotchas\u003e\n\n\u003c/skill\u003e\n","repo_fullName":"kortix-ai/suna","repo_stars":19808,"repo_language":"TypeScript","repo_license":"NOASSERTION","repo_pushedAt":"2026-06-02T03:15:35Z","owner_login":"kortix-ai","owner_type":"Organization","owner_name":"Kortix","owner_avatarUrl":"https://avatars.githubusercontent.com/u/170767358?v=4"}};