GitHub - tamarillo-ai/theta: canonical implementation of the theta-spec

Rust CLI for managing agent configurations defined by theta-spec.

Installation

curl -sfL https://raw.githubusercontent.com/tamarillo-ai/theta/main/scripts/install.sh | bash

Quick start

theta init                                     # scaffold theta.toml
theta add rule python-types                    # add a rule
theta add tool fetch --command "uvx mcp-server-fetch"                       # MCP tool (stdio)
theta add tool context7 --command "npx -y @upstash/context7-mcp@latest"    # another MCP tool
theta add skill vercel-labs/agent-skills/skills/web-design-guidelines@main  # skill from GitHub
theta check                                    # validate everything
theta cast to claude-code                      # --> CLAUDE.md + .mcp.json + .claude/

What it does

theta reads theta.toml and resolves, locks, materializes, and casts agent configurations to any supported harness by solving resources in a common .theta/ folder. Like a package manager but for agent harness resources.

Create from harnesses

Natively supported harnesses include:

Claude Code
Codex CLI
GitHub Copilot
Cursor

cd /path/to/your/project
theta cast from claude-code

Commands

Group	Commands
Lifecycle	`init`, `check`, `lock`, `sync`, `cast to`, `cast from`, `tree`
Dependencies	`add rule/system/tool/skill/subagent`, `rm rule/system/tool/skill/subagent`
Inspection	`describe`, `list rules/tools/skills/subagents`
System store	`register skill/rule/agent`, `list store`, `rm store`, `init --from`

Documentation

Full docs: theta, and it is more than recommended to read theta-spec first, given that this is the standard that theta implements against.

Getting started
Concepts — manifest, sources, locking, casting, system store
CLI reference — every verb, every flag
Settings — environment variables, directory overrides

Or alternatively build the docs locally:

uv run mkdocs serve --livereload

Regenerate CLI reference from clap definitions:

Contributing

Prerequisites

Rust stable toolchain (see rust-version in Cargo.toml for MSRV)
just — task runner (cargo install just)
lefthook — git hooks (installation guide)

All other dev tools (nextest, deny, shear, typos) are installed via just install-tools.

Setup

git clone git@github.com:tamarillo-ai/theta.git
cd theta
just setup   # installs dev tools, hooks, fetches deps

Common tasks

just --list         # see all available recipes
just test           # local tests (no network)
just test-online    # tests including live registries
just check          # run all CI checks locally
just gen-cli-docs   # regenerate docs/reference/cli.md
just fmt            # format all code

Conventions

See STYLE.md for documentation style
clippy::pedantic is enabled workspace-wide — check [workspace.lints.clippy] in Cargo.toml for allowed lints

Hypertextuality with `theta-spec`

theta is the canonical implementation of theta-spec. Behavioral changes in theta SHOULD be accompanied by a respective change in theta-spec. Hotfixes, refactors, and non-protocol changes MAY be pushed without a change in theta-spec. Version-modification-triggering changes MUST follow from a TEP.

Acknowledgments

theta's architecture is heavily inspired by uv by astral. Direct signals of devotion, admiration, and almost plagiarism include:

Settings cascade — CLI flag > env var > default, inspired by uv-settings (cited in source)
Git fetch and cache — 3-tier layout (db/checkouts/locks), system git CLI, url digest keying — derived from uv-git
Lock file design — deterministic manifest hash, content hashing with sha256: prefix, staleness detection, and others
toml_edit for formatting preservation — same approach as uv's pyproject_mut
Materialization lifecycle — .theta/ mirrors uv's .venv/: lock --> materialize --> verify consistency --> cleanup orphans
Output stack — owo-colors + anstream + fs-err + indicatif