@tuple-ai/tuple-runner

Tuple Agent Runner — distributed AI agent daemon. Connects to the Tuple platform, clones the project's repositories into an isolated workspace, and runs the configured agent CLI (Claude Code, Codex, or Kiro) against the task.

tuple-runner setup --key <AGENT_KEY>   # configure
tuple-runner start                     # connect and run tasks
tuple-runner status                    # show config / connection

Standardized project memory (.tuple/)

Different agents read different instruction files — Claude reads CLAUDE.md + .claude/, Codex reads AGENTS.md/AGENT.md, Kiro reads .kiro/steering/. Keeping them in sync by hand causes drift.

.tuple/ is the single canonical source of truth: a project's "memory". Every agent-specific file is generated from it, so a project behaves the same regardless of which agent CLI runs it.

.tuple/
  instructions.md   # canonical instructions — EDIT THIS
  memory/*.md       # optional long-form notes, appended in filename order
  skills/<name>/SKILL.md   # optional agent skills
  docs/*.md         # optional reference docs (indexed, read on demand)
  config.json       # enabled targets + manifest of generated files
  README.md         # adoption guide (emitted by `init`)

Generated (do not edit by hand — each carries a <!-- TUPLE:GENERATED --> marker): CLAUDE.md, AGENTS.md, AGENT.md, .kiro/steering/tuple.md. The generated files inline the instructions/memory plus an index of the project's skills and docs.

Skills & docs

.tuple/ is the project's single general reference. Beyond instructions it can ship:

• skills/<name>/SKILL.md — agent skills. Claude auto-loads them (the runner mirrors them into .claude/skills/); other agents get an index entry and read the SKILL.md on demand (skills aren't portable 1:1 across agent CLIs).
• docs/*.md — reference documentation, indexed by title so any agent can read it on demand without inlining large files.

At execution time the runner stages a single workspace-root .tuple/ aggregating every cloned repo's memory, skills and docs — .tuple/ is THE reference the agent is pointed at.

Adopting it in a project

tuple-runner agents init     # scaffold .tuple/ (migrates an existing CLAUDE.md/AGENTS.md if present)
tuple-runner agents sync     # regenerate the derived files after editing .tuple/
tuple-runner agents check    # CI gate: exits non-zero if derived files are stale

Add the drift gate to CI:

- run: npx @tuple-ai/tuple-runner agents check

How the runner uses it

When Tuple executes a task, the runner clones the project's repos and scans them for .tuple/. If found, it surfaces the memory into the instruction files every agent reads at the workspace root (CLAUDE.md, AGENTS.md, .kiro/steering/tuple.md) — composed alongside the runner's own base instructions and workspace orientation, never replacing them. No manual step is required for the agent to pick it up.

Never put secrets in .tuple/ — it is committed project memory. The runner injects tokens through the process environment, not these files.

Development

npm run build       # tsc -> dist/
npm test            # node --test (generator unit tests)
npm run lint        # eslint