2026-05-27站内改写

theta: a humble approach to harness agnostic configuration

theta is a Rust CLI that manages agent configurations by reading a theta.toml file, resolving, locking, materializing, and casting them to any supported harness (e.g., Claude Code, Codex CLI, GitHub Copilot, Cursor). It works like a package manager for agent harness resources. Installation is straightforward, and it supports adding rules, tools, skills, and subagents, with validation and casting commands. The project is heavily inspired by uv and is the canonical implementation of the theta-spec.

Article intelligence

EngineersIntermediate

Key points

theta is a Rust CLI for managing agent configurations
Supports multiple harnesses: Claude Code, Codex CLI, GitHub Copilot, Cursor, and more
Provides commands like init, add, check, cast, acting like a package manager
Canonical implementation of the theta-spec, inspired by uv

Why it matters

This matters because theta is a Rust CLI for managing agent configurations.

Technical impact

May affect model selection, inference cost, product capability, and evaluation benchmarks.

Notifications You must be signed in to change notification settings

Fork 0

Star 4

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

11 Commits

.github/workflows

assets

crates

docs

scripts

test

.gitattributes

.gitignore

Cargo.lock

Cargo.toml

README.md

STYLE.md

_typos.toml

deny.toml

justfile

lefthook.yml

mkdocs.yml

pyproject.toml

uv.lock

Repository files navigation

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:

just gen-cli-docs

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 [email protected]: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