Rust CLI for managing agent configurations defined by theta-spec.
curl -sfL https://raw.githubusercontent.com/tamarillo-ai/theta/main/scripts/install.sh | bash
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/
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.
Natively supported harnesses include:
- Claude Code
- Codex CLI
- GitHub Copilot
- Cursor
cd /path/to/your/project
theta cast from claude-code
| 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 |
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 startedConcepts— manifest, sources, locking, casting, system storeCLI reference— every verb, every flagSettings— environment variables, directory overrides
Or alternatively build the docs locally:
uv run mkdocs serve --livereload
Regenerate CLI reference from clap definitions:
just gen-cli-docs
Ruststable toolchain (seerust-version
inCargo.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
.
git clone git@github.com:tamarillo-ai/theta.git
cd theta
just setup # installs dev tools, hooks, fetches deps
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
- See
STYLE.mdfor documentation style
clippy::pedantic
is enabled workspace-wide — check[workspace.lints.clippy]
inCargo.toml
for allowed lints
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.
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 byuv-settings
(cited in source)Git fetch and cache— 3-tier layout (db/checkouts/locks), system git CLI, url digest keying — derived fromuv-git
Lock file design— deterministic manifest hash, content hashing withsha256:
prefix, staleness detection, and others— same approach as uv'stoml_edit
for formatting preservationpyproject_mut
Materialization lifecycle—.theta/
mirrors uv's.venv/
: lock --> materialize --> verify consistency --> cleanup orphansOutput stack—owo-colors
+anstream
+fs-err
+indicatif
theta-spec— the standardAgent Skills spec— skill packaging formatMCP— tool protocoluv— architectural reference