# togetherlink

> Use Together AI models in the coding-agent harnesses you already run - OpenCode, Claude Code, Codex CLI, DeepSeek Harness, Grok Build, Hermes, Pi Code, and Prime Agent. togetherlink injects Together settings for a single run so your normal tool configs stay untouched.

togetherlink is an MIT-licensed CLI router. Install once, then launch your agent with short commands (`tcodex`, `tclaude`, `topencode`, `tdeepseek`, `tgrok`, `thermes`, `tpi`, `tprime`). For Claude Code and Codex CLI it routes the agent's API traffic to Together AI through a local translation proxy; for OpenCode, DeepSeek Harness, Grok Build, Hermes, Pi Code, and Prime Agent it injects ephemeral per-run config. The installed binary keeps itself up to date automatically from togetherlink.dev.

This is the LLM-readable documentation file for the project. If you are an AI agent asked to install, configure, or use togetherlink (headless or interactive), read this file first. It covers installation, configuration, every command, the available models, headless/agentic usage patterns, how to keep the tool up to date, and the routing architecture.

- Website: https://togetherlink.dev
- Installer: https://gateway.togetherlink.dev/install
- Version manifest: https://gateway.togetherlink.dev/latest.json
- This file: https://togetherlink.dev/llms.txt

## Install

One command installs the `togetherlink`, `tclaude`, `topencode`, `tcodex`, `tdeepseek`, `tgrok`, `thermes`, `tpi`, and `tprime` commands to `~/.togetherlink/bin/` and installs Bun for you if it isn't already present:

```
curl -fsSL https://gateway.togetherlink.dev/install | sh
```

After install, restart your shell (or run the `export PATH=...` line it prints) so the commands are on PATH. The install:

- Downloads the self-contained JS bundle to `~/.togetherlink/bin/togetherlink.js`.
- Writes shell wrappers (`togetherlink`, `tcodex`, `tclaude`, `topencode`, `tdeepseek`, `tgrok`, `thermes`, `tpi`, `tprime`) that run the bundle with `bun`.
- Links them into a writable directory on your PATH.
- Demand-installs DeepSeek Harness only after `deepseek`/`tdeepseek` is explicitly selected or invoked. Other missing agent CLIs are not installed automatically; togetherlink prints their official install command and exits.

To verify: `togetherlink --version`.

## Configure

