Show HN: theta-spec - a humble harness agnostic configuration spec
theta-spec is a declarative, harness-agnostic configuration standard for AI coding agents. A single theta.toml file defines the full configuration surface (instructions, rules, tools, skills, subagents). A protocol is specified for the lifecycle of this configuration file, and any theta-spec compliant implementation can resolve, lock, and cast it to any supported harness. The project includes a reference Rust CLI (theta) and supports harnesses like Claude Code, Codex CLI, Cursor, and GitHub Copilot.
Article intelligence
Key points
- Declarative, harness-agnostic config standard for AI agents.
- Supports Claude Code, Codex CLI, Cursor 3+, GitHub Copilot.
- Rust reference implementation (theta CLI) for resolution, locking, and casting.
- Aims to simplify config management and enable reproducible agent setups.
Why it matters
This matters because declarative, harness-agnostic config standard for AI agents.
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
1 Commit
1 Commit
assets
assets
docs
docs
schemas/2026-04
schemas/2026-04
.gitignore
.gitignore
CONTRIBUTING.md
CONTRIBUTING.md
README.md
README.md
STYLE.md
STYLE.md
harnesses.toml
harnesses.toml
mkdocs.yml
mkdocs.yml
pyproject.toml
pyproject.toml
uv.lock
uv.lock
Repository files navigation
theta-spec is a declarative, harness-agnostic configuration standard for AI coding agents. One theta.toml file defines the full configuration surface, i.e. instructions, rules, tools, skills, subagents. A protocol is specified for the lifecycle of this configuration file, and any theta-spec compliant implementation can resolve, lock, and cast it to any supported harness.
theta is the default implementation of this spec — a Rust CLI that resolves, locks, and casts theta.toml to any supported harness.
Docs
All the documentation for the specification is present here and can also be built and served locally by running
uv run mkdocs serve --livereload
Motivation
Agent harnesses are here to stay. Each one ships its own configuration format but still all of them share similarities. Maintaining and declaring configurations is a burden. There is no standard way to share, version, or reproduce an agent configuration.
Parametrizing the configuration surface into a single manifest:
Displays the exhaustive configuration at a glance
Provides an entrypoint for searching the resources that define an agent
Enables reproducible configurations between people and between agents
Makes mutation strategies explicit and diffable
Facilitates maintenance across harness updates
Enables a project lifecycle tool, which is why the theta CLI exists
A parametrized function and a well-defined cost function enables function approximation. If the goal is to optimize the way we work with agents, this is the first tiny step towards building the tooling needed to cover at least one gap, the parameters.
Understanding the spec: theta.toml
Most of the spec is read-self-explanatory for anyone familiar with agent harnesses. A detailed and exhaustive description of each one of the defining fields can be found condensed here and also in the manifest section of this doc.
This is how a theta.toml looks:
[theta] schema = "2026-04"
[agent] name = "harness-researcher" description = "researches agent harness configurations across public repos" version = "0.1.0" authors = ["ivan "] model = "claude-sonnet-4-20250514"
[instructions] system = "instructions/system.md"
[instructions.rules.concise] src = "instructions/rules/concise.md" apply = "always"
[instructions.rules.rust] src = "instructions/rules/rust.md" apply = "glob" apply_to = ["*.rs"]
[tools.context7] command = ["npx", "-y", "@upstash/context7-mcp@latest"]
[tools.playwright] command = ["npx", "@anthropic-ai/playwright-mcp"]
[tools.memory] command = ["npx", "-y", "@modelcontextprotocol/server-memory"]
[skills.osint] source = { path = "skills/osint" }
[[subagents]] name = "scraper" description = "scrapes github repos for harness config patterns" prompt_path = "subagents/scraper.md" model = "claude-sonnet-4-20250514" tools = ["playwright"]
[[subagents]] name = "analyst" ref = "agents/analyst/theta.toml"
Supported harnesses
The following harnesses are supported. Prioritization is based on adoption research.
Claude Code
Codex CLI
Cursor (3+)
GitHub Copilot
Related docs
theta — Rust CLI (reference implementation)
MCP — tool protocol standard
Agent Skills spec — skill packaging standard
A declarative, harness-agnostic agent configuration standard.
Contributing
See CONTRIBUTING.md for how to propose spec changes, request new harnesses, and the TEP process.
Style
Check STYLE.md for documentation conventions.
About
harness agnostic configuration standard
Resources
Readme
Contributing
Contributing
Uh oh!
There was an error while loading. Please reload this page.
Activity
Custom properties
Stars
4 stars
Watchers
0 watching
Forks
0 forks
Report repository
Releases
No releases published
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.