get_ctlsurf_instructions
Initialize a project with ctlsurf or get ctlsurf integration instructions.
Use this when the user says "initialize project with ctlsurf" or "set up ctlsurf for this project".
Returns instructions to add to your project memory/config file (CLAUDE.md, AGENTS.md, .cursorrules, etc.):
ctlsurf as source of truth
Checking pending tasks on session start
Documenting assumptions, shortcuts, decisions
Task workflow (claim, progress, complete, follow-up)
Block types guide (text, checklist, table, tree, react_flow, ctlsurf_task, datastore, state, log)
When to update documentation
Usage:
Detect the git remote URL: run
git remote get-url originDetect the hostname: run
hostnameCall this tool with root_path, repo_url, and hostname
If the result has needs_project_choice=true, this checkout (e.g. a fresh clone on a new machine, or a teammate's clone) matches existing projects for the same repo. Show the user the candidates and ASK which project to link it to, then call again with folder_id=; if they want a separate project, call again with create_new=true.
Add the returned 'instructions' to your project memory/config file
A project can live on many machines: each checkout (machine + path) is added to the project's machine list, so several people on several machines share one project.
Examples:
get_ctlsurf_instructions(root_path="/path/to/project", repo_url="https://github.com/user/repo", hostname="macbook-pro")
get_ctlsurf_instructions(root_path="/path/to/project", repo_url="...", hostname="...", folder_id="")
get_ctlsurf_instructions(root_path="/path/to/project", format="text")
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"root_path": "<root_path>"
},
"name": "get_ctlsurf_instructions"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Output format: 'markdown' for CLAUDE.md/Copilot, 'text' for .cursorrules/.windsurfrules (default: markdown) | |
| hostname | No | Machine hostname. Auto-detected by the agent via `hostname` or `uname -n` command. Added to the project's machine list. | |
| repo_url | No | Git repository URL (preferred). Detect with: git remote get-url origin | |
| folder_id | No | Link this checkout to this existing project (an id from a previous needs_project_choice result, chosen by the user). | |
| root_path | Yes | Project root path | |
| create_new | No | The user wants a separate project for this checkout even though projects for the same repo exist. |