Use these examples when wiring CodeInsight into Codex, Claude Code, Cursor, or
another MCP-capable coding agent. The configuration starts the server; the
integration policy tells the agent how to consume agent_first_read.execution_plan[]
without falling back to broad file scans.
For server setup snippets, see MCP client configuration. For the complete field contract, see Client workflow.
Every client should treat agent_first_read.execution_plan[] as the ordered action
plan after the server has completed the first-read route.
1. Call agent_first_read with root, task, and token_budget.
2. If continuation_summary.status is blocked_no_seed, ask for a seed file or
symbol and do not broad-read the repository.
3. Read context_pack.files[] in reading_plan[] order.
4. Use agent_first_read.current_reading_step for the first checklist row.
5. Use reading_plan[].focus as the compact scan label.
6. Use reading_plan[].question as the local checklist for the selected file.
7. Use reading_plan[].reason as the current-step instruction.
8. Use reading_plan[].selection_rank as the candidate rank audit trail.
9. Use reading_plan[].selection_reason only as selection evidence.
10. Show context_pack.read_less as first-read source-line reduction evidence.
11. Call execution_plan[].suggested_tool only when the current step needs deeper
evidence.
12. Use continuation_summary only after selected context has been read.
13. Use continuation_summary.next_action and omitted_candidates[] to explain any
follow-up context request.
14. Run the deferred impact_analysis before edits.
Do not treat route[] and execution_plan[] as the same thing:
route[]explains which tools CodeInsight already ran.execution_plan[]tells the client or agent what to do next.
Use this prompt when a client accepts plain instructions but not repo-specific instruction files:
Use CodeInsight for repository first reads.
When the task is broad, call agent_first_read with the repository root, the user's
task, and token_budget 6000. Follow agent_first_read.execution_plan[] in order:
read_selected_context first, use_current_reading_step_suggested_tool only when
the current file needs deeper evidence, use_continuation_if_needed only after
selected context is consumed, and review_impact_before_edits before changing
code.
Read context_pack.files[] in reading_plan[] order. Treat
agent_first_read.current_reading_step as the first checklist row,
reading_plan[].focus as the compact scan label, reading_plan[].question as the
local checklist for the selected file, reading_plan[].reason as the instruction
for the current file, reading_plan[].selection_rank as the candidate rank audit
trail, and reading_plan[].selection_reason as evidence for why the file was
selected, not as a replacement for focus, question, reason, or rank.
Use context_pack.read_less only to report source-line reduction for the first
read; it is not permission to skip selected context.
If continuation_summary.status is blocked_no_seed, ask for a seed file or
symbol and do not broad-read the repository.
Add the MCP server in ~/.codex/config.toml as shown in
MCP client configuration. Then put this policy in
the repository AGENTS.md:
When CodeInsight MCP is available, call agent_first_read before broad repository
reading. Follow agent_first_read.execution_plan[] exactly:
1. read_selected_context: read context_pack.files[] in reading_plan[] order.
2. use_current_reading_step_suggested_tool: use the current step's
suggested_tool only if the selected file needs deeper evidence.
3. use_continuation_if_needed: inspect continuation_summary only after selected
context has been read.
4. review_impact_before_edits: run the deferred impact_analysis before editing.
If continuation_summary.status is blocked_no_seed, ask for a seed file or
symbol and do not broad-read the repository.
Use reading_plan[].question as the local checklist,
reading_plan[].focus as the compact scan label, reading_plan[].reason as the
current-step instruction, and reading_plan[].selection_rank plus
reading_plan[].selection_reason as selection evidence.
Use context_pack.read_less as reporting evidence for how much source text the
first read avoided.
After adding the stdio MCP server, place the same policy in project instructions or paste it at the start of the session:
Use CodeInsight as the first-read router for this repository. Start broad
questions with agent_first_read. Follow execution_plan[] before raw repository
search: read selected context first, use the current reading step's
suggested_tool only when needed, use continuation only after selected context,
and review impact before edits.
Summaries should name the files read from context_pack.files[] and mention any
continuation or impact-analysis evidence used.
After adding codeinsight to Cursor MCP configuration, add this to Cursor rules
or paste it into the agent prompt:
For repository-understanding tasks, prefer CodeInsight agent_first_read before
broad file search. Use agent_first_read.execution_plan[] as the UI/agent checklist:
read_selected_context -> use_current_reading_step_suggested_tool ->
use_continuation_if_needed -> review_impact_before_edits.
Only offer continuation_summary.suggested_tool after selected context has been
read. Use question for the local checklist, reason for the agent's reading
instruction, selection_rank for candidate order, and selection_reason for
display or audit labels.
If continuation_summary.status is blocked_no_seed, ask for a seed file or
symbol instead of broad file search.
Clients with a visible tool panel should render:
execution_plan[].actionas the next-action checklist.execution_plan[].statusas the availability state.execution_plan[].instructionas the agent-facing instruction.execution_plan[].suggested_toolas an optional action button that becomes active only after the matching selected context file is read.agent_first_read.current_reading_stepas the first checklist row.reading_plan[].focusbeside each selected file as the compact scan label.reading_plan[].questionbeside each selected file as the local checklist.reading_plan[].reasonbeside each selected file.reading_plan[].selection_rankas the candidate rank.reading_plan[].selection_reasonas compact evidence text.context_pack.read_lessas source-line baseline, selected-line, avoided-line, reduction, and ratio evidence.continuation_summary.next_actionas the post-read continuation decision.continuation_summary.suggested_toolas a continue action only after the selected context is insufficient for the current task.impact_analysisas a pre-edit review step before any edit controls are treated as ready.
Suggested-tool buttons should be disabled or visually secondary until the selected file for the current reading step has been consumed. Continuation buttons should stay disabled or hidden until selected context has been consumed and the task still needs more evidence. Impact-review controls should be shown after the first read and before edits; they should not be labeled as a safety guarantee.
A working integration should pass these checks:
- The first broad task calls
agent_first_read. - A
blocked_no_seedresponse asks for a seed file or symbol instead of broad repository reading. - The agent reads selected files in
reading_plan[]order. - The agent can render
agent_first_read.current_reading_stepas the first checklist row. - The agent can show
reading_plan[].focusfor each selected file. - The agent can answer
reading_plan[].questionfor each selected file. - The agent can explain
reading_plan[].selection_rankandreading_plan[].selection_reasonfor selected files. - The client can display
context_pack.read_lesswithout using it as a shortcut around selected context. read_selected_contexthappens beforeuse_current_reading_step_suggested_tool.continuation_summary.suggested_toolis not used before selected context.impact_analysisis reviewed before edits.- The final response can explain which selected files were read and why they were selected.