Skip to content

agents.md

Latest commit

 

History

History
417 lines (353 loc) · 21.1 KB

agents.md

File metadata and controls

417 lines (353 loc) · 21.1 KB
Raw

Agents

Coding agents use Graphicle through MCP, the protocol they use to call tools. graphicle setup connects the agents it finds on your machine to one MCP server, graphicle mcp: the project's code graph (with Graphify's tool names, such as query_graph and get_neighbors), search over the code, documents and reviewed memory, and the memory tools. This page lists, for each agent, what setup and graphicle connect write, where, and how to undo it.

Connect and disconnect

graphicle setup                  # set up this folder and connect the agents it finds
graphicle connect                # connect the agents it finds (it asks on a terminal)
graphicle connect --all          # the same, without asking
graphicle connect cursor         # connect one agent
graphicle connect cursor --graph # connect one agent as setup does (below)
graphicle disconnect cursor      # remove that agent's entry and hooks
graphicle disconnect             # remove everything Graphicle added for this folder's project
graphicle disconnect --all       # the same for every project
graphicle uninstall              # disconnect everywhere, then show how to remove the program

The agent names are claude-code, codex, cursor, vscode, claude (Claude Desktop) and muse (Muse Code). setup --clients also takes the numbers setup shows on a terminal. Restart or reload an agent after you connect or disconnect it. graphicle status lists the connected agents and whether each entry still works.

Setup, and connect without an agent, set each agent up for the code graph, as connect <agent> --graph does:

  • Five tools for Claude Code. Claude Code shows the agent the names of an MCP server's tools and the server's instructions in every request, and loads a tool only when the agent searches for it. Its entry runs graphicle mcp --tools essentials: query_graph, get_node, get_neighbors, recall_project and read_project_source, with short instructions on when to call them and when grep is enough; each tool's description says how its answers cite code and, for the search tools, when to use it instead of grep. --tools all gives it every tool, as 0.1.0 did.
  • Memory drafts. The other agents' entries run the whole server with --allow-learning, so the agent can propose a memory: a decision, a procedure or a note, quoting current sources word for word. A draft is only a draft. Recall and session start use it only after a person approves it in the app (Memory).

The graph guard is off unless you ask for it with --guards (setup or connect):

  • The graph guard (Claude Code). Two hooks in .claude/settings.local.json run before Claude Code searches (Grep, or a shell command such as grep, rg or find) or reads a source file in a project whose code graph holds code. They point it to query_graph, get_node, get_neighbors and recall_project first (the search hook adds that grep is enough for an exact identifier the agent already knows); reading a file to change it stays the agent's choice. get_node also lists the reviewed memories anchored to the symbol and the documents that name it. In other folders they pass the request to the graph engine's own guard. Each agent gets at most five of these nudges a session (a subagent counts on its own, and the first nudge always comes); the environment variable GRAPHICLE_HOOK_NUDGE_CAP sets another limit, and 0 lifts it. The other agents' hooks cannot add context before a tool call, so they get the entry only. Setup or connect without an agent, run without --guards, removes the guard hooks an earlier setup installed.

The prompt hook is off unless you ask for it with graphicle setup --prompt-context:

  • The prompt hook (Claude Code). One UserPromptSubmit hook in .claude/settings.local.json runs graphicle context on each prompt that is a code question (it names code, such as an identifier, a call or a code file, reads like an issue or bug report, or asks where code is, such as "Which file and function compute this?") and gives Claude Code the packet's Markdown, at most 8,400 characters (Claude Code shows hook output over 10,000 characters only as a 2 KB preview), as the prompt's additional context. The packet's excerpts say at which line of the file to read on. It adds nothing for a prompt with fewer than 16 characters besides spaces, for a question in plain words, in a folder of no Graphicle project, when graphicle context fails, and when it has not answered within its budget: 10 seconds unless graphicle config set prompt_context.seconds N (1 to 25) or the GRAPHICLE_PROMPT_CONTEXT_SECONDS variable sets another (it is stopped; the hook's own timeout is 30 seconds). While the passage index of a project of 2,000 files or more is not ready (see Configuration), the hook gives the files that define the code names a prompt gives, which needs no full read of the project. A smaller project, and a project with reviewed memory (whose memories only the full read gives), are asked in full. When the hook gives up for time, or answers that way, Claude Code shows you one note a session saying so and what to run. Setup without --prompt-context leaves the hook as an earlier setup left it; graphicle disconnect claude-code removes it with the other hooks.

