Agent Setup Prompt

Agent Setup Prompt

If your AI agent still falls back to built-in file reads, grep, or text-based edits after SymForge is installed, give it the following prompt once. It is written to work whether the machine has one client or several.

When to use this

Run this prompt once after installing SymForge. It detects installed clients, configures SymForge for each, updates instruction files, and validates the setup. You should not need to run it again unless you add a new client.

The prompt

Copy and paste the entire block below into your AI agent:

SymForge is already installed on this machine. Your job is to detect which supported AI clients are actually installed on this computer or in this workspace, configure SymForge for the ones you find, and update only the relevant instruction files. Do not assume every client is installed. Do not split this into multiple partial tasks. Complete the whole setup flow for every detected client.

Work in this order:
1. Detect installed clients and existing config files before editing anything.
2. Prefer running `symforge init` for any client that supports it.
3. Repair or add the SymForge MCP entry in that client's MCP config only if needed.
4. Update the corresponding global or workspace instruction file so the agent treats SymForge as the primary code navigation and structural editing layer.
5. Validate the edited config, reload the client if needed, and confirm that SymForge is connected or ready.

Requirements:
- First inspect what exists. Only modify files for clients you actually detect.
- Preserve existing user instructions and existing MCP servers. Merge missing SymForge settings; do not duplicate entries or overwrite unrelated content.
- Use the SymForge binary path for the current OS: `~/.symforge/bin/symforge` on macOS/Linux or `C:\Users\<user>\.symforge\bin\symforge.exe` on Windows. Use no arguments unless that client already requires extra fields.
- For JSON-based MCP clients, keep the client's existing schema. Native VS Code MCP uses a top-level `servers` object in `mcp.json`. Many extension-managed clients use a top-level `mcpServers` object. Reuse the schema already present in that client's config file instead of forcing one client's format into another.
- Preserve client-specific keys such as `disabled`, `alwaysAllow`, `autoApprove`, `timeout`, `type`, `env`, or trust fields if that client supports them. Do not invent unsupported keys.
- If a SymForge entry already exists, update it in place. Do not create duplicate `symforge` entries.
- After editing any JSON config, validate that it is still valid JSON and confirm the client can start the SymForge MCP server.
- If a client reports MCP schema errors that mention another tool or server, do not blame SymForge by default. Check the other configured MCP servers in that client, because many strict clients reject the whole MCP set when any one server advertises invalid JSON Schema.

Detect and update whichever of these are actually present:
- Claude Code: `~/.claude.json`, `~/.claude/settings.json`, `~/.claude/CLAUDE.md`
- Codex: `~/.codex/config.toml`, `~/.codex/AGENTS.md`
- Gemini CLI: `~/.gemini/settings.json`, `~/.gemini/GEMINI.md`
- Native VS Code MCP: workspace or user `mcp.json` and the nearest project instruction file such as `AGENTS.md`
- Cline: its MCP JSON settings file plus its rules file such as `~/Documents/Cline/Rules/mandatory.md`
- Kilo Code: `.kilocode/mcp.json` and `.kilocode/rules/symforge.md`
- Roo Code and similar extensions: their existing MCP JSON file if present, otherwise the nearest MCP config file the extension already uses, plus the nearest project instruction file the client already consumes
- If a client is not installed or you cannot find its real config path from existing files, do not guess and do not create random paths for it

Client-specific setup notes:
- Claude Code, Codex, and Gemini CLI are home-scoped clients. If their home directories already exist, prefer `symforge init` and then verify the written config instead of hand-authoring everything from scratch.
- Kilo Code is workspace-local. Run `symforge init --client kilo-code` from the target project directory when possible. That workspace should end up with `.kilocode/mcp.json`, `.kilocode/rules/symforge.md`, and `.symforge/`.
- Native VS Code MCP usually uses user- or workspace-level `mcp.json`. Keep its top-level `servers` shape intact.
- Cline, Roo Code, Kilo Code, and similar VS Code extensions may use extension-managed JSON files instead of native VS Code `mcp.json`. Detect the real file first and preserve its root key and surrounding schema.
- For VS Code-family extensions, update both sides when appropriate: the MCP JSON file that launches SymForge and the instruction/rules file the extension already consumes.

Add or merge a SymForge rule block with this behavior:
- When SymForge is available, prefer it over built-in file, search, and edit tools for source code work.
- Use SymForge first for: `search_symbols`, `search_text`, `get_file_context`, `get_repo_map`, `get_symbol`, `get_symbol_context`, `find_references`, `find_dependents`, `inspect_match`, `what_changed`, `diff_symbols`, `explore`, `ask`, `conventions`, `edit_plan`, `context_inventory`, `investigation_suggest`.
- Prefer SymForge edit tools: `replace_symbol_body`, `edit_within_symbol`, `insert_symbol`, `delete_symbol`, `batch_edit`, `batch_rename`, `batch_insert`.
- Do not default to built-in tools such as `read_file`, `search_files`, `list_files`, `write_to_file`, `replace_in_file`, grep, or broad raw file reads for normal source-code work.
- Raw reads are still acceptable for non-code files where exact wording matters, such as docs and config files.
- If SymForge reports that the project is empty, missing, stale, loading, degraded, or otherwise unavailable, do not give up on SymForge. Run `health`, then run `index_folder` on the workspace root if needed, then retry the original SymForge operation.
- Only fall back to built-in code tools after SymForge recovery was attempted and still failed for a non-indexing reason.
- After small edits, run `analyze_file_impact` on changed files.
- After larger multi-file jobs, major refactors, or sprint-sized tasks, run `index_folder` on the workspace root so the index is fresh.
- Before finishing a large task, do a final `health` check and reindex if needed.

Your output must include:
- which clients you detected
- which files you changed
- which files you intentionally left untouched because the client was not installed or no real config file was found
- the SymForge rule block you added or updated
- confirmation that each edited MCP config still parses and points to the SymForge binary