Connect
Default to the hosted server. Use open-source Graphify only when the user asks for an offline, on-machine or self-hosted setup.
Before you change a config file, tell the user what you will change and wait for a yes. After you connect, check the connection with
list_repositories. If anything fails, use Check your agent is using Graphify.
Pick the tool
The hosted server sends instructions on connect that map question types to tools. Your client builds its tool list from the server’stools/list response, so trust that live list and its input schemas over this table.
Rules for the results:
- Use a
repository_idfromlist_repositories: the UUID or theowner/name. Never invent an ID or silently pick a different repository. - Check the returned symbol and file before you cite them. If a name matches several definitions,
graphify_callersandgraphify_noderefuse and list the candidate ids. Pass an id to pick one, and say which one you used. If a name does not resolve,graphify_nodecan return a semantic match. Theresolvedfield isexactorsemantic. A semantic result is a suggestion, not proof the symbol exists. graphify_tracecan also return a semantic match forsrcortgt. Checkresolved.srcandresolved.tgt. An empty path means no directed call path was found in the indexed graph. Dynamic calls can hide a real path, so don’t say A never reaches B from an empty path alone.- An empty caller list means no call edge was indexed. It does not prove the symbol is unused.
searchandgraphify_findmatch part of a symbol’s name, likeReaSourceorwebhook, not a question. If a fragment returns nothing, try another name or askquery_graphin a full sentence.- An empty
recallresult means nothing relevant is remembered yet. graphify_impactandgraphify_tests_forread the graph. They don’t run tests or prove runtime behavior.include_riskranks hotspot files by linked-test coverage. That ranking is a signal from the graph, not a verdict.- Use grep for exact strings, such as error messages or config keys.
- If a Graphify tool fails or the repository isn’t indexed, say so, then fall back to reading files. Don’t guess.
Ask before you change state
The tools don’t edit source files. Ask the user before you call a tool that changes stored state:remembersaves a note to the workspace’s shared Memory. Save only what the user asked you to save. Saving records intake, not publication, until someone keeps it.set_workspacechanges which workspace, and so which repositories, the session reads. Withmake_default, it also changes the user’s default. See Graphify MCP.
recall reads notes the workspace already has, such as ones saved with remember, created through the API, or recorded from a workspace event such as a merged pull request.
Keep answers fresh
Hosted Graphify serves the indexed graph of each repository’s default branch. A push to the default branch starts a new index. Other branches and uncommitted changes are not in the graph. See Repository indexing and sync.- Before you edit, read the local files the graph pointed you to. The checkout can be ahead of the index.
- If the user’s change is on a feature branch, say that the graph reflects the default branch.
- If a repository shows Out of date, tell the user. A reindex in the Console refreshes it.
graphify hook install to refresh it after commits, pulls, merges and rebases, or run graphify update . by hand. See Incremental updates.
While sign-in is pending
You can add the server, but only the user can finish the OAuth sign-in in a browser. Until they do, every tool call fails and the client shows the server as needing login.- Don’t retry in a loop, and don’t switch to Graphify CLI unless the user asks.
- Tell the user exactly what to do for their client: for example
/mcp→ graphify → Authenticate in Claude Code, orcodex mcp login graphifyin Codex. The full list is in Check your agent is using Graphify. - Remind them that a new server loads only when a session starts, so they may need to reload the editor or start a new session.
- Meanwhile, answer from the local files and say that the answer did not come from Graphify.
- After sign-in, call
list_repositoriesand show the result.
list_repositories succeeds but is empty, sign-in worked and no repository is indexed in this workspace. Ask the user to index one at app.graphify.com or switch workspace.
Related
Setup for AI agents
The step-by-step setup to follow for a user.
Check your agent is using Graphify
Test prompts and fixes per client.
Graphify MCP
Sign-in, workspaces, limits and errors.
Make agents use the graph
Rules and hooks so the agent picks Graphify before grep.