A plain graphicle connect <agent> writes the entry without --allow-learning and adds no guard hooks; run after setup (0.1.0's too, or setup --tools all), it keeps setup's entry as it is.

graphicle setup --tools all --guards brings back 0.1.0's setup for Claude Code: every tool, with 0.1.0's server instructions and replies (recall at the budget asked for and in 0.1.0's order), the guard hooks, and 0.1.0's AGENTS.md section. The instructions and the search tools' descriptions also say when to use Graphicle and when grep is enough, as every set's do. Two things are as in the default setup: the session-start hook prints only its line on when to use Graphicle when the project has no reviewed memory, no open work and no stale memory (0.1.0 printed the last captured turns), and graphicle context in a terminal puts test files last unless a call asks otherwise (include_tests: true through graphicle call context).

An entry that runs graphicle mcp --workspace instead gives the agent a workspace connection to every project its key can read: list_projects names them, workspace_map shows what each holds and the imports between them, and recall_project searches them, up to 8 at a time, unless repo names one (mcp.md).

How Graphicle edits your files

  • Only its own entries. Graphicle adds an MCP entry named graphicle or graphicle-<project>, hooks that run graphicle hook, and sections and lines between markers that name Graphicle. Everything else in each file stays as it was.
  • A backup first. Before it first changes a file, Graphicle copies it to <file>.graphicle-bak beside it. Later runs keep that first copy. In a Git repository, a marked *.graphicle-bak line in .git/info/exclude keeps the backups out of git status (a copy of an ignored file, such as .claude/settings.local.json, stays ignored), and syncs never read them.
  • Safe to repeat. Running setup or connect again changes nothing that is already in place, and says so.
  • No keys in files. The model settings name the environment variable that holds a key, never the key itself.
  • Undo by name. graphicle disconnect finds Graphicle's changes in the record it keeps in the data folder, and by their entry names and markers, and removes only those. When a file is then the same as its backup, the backup is put back, so the file is exactly as it was.

A project is a folder you set up, and <project> is its name in lower case, for example graphicle-my-app. When another project already has that name (two repositories called api), the entry gets the project's short id too, for example graphicle-api-1a2b3c4d, and each keeps its own. Agents with a settings file per folder (Claude Code and VS Code) get one entry named graphicle that finds the project from the folder they start in. Agents with one settings file for your user account (Codex, Cursor, Claude Desktop and Muse Code) get one entry per project.

Claude Code

What Where Written by
MCP server graphicle .mcp.json in the project folder setup, connect claude-code
Session capture hooks .claude/settings.local.json in the project folder setup (unless --no-capture), connect claude-code --hooks
Graph guard hooks .claude/settings.local.json in the project folder setup --guards, connect claude-code --guards
Prompt hook .claude/settings.local.json in the project folder setup --prompt-context
Graphicle section CLAUDE.md, if the project has one and another agent is connected too setup (unless --no-instructions)
  • Claude Code asks you to approve the servers in a project's .mcp.json the first time it starts there.
  • .claude/settings.local.json holds your personal settings, and the hooks name the program on your machine. Keep this file out of version control.
  • If graphicle graph install (or graphicle graph claude install) also added the graph engine's guard hook in the project, remove it with graphicle graph uninstall, or Claude gets two reminders.
  • Undo: graphicle disconnect claude-code. By hand, delete the graphicle entry from .mcp.json and the hooks whose command contains hook claude-code (capture and guard hooks) from .claude/settings.local.json.

Codex

What Where Written by
MCP server graphicle-<project> Codex's own settings, through codex mcp add; without the Codex command line, ~/.codex/config.toml ($CODEX_HOME/config.toml) between Graphicle's markers setup, connect codex
Session capture hooks ~/.codex/hooks.json ($CODEX_HOME/hooks.json when that is set) setup (unless --no-capture), connect codex --hooks
Graphicle section AGENTS.md in the project folder setup (unless --no-instructions)
  • With the Codex command line, codex, on your PATH, Graphicle adds the entry through it. Without it (the Codex IDE extension alone), Graphicle writes the entry's table into config.toml itself, between the lines # graphicle-start (added by graphicle connect; graphicle disconnect removes it) and # graphicle-end. A server of the same name that is not Graphicle's is left alone.
  • Codex asks you to review and trust new hooks before they run.
  • Undo: graphicle disconnect codex. By hand, run codex mcp remove graphicle-<project> (or delete the lines between Graphicle's markers in config.toml) and delete the hooks whose command contains hook codex from hooks.json.

Cursor

What Where Written by
MCP server graphicle-<project> ~/.cursor/mcp.json setup, connect cursor
  • Undo: graphicle disconnect cursor, or delete the entry by hand.

VS Code

What Where Written by
MCP server graphicle .vscode/mcp.json in the project folder setup, connect vscode
  • The entry passes VS Code's workspace folder to Graphicle, which finds the project from it.
  • Undo: graphicle disconnect vscode, or delete the graphicle entry under servers by hand.

Claude Desktop

What Where Written by
MCP server graphicle-<project> ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, ~/.config/Claude/claude_desktop_config.json on Linux setup, connect claude
  • Claude Desktop has no project folder, so each project you connect gets its own entry.
  • Undo: graphicle disconnect claude, or delete the entry by hand.

Muse Code

What Where Written by
MCP server graphicle-<project> ~/.config/muse/settings.json, in its mcp_servers object setup, connect muse
Graphicle's plugin (preview): MCP server, skill graphicle, six hooks Graphicle's data folder, muse-code-plugin/, installed with muse plugins install connect muse --hooks
  • Setup finds Muse Code by its settings folder, ~/.config/muse, or the muse program, and writes the settings entry: a stdio server ("transport": "stdio") with "mode": "optional", so a Muse Code session still starts, with a warning, when Graphicle is not installed. Graphicle changes only its own entry; the file's other settings stay. Muse Code requires "schema_version": 1 in the file, and Graphicle adds it when the file has none.
  • Graphicle's plugin is a preview, tested against a stand-in muse program and in one live Muse Code session, so setup does not install it. In that session Muse Code ran four of its six hooks and called its pack tool, but stopped the session-start hook, whose output passed the 16,384 bytes Muse Code takes from a hook; 0.1.11 keeps that output under 14,000 bytes, tested against the stand-in program only. graphicle connect muse --hooks --allow-learning installs it; approve it once with muse plugins approve graphicle. Its server replaces the project's settings entry. Its hooks are built to add the project's map and reviewed memory at session start and cited excerpts after a code question, and capture each session as a source (below). They never block Muse Code.
  • Muse Code reads a project's AGENTS.md (else CLAUDE.md) once you trust the workspace, so the Graphicle section setup writes there for Codex or Claude Code reaches Muse Code too.
  • Undo: graphicle disconnect muse removes the settings entry and the plugin (muse plugins remove graphicle).
  • Graphicle with Muse Code has the details: what each hook adds, how the context keeps the prompt cache, and session memory.

Claude Code and Codex on Meta's models

Meta documents running Claude Code and Codex on its models (https://dev.meta.ai/docs/coding-agents.md). Graphicle connects to them the same way whatever model they use: graphicle setup adds its MCP server and capture hooks as above. Pointing them at Meta changes where they send their requests and who bills them, so Graphicle does not write that part for you: it would change every session of the agent, not only Graphicle's.

Claude Code, through the Messages API, for one shell:

export ANTHROPIC_BASE_URL=https://api.meta.ai
export ANTHROPIC_AUTH_TOKEN="$MODEL_API_KEY"
export ANTHROPIC_MODEL=muse-wonder-1.0
export ANTHROPIC_DEFAULT_OPUS_MODEL=muse-wonder-1.0
export ANTHROPIC_DEFAULT_SONNET_MODEL=muse-spark-1.3
export ANTHROPIC_DEFAULT_HAIKU_MODEL=muse-spark-1.3
export CLAUDE_CODE_SUBAGENT_MODEL=muse-spark-1.3
export ENABLE_TOOL_SEARCH=true
claude
  • The base URL has no /v1: Claude Code adds /v1/messages.
  • ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY, which sends another header.
  • Name every model: a background task, Plan Mode or a sub-agent otherwise asks for a model the Meta Model API does not serve.
  • ENABLE_TOOL_SEARCH=true keeps tool search, which Claude Code turns off for other hosts, so Graphicle's tools load when the agent needs them.

Codex, through the Responses API: add a provider and a profile to ~/.codex/config.toml, and your default provider stays as it is.

[model_providers.meta]
name = "Meta Model API"
base_url = "https://api.meta.ai/v1"
env_key = "MODEL_API_KEY"
wire_api = "responses"

[profiles.meta]
model = "muse-wonder-1.0"
model_provider = "meta"
model_reasoning_effort = "high"
model_reasoning_summary = "auto"
export MODEL_API_KEY=...
codex --profile meta -c model_context_window=1048576 -c model_auto_compact_token_limit=900000
  • Codex sends MODEL_API_KEY as a bearer token; the key never goes in the file.
  • Meta's page sets these keys at the top level instead, which makes Meta Codex's default, and asks you to /logout from OpenAI first. A CODEX_HOME of its own keeps such a setup apart from your usual one.

Billing. Both bill the Meta Model API key by usage. Their cost displays show $0 for a provider without prices; the Model API's usage page has the real figures.

Other MCP clients

Any client that starts an MCP server over stdio, such as Windsurf, can use Graphicle. mcp.md shows the entry to add by hand. connect also writes to another settings file in the same format with --config-path PATH. mcp.md lists every option of connect.

In the repository

Agent instructions

Setup adds a two-line Graphicle section to AGENTS.md in the project folder, and to CLAUDE.md if it exists. Many agents read these files with every request. The section tells them when to call Graphicle's tools and when grep is enough, and what to run in a terminal without them.

  • The section sits between the lines <!-- graphicle:start (added by graphicle setup; graphicle disconnect removes it) --> and <!-- graphicle:end -->, under the heading ## Graphicle.
  • If AGENTS.md does not exist, setup asks before it creates it. --yes answers yes.
  • When Claude Code is the only agent connected, setup adds no section: the server's instructions already tell Claude Code when to call the tools. A section an earlier setup wrote is kept and brought up to date.
  • setup --tools all writes 0.1.0's longer section instead, which names the whole server's tools, whichever agents are connected.
  • --no-instructions skips this step.
  • Undo: graphicle disconnect removes the section. By hand, delete the lines between Graphicle's markers.

Git hooks

Setup adds a few marked lines to three Git hooks: post-commit, post-merge and post-checkout, in the hooks folder Git uses for the repository (.git/hooks, or the folder Git's core.hooksPath setting names when it is inside .git). The lines start a quiet graphicle sync of the project's folder in the background, so Git does not wait, and your next question sees the new code.

  • Existing hooks are kept. Graphicle adds its lines before a final exit or exec line, else at the end of the file.
  • The lines sit between # graphicle-sync-start <folder> and # graphicle-sync-end.
  • A hooks folder outside .git (one kept in the repository, such as Husky's, or one shared by all your repositories) is left alone: setup prints the line to add there yourself.
  • --no-hooks skips this step.
  • Undo: graphicle disconnect removes the lines. By hand, delete the lines between Graphicle's markers.

Session capture

Session capture saves your Claude Code, Codex and Muse Code conversations in the project, so that you and your agents can search what was said and decided before. Setup turns it on; --no-capture leaves it off. Muse Code's capture comes with Graphicle's plugin, a preview you add with graphicle connect muse --hooks (Muse Code).

  • After each answer, a background process stores the session's completed turns. The hooks never make the agent wait.
  • At the start of a session, the agent receives the titles of your reviewed memories and the latest turns, at most 8,000 characters. Reviewed memories are decisions, procedures and notes that a person approved in the app.
  • Text inside <private>…</private> is dropped, and credentials are redacted, before anything is stored. No model is called.
  • graphicle sessions forget --client claude-code --session-id ID forgets one session and returns a receipt.

After an upgrade

Codex, Cursor and Claude Desktop entries, and the capture hooks, start the program by the path on your PATH that leads to it, such as Homebrew's /opt/homebrew/bin/graphicle, which an upgrade keeps, not by the versioned folder an upgrade removes. If something stopped working anyway (entries an older Graphicle wrote, or a program you moved), run:

graphicle doctor --fix

doctor finds entries, capture hooks and guard hooks that start a program that no longer exists, entries Graphicle wrote that no longer run graphicle mcp or are gone, and capture hooks that lack an event; --fix rewrites them, and keeps each entry's --tools, --allow-learning and --work-state. An entry that names no --tools is the whole server, and an entry that is gone from its file comes back as the whole server, since nothing is left to say which set it had. For anything else it reports, run the command it prints.

Optional: the graph-only server and the graph skill

Setup connects Graphicle's MCP server, graphicle mcp. It walks the project's code graph with the graph engine's tools under Graphify's names (neighbours, dependency paths, communities and the most connected code), and it searches your code, documents, reviewed memory and past sessions. mcp.md lists its tools. Two more tools are optional, and setup does not install them:

  • The graph-only server, graphicle graph serve, serves a graph.json file on its own, as Graphify's server does, for an agent that should see the graph and nothing else. mcp.md shows how to add it.
  • The graph skill, for agents that work through the command line: graphicle graph install (or --platform NAME for another agent). graphicle graph uninstall removes it.