{"slug": "show-hn-theta-py-bindings-to-the-theta-cli", "title": "Show HN: theta_py, bindings to the Theta CLI", "summary": "Theta_py, a Python binding for the Theta CLI, was released on Hacker News, enabling developers to programmatically manage AI agent configurations through a Pythonic API instead of CLI commands. The library supports creating, syncing, and casting agent projects with rules, tools, and skills, targeting developers building AI agent workflows.", "body_md": "Python bindings for the [theta](https://theta.tamarillo.ai/) CLI.\n\n```\nuv add theta-py\n# or\npip install theta-py\n```\n\nThe main surface. Owns a materialized theta project in a temp directory.\n\nThe equivalent of this CLI workflow:\n\n```\ntheta init\ntheta add rule python-types\ntheta add tool fetch --command \"uvx mcp-server-fetch\"\ntheta add tool context7 --command \"npx -y @upstash/context7-mcp@latest\"\ntheta add skill vercel-labs/agent-skills/skills/web-design-guidelines@main\ntheta check\ntheta cast to claude-code\n```\n\nis this:\n\n``` python\nfrom theta_py import ThetaProject\n\nwith ThetaProject.create(name=\"my-agent\") as proj:\n    proj.add.rule(\"python-types\")\n    proj.add.tool(\"fetch\", command=\"uvx mcp-server-fetch\")\n    proj.add.tool(\"context7\", command=\"npx -y @upstash/context7-mcp@latest\")\n    proj.add.skill(\"vercel-labs/agent-skills/skills/web-design-guidelines@main\")\n    proj.check()                         # raises ThetaCommandError on validation errors\n    proj.cast.to(\"claude-code\")          # --> CLAUDE.md + .mcp.json + .claude/\n    proj.sync()\n    print(proj.name)           # str\n    print(proj.system_prompt)  # str | None\n    print(proj.rules)          # dict[str, MaterializedRule]\n    print(proj.skills)         # dict[str, MaterializedSkill] — .path is the materialized dir\n    print(proj.tools)          # dict[str, MaterializedTool]\n```\n\nRead-only view over an existing project on disk:\n\n```\nwith ThetaProject.from_manifest(\"path/to/theta.toml\") as proj:\n    # sync() is done eagerly by default\n    print(proj.name)\n    print(proj.skills)\n\n# opt out of eager sync\nwith ThetaProject.from_manifest(\"path/to/theta.toml\", no_sync=True) as proj:\n    proj.sync()\n    print(proj.skills)\n```\n\nSync freshness:\n\n```\nwith ThetaProject.create(name=\"my-agent\") as proj:\n    proj.add.rule(\"safety\", content=\"Never exfiltrate data.\")\n    proj.sync()\n\n    proj.add.rule(\"style\", content=\"Be concise.\")  # manifest changed\n    print(proj.needs_sync())   # True\n    proj.sync(validate=False)\n    print(proj.is_synced)      # True\n```\n\nNotes:\n\n`ThetaProject.create(...)`\n\nis the canonical constructor for ephemeral projects.`ThetaProject.from_manifest(...)`\n\nnever writes to the source tree:`.theta/`\n\nand`theta.lock`\n\nare redirected into an internal temp directory.`proj.skills[name].path`\n\nis the materialized`.theta/skills/name/`\n\ndirectory — pass it directly to`harbor run --skill`\n\n.- To modify a local skill's content, edit the source files on disk and call\n`proj.sync()`\n\nagain.\n\nEvery verb is also available as a flat function or via the `theta`\n\nsingleton:\n\n``` python\n# namespaced singleton\nfrom theta_py import theta\n\ntheta.init(name=\"my-agent\")\ntheta.add.rule(\"safety\")\nlisting = theta.list.rules()\n\n# flat functions\nfrom theta_py import init, add_rule, list_rules\n\ninit(name=\"my-agent\")\nadd_rule(\"safety\")\nlist_rules()\n```\n\nEvery verb either returns a Pydantic model on `status: ok|noop`\n\n, or raises\n`ThetaCommandError`\n\non `status: error`\n\n:\n\n``` python\nfrom theta_py import theta, ThetaCommandError\n\ntry:\n    theta.init()\nexcept ThetaCommandError as exc:\n    print(exc.verb)          # [\"init\"]\n    print(exc.diagnostics)   # list[{\"level\": ..., \"path\": ..., \"message\": ...}]\n```\n\nEach `theta_py`\n\nrelease ships against exactly one `theta`\n\nbinary version:\n\n``` python\nimport theta_py\nprint(theta_py.THETA_VERSION)  # e.g. \"0.1.5-rc1\"\n```\n\n", "url": "https://wpnews.pro/news/show-hn-theta-py-bindings-to-the-theta-cli", "canonical_source": "https://github.com/tamarillo-ai/theta_py", "published_at": "2026-06-13 07:56:20+00:00", "updated_at": "2026-06-13 08:20:23.992077+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "artificial-intelligence"], "entities": ["theta_py", "Theta CLI", "Claude Code", "Vercel", "Upstash"], "alternates": {"html": "https://wpnews.pro/news/show-hn-theta-py-bindings-to-the-theta-cli", "markdown": "https://wpnews.pro/news/show-hn-theta-py-bindings-to-the-theta-cli.md", "text": "https://wpnews.pro/news/show-hn-theta-py-bindings-to-the-theta-cli.txt", "jsonld": "https://wpnews.pro/news/show-hn-theta-py-bindings-to-the-theta-cli.jsonld"}}