Context

Context is everything that helps an agent understand the job before it acts.

Some context comes from Coldtea: the project path, the active worktree, the task you started from, and the pane the agent is running in. Some context comes from your repo: files, tests, scripts, and local instructions like AGENTS.md. Some context has to come from you because no tool can guess it safely.

If it matters, say it.

Context is not one bucket

Think of context in layers:

1. Workspace context — the open project, active tab, pane, branch, and worktree.
2. Task context — the task description, constraints, latest plan, and session logs.
3. Repo context — source files, docs, tests, scripts, and project instructions.
4. Prompt context — the specific instruction you give this turn.
5. Agent context — whatever the agent CLI and model provider keep in its own session.

Those layers do not all behave the same way. A task description is durable. A prompt is temporary. A terminal screen can scroll away. A provider's model context has limits.

Start from the durable stuff

For task-linked work, the task should carry the facts a reviewer will need later:

• What problem should be solved.
• What outcome counts as done.
• What should not be touched.
• Which checks matter.
• Links or screenshots that explain the request.

Then the prompt can stay short. You can ask the agent to read the task, inspect the repo, propose a plan, and run a named check. That is better than hiding the real requirements in a one-off terminal message.

Pass precise local context

When a file, command, or error matters, name it.

Useful:

Review `apps/docs/content/docs/start/install-coldtea.mdx`. The issue is the sentence about layout persistence. It should only claim recent-project persistence.

Less useful:

Fix the overclaim in the docs.

The first prompt tells the agent where to look and what kind of claim is unsafe. The second prompt makes the agent rediscover your review comment and guess the boundary.

Use the editor when words are clumsy

Sometimes the best context is a selected block of code, a diff hunk, or a file already open in the editor. Send that context as an annotation where the workflow supports it, or paste the file path, range, or relevant snippet into the prompt.

The rule is simple: send the smallest context that preserves the point. A whole file is useful when the whole file matters. A selected function is better when the bug is inside that function.

Do not assume the agent sees everything you see

Coldtea can keep terminal output, files, tasks, and panes close together, but that does not mean every visible thing is automatically inside the agent's next model call.

If a review comment, failed command, or design constraint is required for the next step, put it in the task, plan, log, or prompt. Make the important context explicit.

Context has a privacy cost

Local files and prompts may be sent to the agent provider according to the agent CLI you launched and its configuration. Coldtea hosts the session; it does not change the provider's data handling rules.

Do not paste secrets into prompts. Do not ask an agent to inspect credentials unless you would be comfortable sending that same material through the agent's normal terminal flow.

Next: tasks, plans, and logs explains where durable context lives.