HeyTim

One monorepo for HeyTim's native AI friends app, public website, reviewed skills, API and AgentCore runtime. The Expo application has been archived outside the repository; it is no longer a build or release target.

HeyTim is source-available under the PolyForm Noncommercial License 1.0.0. Noncommercial use, modification, and distribution are permitted under that license; commercial use requires a separate commercial license. This is not an OSI-approved open-source license.

Structure

apps/
  iOS/                         Shared SwiftUI iPhone + macOS app
  website/                     Vite + React marketing site and skills library
services/
  API/                         Amplify application backend and API contract
  runtime/                     AgentCore Python runtime, tools and evaluations
catalog/                       Reviewed bots, skills, tool schemas and validation
packages/
  heytim-contract/             Generated TypeScript route contract and tests
  heytim-transcription/        Native Swift transcription core
agentcore/                     Declarative AWS resources and deployment wrapper

These are component boundaries within one product. tmoreton/heytim is the canonical source and publishing repository. See the repository and licensing model.

apps/iOS builds both iOS and macOS. There is no public browser chat. The website's /app and /invite routes help people open the installed Apple app. The backend's existing users, data, and AWS resource identities remain stable through the brand change. The public website and bot catalog live at heytim.ai.

Local development

Use Node 22.23.2, Python 3.14, uv, and Xcode with the installed iOS simulator.

# iPhone or Mac
./scripts/apple-app.sh run ios
./scripts/apple-app.sh run macos

# Build both Apple destinations without launching
./scripts/apple-app.sh build

# Public website, with no cloud credentials required
npm ci --prefix apps/website
npm run dev --prefix apps/website

# Server dependencies
npm ci --prefix services/API
npm ci --prefix agentcore/cdk
uv sync --project services/runtime --frozen

The native speech model and frameworks are prepared and checksum-verified by packages/heytim-transcription/scripts/prepare-apple.sh. These large generated assets are intentionally not committed.

Verify

./scripts/verify.sh application  # Vite build, library behavior, catalog, contracts
./scripts/verify.sh server       # API, runtime, AgentCore schema and wrapper
./scripts/verify.sh apple        # Speech tests, macOS tests, iPhone UI tests
./scripts/verify.sh all

The website build prerenders every public page and publishes only the public catalog allowlist. It tests that chat, auth and Expo dependencies cannot leak into the bundle. Catalog instructions remain versioned; existing installed versions are not changed by this migration.

Releases

• A push to main runs affected checks on the Mac mini. It does not deploy.

• AWS production releases remain manually triggered through the protected production workflow. See the release guide.

• Apple-only releases can be built and uploaded locally, without GitHub Actions:

  APPLE_TEAM_ID=GVXC5FQ2RP ./scripts/apple-app.sh testflight ios
  APPLE_TEAM_ID=GVXC5FQ2RP NOTARY_KEYCHAIN_PROFILE=HeyTimNotary \
    HEYTIM_MARKETING_VERSION=1.0.1 ./scripts/apple-app.sh distribute-macos

  iPhone remains on TestFlight. Mac releases use a Developer ID signed, notarized drag-to-Applications DMG, with a ZIP for Sparkle updates. Both are attached to GitHub Releases alongside the signed feed. Configure the signing variables documented by each script. Signing keys remain outside Git. Preflight checks require committed source and production client configuration; the script runs native tests before upload.

• The Pages workflow publishes heytim.ai directly from this repository. The website's publish script verifies the release and queues that workflow.

services/API/amplify_outputs.json is the public configuration generated by Amplify. npm run outputs:apple --prefix services/API copies only the native client fields into the app. The marketing website does not consume it.

Working safely

AgentCore JSON is authoritative. Keep resource names stable, read the matching schema before changing config, and run agentcore validate. Directory cleanup must never recreate live users, memories or storage. Backend authorization and tool approval remain server-enforced. Skills are reviewed instructions, never downloaded executable code or credentials.

The Expo reference archive is at an offline maintainer-controlled location. Original history also remains in Git. The imported catalog began from public commit 62a1f53; verified local bundles preserve the retired repositories. See migration notes.

Guides

• Architecture
• Contributor walkthrough
• Verification
• Cost-efficient builds and the Mac mini
• Production release
• Operations and recovery
• Integrations
• Webhooks and local Mac routing
• Public launch checklist
• Support
• Catalog contribution and safety

Licensing and contributions

• LICENSE contains the unmodified PolyForm Noncommercial 1.0.0 terms.
• NOTICE contains the required copyright notice and scope.
• THIRD_PARTY_NOTICES.md identifies bundled third-party materials and their license locations.
• COMMERCIAL-LICENSE.md explains how to request commercial rights.
• CONTRIBUTING.md describes the current contribution policy.

Third-party dependencies, models, frameworks, and vendored components retain their own licenses. Their terms are not replaced by the repository's root license.

Use scripts/clean-generated.sh to remove rebuildable caches. Its optional --archives mode retains only the newest archive per Apple platform; preserve additional archives separately when their symbols are needed.