# Script

Finds tool sequences that repeat identically across many runs and look like a deterministic script.

---

Script flags sessions whose tool-call sequence is structurally identical across many runs. When the same sequence shows up dozens of times, a deterministic shell script could replace the agent for that workload.

```bash
tj optimize script
```

`script` is [skipped](/docs/optimize-more#when-an-analyzer-does-not-run) for a window an interactive coding agent dominates. An absent finding there means the analyzer never ran.

## What it does

A session's signature is the ordered tuple of `(tool_name, arg_shape)` pairs across its tool spans. `arg_shape` is the *type* of each argument, not its value:

| Category | Matches |
|---|---|
| `file_path` | strings starting with `/`, `~`, `.`, or matching `[A-Z]:\` |
| `command_string` | strings starting with a known shell command (`git`, `npm`, `pytest`, …) |
| `json_object` | dict values |
| `array` | list values |
| `number`, `boolean` | scalar primitives |
| `string` | generic string |

Argument keys are sorted before the signature is built, so dict order doesn't change the result. Clustering by shape rather than value is what makes the analyzer useful. A "deploy staging" run and a "deploy prod" run touch different arguments but share the same structural shape, so they land in the same cluster. That shape is what would map cleanly to a parametrised script.

## Thresholds

A cluster needs at least 20 sessions with an identical signature before it's flagged. v1 leans hard toward false negatives: one false-positive recommendation that a user investigates and rejects erodes trust faster than a missed opportunity.

Without `[capture] tool_inputs = true` the analyzer can't read `arg_shape`. It degrades to clustering by tool-name sequence alone and marks the finding `degraded: true` so the weaker signal is disclosed. Even degraded it can be useful — a session that runs `(bash, bash, bash, pm2)` 23 times is probably a deployment pattern regardless of the exact shapes.

## How to read the output

Each flagged cluster shows its signature and how many sessions share it. That count is the size of the opportunity: a script would eliminate the agent cost on every one of those runs. Review the sessions in a cluster before you write the script.

## Honesty caveat

Script confidence is structural, with an explicit caveat about reviewing each cluster before replacing it. The analyzer claims structural identity, which is a different and weaker thing than quality equivalence:

> Structural shape matches. Review the cluster before replacing it with a script.

## See also

- [Reuse](/docs/optimize-reuse) — repeated planning that can be templated
- [Downsize](/docs/optimize-downsize) — flag sessions whose shape matches a cheaper-model candidate