Reference

Agent mode output

Every Tinka Command has two audiences. People get styled text, and agents get Agent mode: no prompts, no colors and exactly one JSON object on stdout when the Command finishes. Agents spend their context window on every byte they read, so a fixed, parseable shape saves tokens and removes guesswork.

When Agent mode turns on

Tinka checks four signals in order, and the first one that applies decides:

The --json flag. --json turns Agent mode on and --json=false turns it off, whatever the environment says.
The TINKA_AGENT variable. 1 forces Agent mode and 0 disables it.
Agent detection. AI_AGENT or AGENT name the agent explicitly. Otherwise Tinka recognizes the variables that Claude Code, Codex, Cursor, Gemini CLI, Copilot, Amp, OpenCode and other agents set.
Otherwise the output is for people.

Some variables also appear in terminals that people type into, because IDEs set them for their integrated terminal. CLAUDECODE, CURSOR_TRACE_ID and REPL_ID therefore only count when stdin is not a terminal.

The result object

A successful run prints one line, with the Command’s own fields between result and duration_ms:

Terminal

tinka version --json

Output

{"command":"version","result":"ok","version":"v1.0.0-alpha.1","go":"go1.27.2","platform":"linux/amd64","duration_ms":0}

Every result carries these keys:

commandstring: The Command that ran, without the program name, such as version or db ping.
resultstring: ok when the Command succeeded, error when it failed.
duration_msnumber: How long the Command took, in milliseconds.

The keys error, log and tail appear only on failure. A Command never uses any of these six names for its own fields.

Failed runs

A failed run replaces the Command’s fields with an error object that tells the agent how to recover. This example comes from tinka verify, the Command contributors run inside the Tinka repo:

Output

{"command":"verify","result":"error","error":{"code":"check_failed","message":"gofmt failed","fix":"Run `gofmt -w .`"},"log":"/tmp/tinka-3342195989.log","tail":"✗ gofmt\nposts.go","duration_ms":25}

error.codestring: A stable snake_case identifier such as check_failed or usage. Match on this, not on the message.
error.messagestring: What went wrong, in one sentence.
error.hintstring: Why it happened or what to check. Omitted when there is nothing to add.
error.fixstring: The command or change that resolves the error. Omitted when there is no single fix.
error.docsstring: A link to the page that explains the error. Omitted when there is none.
logstring: The path of the file holding everything the Command printed while it ran. Present only when the Command wrote progress before failing.
tailstring: The last 50 lines of that file, without terminal colors.

In Agent mode a Command writes its progress to a temporary log file instead of the terminal. Tinka deletes the file when the Command succeeds and keeps it when it fails, so you can read the full output.

Exit status

The exit status agrees with result, so scripts can rely on either:

| Status | Meaning | |---|---| | 0 | The Command succeeded | | 1 | The Command failed | | 2 | The Command was used wrongly: an unknown Command or flag, or a missing argument |

Listing Commands

Running a group without a Command, or passing --help, lists the available Commands as JSON:

Terminal

tinka --help --json

Output

{"command":"tinka","result":"ok","summary":"The Tinka CLI","commands":[{"name":"version","summary":"Print the Tinka version"}],"duration_ms":0}