Insilode GitHub

Agent tools

The insilode MCP server

Claude Code over /ide only shows its model the getDiagnostics tool, so Insilode ships its own small MCP server, insilode, that lets an agent work with the editor. All tools are read, display or open only: they write no files and run no commands, and paths must lie inside an open workspace folder.

Tool What it does
open Opens a file at a line or range, without taking focus
open_diff Opens git changes (modified, staged, deleted, new) in the multi-file diff view, optionally also on the flow canvas; base picks what they are measured against: uncommitted (HEAD), the whole branch, or the last commit
get_diagnostics The errors and warnings the language servers report now, for a file or the whole workspace
find_symbol Searches classes, methods, functions and fields by name
go_to_definition, find_references Where a symbol is defined (with its signature), and every place that uses it
find_entry_points Free-text search over endpoints and jobs ("delete user" finds DELETE /users/{id})
show_flow, flow_text Opens the flow canvas, or returns the call chain as compact text (files, call lines, tables touched; ~table after a database line means the table name is a guess)
impact Who calls a method, and which entry points reach it (through interfaces, mediators and, as a guess, HTTP calls and messages between services). With table or entity instead of a method: the endpoints that write that table and the endpoints that read it, each with the method and database card it goes through, a guess marked ~table?, and a "not checked" line (see Tables and entities). A migration file or an entity file alone (file without method or line) answers the same for the tables it changes, with what a migration adds and drops and the code that may still use a dropped column
get_context Active file, selection, flow on the canvas, open tabs, git changes, diagnostics, boards
draw_board, update_board The agent draws a flow, plan, class, ER, sequence, architecture or state board (format and lint: boards.md), explains it with steps, and ticks its steps off as it works
board_from_code Generates a board from the index instead of the agent drawing it: sequence (the calls of an endpoint or method, in order, between classes; HTTP, topic, mediator and name-only hops are dotted and marked ?), er (tables with columns, PK/FK, relations and cardinality from the entity and migration readers), architecture (modules or packages and their dependencies; C4 container level with several services), state (an enum and its transitions, only where a method assigns a value and checks the previous one; otherwise it answers with the reason it drew nothing). Takes a scope per kind and optional title, description and notes (never nodes or edges). Every node carries its symbol and file:line; boards are capped (8 lifelines and 30 messages, 20 tables, 30 boxes) and the result lists what was cut or guessed. The command Insilode: Board from Code… does the same from the canvas
tour, tour_control The agent walks the user through code on the flow canvas: a cursor moves from card to card, the rest dims, the lines it names light up and its caption says why. The tool returns at once with each step marked ok, moved, offflow (not on the drawn flow: shown as a side card) or missing (with the closest names); the user steps through it by hand. tour_control answers the user's questions (note, go, resume) or closes the tour
check_skeleton Skeleton first (opt-in, insilode.skeletonFirst.enabled). Called once after a plan that adds types is approved: says the mode is off (implement as usual), or asks for the design as a class/ER board and a stop; later returns the developer's skeleton against that design, each planned type and member matches, MISSING or DIFFERS with what the code has. Read-only. See skeleton-first.md
  • Agents started from the Agents dock get the server automatically (flow.agents.mcp, on by default; it adds --mcp-config and keeps your own MCP servers).
  • A claude you start yourself gets it after the command Insilode: Connect Claude Code Tools (MCP). It shows the exact claude mcp add it will run and changes your Claude Code user configuration only when you confirm; Disconnect removes it.
  • Each Insilode window lists itself in ~/.insilode/bridge/<pid>.json (loopback port and token); the server picks the window whose workspace folder contains its working directory.
  • In plan mode, the plan an agent submits is drawn as a board (flow.agents.planBoard), its steps move to doing and done as files are edited, and when a turn ends the Agents dock lists the flows it touched (flow.agents.turnImpact), and the table, with its endpoint count, when an edit landed in an entity. That list follows the methods the turn's edits landed in, and names them on hover; an edit outside every method (an import, a field) counts its whole file. Boards open as a Markdown preview with a Mermaid diagram; Insilode: Show Board… lists them.

Guided tours. The server instructions, the tour description and the tour_guide prompt tell an agent to explain code by showing it: "walk me through how X works", "explain this flow" or "anlat" should end in a tour call, not a long text answer (show_flow and flow_text point there too). To explain code, an agent calls tour with 3 to 12 steps in the order the code runs. A step names its code by file + method (it survives edits) with a line hint, and lines for the few lines the caption talks about; table points at a database card; a step with only a caption is an intro or an outro. flow says which canvas to play on: an entry point id, a file with method, or {"changes": true} for the git changes; left out, the tour plays on the canvas the user has open. Limits: 30 steps, captions of 600 characters in plain text (code in backticks is shown as code), 3 highlighted ranges of 80 lines, one tour at a time (a new one replaces it). A path outside the workspace, a field the tool does not know or a limit that is exceeded is an error that names it. The MCP prompt tour_guide (in Claude Code: /mcp__insilode__tour_guide) holds the advice for writing good tours. A tour file played from the command palette (Insilode: Play Tour from File…) uses the same format and checks; see editor/extensions/flow-view/test/tour-fixtures.