Before the first launch you need a Together API key (get one at https://api.together.ai/settings/api-keys):

```
togetherlink configure
```

This stores your Together API key in `~/.togetherlink/` and optionally an Exa API key (https://exa.ai) that powers web-search emulation in Claude Code. Web search is optional - without it, searches return a clear "EXA_API_KEY not set" error instead of failing silently.

You can also set the key non-interactively:

```
export TOGETHER_API_KEY=...
togetherlink configure        # stores it (skip prompts with the env present)
```

The API key is required to actually route traffic; the installer lets you skip it (press Enter) and add it later.

To route model requests through a compatible credential proxy, set `TOGETHER_BASE_URL` in the launcher environment. TogetherLink appends `/v1` when needed and defaults to `https://api.together.ai/v1` when the variable is absent:

```
export TOGETHER_API_KEY=phantom-key
export TOGETHER_BASE_URL=http://127.0.0.1:1234/together
togetherlink codex
```

This applies to every coding harness. `TOGETHER_BASE_URL` is intentionally not loaded from repository `.env` files.

To disable TogetherLink's anonymous analytics:

```
export TOGETHERLINK_TELEMETRY_DISABLED=1
```

When set, TogetherLink does not create analytics install state or send requests to its telemetry endpoint.

## Commands

Running `togetherlink` with no arguments opens an interactive launcher (requires a TTY) that lets you pick a tool. Run a tool directly with a subcommand:

```
togetherlink configure                      # set API keys
togetherlink whoami                         # print your anonymous install id
togetherlink --version | -v                 # print the version
togetherlink help | --help | -h             # print this usage

togetherlink codex [...]        # alias: tcodex   (Codex CLI)
togetherlink claude [...]       # alias: tclaude  (Claude Code)
togetherlink deepseek [...]     # alpha, alias: tdeepseek (DeepSeek Harness web UI)
togetherlink grok [...]         # alias: tgrok    (Grok Build)
togetherlink hermes [...]       # alias: thermes  (Hermes Agent)
togetherlink hermes desktop [...] # Hermes Desktop
togetherlink pi [...]           # alias: tpi      (Pi Code)
togetherlink prime [...]        # alias: tprime   (Prime Agent)
togetherlink opencode [...]     # alias: topencode (OpenCode)

togetherlink chatgpt [--model <model>] [--restore]   # alpha: ChatGPT Desktop (alias: codex-app)

togetherlink daemon stop                   # stop it until the next daemon-backed command or login
```

Any arguments after the harness name are passed straight through to the underlying agent CLI. For example, `tcodex exec "fix the typo"` runs `codex exec` with togetherlink routing.

Recognized togetherlink flags (parsed before the passthrough):

- `--api-key <key>` - use this Together API key for the run.
- `--main <model>` / `--model <model>` - select the model for this run.
- `--search <value>` - search setting (harness-specific).
- `--slot <value>` - session slot selection.
- `--json` - print machine-readable payloads where supported.
- `--restore` - restore (used with `chatgpt`).

### ChatGPT Desktop App (alpha)

`togetherlink chatgpt` persistently patches the ChatGPT Desktop config so the desktop app routes through Together. Unlike the CLI wrappers, this change stays active until you restore it:

```
togetherlink chatgpt                     # configure (patches config)
togetherlink chatgpt --restore           # restore your OpenAI profile
togetherlink chatgpt --model <model>     # use a specific model
```

Backups of your original config live under `~/.togetherlink/backup/codex-app/`.

## Available Models

togetherlink routes to a curated set of Together AI models. The default for every coding harness is Kimi K3.

Serverless prices below are in USD per 1 million tokens and come from Together's authenticated `/v1/models` catalog, checked August 15, 2026. Cached input is billed at the lower rate when Together's automatic prompt cache matches a prefix; otherwise the standard input rate applies. Together may change these prices, so check the live catalog for billing-critical decisions.

| Model | Together API id | Input | Output | Cached input |
| --- | --- | ---: | ---: | ---: |
| Kimi K3 (default) | `moonshotai/Kimi-K3` | $3.00 | $15.00 | $0.30 |
| GLM 5.2 | `zai-org/GLM-5.2` | $1.40 | $4.40 | $0.26 |
| MiniMax M3 | `MiniMaxAI/MiniMax-M3` | $0.30 | $1.20 | $0.06 |
| Qwen 3.7 Max | `Qwen/Qwen3.7-Max` | $1.25 | $3.75 | $0.125 |
| DeepSeek V4 Flash 0731 | `deepseek-ai/DeepSeek-V4-Flash-0731` | $0.14 | $0.28 | $0.03 |

### Selecting a model (flag order matters)

Put `--model` (or `--main` for Claude) BEFORE the harness subcommand - togetherlink consumes it there and routes to that model. Verified against the installed CLI (v0.8.3):

```
togetherlink --model MiniMaxAI/MiniMax-M3 codex exec "task"
togetherlink --model MiniMaxAI/MiniMax-M3 claude -p "task"
togetherlink --main together-glm-5-2 claude -p "task"   # Claude matches alias OR id
togetherlink --model deepseek-ai/DeepSeek-V4-Flash-0731 deepseek
```

Do NOT put `--model` after the harness (e.g. `tcodex --model X` or `tclaude --model X`). The short aliases expand to `togetherlink <harness> ...`, so the flag lands after the harness name, goes to the agent's passthrough, and is then stripped - it is silently ignored and the run uses the default (Kimi K3), not the model you asked for. Always use the long form with the flag first.

Capabilities:

- `moonshotai/Kimi-K3` - Kimi K3 · default. Vision, 1M context, reasoning. The default coding model.
- `zai-org/GLM-5.2` - GLM 5.2. Text-only, 512K context, reasoning.
- `MiniMaxAI/MiniMax-M3` - MiniMax M3. Vision, 512K context, cheapest vision primary.
- `Qwen/Qwen3.7-Max` - Qwen 3.7 Max. Vision, 1M context.
- `deepseek-ai/DeepSeek-V4-Flash-0731` - DeepSeek V4 Flash 0731. Text-only, 1M context, low/high/max reasoning, 384K documented output guidance, function calling.

Vision-capable models accept image attachments directly. GLM 5.2 and DeepSeek V4 Flash are text-only; harnesses with vision delegation use Kimi K3 for image work.

## Headless & agentic usage

Claude Code, Codex CLI, and Grok Build run headlessly (no TTY), so you can delegate code changes to an AI agent from scripts, CI, or another orchestrating agent. Grok's headless form is `tgrok --output-format streaming-json --disable-web-search --no-memory --no-subagents -p "task"`.

### The working invocation pattern

Both wrappers spawn the agent pointed at the local Together proxy and pass your flags through to the underlying binary. Always close stdin and capture stderr. To run a non-default model, put `--model <id>` before the harness (see Models above).

### Prefer native subagents for delegated togetherlink runs

If you are an orchestrating agent running inside Claude Code, Codex, or another CLI that has its own native subagent/delegation tool, prefer this pattern for non-trivial togetherlink work:

1. Spawn a native subagent first.
2. Tell that subagent to run the needed `togetherlink` command itself (`tcodex`, `tclaude`, `topencode`, `tgrok`, `thermes`, `tpi`, or `tprime`) with a tight task, explicit files, `< /dev/null`, and the guardrails below.
3. Have the subagent wait for the delegated togetherlink run, inspect its result/diff, and report only the useful summary back to you.

Do this instead of having the main orchestrating agent call `tcodex`/`tclaude` directly for every delegated edit. It keeps the main agent's context and inference budget focused on coordination/review, lets the native subagent own the details of launching and monitoring togetherlink, and works especially well when Claude Code delegates to a subagent that then uses Codex through `tcodex`.

Codex CLI - non-interactive `exec` (the `-s workspace-write` sandbox grants write access; `exec` never prompts interactively):

```
togetherlink codex exec -s workspace-write -C /abs/repo "<tight, single-concern task with explicit files + guardrails>" < /dev/null 2>&1
```

If the working directory isn't a git repo, codex refuses to start ("Not inside a trusted directory"); add `--skip-git-repo-check`, or run inside a git repo.

Claude Code - print mode `-p` (runs once and exits). Add `--dangerously-skip-permissions` so a headless subagent never blocks on a permission prompt:

```
togetherlink claude -p "<tight, single-concern task with explicit files + guardrails>" --dangerously-skip-permissions --output-format json < /dev/null 2>&1
```

Run it in the background, health-check at ~60s, review the diff, run lint, then commit. One file or one concern per task gives the cleanest reviews.

### Always close stdin: `< /dev/null`

This is the single biggest footgun. When launched in the background with an open/inherited stdin and no TTY, the process prints `Reading additional input from stdin...` and blocks forever - it never starts the task and produces no edits.

- **Workaround:** append `< /dev/null` to every invocation. With stdin closed it runs cleanly every time.
- **Do not** treat the `Reading additional input from stdin...` line as a hang signal on its own - that line also prints on healthy `< /dev/null` runs (it reads EOF immediately and proceeds). The real hang signal is: that line is the **last** line AND the output line count stays frozen. Health checks should watch for a *frozen line count*, not the presence of the stdin message.

### Health-check a launch, don't assume

A hung/failed start and a legitimately-working task both look like "background process still running." Without tailing the log there's no way to tell in the first minute whether it connected. Adopt a scripted ~60s health check:

- process alive, AND
- the banner line `Routing Codex → Together AI` (or `Routing Claude Code → Together AI`) is present (confirms it connected, not hung pre-connection), AND
- no `command not found` / startup error in the log, AND
- output line count is still growing (not frozen).

Kill and relaunch on a failed start.

### One concern per task; keep taste on the orchestrator side

Give explicit file lists and verbatim text for any creative content. Keep taste decisions (copy, design) on the human/orchestrator side and pass the exact text to insert. When told to touch only a named set of files, the agent respects the scope precisely and will flag (not silently fix) a file outside the scope that has the same issue - surface that gap for a human to decide.

### Wait for done before reviewing or linting

Do not lint or review mid-run. The agent rewrites files in passes and a file can be briefly malformed mid-edit (e.g., a stray `*/` mid-comment) that is correct by task end. Reviewing mid-run chases phantom errors. Wait for the done signal, then:

1. Review the diff yourself.
2. Re-run lint yourself (the agent self-verifies with lint and reports honestly, but the review step has caught real issues - e.g., a `server-only` import that would crash, or a 7th file needing the same fix).
3. Commit.

### Cost awareness

Per-task cost varies a lot with how verbose the agent is. Mechanical, well-scoped changes are cheap (~$0.10); a single change that triggers verbose JSDoc + defensive guard code can cost ~10 - 20× more. To keep cost down: scope tasks tightly, and prefer a "match surrounding comment density; don't over-explain" instruction for small mechanical changes.

### Summary of recommendations

1. Always `< /dev/null`.
2. One concern per task; give an explicit file list and verbatim text for creative content.
3. 60s health check after launch; kill + relaunch on a failed start (watch for frozen line count).
4. Never lint/review mid-run; wait for the done signal.
5. Review the diff + re-run lint yourself before committing.
6. To select a model, put `--model` (or `--main` for Claude) before the harness subcommand - after the harness it is silently ignored and the default runs.
7. For Claude `-p`, pass `--dangerously-skip-permissions` so a headless subagent never blocks on a permission prompt. Codex `exec` is non-interactive by design; use `-s workspace-write` for edits and `--skip-git-repo-check` outside a git repo.
8. If your current CLI has native subagents, delegate togetherlink launches to one of those subagents and let it return the result, instead of spending the main orchestrator's context on the full `tcodex`/`tclaude` run.

## Keeping togetherlink up to date

The installed binary self-updates automatically in the background. The check is throttled and bounded, never throws, and runs before argument parsing - so even `togetherlink help` keeps an install current. The update is pulled from https://gateway.togetherlink.dev/latest.json, which contains `version`, `url`, and `publishedAt`.

To force a refresh, re-run the install one-liner:

```
curl -fsSL https://gateway.togetherlink.dev/install | sh
```

You can check the installed version with `togetherlink --version` and compare it against the published manifest at https://gateway.togetherlink.dev/latest.json.

## Architecture (how routing works)

There are two harness families behind the supported tools:

- **Proxied harnesses - Claude Code, Codex CLI.** `tclaude` and `tcodex` spawn a shared local daemon and route the agent's `/v1/*` traffic through it. The daemon translates the agent's native wire format (Anthropic Messages for Claude, OpenAI Responses for Codex) to Together's chat-completions API and back. Per run: it resolves the model, ensures the daemon, registers a session with your token, prints a banner, spawns the agent pointed at the local proxy, tracks cost, and deregisters on exit. Nothing is written to your real agent config - close it and your setup is exactly as it was.

- **Spawned harnesses - OpenCode, DeepSeek Harness, Grok Build, Hermes, Pi Code, Prime Agent.** `topencode`, `tdeepseek`, `tgrok`, `thermes` (including `thermes desktop`), `tpi`, and `tprime` spawn the agent binary directly. The binary talks to Together itself, using inline config (OpenCode), a credential-free per-launch `--patch` overlay (DeepSeek Harness alpha), a local metadata-only model catalog plus temporary auth isolation (Grok), a temporary standalone provider plugin in a credential-isolated home overlay (Hermes), a temporary `models.json` (Pi), or a credential-free provider extension activated only for the TogetherLink launch (Prime Agent). DeepSeek Harness and Prime metadata remain under TogetherLink's own home; API keys are runtime-only, and the harnesses' normal user configuration is untouched. No inference proxy is involved.

The daemon is one persistent local process shared by all proxied sessions. If you ever need to stop it manually:

```
togetherlink daemon stop
```

This unloads the OS-supervised service so the always-restart policy does not immediately bring it
back. The next daemon-backed TogetherLink command, or the next login, starts it again.

`togetherlink chatgpt` (alpha) is the exception: it persistently patches ChatGPT Desktop config to route through Together (instead of per-run injection), with backups under `~/.togetherlink/backup/codex-app/`. Restore with `togetherlink chatgpt --restore`.

## Troubleshooting

- **"No Together API key found"** - run `togetherlink configure` or set `TOGETHER_API_KEY`.
- **A tool command is not found** - togetherlink does not install the agent CLIs for you. It prints the official install command (e.g. `npm install -g @openai/codex`) and the docs link when the tool is missing; install it, then re-run.
- **Web search fails in Claude Code** - set an Exa API key via `togetherlink configure`. Without it, searches return a clear "EXA_API_KEY not set" error.
- **Headless run hangs and produces no edits** - you forgot `< /dev/null`. Close stdin and relaunch; see the Headless usage section.
- **Cost seems high for a small change** - the agent over-documented. Scope the task tighter and add a "don't over-explain" instruction.
- **Grok web search or image generation is unavailable** - `tgrok` disables Grok's xAI-backed web search and Imagine image tools because Together's direct chat-completions route does not provide those xAI-specific API surfaces. Coding tools, workflows, image understanding through supported Together vision models, and Together model requests still work.
- **Want your normal config back** - stop using the wrappers. No agent config was saved, so your OpenCode / Claude Code / Codex CLI / DeepSeek Harness / Grok Build / Hermes / Pi Code / Prime Agent setup is untouched. For ChatGPT Desktop, run `togetherlink chatgpt --restore`.

## Links

- [Website](https://togetherlink.dev): landing page
- [Install script](https://gateway.togetherlink.dev/install): one-command installer (`curl -fsSL https://togetherlink.dev/install | sh`)
- [Version manifest](https://gateway.togetherlink.dev/latest.json): current published version and release timestamp
- [This LLM docs file](https://togetherlink.dev/llms.txt): the file you are reading now
- [Together AI API keys](https://api.together.ai/settings/api-keys): get a key to route traffic
- [llms.txt specification](https://llmstxt.org): the convention this file follows