Triss mascottrisscoworker
GitHub ↗
quickstart

Your first delegated task.

Five steps take you from an empty shell to a delegated research task. You need Node.js ≥ 22.12 and a credential (an API key) for the provider you plan to use.

The connection guide in step 4 differs by host. This page covers Claude Code, Codex, and terminal use — every variant is shown below, so nothing is lost without JavaScript.

step 01

Check Node

Triss requires Node.js ≥ 22.12. Print your current version and, if it is older, install a current Node.js release before continuing.

$ node --version
step 02

Install Triss

Install the CLI globally with npm, or pick another package manager below. Every labeled variant stays visible until JavaScript narrows the list to your selection.

npm
$ npm install -g triss-coworker
pnpm
$ pnpm add -g triss-coworker
yarn
$ yarn global add triss-coworker

Prefer the npm-free standalone installer, or building from source? Both are listed inAlternative installation methods below the steps.

step 03

Configure a provider

Triss runs model calls through one canonical provider runtime, and you choose whose credential to use — for example openai-compatible, zai,opencode-zen, opencode-go, moonshot, orkimi-for-coding. The wizard opens on the Easy path: pick the provider, paste its key, choose which assistant host to connect — Claude Code, Codex, both, or skip host wiring entirely — review the summary, and the run ends with your first command. Rerunning it reuses what you already configured instead of resetting it:

$ triss config wizard

Everything else is one flag away. triss config wizard --advanced opens the full tuning sections — providers, execution (engine, effort, credential protection), connections, integrations, and runtime — and a target argument configures a single piece, like triss config wizard zai, triss config wizard coder, or triss config wizard jira. Non-interactive shells apply a complete configuration headlessly from existing files, the environment, and explicit flags:

$ triss config wizard --advanced
$ triss config wizard --yes --agent none

For a terminal-only setup with no host wiring, you can also set the profile directly:

$ triss config set -g TRISS_OPENAI_COMPATIBLE_BASE_URL
$ triss config set -g TRISS_OPENAI_COMPATIBLE_API_KEY
$ triss config set -g TRISS_OPENAI_COMPATIBLE_MODEL
$ triss config set -g TRISS_OPENAI_COMPATIBLE_SMALL_MODEL

Each command without a value prompts for it interactively — key and token input is masked as you type and never lands in your shell history. openai-compatible is a configurable profile, not a provider detector: its built-in endpoint ishttps://api.deepseek.com/v1, so set the base URL explicitly when using another compatible endpoint. These commands edit profile fields; they do not reset an existing default provider or engine. For headless use, interactive prompts do not apply — assemble a complete configuration withtriss config wizard --yes --agent none instead. With no host wired, nothing is written to Claude Code or Codex; the CLI alone is enough for the workflows on this site.

Then check that your configuration is ready:

$ triss status

triss status lists every provider with its credential state (ready or missing), the default provider and role models, and which env file each value came from — secrets are masked. You are ready when your chosen provider's credential is present and the defaults point where you intend.

Upgrading from a pre-0.42 release? Run the migration first. The full provider and field reference lives in theconfiguration documentation.

step 04

Connect your agent

Connect Triss to the host where you will use it — the guide for each host is below. If the Easy wizard in step 3 already wired the host you selected, verify the result with triss mcp status and restart that host's session instead of re-running setup. Terminal users skip host wiring entirely — the CLI is the whole interface for that target.

Claude Code

# Claude Code — explicit global setup
triss mcp install --target claude --global
triss init --target claude --global

triss mcp install --target claude --global registers the Triss MCP server in Claude Code's global agent config; triss init --target claude --globaladds the Triss delegation rules at the same global scope. Restart your Claude Code session so the new server and rules load, then confirm the registration with triss mcp status or triss status.

For a single-project registration, triss mcp install also accepts--local, which writes ./.mcp.json in the current project; the global install follows your session and does not pin one project. After connecting, triss agent-help --target claude prints the full delegation cookbook for the Claude flavour.

Codex

# Codex — explicit global setup
triss mcp install --target codex --global
triss init --target codex --global

Both commands target Codex's global config — Triss has no project-local MCP config for Codex. Restart the Codex CLI after registering, then verify withtriss mcp status. Current releases of the Codex CLI also shipcodex mcp list to show registered servers; check your installed Codex CLI for the exact command. After connecting, triss agent-help --target codexprints the full delegation cookbook for the Codex flavour.

