Machine agent guide #

This file applies to the whole repository. Read the README, this file, and the nearest example README before changing code.

What Machine is #

Machine is one product with two host adapters:

• extensions/ integrates with Pi, including the Tinker provider and /tinker.
• mods/ integrates with Letta Code.
• lib/ contains shared storage, trajectory, reporting, Python, CLI, and the Tinker chat catalog.
• templates/ contains generated Tinker scripts.
• skills/ contains Tinker research and debug skills.
• examples/ contains executable research demonstrations and their evidence contracts.

Do not install pi-tinker alongside Machine. Machine owns /tinker now.

Keep Pi and Letta behavior aligned. Host-specific UI code may differ, but data shape, command semantics, defaults, and safety boundaries should not drift.

Before editing #

1. Run git status --short --branch. Do not overwrite unrelated local work.
2. Read docs/commands.md before changing a slash command.
3. For example work, read that example's README and design documents first.
4. Inspect the public command path, not only an internal handler. A direct unit call can miss argument normalization or host-adapter defects.

Machine stores judged and observed trajectories outside the repository under ~/.machine/ by default. Those rows can contain private prompts, source code, and tool output. Inspect them before copying, training on, or publishing them. Never stage ignored datasets, credentials, generated training scripts, raw responses, or run receipts.

Setup and validation #

The core package has no runtime npm dependencies. It requires Node 22.18 or newer. Python 3.11 through 3.13 is the supported Tinker environment; the ordinary example tests use only the standard library. Project Euler's full functional gate also needs Docker, Pi, and Python, Node, and Julia runtimes.

Run the complete local gate after code changes:

npm test

That runs syntax/smoke, unit, storage, example, package, and real local Pi integration checks. Tangled CI runs the same repository checks except the real Pi integration. Provider-backed Tinker runs and Docker-backed model evaluations are deliberately local-only.

Useful focused commands:

npm run unit-test
npm run example-test
npm run package-test
npm run local-integration-test
git diff --check

The package test is also a privacy check. Keep it green whenever files or ignore rules move. Do not weaken it to make a local artifact disappear from a failure.

Training and evaluation rules #

• A checkpoint being created, registered, or selected is not evidence that it improved behavior.
• Do not make a provider-backed call or start paid training without an explicit cost boundary for that run.
• Freeze tasks, scorer, sandbox, sampling settings, thresholds, and source checkpoint before sampling a promotion gate.
• Retrospective replay can invalidate a claim; it cannot authorize promotion.
• Preserve raw trajectories and manifests when a scorer defect is found.
• Use exact checkpoint IDs for comparisons and release trials. Do not rely on whichever checkpoint happens to be “latest.”
• A blocked escape attempt is still failed agent behavior even when isolation prevented host damage.

docs/behavior-releases/ contains release contracts. A null required holdout digest or spend_authorized: false is a hard stop, not an invitation to fill in the blank after observing a candidate.

Repository workflow #

This repository currently lands validated work directly on main; a pull request is not required merely by convention. That does not grant standing authority to commit, push, tag, publish, or spend. Follow the caller's explicit authorization, keep commits focused, and verify the remote commit and hosted CI after a push.

Do not rewrite public history or move a release tag. Release tags identify the exact reviewed commit.

Tangled CLI (tg) #

Use tg for Tangled repository context, issues, pull requests, and CI. It discovers this repository from the origin remote.

Install the stable CLI with Homebrew:

brew tap alyraffauf/tap
brew trust alyraffauf/tap
brew install alyraffauf/tap/tg

Or install from source with Go:

go install github.com/alyraffauf/tg/cmd/tg@latest

Verify and authenticate:

tg --version
tg auth login <atproto-handle>
tg auth status

Common repository commands:

tg --json pipeline status
tg pipeline list
tg pipeline logs
tg issue list
tg pr list
tg browse

Public CI reads may work without an active session. Mutations require authentication. Never print tokens or copy auth state into the repository.

tg is the upstream Go CLI at https://tangled.org/aly.codes/tg. An independent tang CLI may also be installed on some machines; do not silently mix their command syntax in scripts or documentation.

Common traps #

• Node executes the TypeScript sources through native type stripping. Do not add a build step unless the package actually needs one.
• npm run local-integration-test expects a real pi binary on PATH.
• Project Euler answers and source data must never enter an evaluated agent's workspace.
• Run manifests and hash receipts are part of the evidence. A prose summary is not a substitute.
• Registration through /tinker use does not promote a checkpoint. During an experiment, pass the exact checkpoint to /machine student <checkpoint>.