# Agent mode output

> How Tinka Commands answer when an AI agent runs them, with one JSON result per run.

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:

1. The `--json` flag. `--json` turns Agent mode on and `--json=false` turns it off, whatever the environment says.
2. The `TINKA_AGENT` variable. `1` forces Agent mode and `0` disables it.
3. 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.
4. 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.

:::tip
If your agent runs inside a container that does not pass its variables through, set `TINKA_AGENT=1` in the container, or pass `--json` explicitly.
:::

## The result object

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

```sh
tinka version --json
```

```text title="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:

::::options

:::option{name="command" type="string"}
The Command that ran, without the program name, such as `version` or `db ping`.
:::

:::option{name="result" type="string"}
`ok` when the Command succeeded, `error` when it failed.
:::

:::option{name="duration_ms" type="number"}
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:

```text title="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}
```

::::options

:::option{name="error.code" type="string"}
A stable snake_case identifier such as `check_failed` or `usage`. Match on this, not on the message.
:::

:::option{name="error.message" type="string"}
What went wrong, in one sentence.
:::

:::option{name="error.hint" type="string"}
Why it happened or what to check. Omitted when there is nothing to add.
:::

:::option{name="error.fix" type="string"}
The command or change that resolves the error. Omitted when there is no single fix.
:::

:::option{name="error.docs" type="string"}
A link to the page that explains the error. Omitted when there is none.
:::

:::option{name="log" type="string"}
The path of the file holding everything the Command printed while it ran. Present only when the Command wrote progress before failing.
:::

:::option{name="tail" type="string"}
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:

```sh
tinka --help --json
```

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

See also: [tinka version](version.md)