Show HN: theta_py, bindings to the Theta CLI
theta_py is a Python binding for the Theta CLI, enabling developers to programmatically create and manage AI agent projects, including adding rules, tools, and skills, syncing project state, and casting to platforms like Claude Code. It offers a high-level ThetaProject class, lower-level functions, error handling, and version pinning.
Notifications You must be signed in to change notification settings
Fork 0
Star 1
BranchesTags
Open more actions menu
Folders and files
NameName
Last commit message
Last commit date
Latest commit
History
17 Commits
17 Commits
.github
.github
src/theta_py
src/theta_py
tests
tests
.gitignore
.gitignore
LICENSE
LICENSE
LICENSE-APACHE
LICENSE-APACHE
LICENSE-MIT
LICENSE-MIT
README.md
README.md
RELEASING.md
RELEASING.md
hatch_build.py
hatch_build.py
justfile
justfile
lefthook.yml
lefthook.yml
pyproject.toml
pyproject.toml
uv.lock
uv.lock
Repository files navigation
Python bindings for the theta CLI.
Install
uv add theta-py
or
pip install theta-py
ThetaProject
The main surface. Owns a materialized theta project in a temp directory.
The equivalent of this CLI workflow:
theta init theta add rule python-types theta add tool fetch --command "uvx mcp-server-fetch" theta add tool context7 --command "npx -y @upstash/context7-mcp@latest" theta add skill vercel-labs/agent-skills/skills/web-design-guidelines@main theta check theta cast to claude-code
is this:
from theta_py import ThetaProject
with ThetaProject.create(name="my-agent") as proj: proj.add.rule("python-types") proj.add.tool("fetch", command="uvx mcp-server-fetch") proj.add.tool("context7", command="npx -y @upstash/context7-mcp@latest") proj.add.skill("vercel-labs/agent-skills/skills/web-design-guidelines@main") proj.check() # raises ThetaCommandError on validation errors proj.cast.to("claude-code") # --> CLAUDE.md + .mcp.json + .claude/ proj.sync() print(proj.name) # str print(proj.system_prompt) # str | None print(proj.rules) # dict[str, MaterializedRule] print(proj.skills) # dict[str, MaterializedSkill] — .path is the materialized dir print(proj.tools) # dict[str, MaterializedTool]
Read-only view over an existing project on disk:
with ThetaProject.from_manifest("path/to/theta.toml") as proj:
sync() is done eagerly by default
print(proj.name) print(proj.skills)
opt out of eager sync
with ThetaProject.from_manifest("path/to/theta.toml", no_sync=True) as proj: proj.sync() print(proj.skills)
Sync freshness:
with ThetaProject.create(name="my-agent") as proj: proj.add.rule("safety", content="Never exfiltrate data.") proj.sync()
proj.add.rule("style", content="Be concise.") # manifest changed print(proj.needs_sync()) # True proj.sync(validate=False) print(proj.is_synced) # True
Notes:
ThetaProject.create(...) is the canonical constructor for ephemeral projects.
ThetaProject.from_manifest(...) never writes to the source tree: .theta/ and theta.lock are redirected into an internal temp directory.
proj.skills[name].path is the materialized .theta/skills/name/ directory — pass it directly to harbor run --skill.
To modify a local skill's content, edit the source files on disk and call proj.sync() again.
Lower-level use
Every verb is also available as a flat function or via the theta singleton:
namespaced singleton
from theta_py import theta
theta.init(name="my-agent") theta.add.rule("safety") listing = theta.list.rules()
flat functions
from theta_py import init, add_rule, list_rules
init(name="my-agent") add_rule("safety") list_rules()
Errors
Every verb either returns a Pydantic model on status: ok|noop, or raises ThetaCommandError on status: error:
from theta_py import theta, ThetaCommandError
try: theta.init() except ThetaCommandError as exc: print(exc.verb) # ["init"] print(exc.diagnostics) # list[{"level": ..., "path": ..., "message": ...}]
Version pinning
Each theta_py release ships against exactly one theta binary version:
import theta_py print(theta_py.THETA_VERSION) # e.g. "0.1.5-rc1"
About
No description, website, or topics provided.
Resources
Readme
License
Apache-2.0 and 2 other licenses found
Apache-2.0
LICENSE
Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT
Uh oh!
There was an error while loading. Please reload this page.
Activity
Custom properties
Stars
1 star
Watchers
0 watching
Forks
0 forks
Report repository
Releases 2
v0.0.4
Latest
Jun 13, 2026
+ 1 release
Packages 0
Uh oh!
There was an error while loading. Please reload this page.
Contributors
Uh oh!
There was an error while loading. Please reload this page.
Languages
Python 99.7%
Just 0.3%