Guide

Preparing failure logs for coding agents

A coding agent can only reason from the evidence you give it. Before using tokensift, capture the smallest log range that still explains what command ran, where it failed, and what exact error appeared.

This guide focuses on practical log preparation. It helps you avoid two failure modes: pasting a whole terminal session with thousands of irrelevant lines, or pasting only the last line and losing the context needed for a fix.

Open the main Sift tool Use the workflow

Preparation workflow

1. Start at the command

Include the command that produced the failure. Flags often matter more than surrounding chat. For example, batch size, precision, test node id, build target, Docker progress mode, and package manager are all useful evidence.

If the command is missing from the terminal transcript, add a short plain-language line before the log, such as: "I ran pnpm build in a Vite project after upgrading TypeScript."

2. Keep the first real error and the final wrapper

The first real error often names the root cause. The final wrapper often names the failed process or exit code. Keep both when they differ.

Example: a Docker build may first show "No matching distribution found" and later show "failed to solve: exit code: 1." The package error is the likely cause; the solve line confirms the failed build step.

3. Keep the nearest owned location

For Python, keep the top non-site-packages frame and the failing code line. For TypeScript, keep the file, line, column, and TS code. For tests, keep the failing test id and assertion. For Docker, keep the Dockerfile line and failing RUN command.

4. Add only context that changes the fix

Useful context includes package versions, GPU memory, base image, OS, recent dependency upgrade, CI-only environment, or a feature flag. Avoid adding general project descriptions unless the failure cannot be understood without them.

Recommended capture ranges

Python traceback: command, traceback header, all user-owned frames, final exception, and any wrapper exit line.
CUDA/PyTorch OOM: command, model/batch/precision flags, OOM line, GPU memory stats, top user frame, and relevant CUDA/PyTorch version line.
TypeScript build: build command, TS error line, source location, expected/actual type detail, import trace if present, and package-manager exit line.
Docker build: docker command, failing BuildKit step, Dockerfile context, package-manager error, base image, and final failed solve line.
pytest: pytest command, failing node id, assertion, expected/actual values, fixture/setup error if present, and short test summary.
Generic terminal failure: command, first error, final error, exit/status/errno line, nearby path or config line, and version/platform line if relevant.

What to remove before using the tool

Redact sensitive material before pasting whenever possible. TokenSift applies deterministic patterns for several common secret formats, but that pass is a safety net rather than a complete data-loss-prevention check.

Previous unrelated commands from the same terminal pane.
Long success sections before the failing command.
Repeated progress output, watcher refreshes, heartbeat lines, and timestamp-only blocks.
Large source files pasted after the log unless the error line points to that source and the small excerpt is necessary.
Secrets, credentials, tokens, private URLs, customer data, and internal identifiers that are not needed for debugging.

Verified example

This is a raw log excerpt, not a command sequence to run. It was checked against the current tokensift parser output.

Raw excerpt with enough context

$ pnpm build
vite v5.4.2 building for production...
transforming...
src/pages/report.tsx:42:17 - error TS2322: Type 'string | undefined' is not assignable to type 'string'.
  Type 'undefined' is not assignable to type 'string'.
42   <Report id={params.reportId} />
                   ~~~~~~~~~~~~~~~
Found 1 error in src/pages/report.tsx:42
ELIFECYCLE Command failed with exit code 2

Conservative brief

Debug TypeScript/build failure.

Type:
- TypeScript / npm / Vite / Next.js (high confidence)

Keep:
- cmd: pnpm build
- error: src/pages/report.tsx:42:17 - error TS2322: Type 'string | undefined' is not assignable to type 'string'.
- build: ELIFECYCLE Command failed with exit code 2
- type: Type 'undefined' is not assignable to type 'string'.
- env: vite v5.4.2 building for production...

Folded:
- build/cache/asset noise folded: 2

Ask: root cause, smallest fix, verify command.

Manual note examples

Add a short note after the cleaned brief only when the log cannot show the relevant fact by itself.

"This started after upgrading pydantic from v1 to v2."
"This fails only in CI; local pytest passes with the same command."
"The private package is available in our registry, but the Docker build runs without the registry token."
"The GPU is shared with another process during the training run."

Prompting checklist

Ask for a root cause, not a broad tutorial.
Ask for the smallest fix that matches the evidence.
Ask for one or two verification commands.
Tell the agent when it should avoid changing unrelated files.
Say when the log is partial or when important project context is missing.

Limits

Some failures need more than a log: source code, config, dependency lockfiles, screenshots, traces, or access to a runtime environment. A compact brief is the right first message when the log is enough to orient the agent. It is not enough when the failure depends on hidden state.

tokensift's approximate token counts are for before/after comparison only. They are not exact model tokenizer counts.

Submission storage boundary

When a visitor clicks the Sift button on the backend-hosted deployment, tokensift stores the submitted raw input, generated output, user IP address, user agent, and KST timestamp in a private SQLite database controlled by tokensift. Backend-hosted raw submissions in SQLite and private operator JSONL preview logs are retained for up to 30 days by default for diagnostics and parser improvement. Raw logs are not sent to analytics or ads.