Imported from cybergarage/go-matter (.codex/AGENTS.md). Install upstream with npx skills add cybergarage/go-matter --skill .codex. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Specification & Reference

go-matter implements Matter Specification Version 1.5. Code comments cite relevant spec sections (e.g., // 2.5.2. Vendor Identifier). The implementation is based on the official C++ reference: https://github.com/project-chip/connectedhomeip.

Reference Implementation

The Matter implementation is based on the official C++ implementation: https://github.com/project-chip/connectedhomeip.

Commands

# Full pipeline: format → vet → lint → test
make test

# Individual steps
make format   # runs version.gen then gofmt
make vet      # go vet
make lint     # golangci-lint
make install  # build+install matterctl CLI and regenerate doc/matterctl.md

# Run a single test
go test -v -run TestName ./matter/...
go test -v -run TestName ./mattertest/...

# Run all tests without linting
go test -v -p 1 -timeout 10m -cover -coverpkg=github.com/cybergarage/go-matter/matter/... \
  -coverprofile=matter-cover.out \
  github.com/cybergarage/go-matter/matter/... \
  github.com/cybergarage/go-matter/mattertest/...

Tests run with -p 1 (single-threaded) because BLE and mDNS operations are not concurrency-safe across test cases.

Package Layout

Key Design Patterns

• Interfaces in *.go, implementations in *_impl.go — e.g., commissioner.go defines the interface; commissioner_impl.go has the struct.
• The root matter/ package re-exports types from sub-packages as type aliases so users have a single import path.
• Commissioner embeds ble.Central and mdns.Discoverer, supporting simultaneous BLE (BTP) and mDNS discovery.
• Device / CommissionableDevice / Node form the core domain model.
• Integration tests live in mattertest/; unit tests sit alongside source files inside each sub-package.

Dependencies

Depends on sibling cybergarage packages (go-ble, go-mdns, go-logger) developed in parallel — these may have unreleased APIs.

Conventions

• Spec references in comments: cite the Matter spec section in comments (e.g., // 2.5.2. Vendor Identifier, // 5.4.3. Discovery by Commissioner). Follow this pattern for new code.
• version.go is generated: make format runs matter/version.gen to regenerate matter/version.go. Do not edit it manually.
• Linter: golangci-lint v2, configured in .golangci.yaml. Run make lint before submitting changes.
• Test logging: use go-logger (log.EnableStdoutDebug(true)) for debug output in tests, not t.Log.