Asking during a tour. The tour bar has an ask box (/ focuses it; a tour of your own changes has none). A question pauses the tour on its step and goes, as a prompt that quotes it as the user's own words, to the agent that made the tour: agents started from the Agents dock tell the insilode server their session (INSILODE_SESSION, one MCP config file per session), and a tour of an agent Insilode did not start has a plain pointer and sends the question to the agent chosen for questions. The agent answers with tour_control note (pinned to the step's card and shown under its caption until the tour ends, up to 10 per step), may go to a step that answers it better, and then resume; the user may also press play. go is accepted only while the tour is paused or waiting for an answer. The cursor takes the agent's name and colour from the dock.

Point and ask. On any card, the ? tool in its header, Alt+click, or ? with lines selected in its code opens a small box at the card; the selection (or the whole method) is what is asked about. The question goes to the agent chosen for questions with the code, the lines and the flow, and the agent answers by playing a short tour on the same canvas; the question is that tour's first note. An agent without the insilode tools answers in text.

Skeleton first. Each agent's row in the Agents dock has one Skeleton button (pressed when on; its tooltip says what it does). It lets the developer write the structure of a change themselves, for that agent only; the setting insilode.skeletonFirst.enabled (off by default) is the starting value for agents not switched by hand. Before its first edit for a request or an approved plan that adds or changes types (plan mode or not), the agent calls check_skeleton, draws its design with draw_board (every new or changed type with the members to write), stops, and tells the developer which types are new, which existing types get which members, and what to say next. The rest is a conversation: the board colours each planned type and member from the type index after every save (matches green, missing grey, differs amber, and types that already existed neutral, with only the members the change adds to them coloured); "check" makes the agent explain each difference without fixing it; "hand over" (check_skeleton step handover) has it fill the bodies and close with a tour; "just do it" skips the whole thing. A declaration the agent then changes shows on the board and in the agent's reply, with the before and after text; "keep it" accepts it, and "revert" (or the command Insilode: Revert an Agent's Change to Your Declaration) puts the developer's declaration back, body untouched. Nothing is scored and nothing leaves the machine; the MCP prompt skeleton_first holds the agent's side of the flow.

Explain this. When an agent has finished a turn in which it edited a file, its row in the Agents dock offers Explain this. It types a prompt into that same session (the author explains its own change; never into a session that is working or asking a question) that names what the turn touched, taken from the turn-end check (the methods, the tables, the endpoints; or, when there is none, the files), and asks for a tour on the git changes: one step per changed method in the order a request runs through them, a step for each changed table, captions on why it changed and what could break, and a last step on the risks. The same request is the MCP prompt explain_change (in Claude Code: /mcp__insilode__explain_change). It explains the latest turn only.

Changes in flow. Ask an agent to "show what you did in flow" (it calls open_diff with flow: true), or run Insilode: Show Git Changes in Flow from the command palette, the Source Control title or a diff editor. Either way one canvas shows the whole change set: every endpoint flow the changed files reach, cut down to the paths that lead to a changed method, plus the changed methods no endpoint reaches. Changed cards show added lines in green and removed lines in red. Pick what to compare with:

  • Uncommitted changes: against HEAD. Cards offer Undo and Keep.
  • This branch: everything since the branch left main or master, committed or not. On main itself, the commits not pushed yet.
  • Last commit: the last commit plus anything uncommitted on top.

A branch or last-commit card says "Changed since main" and has no Undo, because Insilode does not undo commits.

Home's prompt and Ask about this flow send the question to the agent you choose. The first time, a picker offers the running sessions that are waiting at their prompt (Claude Code, Codex, or a custom agent marked acceptsInput), a new Claude Code, Codex or custom session, the chat panel when a chat provider is installed, and the clipboard. Later questions go to the same place without asking; a note in the status bar says where each one went, and clicking it (or Insilode: Change Agent for Questions…, or change under Home's prompt) picks again. If the session you chose has closed, the question goes to another waiting session of the same CLI, else a new one. Text is only typed into a session that is at its prompt, never into one that is working or waiting on a permission question: then the question goes to the clipboard. The setting flow.agents.askTarget makes it ask every time, or fixes it to claude, codex, custom:<name>, chat or clipboard. Insilode: Pin Flow as Board keeps the flow on the canvas as a board, so boards do not need an agent.

How agent status works

Insilode starts claude with --settings <file> that adds observe-only hooks on top of your own settings (your hooks still run). Each hook runs a small Node script that posts the event to the Insilode window. The hooks never answer a permission question: Claude Code keeps asking you itself. The one thing a hook hands back is context for the agent to read: while Skeleton first is on for that agent, the hooks remind Claude to call check_skeleton before its first edit for a change that adds types: with each prompt (UserPromptSubmit, so it works outside plan mode) and when a plan is approved (PostToolUse on ExitPlanMode).

Codex reads hooks only from its config layers, so Insilode writes its own profile, $CODEX_HOME/insilode.config.toml, the first time it starts Codex, and starts it with codex -p insilode; your config.toml is not changed, and a codex you start yourself does not see these hooks. Codex runs a hook only after you trust it: run /hooks in Codex once and trust Insilode's. Until then the dock shows a hint instead of a status. An older Codex that cannot take -p insilode is started as before, without status. Turn it off with flow.agents.codexHooks.

Custom agents (any other CLI) are listed without status.

This page is docs/agent-tools.md in the repository. Suggest a change.