Use File Mentions and Image Attachments to Give Agents Better Context

Developers searching for better AI coding agent context are usually not asking for a longer prompt. They are trying to stop Claude Code or Codex from guessing which file matters, which screenshot shows the bug, or which part of a large repo should be treated as the source of truth.

That is the gap Junction's rich chat workflow is meant to close. Junction gives you a browser and mobile control surface for local AI coding agents, while the daemon runs on your own machine and the agent executes where your code already lives. In that setup, file mentions and image attachments are not decorative chat features. They are a way to make a remote control surface precise enough for real engineering work.

This post covers when to use file mentions, when to add screenshots or images, and how to keep context focused enough that an agent can act without wandering through the whole repository.

Why agent context usually fails

Most failed AI coding runs do not start with a bad model. They start with a vague handoff.

Examples:

• "Fix the dashboard layout."
• "Make the mobile screen look better."
• "Investigate why this test is flaky."
• "Update the settings page."

Those prompts may be clear to the developer who has the repo open, the failing screen visible, and the relevant files already in their editor. They are not automatically clear to an agent process. The agent has to infer the route, component, state hook, test, fixture, style layer, and intended behavior.

A better handoff gives the agent a narrow set of facts:

• The file or files that define the current behavior.
• The screen, screenshot, or visual state that explains the problem.
• The expected result.
• The boundaries of the task.
• The checks that should pass before the work is done.

Junction helps because the browser/mobile app can carry those inputs to a local Claude Code or Codex session without turning the work into a cloud sandbox. The daemon still controls the local process. The code stays on your machine. The agent just receives better context through the control surface.

Use file mentions when the source of truth is in code

File mentions are best when the prompt depends on specific implementation details. Instead of asking the agent to "find the billing plan copy," point it at the files that define that copy.

For example:

Use the pricing data and billing plan UI as the source of truth.
 
The Free plan should still read as one saved daemon connection and two open chats.
Update the related helper copy so it stays consistent.
 
Mentioned files:
- packages/site/src/data/pricing.ts
- packages/app/src/features/billing/billing-plan-data.ts

That is stronger than a broad instruction because it gives the agent a bounded map. The agent can still search if it needs supporting context, but it does not have to discover the primary files from scratch.

File mentions are especially useful for:

• Pricing or plan copy that must match product rules.
• Component bugs where the route and file are already known.
• Tests that fail in a known area.
• Refactors that should stay within one module.
• Documentation updates that must mirror a local config file.
• Agent instructions stored in repo files such as CLAUDE.md or AGENTS.md.

This is different from using Junction's file browser to inspect output after a run. File mentions improve the input side of the workflow. The file browser helps you inspect what happened afterward.

Use image attachments when the problem is visual

Screenshots are often the fastest way to explain a UI defect. A written prompt like "the spacing feels off" is ambiguous. A screenshot with a clear instruction is much better.

For example:

The attached screenshot shows the mobile settings drawer at 390px wide.
 
Fix the wrapping in the plan selector. Do not change the plan names, prices, or billing logic.
Keep the existing component structure unless a smaller local extraction is needed.

That prompt does three useful things:

• It tells the agent what the image represents.
• It says what should change.
• It says what must not change.

In Junction, image attachments fit naturally into the same chat surface as the rest of the run. You can attach the screenshot, mention the relevant files, start the agent, then monitor output and review diffs from the same browser or phone. The provider runtime determines exactly how image input is interpreted, so keep prompts explicit and verify the resulting diff instead of assuming the screenshot alone is enough.

Image attachments are most useful for:

• Mobile layout bugs.
• Visual regressions.
• Error states that are easier to recognize in a screenshot than in logs.
• Charts, tables, or dense dashboards.
• Before/after UI comparisons.
• Design QA where the agent needs to connect a visual symptom to a code path.

They are less useful for backend defects, security reviews, dependency upgrades, or tasks where the source of truth is a failing test.

Combine files and images for UI fixes

The strongest handoff often uses both. The image shows the symptom. The file mentions show where the agent should start.

The attached screenshot shows the route settings page on mobile.
 
Start with these files:
- packages/app/src/features/switchboard/components/repository-detail/repository-detail-settings-tab.tsx
- packages/app/src/features/switchboard/components/route-team-settings-section.tsx
 
Fix the plan mode and automation controls so labels wrap cleanly and the switches stay aligned.
Do not change route persistence, provider options, or pricing gates.
Run the relevant tests and typecheck before stopping.

That prompt is actionable because it narrows the search space and names the risk. Without the file mentions, the agent may spend time finding the component. Without the screenshot, it may fix the wrong layout state. Without the "do not change" line, it may over-edit product logic that only needed styling.

Keep the context narrow

More context is not always better. Dumping ten files and five screenshots into a prompt can make the run harder to supervise. The agent may treat all of them as equally important.

Use this rule of thumb:

If you are not sure which files matter, start with a planning or investigation prompt instead of guessing. Ask the agent to identify the files it expects to touch, then continue only after the plan is specific enough to review.

What this looks like from a phone

The mobile workflow is where this matters most. When you are away from your desk, you probably do not want to run terminal commands, copy stack traces, and paste long file paths manually.

A practical Junction flow looks like this:

1. Open the Junction app from your phone.
2. Pick the daemon connected to the machine where the repo lives.
3. Start or resume the Claude Code or Codex chat for the workspace.
4. Attach a screenshot of the bug or mention the files that define the behavior.
5. Give the agent a narrow task and explicit boundaries.
6. Watch the output stream for drift, permission prompts, or errors.
7. Review the diff before turning the work into a pull request.

The important part is not that the phone replaces your workstation. It does not. Your workstation still hosts the daemon, the repo, the agent process, provider auth, Git credentials, and local tooling. The phone becomes a control surface that can send focused context and supervise the run.

Objections and tradeoffs

File mentions can become stale if the repo moves. If a file was renamed, the agent may need to search anyway. That is fine, but make the prompt clear that the mentioned file is a starting point, not a permission slip to ignore current code.

Screenshots can be ambiguous. An agent can see that something is wrong without knowing the intended behavior. Pair images with plain-language acceptance criteria.

Attachments can also tempt teams to skip tests. Do not let them. Visual context should guide the fix, not replace verification. Ask the agent to run the relevant checks, then review the diff yourself.

Finally, do not attach secrets, private customer data, or anything the agent does not need. Junction is local-first, and the daemon runs where your code lives, but your provider runtime still receives the prompt context needed to perform the task. Keep prompts scoped to the work.

A better context checklist

Before starting a meaningful agent run, check:

• Did I name the exact behavior I want changed?
• Did I mention the files that are likely to matter?
• Did I attach a screenshot only if visual context is useful?
• Did I say what should not change?
• Did I include the validation command or expected check?
• Did I keep the prompt short enough to supervise?

If the answer is no, improve the prompt before launching the run.

Junction is built for this kind of controlled handoff: local execution, rich chat input, live output streaming, file and diff review, and mobile supervision in one workflow. Start with the setup guide if you want to try this with one daemon and one Claude Code or Codex workflow.