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.

  1. Launch 360 Hextile and open the Shader. A built-in is not edited in place. Duplicate it into My Library or a Project first.
  2. The agent calls get_live_context(view="shader") once. The reply names the Shader, the lease (holder and generation), the commit and the revision.
  3. open_shader_workspace takes the Shader id and one new request id. It returns the lease, commit and revision. The same request id returns the recorded open.
  4. shader_edit sends one batch. Each edit is set, create, reshape or delete on one address, such as ["values", "gain"]. Typed tools for a parameter, the clock, the timeline, Looks, tags and images use the same save. shader_edit cannot write provenance.json.
  5. register_shader_update sends the package digest, the lease and seen, and saves. Read merge. Watch compile. If prepare fails, fix the package and register again with a new request id. get_shader_update reads that same save. Only compile may still change.
  6. For a field you have edited, the agent sends the human number it read, in seen. If the result says lost_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.

Esc
Searching...
No results found.
Type to search the documentation
↑↓ Navigate ↵ Select Esc Close

We use cookies for analytics to understand how visitors use our site. Privacy Policy