Matea

Your local-first action assistant for software work.

English · 简体中文

Matea gives ChatGPT a durable local workspace for understanding projects, carrying out bounded actions, and returning reviewable evidence. It focuses on software repositories today and is designed to extend into connected tools, services, devices, and personal workflows without giving up local control.

Why Matea

• Context that survives the chat — repository registration, plans, work state, handoffs, and verification evidence remain available across sessions.
• Actions with clear boundaries — normal local work can flow quickly, while remote writes, destructive effects, and secret access remain explicitly gated.
• Reviewable execution — patches, dedicated branches or worktrees, exact checks, and immutable release evidence make results inspectable.
• One local controller, many repositories — ChatGPT connects once, then work is routed to an explicitly selected repository and checkout.
• A compact default workflow — start with status, context, work, and verification; use advanced tools only when the task needs them.

Release status

1.4.0-rc.6 is the current GitHub release candidate for Matea. The npm package @moretea-labs/matea is not public yet, so source installation remains the currently verified package path. A GitHub prerelease and an npm publication are separate facts.

Quick start

Requirements: Git, Node.js 20.10 or newer, npm, and a writable home directory. Bun 1.0+ is optional and recommended for source development and the complete test suite.

git clone https://github.com/moretea-labs/matea.git
cd matea
npm ci --ignore-scripts --no-audit --no-fund
npm install -g . --omit=optional --no-audit --no-fund

matea --version
matea init --target both
matea doctor

Register or adopt a repository:

matea adopt --repo /path/to/your-project --dry-run
matea adopt --repo /path/to/your-project
matea repo list --json

Then follow the maintained path:

1. Install and start
2. Connect ChatGPT
3. Complete the first repository task

When the npm RC is published:

npm install -g @moretea-labs/matea@next
# or, from the same npm package:
bun add -g @moretea-labs/matea@next

Bun consumes the same npm package; it does not have a separate publication or version line.

Safety model

Matea separates reading, local repository changes, remote effects, destructive actions, and secret access. It keeps work scoped to a registered repository, records durable evidence, and fails closed when release identity or runtime ownership is ambiguous. See Core Concepts, Work Lifecycle, and Security Model.

Compatibility

The repo-harness and repo-harness-hook commands remain compatibility aliases during the Matea 1.x migration. Existing .repo-harness runtime directories and protocol identifiers are intentionally preserved so the product rename does not invalidate local state or integrations.

Documentation

• Documentation hub
• Wiki Home and GitHub Wiki
• Public usage guide
• Platform support
• Troubleshooting
• Release process

The README stays focused on first use. Architecture, lifecycle, integrations, recovery, and operator procedures live in versioned docs and the Wiki source.

Project status and support

Matea remains in release-candidate hardening. Interfaces may change before 1.4.0, and releases are created only from an immutable revision that passes the published release gate.

• Bugs and documentation: GitHub Issues
• Usage questions: SUPPORT.md
• Security reports: SECURITY.md
• Contributions: CONTRIBUTING.md
• Release history: CHANGELOG.md

License and attribution

Licensed under the MIT License. Matea began as a derivative of AncientTwo/repo-harness and has since developed into a substantially modified, independently maintained product. The upstream copyright and permission notice remain part of the distribution; see NOTICE and THIRD_PARTY_NOTICES.md.