[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93030":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":16,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":16,"starSnapshotCount":16,"syncStatus":13,"lastSyncTime":26,"discoverSource":27},93030,"kastor","weirdGuy\u002Fkastor","weirdGuy","Terraform-style source-of-truth layer for AI agents: HCL specs, LangGraph codegen, and plan\u002Fapply\u002Fstate for hosted agents.","https:\u002F\u002Fwww.getkastor.dev",null,"Go",51,2,1,9,0,41.43,"Apache License 2.0",false,"main",true,[],"2026-07-22 04:02:07","# Kastor\n\n**Kastor is a source-of-truth layer for AI agents.**\n\nDefine agents, tools, prompts, models, and targets in HCL. Validate the spec. Compile it to runnable framework code. Later, reconcile hosted agents with Terraform-style `plan` \u002F `apply` \u002F `state`.\n\n```sh\nkastor validate examples\u002Fweather\nkastor build examples\u002Fweather\nkastor plan examples\u002Fweather\n```\n\nAgents today are often split across framework code, prompt files, tool files, platform UI settings, and environment configuration. Kastor's idea is that agents need a versionable, reviewable, declarative contract before they become serious software.\n\nThe full design lives in [SPEC.md](SPEC.md).\n\n## Status\n\nKastor is an early proof of concept.\n\nWorking today:\n\n- parse `.agent`, `.tool`, `.prompt`, and `kastor.hcl`\n- validate references and prompt variables\n- build runnable LangGraph projects\n- run `kastor plan` \u002F `kastor apply` \u002F `kastor destroy` against the built-in in-memory platform\n- local state file, three-way diffs, and drift detection\n- examples: [weather agent](examples\u002Fweather), [content scheduler](examples\u002Fscheduler)\n\nPlanned for v0:\n\n- a second codegen target: Vercel eve\n- hosted platform providers (in design — candidates: Bedrock AgentCore, Dify)\n\nKastor is **not** an agent runtime.\n\n## Demo\n\n![Kastor building the agent from files](.\u002Fdocs\u002Fassets\u002Fdemo-1.gif)\n\n## How it works\n\n```text\n.agent + .tool + .prompt + kastor.hcl\n                │\n                ▼\n        kastor validate\n                │\n      ┌─────────┴─────────┐\n      ▼                   ▼\nkastor build        kastor plan\u002Fapply\nframework code      hosted agents\n(LangGraph)         (platform targets)\n```\n\nKastor has two paths:\n\n- `kastor build` compiles a Kastor module into runnable framework code.\n- `kastor plan` \u002F `kastor apply` reconciles long-lived hosted agents with state, diffs, and drift detection.\n\n## Example\n\nAn agent in Kastor is a small declarative spec:\n\n```hcl\nagent \"weather\" {\n  description = \"Answers weather questions for a location and date\"\n\n  model         = model.fast\n  system_prompt = prompt.weather_system\n  tools         = [tool.web_search]\n\n  input \"location\" {\n    type        = string\n    description = \"The location to get weather for\"\n  }\n\n  input \"date\" {\n    type     = string\n    optional = true\n  }\n\n  output \"weather\" {\n    type = string\n  }\n}\n```\n\nThe generated code is not the source of truth. The Kastor module is.\n\n## Quickstart: no credentials required\n\nThis path validates the example and runs `plan` \u002F `apply` against the built-in in-memory platform target. It does not create remote resources and does not require API keys.\n\n```sh\ngo build -o kastor .\u002Fcmd\u002Fkastor\n.\u002Fkastor validate examples\u002Fweather\u002F\n.\u002Fkastor plan examples\u002Fweather\u002F\n.\u002Fkastor apply examples\u002Fweather\u002F\n```\n\nExample plan output:\n\n```console\n$ kastor plan examples\u002Fweather\u002F\n  + agent.forecast (not in state)\n  + agent.geocoder (not in state)\n  + agent.weather (not in state)\n\nPlan for target.memory: 3 to create, 0 to update, 0 to delete, 0 unchanged.\n```\n\n`kastor plan` is a pure read: it never touches remote resources or the state file. Updates show attribute-level diffs, and out-of-band remote changes surface as drift warnings.\n\n## Quickstart: generate and run LangGraph\n\nThis path compiles the weather agent to a runnable LangGraph project.\n\nPrerequisites:\n\n- Go 1.26+\n- Python 3.11+\n- an OpenAI API key\n- a [Tavily](https:\u002F\u002Ftavily.com) API key, because the example's search tool runs against Tavily's hosted MCP server\n\nCompile the spec to a LangGraph project:\n\n```sh\ngo build -o kastor .\u002Fcmd\u002Fkastor\n.\u002Fkastor validate examples\u002Fweather\u002F\n.\u002Fkastor build examples\u002Fweather\u002F\n```\n\n`kastor build` writes the generated project to `examples\u002Fweather\u002Fgen\u002Flanggraph` — the target's declared `output`.\n\nGenerated output is not committed. It is reproducible from the spec, and codegen determinism is enforced by tests.\n\nSet up the generated project:\n\n```sh\ncd examples\u002Fweather\u002Fgen\u002Flanggraph\npython3 -m venv .venv\n. .venv\u002Fbin\u002Factivate\npip install -r requirements.txt\n```\n\nThe example's `web_search` tool is pinned to an MCP server and tool by its spec URI:\n\n```text\nmcp:\u002F\u002Fsearch-server\u002Ftavily_search\n```\n\nHow to reach that server is deployment configuration, not spec. Create `mcp_servers.json` in the generated project's working directory, or point the `KASTOR_MCP_CONFIG` environment variable at a file elsewhere.\n\nFor Tavily's hosted server:\n\n```json\n{\n  \"search-server\": {\n    \"transport\": \"streamable_http\",\n    \"url\": \"https:\u002F\u002Fmcp.tavily.com\u002Fmcp\u002F?tavilyApiKey=tvly-YOUR-KEY\"\n  }\n}\n```\n\nThe URL embeds your API key, which is why `mcp_servers.json` is gitignored. Treat it as a secret and never commit it.\n\nThe spec URI's last path segment, `tavily_search`, must name a tool the server actually advertises. If it does not, calls fail with `does not expose tool`.\n\nExport the model credential. The example's `model \"fast\"` block uses provider `openai`:\n\n```sh\nexport OPENAI_API_KEY=sk-...\n```\n\nRun the agent:\n\n```sh\npython3 main.py weather --inputs '{\"location\": \"Lisbon\", \"date\": \"tomorrow\"}'\n```\n\nIt prints the agent's declared output contract as JSON:\n\n```json\n{\n  \"weather\": \"...\"\n}\n```\n\nThe generated `README.md` inside `gen\u002Flanggraph` owns the run-the-project side in full: every agent's inputs and outputs, tool bindings, and MCP configuration.\n\nOne v0 caveat: `agent.weather`'s optional `forecast_context` input references `agent.forecast`'s output. That reference is validated at compile time and orders the dependency graph, but generated code does not run the upstream agent for you. If you want the context, run `forecast` yourself and pass its summary via `--inputs`.\n\n## File types\n\nA Kastor module is a directory tree containing declarative files:\n\n| File type | Purpose |\n| --- | --- |\n| `.agent` | Agent definitions: model, prompt, tools, inputs, outputs, dependencies |\n| `.tool` | Tool interface plus implementation source |\n| `.prompt` | Prompt template plus required variables |\n| `kastor.hcl` \u002F `*.kastor` | Project file: models, targets, defaults |\n\nReferences connect blocks by address, not by file path. For example, an agent references `model.fast`, `prompt.weather_system`, and `tool.web_search`.\n\nReferences also build the dependency graph. A reference like `agent.forecast.output.summary` validates that the output exists and orders the graph.\n\n## What Kastor is not\n\nKastor is not an agent runtime.\n\nFrameworks like LangGraph still execute agents. Hosted platforms like Dify still run managed agents. Kastor sits above them as the declarative source-of-truth layer: model, prompts, tools, inputs, outputs, dependencies, and targets.\n\nKastor also does not try to standardize the full behavior or control loop of an agent. That layer is still changing quickly. The narrower bet is that the outer contract around agents should be reviewable, versionable, and diffable.\n\n## Why not Terraform?\n\nTerraform is great for managing remote resources. A Terraform provider for hosted agents may make sense later.\n\nKastor starts one layer earlier: the agent spec itself.\n\nThe same Kastor module should be able to:\n\n- generate runnable framework code with `kastor build`\n- reconcile hosted platform agents with `kastor plan` \u002F `kastor apply`\n\nThat codegen path is why Kastor is a separate toolchain rather than only a Terraform module or provider.\n\n## Why not just LangGraph?\n\nLangGraph is a runtime\u002Fframework. Kastor is not trying to replace it.\n\nKastor defines the agent contract and generates a LangGraph project from that spec. The generated code is an output; the Kastor module is the source of truth.\n\n## Install\n\nHomebrew:\n\n```sh\nbrew tap weirdGuy\u002Ftap && brew install kastor\n```\n\nInstall script:\n\n```sh\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FweirdGuy\u002Fkastor\u002Fmain\u002Fscripts\u002Finstall.sh | sh\n```\n\nThe install script verifies the release checksum, installs to `\u002Fusr\u002Flocal\u002Fbin` or `~\u002F.local\u002Fbin`, and never uses `sudo`.\n\nWith Go 1.26+:\n\n```sh\ngo install github.com\u002FweirdGuy\u002Fkastor\u002Fcmd\u002Fkastor@latest\n```\n\nOr download an archive for your platform from the [releases page](https:\u002F\u002Fgithub.com\u002FweirdGuy\u002Fkastor\u002Freleases), verify it against `checksums.txt`, and put the `kastor` binary on your PATH.\n\n## Development\n\n```sh\ngo build .\u002F...   # build everything\ngo test .\u002F...    # run all tests\ngo vet .\u002F...     # static checks\ngofmt -l .       # formatting check\n```\n\nSPEC.md is the source of truth for design decisions. CLAUDE.md documents the day-to-day development conventions.\n\n## Early feedback\n\nI'm currently looking for feedback from people building agents in production or experimenting with agent tooling.\n\nUseful feedback areas:\n\n- whether the source-of-truth layer makes sense\n- where the spec is too rigid or too loose\n- what framework or hosted platform target should come next\n- what would make the first-run experience smoother\n\nTo follow or discuss the project:\n\n- star\u002Fwatch the repo for updates\n- open an issue for bugs or design feedback\n- join the early Discord: [invite](https:\u002F\u002Fdiscord.gg\u002Fbb4UwtJFe)\n","Kastor 是一个面向 AI 智能体的声明式源码层工具，借鉴 Terraform 的设计理念，通过 HCL 配置文件统一定义智能体、工具、提示词、模型及目标平台。它支持配置校验、LangGraph 代码生成，以及对托管智能体执行 plan\u002Fapply\u002Fstate 管理（含状态持久化、三路 diff 和漂移检测）。项目不提供运行时，而是作为基础设施即代码（IaC）范式在 AI 工程化中的实践：将智能体生命周期管理纳入版本可控、可评审的声明式流程。适用于需要规模化部署、持续演进和跨环境一致性的 AI 智能体开发与运维场景。","2026-07-11 02:30:42","CREATED_QUERY"]