{
  "markdown": "# Kast\n\nKast gives coding agents compiler-grounded search over one exact Kotlin\nrepository. It resolves declarations and relationships that text search can only\napproximate, while retaining the scope and limits behind each answer.\n\nDevelopers install Kast and connect it to an agent harness. Kast owns runtime\nreadiness, workspace synchronization, and intermediate semantic operations.\n\n[Install and connect Kast](https://kast.michne.com/start/) ·\n[Search with Kast](https://kast.michne.com/search/) ·\n[Integrate an agent harness](https://kast.michne.com/agent-harnesses/) ·\n[Troubleshoot Kast](https://kast.michne.com/troubleshooting/) ·\n[Explore the source-bound knowledge base](knowledge/index.md)\n\n## Existing IDEA index\n\nThe primary indexing commands in this checkout are `kast index classes <name>`\nand `kast index supertype <qualified-name>`. They provide bounded compiler-resolved\nclass discovery in an already open IDEA project. It uses that project's Kotlin\nindex and saved content through the separate hosted plugin. Missing IDE state\nreturns unavailability. Build and install the plugin following the\n[existing-IDE endpoint runbook](experiments/host-observation/HOSTED_ENDPOINT.md),\nthen use `kast index status --root /path/to/repository` and\n`kast index classes Refinement --root /path/to/repository`.\n\nIDEA owns index updates. These commands require no Kast index synchronization,\nseparate workspace, copied index storage, or Python runtime. The earlier `kast ide`\nspelling remains available through the same command implementation.\n\nThe hosted command runs before isolated-runtime bootstrap. General semantic\ncommands and App Server queries retain their existing runtime and publication\ncontracts; the hosted class answer explicitly carries its narrower provenance.\n\nRead the [detailed HTML implementation review](docs/reviews/hosted-indexing.html)\nfor the architecture, qualification evidence, and remaining migration work.\n\n## Install\n\nKast currently requires:\n\n- macOS on Apple silicon;\n- an on-disk Kotlin Gradle repository; and\n- IntelliJ IDEA build `262.10315.125` with its bundled Java 25 JBR.\n\nInstall the latest published release:\n\n```shell\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/amichne/kast/main/install.sh)\"\n```\n\nThe installer discovers the supported IntelliJ runtime, verifies the matched\nKast payloads, installs the exact-build existing-IDE plugin, and installs the\nintegration entrypoints. Restart IDEA after installation to activate the plugin. If discovery is\nambiguous, select IDEA explicitly:\n\n```shell\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/amichne/kast/main/install.sh)\" \\\n  -- --idea-home \"/Applications/IntelliJ IDEA.app\"\n```\n\nSee [Install and connect Kast](https://kast.michne.com/start/) for the complete\nhost contract and uninstall path.\n\nTo build and install the current checkout, run one of these from its root:\n\n```shell\n# Isolated installation, activated only in this Bash or Zsh session:\nsource \"$(./install.sh --local session)\"\n\n# Persistent installation into your configured KAST_* paths:\n./install.sh --local persistent\n```\n\nBoth modes build the working tree, including uncommitted changes, and verify\nthe matched control and semantic runtime archives. Session mode isolates its\nconfiguration, caches and sockets and disables persistent services. Repeated\nactivation is safe; its temporary files remain under `$KAST_SESSION_ROOT`.\n\nPersistent mode honors `KAST_INSTALL_ROOT` and `KAST_BIN_DIR`, writes a fresh\nrelease-local runtime configuration, and enables launchd indexer ownership. It\nstops the previous installed App Server before activation and enables the new\nApp Server login service for this checkout.\nThis requires the App Server's Codex prerequisites. If service enablement fails,\nthe installation remains available and the command reports failure. The\ninstallation persists for your user account across sessions; it is not an\nall-users system daemon. Run it from a shell without an active Kast session.\n\n## Connect an agent\n\nKast includes a Codex integration. Start it from the Kotlin repository the agent\nwill inspect:\n\n```console\ncd /path/to/kotlin-repository\nkast codex\n```\n\n`kast codex` now enrolls the current workspace, installs or refreshes the login\nbootstrap, recovers stale owned broker state, and starts the persistent service\nbefore launching Codex. `kast codex desktop` performs the same preparation and\nattaches to that service. Client closure leaves the service running. Use\n`kast app-server status`, `stop`, or `disable` to manage its lifecycle.\n\n`kast app-server status` reports the exact service-log and resolved launch-\nenvironment paths. Set `KAST_DEBUG=1` for bounded launch stages on the calling\nprocess's stderr. If normal ownership recovery cannot converge, the explicit\n`kast app-server repair --destructive` command deletes only the active\ninstallation's owned runtime, cache, broker, and workspace-registry state,\nre-enrolls the current workspace, and starts clean.\n\nDesktop build-specific discovery is checked, but full desktop compatibility is\nstill unqualified. See the module's [compatibility and blocker record](app-server/docs/compatibility.md)\nfor exact evidence and the outstanding real-client release gate.\n\nKast qualifies the installed tool contract before a thread starts. The default\ncatalog includes one eager `kast.query` tool plus deferred source, semantic,\nimpact, diagnostic, and change tools. Direct `symbol_lookup` and\n`symbol_inspect` routes are omitted by default; change tools retain explicit\napproval requirements.\n\nOther harnesses should consume the exact installed `serverProjection`; they\nshould not copy command names, schemas, or selection policy into another\nconfiguration. See [Integrate an agent harness](https://kast.michne.com/agent-harnesses/).\n\n## Search first\n\nThe primary read surface is `kast.query`. It can search declarations, filter\nresults, and expand semantic relationships while Kast preserves exact compiler\nidentity between stages.\n\nAgents should use specialist reads only when their narrower contract is needed.\nThey should not start the runtime, synchronize the workspace, or build topology\nas prerequisites. Each semantic request acquires the evidence it needs.\n\n## Know when something went wrong\n\nKast never turns partial or unknown state into an unqualified answer:\n\n- **Complete** means the request met its declared scope and limits.\n- **Qualified** means the returned evidence is useful only with the attached\n  limitation.\n- **Rejected** means Kast established no successful semantic payload.\n\nThe harness should keep these outcomes visible. If the integration cannot start\nor a request rejects, follow [Troubleshoot Kast](https://kast.michne.com/troubleshooting/).\nBare `kast`, run from the repository root, is a passive support command that\nreports local runtime and bootstrap state without starting or repairing it.\n\nHosted semantic reads log bounded diagnostic records to the IDE log by default.\nSee [read limits and diagnostics](docs/hosted-read-configuration.md) for the 45 tunable settings and activation instructions.\n\n## Develop Kast\n\nDevelopment requires Java 25 or newer and the Python version in\n[`.python-version`](.python-version).\n\n```shell\n./gradlew build\n./gradlew assembleSidecarRelease\n```\n\nValidate the public documentation with `mint validate` from `docs/public`.\n\n## Security and license\n\nReport vulnerabilities through [GitHub private vulnerability\nreporting](https://github.com/amichne/kast/security/advisories/new). Kast is\navailable under the [MIT License](LICENSE).\n",
  "bytes": 7579,
  "sha": "3418aa0ffef50b4f5a25abb479366f9615e883195d1a4c9ea72e4d34da436a87",
  "repo_slug": "amichne/kast",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_amichne_kast_knowledge_index_md_06013f64/readme"
}