Terminal

No host setup is needed for terminal use — the Triss CLI you installed in step 2 is the whole interface for this target. No MCP registration or agent rules are involved; continue with step 5 and run your first delegated task directly in the terminal.

step 05

Delegate a real task

From the root of a project that has a README.md, ask a focused question about it:

$ triss ask --paths README.md \
    --question "What does this project do, and which setup steps does its README require? Cite the relevant lines."

This is an example input, not a recorded answer — read the output your own run produces. If your project has no README.md, point --pathsat an existing text file. Check the cited lines in the sources before you rely on the answer: model answers can be wrong.

For a recorded, source-linked research run over real Triss sources, see theresearch workflow.

Upgrading from older Triss versions

Triss 0.42 replaces worker configuration and model presets with unified provider profiles. After installing the update and before running model commands:

triss migrate
triss status

Restart MCP hosts and agent sessions after migration. Do not downgrade to a pre-0.42 release after migration.

Advanced model and engine setup

The steps above use your chosen provider directly. These optional setups route work through a coding engine instead; see the linked engine documentation for the full contracts.

Optional: use the OpenCode 2 beta engine
$ npm install -g @opencode-ai/cli@beta
$ triss coder init --engine opencode2 --provider opencode-zen
$ triss coder run --engine opencode2 --model opencode-zen/deepseek-v4-flash-free "Implement the task"

OpenCode 2 0.0.0-beta-19059 or newer is accepted by default. Triss never pins an exact build and checks required option declarations rather than help-description wording. Lower or malformedTRISS_CODER_OPENCODE2_VERSION values fall back to that floor. Seedocs/engines/opencode2.md.

Optional: use the native OMP coder engine
$ curl https://omp.sh/install | sh
$ triss coder init --engine omp --provider opencode-go
$ triss coder run --engine omp --model opencode-go/deepseek-v4-flash "Create result.txt containing OMP_OK"

The OMP runtime must meet Triss's effective minimum (18.0.6 or newer) and capability checks before it is used. The manualcurl | sh line above is one conscious way to install it; the setup wizard can also install a missing engine when installation is part of the plan it shows before apply, and headless installation requires --install. Direct runtime use still requires a compatible binary onPATH. Installing OMP does not grant permission to send a task or credentials, and OMP defaults to worktree isolation — which is not host-filesystem confinement. The default credential mode is best_effort_raw; add--protect-credentials when the selected key must stay behind the parent-owned proxy. Seedocs/engines/omp.md.

Optional: use OpenCode Go Muse for ask and review
$ triss coder init --engine opencode --provider opencode-go
$ triss config set TRISS_DEFAULT_PROVIDER opencode-go
$ triss config set TRISS_DEFAULT_ENGINE opencode
$ triss config set TRISS_OPENCODE_GO_MODEL muse-spark-1.3-contributor
$ triss config set TRISS_OPENCODE_GO_SMALL_MODEL muse-spark-1.3-contributor
$ triss ask --paths 'src/**/*.js' --question "find correctness defects"
$ triss review

Run coder init first: it verifies OpenCode, configures the key and provider, and writes the required engine configuration. The fourconfig set commands then make bare triss ask andtriss review use opencode-go/muse-spark-1.3-contributor. Every call installs and verifies a transient primarytriss-readonly-projection agent that denies every tool by default and receives the complete request context in the prompt; it has no ambient file, shell, edit, skill, or delegation access. Pass a quoted glob such assrc/**/*.js because directories are not read recursively. Explicit flags still win; add --protect-credentials when the key must stay behind the parent-owned proxy.

Alternative installation methods

npm is the primary route shown in step 2. The same public commands for the other package managers, the standalone installer, and a source build:

pnpm
$ pnpm add -g triss-coworker
yarn
$ yarn global add triss-coworker
Standalone installer (no npm)
$ curl -fsSL https://raw.githubusercontent.com/ayleen/triss-coworker/main/install.sh | bash

Runs install.sh from the repository. It still requires Node.js.

From source
$ git clone https://github.com/ayleen/triss-coworker.git
$ cd triss-coworker && npm install && npm link
$ triss --version && triss status

Verify with triss status after linking, and keep in sync with the README.