{"id":50758603,"url":"https://github.com/t3x-dev/t3x-core","last_synced_at":"2026-06-11T08:00:29.869Z","repository":{"id":363948907,"uuid":"1105938908","full_name":"t3x-dev/t3x-core","owner":"t3x-dev","description":"Version control for structured state.","archived":false,"fork":false,"pushed_at":"2026-06-11T03:41:05.000Z","size":94157,"stargazers_count":4,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T04:11:37.601Z","etag":null,"topics":["ai","structured-data","version-control","yaml","yops"],"latest_commit_sha":null,"homepage":"https://t3x.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/t3x-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-28T11:30:16.000Z","updated_at":"2026-06-11T03:25:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/t3x-dev/t3x-core","commit_stats":null,"previous_names":["t3x-dev/t3x-core"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/t3x-dev/t3x-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t3x-dev%2Ft3x-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t3x-dev%2Ft3x-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t3x-dev%2Ft3x-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t3x-dev%2Ft3x-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/t3x-dev","download_url":"https://codeload.github.com/t3x-dev/t3x-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t3x-dev%2Ft3x-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34188272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","structured-data","version-control","yaml","yops"],"created_at":"2026-06-11T08:00:22.217Z","updated_at":"2026-06-11T08:00:29.863Z","avatar_url":"https://github.com/t3x-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/t3x-logo.svg\" alt=\"T3X\" width=\"80\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eT3X\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eVersion control for structured state.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://t3x-docs.vercel.app\"\u003eDocs\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://t3x.dev\"\u003eWebsite\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://discord.gg/t3x\"\u003eCommunity\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache--2.0-blue\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/alpha-v0.5.0%20public-green\" alt=\"public alpha v0.5.0\" /\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/concept.svg\" alt=\"How T3X works\" width=\"760\" /\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\nStructured YAML is easy to change and hard to govern. Decisions, requirements,\ninfrastructure, and plans drift across chats, docs, specs, and prompt runs.\n\nT3X records schema-backed YAML changes as deterministic YOps patches, then\nversions the result with commits, diffs, merges, provenance, and generated\noutputs.\n\n\u003cbr/\u003e\n\n## Quickstart\n\n### Develop from source\n\nUse this path if you want to inspect and change the repository itself.\n\n```bash\ngit clone https://github.com/t3x-dev/t3x-core.git \u0026\u0026 cd t3x-core\npnpm install\npnpm dev:api     # API at localhost:8000\npnpm dev:webui   # WebUI preview at localhost:3000\n```\n\nRequires Node.js 20+ and pnpm 10+.\n\nSource development opens straight into the app by default; set\n`AUTH_DISABLED=false` before starting both processes if you want to exercise\nthe login flow.\n\n### Try the local package\n\nUse this path to run the packaged local T3X experience:\n\n```bash\nnpx -p @t3x-dev/local t3x-local start\n```\n\nUse this for the packaged local T3X experience, including the preview WebUI.\nPackage and runtime release assets are public alpha artifacts; see\n[Availability](#availability).\n\n### Use YOps as a library\n\nUse this path when you want the deterministic YAML operation engine inside your\nown app:\n\n```bash\nnpm install @t3x-dev/yops\n```\n\nThe package is part of the public alpha npm release surface.\n\n### Validate the self-hosted stack \u003csup\u003eevaluation\u003c/sup\u003e\n\n```bash\ncp .env.example .env\ndocker compose up -d --build\n```\n\n\u003e **WebUI** \u0026rarr; [localhost:3000](http://localhost:3000) \u0026nbsp;|\u0026nbsp; **API** \u0026rarr; [localhost:8000](http://localhost:8000)\n\nDocker Compose starts WebUI, API, and Postgres for self-hosted evaluation.\nReview the [deployment guide](docs/deployment.md) before exposing it beyond\nlocalhost. Docker and self-hosted runs keep auth on by default, so the first\nWebUI visit goes through the built-in username/password login at `/login`.\n\n\u003cbr/\u003e\n\n## WebUI preview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://t3x-docs.vercel.app/img/screenshots/chat-light.png\" alt=\"T3X WebUI chat preview\" width=\"760\" /\u003e\n\u003c/p\u003e\n\nThe `/chat` view shows the `Source -\u003e YOps -\u003e Commit` workflow before the\nfirst extraction run. Screenshot assets live in the docs site so the core\nrepository does not need to carry generated image files.\n\nWhen the source-dev WebUI is running, open the\n[intro demo preview](http://localhost:3000/chat?introDemo=1) to load the guided\nintro demo. The `introDemo` flag is development-only.\n\n\u003cbr/\u003e\n\n## How it works\n\nT3X follows a `Source -\u003e YOps -\u003e Commit` loop. Source evidence proposes a\nstructured change; YOps applies that change to YAML state; commits preserve the\nresult with parents, operation logs, and provenance.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\" align=\"center\"\u003e\u003cstrong\u003eSource\u003c/strong\u003e\u003c/td\u003e\n\u003ctd width=\"34%\" align=\"center\"\u003e\u003cstrong\u003eYOps\u003c/strong\u003e\u003c/td\u003e\n\u003ctd width=\"33%\" align=\"center\"\u003e\u003cstrong\u003eCommit\u003c/strong\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003csub\u003eChat, doc, spec, prompt run\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003csub\u003eReview and apply deterministic YAML operations\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003csub\u003eVersion the new state with parents and provenance\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003ccode\u003esource evidence\u003c/code\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003ccode\u003eold YAML + YOps -\u003e new YAML\u003c/code\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003ccode\u003ecommit / diff / merge\u003c/code\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003e Extraction and generation can use LLMs. YOps Apply, validation, commit\n\u003e hashing, diff, and merge are deterministic.\n\nDiff and merge compare committed structured states. Fixes, extraction edits, and\nmerge resolutions are applied back through YOps before a new commit is written.\n\n### Small example\n\n```yaml\nsource:\n  text: Move launch region from US to EU and add security review before release.\n\nstate_before:\n  launch:\n    region: us\n    gates:\n      - qa\n\nyops:\n  - set:\n      path: launch/region\n      value: eu\n  - append:\n      path: launch/gates\n      value: security_review\n\nstate_after:\n  launch:\n    region: eu\n    gates:\n      - qa\n      - security_review\n\ncommit:\n  parents:\n    - sha256:...\n  provenance:\n    source: launch-note\n```\n\n\u003cbr/\u003e\n\n## The Y-Family\n\nT3X uses three spec-driven tools for structured YAML state. Together they form a\nvalidate-and-fix loop: detect issues, emit fix operations, apply them, confirm.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth width=\"33%\"\u003eYOps\u003c/th\u003e\n\u003cth width=\"33%\"\u003eYSchema \u003csup\u003eWIP\u003c/sup\u003e\u003c/th\u003e\n\u003cth width=\"33%\"\u003eYLint\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cstrong\u003eHow to mutate\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cstrong\u003eWhat is valid\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cstrong\u003eIs it clean\u003c/strong\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eAtomic YAML operations\u003cbr/\u003eSpec-driven, deterministic\u003cbr/\u003eSequential, fail-fast\u003c/td\u003e\n\u003ctd\u003eUser-defined domain schemas\u003cbr/\u003eSlot types, enums, ranges\u003cbr/\u003eCross-node rules\u003c/td\u003e\n\u003ctd\u003eBuilt-in structural rules\u003cbr/\u003eRuns without a schema\u003cbr/\u003eAuto-fix via YOps\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ca href=\"packages/yops/yops.yaml\"\u003e\u003ccode\u003eyops.yaml\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ca href=\"packages/yschema/yschema.yaml\"\u003e\u003ccode\u003eyschema.yaml\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003eBuilt into \u003ccode\u003e@t3x-dev/core\u003c/code\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nTwo functions cover the core loop:\n\n```typescript\napplyYOps(doc, ops)              // mutate: apply operations to a YAML tree\nvalidateTree(content, { schema }) // validate: check structure + domain, get fixes\n```\n\n`validateTree` runs ylint and yschema internally, collects warnings, and returns\na ready-to-apply fix plan. Auto-fixable issues resolve through `applyYOps()`.\nEverything else is surfaced for review.\n\n### YOps \u0026mdash; Declarative YAML Operations\n\n```yaml\nyops:\n  - define:\n      path: user/preferences\n  - populate:\n      path: user/preferences\n      values: { theme: dark, language: en }\n  - sort:\n      path: user/tags\n  - assert:\n      path: user/preferences/theme\n      equals: dark\n```\n\n\u003ctable\u003e\n\u003ctr\u003e\u003cth\u003eCategory\u003c/th\u003e\u003cth\u003eOps\u003c/th\u003e\u003cth\u003ePurpose\u003c/th\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cstrong\u003eDDL\u003c/strong\u003e\u003c/td\u003e\u003ctd\u003e\u003ccode\u003edefine\u003c/code\u003e \u003ccode\u003edrop\u003c/code\u003e \u003ccode\u003erename\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eCreate, remove, rename keys\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cstrong\u003eDML\u003c/strong\u003e\u003c/td\u003e\u003ctd\u003e\u003ccode\u003eset\u003c/code\u003e \u003ccode\u003eunset\u003c/code\u003e \u003ccode\u003epopulate\u003c/code\u003e \u003ccode\u003eappend\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eSet values, add to sequences\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cstrong\u003eDTL\u003c/strong\u003e\u003c/td\u003e\u003ctd\u003e\u003ccode\u003emove\u003c/code\u003e \u003ccode\u003eclone\u003c/code\u003e \u003ccode\u003enest\u003c/code\u003e \u003ccode\u003esplit\u003c/code\u003e \u003ccode\u003efold\u003c/code\u003e \u003ccode\u003emerge\u003c/code\u003e \u003ccode\u003esort\u003c/code\u003e \u003ccode\u003eunique\u003c/code\u003e \u003ccode\u003epick\u003c/code\u003e \u003ccode\u003eomit\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eReshape the tree\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cstrong\u003eDCL\u003c/strong\u003e\u003c/td\u003e\u003ctd\u003e\u003ccode\u003eassert\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eValidate conditions (read-only)\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\nThe full spec \u0026mdash; including a decision guide, type contracts, composition recipes, and error reference \u0026mdash; lives in [`yops.yaml`](packages/yops/yops.yaml). Any language can implement a conformant engine from this single file.\n\n### Validation\n\nYSchema defines domain-specific shape: required nodes, slot types, enums, ranges,\nand cross-node rules. YLint checks structural hygiene: key naming, value quality,\nlist hygiene, and tree depth. Both can emit YOps fixes.\n\nSpecs: [`yschema.yaml`](packages/yschema/yschema.yaml), YLint in\n[`@t3x-dev/core`](packages/core/).\n\n\u003cbr/\u003e\n\n## Configuration\n\n```\n~/.t3x/config.json          # API keys, default server URL\n\u003cproject\u003e/.t3x/config.json  # Project-specific settings\n```\n\nFor one-machine local product use, CLI (`t3x auth/config`) and MCP read the\nmachine-level `~/.t3x/config.json`, and WebUI (`/settings/access`) manages that\nsame file through the standalone API. Effective lookup order is:\n\n```text\nT3X_API_URL / T3X_API_KEY (environment)\n-\u003e ~/.t3x/config.json\n-\u003e built-in defaults\n```\n\nEnvironment variables always win over the shared file.\n\nAfter changing local access settings, use `t3x auth check` or the WebUI\n`Test Access` action in `/settings/access` to verify the effective API URL, and\nwhether the current deployment requires or accepts the configured key.\n\nCopy `.env.example` to `.env` to add provider keys for source development or to make auth settings explicit for Docker and other self-hosted deployments.\n\nThe core engine works without any API key. To use extraction or chat, add an Anthropic, OpenAI, or Google AI Studio key.\n\nFirst-run auth defaults:\n\n- Source development (`pnpm dev:api`, `pnpm dev:webui`) opens directly into the app by default.\n- To exercise the login flow in source development, set `AUTH_DISABLED=false` in the shell before starting both dev processes.\n- Docker and self-host keep auth on by default and use the built-in username/password login.\n\n## Architecture\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cstrong\u003eProduct\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eWebUI (Next.js) \u0026middot; API (Hono) \u0026middot; CLI (preview) \u0026middot; MCP (preview)\u003c/sub\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cstrong\u003eStorage\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003ePostgreSQL (Drizzle ORM) \u0026middot; Embedded PG (dev)\u003c/sub\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cstrong\u003eCore\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eHash chains \u0026middot; Diff engine \u0026middot; Merge \u0026middot; YLint \u0026middot; Extract\u003c/sub\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cstrong\u003eY-Family\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eYOps (mutate) \u0026middot; YSchema (validate, WIP) \u0026middot; YLint (hygiene)\u003c/sub\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n**Design principles:**\n\n- **Deterministic core** \u0026mdash; Same inputs, same outputs. No LLM in the critical path.\n- **Append-only** \u0026mdash; Hash chains are immutable.\n- **Evidence-backed** \u0026mdash; Every finding traces to source text with character offsets.\n- **Pluggable** \u0026mdash; LLMs are optional plugins for extraction, never required.\n\n### Project structure\n\n```\npackages/yops        # YOps — Declarative YAML operations\npackages/yschema     # YSchema — WIP validation candidate with auto-fix\npackages/core        # T3X engine — diff, merge, hash chains, extraction, ylint\npackages/storage     # PostgreSQL persistence (Drizzle ORM)\npackages/api-client  # TypeScript API client\napps/web             # WebUI (Next.js 16 + App Router)\napps/api             # Hono API server with OpenAPI\napps/cli             # Command-line interface (preview)\napps/mcp             # MCP server (preview)\napps/runner          # Grey-box agent evaluation engine\n```\n\n### Build\n\n```bash\npnpm build           # Build all packages\npnpm test            # Run all tests\npnpm check           # Lint + format (Biome)\n```\n\n\u0026rarr; [Contributing guide](./CONTRIBUTING.md)\n\n\u003cbr/\u003e\n\n## Availability\n\nThe current npm release surface is intentionally narrow and declared in\n[`RELEASE.md`](RELEASE.md) and [`release/surface.yaml`](release/surface.yaml).\n\n| Package | Status | Description |\n|:--------|:----|:------------|\n| [`@t3x-dev/local`](apps/local/) | public alpha | Local installer and no-key demo entrypoint |\n| [`@t3x-dev/yops`](packages/yops/) | public alpha | Declarative YAML operations |\n\nOther packages remain internal or preview until they are promoted into the\nrelease surface.\n\n\u003cbr/\u003e\n\n## Documentation\n\n[t3x-docs.vercel.app](https://t3x-docs.vercel.app) \u0026mdash; Quickstart, YOps\nreference, WebUI guide, and release notes.\n\nPolicies: [Security](SECURITY.md) \u0026middot; [Alpha limitations](docs/limitations.md) \u0026middot;\n[Deployment](docs/deployment.md) \u0026middot; [Stability](docs/stability.md)\n\n\u003cbr/\u003e\n\n## License\n\n[Apache License 2.0](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft3x-dev%2Ft3x-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ft3x-dev%2Ft3x-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft3x-dev%2Ft3x-core/lists"}