Build the app

Prepare the checkout and toolchain, build Mellow and separate development from release delivery.

Mellow development spans a native Mac app, core services, a command-line interface, and supporting packages. Work from the current repository instructions and validate the behavior your change affects. A documentation edit, an API parser change, and a model-runtime change require different evidence.

Set up the checkout

Open the checked-out mellow.xcworkspace in Xcode. Select the app scheme and an appropriate Mac destination. Use the repository's configured dependencies and signing settings rather than replacing package pins to make an initial build pass.

The command-line build lanes are defined in the root Makefile:

make cli
make app
make test
make ci-test

make test runs the fast MellowCore package tests. make ci-test mirrors the core Xcode test lane and writes an xcresult bundle under build/Tests.xcresult. Use the same toolchain and dependency state as the build you intend to compare.

Find the right component

Read the applicable AGENTS.md before editing. It defines release evidence, configuration catalog obligations, and runtime constraints that a short build command does not capture.

Protect the normal user profile

For tests that do not need real identity or provider credentials, use the supported isolation environment:

MELLOW_DISABLE_KEYCHAIN_FOR_TESTS=1 \
MELLOW_TEST_ROOT=/tmp/mellow-test \
MELLOW_MODELS_DIR=/tmp/mellow-test-models \
make test

Use an empty isolated model directory when the harness must not load a person's installed models. This matters because a package test process may not contain the Metal resources required by a real generation path.

Some tests intentionally require Keychain access and will not establish their contract with Keychain disabled. Keep those tests separate. Never reset the real profile or remove credentials merely to make a deterministic test pass.

Treat settings as a complete path

When adding or renaming a setting, update its exact title and location in SettingsSearchIndex.swift, its landing anchor, the bundled settings guide, and the self-find probe. This keeps settings search, app navigation, and agent-assisted configuration aligned.

Trace the value from editing to persistence to the consumer. Then change it in the built app, navigate away and back, exercise the affected workflow, and relaunch if persistence or next-load behavior is part of the contract. A saved JSON value does not prove the runtime consumed it.

Verify at the right level

Start with a focused test for the changed contract. Run the relevant broader suite once the focused check passes. Use the actual native app for permissions, Keychain, browser OAuth, paired devices, model generation, and execution lifecycle behavior.

For an agent-loop change, inspect the whole turn: reasoning closure where applicable, tool arguments and results, subagent completion, disappearance of Stop, unlocked input, and a working follow-up turn. For cancellation, test during load and execution rather than only before the task starts.

For local inference, record the exact model bundle, effective sampler and cache settings, tokens per second, and physical memory. A load-only test cannot support a claim about tool use, vision, cache correctness, or multi-turn coherence.

Use evaluations as evidence

make evals
make evals-all

Choose the suites relevant to the behavior, preserve raw artifacts, and report denominators and failures. Keep model-specific failures separate from harness failures. If a required external judge or provider credential is unavailable, label that row unproven rather than implying an omitted check passed.

Prepare a reviewable change

Describe the concrete before/after behavior and the source revision tested. Include tests, build identifiers, evaluation results, and remaining limitations. Keep credentials and private screenshots out of commits. For release work, signing, notarization, update delivery, native consent, and paired-device proof remain distinct checks.

See Architecture to choose an integration boundary and Diagnostics to collect a useful failure report.