Shader Agents and Project Git
Edit a Shader package with a coding agent. Save, merge and the code lease stay in the app.
Last updated: 2026-11-15
This guide is for a coding agent and for Project Git. Start with the Shader Workshop for ordinary editing, animation, Import and sharing. Reading it does not grant permission to write or to turn a plugin on.
Files and one program
A Shader package is one folder. A .hexshader file is a zip of that same folder. "hexshader": 1 is the first key of shader.json.
shader.json authored data, one unit at a time
source.glsl entry GLSL, no header
modules/**/*.glsl GLSL modules
provenance.json credits, licenses, lineage
resources/<sha256>.png input image bytes
originals/<sha256>.glsl imported third-party source
cover.jpg optional browsing picture, not in the zip identity
source.glsl defines hxMain. A helper lives under modules/. From the entry, include it as #include "modules/lib/noise.glsl". Limits: 31 modules plus the entry, 64 KiB of GLSL, include depth 16. The package contract is the .hexshader format.
Shader Coding Agent: open, edit, register, repair, review
Use Claude Code, Grok Build or Codex. Install 360-hextile through Agent Mode & MCP and turn Enable MCP on. Invoke the installed shader skill. Claude Code shows /360-hextile:shader. 360-hextile remains the Workflow hub.
A connected agent is fully trusted to read the open Shader and to change its values and code through the native tools. Only you Apply credits. Only you move the code lease, with Take control or Hand back.
You can keep editing values, the clock, the timeline, Looks and other fields while an agent works. If you both change the same field, yours is kept and the agent is told. Editing the code yourself needs Take control.
- Launch 360 Hextile and open the Shader. A built-in is not edited in place. Duplicate it into My Library or a Project first.
- The agent calls
get_live_context(view="shader")once. The reply names the Shader, the lease (holderandgeneration), the commit and the revision. open_shader_workspacetakes the Shader id and one new request id. It returns the lease, commit and revision. The same request id returns the recorded open.shader_editsends one batch. Each edit isset,create,reshapeordeleteon one address, such as["values", "gain"]. Typed tools for a parameter, the clock, the timeline, Looks, tags and images use the same save.shader_editcannot writeprovenance.json.register_shader_updatesends the package digest, the lease andseen, and saves. Readmerge. Watchcompile. If prepare fails, fix the package and register again with a new request id.get_shader_updatereads that same save. Onlycompilemay still change.- For a field you have edited, the agent sends the human number it read, in
seen. If the result sayslost_to_human, you changed it again. The result shows your value. The agent resends only if it still means that edit.
Register saves. There is nothing to approve, and no second Apply step. A failed compile keeps the last good picture. The activity line says why.
Take control gives you the code. Hand back returns it to the agent. Disconnect MCP turns Enable MCP off so agents cannot make new calls. It does not cancel a running job. Hextile MCP does not commit Git; external native Git needs your instruction. A save is not a Git commit.
A stale_lease result means you hold the code, or the generation the agent sent is no longer current. Hand the code back, then register again. No MCP tool moves the lease.
When an agent wants to open a Shader
By default the agent asks. A toast at the bottom right says it wants to open that Shader. Open switches to it. Dismiss leaves you where you are. ⋯ More can Always allow, Block for this session, or Never allow.
Settings → MCP and the header MCP panel keep the same choices. Agent opens Shaders is Ask, Always allow, or Never. Allow force-open is its own switch, on by default. Block for this session lasts until you unblock it or restart the app. An agent cannot change these.
Always allow opens the Shader without the question. Force is for a session you asked the agent to drive. The Shader switches at once, then a short toast says the agent opened it. Go back returns to the previous Shader. ⋯ More can ask next time, turn force-open off, or leave it. Force is still refused while you are typing or have unsaved edits.
Copilot
Copilot is the chat inside the studio. It edits the same package. A change shows on the control and in the Agent changes panel. You are not asked to approve it.
Include shader source chooses what that turn may send. Take control before you ask Copilot to edit code an external agent still holds. Git still needs your own instruction.
Credit text is separate. Copilot can propose it. Nothing in provenance.json changes until you apply the proposal on the Credits card.
Enable MCP
Settings → MCP is headed MCP, "Control external coding agents connected to this app." Turn on Enable MCP ("Allow external coding agents to use Hextile tools."). The docs tools and the other agent tools follow that switch. When it is off, a call is refused.
Local port is where agents reach Hextile, at 127.0.0.1. The default is 8000 when no port is saved. Apply saves a new port without a restart. The app writes local-endpoint.json, and the bundled client discovers the app from that file. It does not assume port 8000.
If the plugin is already installed, the footer says "Already installed the 360 Hextile plugin? Update it and restart your coding agent to use this switch."
Live context
Call get_live_context with view set to shader. Report shader.origin, shader.shader_id, lease, commit, revision, connected and mcp_enabled. Do not guess a title from an id. Do not fetch the GLSL just to see which Shader is open.
If the app is not running, launch 360 Hextile and retry. If MCP is off, turn on Enable MCP. A connection is not a save and not permission to write.
Shader agent status
Nothing asks you to approve agent work. There is no card to accept, and no second save step.
The app-header MCP popover shows who holds the code: "Agent editing code", or "Agent stopped · Take control to edit code". The code stays with the agent until you take control or the agent hands it back.
When an agent save changes something, the control marks it. A slider or swatch pulses. Changed code lines tint in the editor. The mark does not take focus and does not scroll. The activity line is one sentence, for example that the code does not compile and the picture is the last working version.
The Agent changes panel is a log. It is collapsed until you open it. Each row is one agent save. Open a row to see the old value, the new value, and a note when a change was clamped, skipped or kept yours. A row has no other action. Credit proposals do not appear here. They stay on the Credits card.
Disconnect MCP ("Disconnecting…") is shown while MCP is on. It turns Enable MCP off. It does not cancel a running job.
Doctor from an agent
request_shader_doctor runs one GPU Doctor pass on the clean Shader that is currently previewed. It works for a Built-in, a My Library Shader and a Project Shader. Send a new request id once. If the reply is uncertain, poll get_shader_doctor with that same id. Do not send the request again. A finished request returns bounded diagnostics only: no source, no pixels and no overlay mask.
In the Workshop the same check is 360 Doctor. Shown on 360 paints the mask. See Shader Controls.
Credits from an agent
shader_get_credits reads the saved Source card. shader_research_sources reads one public page you supply plus at most four named links. It does not crawl, and the text is not permission to reuse the work. shader_propose_credits stores a proposal and returns state: proposed. It does not edit GLSL, and it does not change provenance.json.
You apply the proposal on the Credits card: Review pending credits, then Apply credits. Any other agent write to that file is refused. The fields and the license list are on Shader Library.
Shader tool map
Call tools/list for the installed names and schemas. The table is a map of where to start, not the catalog.
| Group | Where to start |
|---|---|
| What is open | get_live_context, get_shader_parameters |
| Package | open_shader_workspace, shader_edit, register_shader_update, get_shader_update |
| Parameters, clock and timeline | shader_edit (for example ["values","gain"], ["clock","bpm"], ["timeline","start"]); playback with shader_control_clock and shader_step_frame |
| Looks, history and library | shader_get_looks, shader_get_history, shader_restore_revision, shader_list_assets, shader_organize_library |
| Credits | shader_get_credits, shader_research_sources, shader_propose_credits |
| Doctor | request_shader_doctor, get_shader_doctor |
| Still and sequence output | shader_request_preview, shader_preflight_still_export, shader_export_still, preflight_shader_sequence, render_shader_sequence |
| Guides and docs | get_guide, search_docs, read_doc |
shader_edit changes one unit at a time. register_shader_update saves the package digest. Read merge. Watch compile. Playback (shader_control_clock play, pause and seek, and shader_step_frame) does not save. Changing bpm, speed, start, end or loop does.
get_guide names are workflow-schema, best-practices, website-index, recipes (start here), recipes-detail and shader-cookbook. index, or an empty name, lists the guides.
Search docs and read doc
search_docs searches the public docs bundled with this version of the app. Pass a query. Then read_doc reads one page, or one section whose anchor came from the search. A long page returns an outline so you can request a section. When the app is closed, use get_guide with website-index and https://360hextile.com/llms.txt. Both tools follow Enable MCP, the same as every other tool.
Project Git and complete portable workspaces
One optional Git repository at the Project root can cover many Shaders. MCP has no Git tool. Register does not commit. Export copies the saved package. It does not zip unsaved editor bytes, and it does not zip Git HEAD.
Track the package: shader.json, source.glsl, modules/, provenance.json, and the referenced files in resources/ and originals/. Optional templates, inspect before use:
The gitignore download ignores machine-local .local/ only. Track shader.json, source.glsl, modules/, provenance.json, and the referenced files in resources/ and originals/. Read both downloads and merge them yourself. Do not apply a wildcard ignore until every Shader it covers has a complete package.
Optional Git policy downloads
Save the downloads under the names .gitignore and .gitattributes after you have read them. Do not add a line that hides the package. -text on files under shaders/ avoids newline conversion. It does not turn on LFS. If you use LFS, materialize every object after clone. A missing resource refuses admission.
Clone, first Apply and history
Clone the Project and open it. The saved package is the Shader. Register saves a change. There is no separate Apply step, and a clone does not need one to become "accepted."
Editor Undo restores your previous value of that one field. If the agent changed the same field in between, undo writes your value back. Restore copies a checkpoint or an older revision into a new save. It restores code, so it needs the code lease, and it keeps current credits. Open as Copy saves that revision as a new Shader. Git checkout changes files on disk and still needs a register before the app treats them as saved. Git cannot replace Restore.
History is the commit list. Export Shader Bundle… copies the saved package, including unused modules, Looks and every referenced frame.