workled MCP Controller

MCP Tool Reference

Tool	Property	Description	Usage
set_agent_state	state_name: string	Set LED to reflect agent state (thinking/waiting/idle/error)	set_agent_state("thinking")
get_agent_state	—	Returns current agent LED state (empty string if unset)	get_agent_state()
set_brightness	brightness: integer	LED brightness 0-255; 0 = off	set_brightness(128)
get_brightness	—	Returns current LED brightness 0-255;	get_brightness()
set_effect	effect_name: string, effect_json: string	effect_name ∈ led(manual effect)/thinking/waiting/idle/error/touch(touch effect); effect_json is a JSON string {"type","hue","saturation","value","speed"}. Light must be on first (set_brightness > 0). Map natural-language colors to HSV (see table below).	set_effect("led", '{"type":"breathe","hue":180,"speed":50}')
get_effect	effect_name: string	Get effect_name config as JSON	get_effect("thinking")
set_macro	macro_name: string, macro_json: string	Set the macro for a touch pad gesture; macro_name ∈ single_click/double_click/long_press; macro_json is a JSON array of segments (see Macro Format); empty macro_json resets	set_macro("single_click", '[{"combo":"ctrl+c"}]')
get_macro	macro_name: string	Returns the macro as a JSON array string, or empty string if unset (password values masked)	get_macro("single_click")

Mapping natural-language colors to set_effect

Use type:"solid" unless the user asks for an animation. Map a color name to HSV:

Description	type	hue	saturation	value
pure white	solid	0	0	255
warm white	solid	30	80	255
red	solid	0	255	255
orange	solid	30	255	255
yellow	solid	60	255	255
green	solid	120	255	255
cyan/teal	solid	180	255	255
blue	solid	240	255	255
purple/violet	solid	270	255	255
pink	solid	330	200	255
dim/night mode	solid	30	80	60
rainbow (animated)	rainbow	-	-	-

Rule of thumb: hue 0-359 picks the hue, saturation 0-255 (0 = white/pastel, 255 = vivid), value 0-255 brightness. Pastel/white tones use low saturation; vivid tones use 255.

Verify & Troubleshooting

Whenever workled is newly installed, used for the first time in a session, or the LED is not responding:

• In the "Agent" dialog box, enter Is the workled diagnosis in effect? or 诊断workled生效了吗？
• Or manually run the diagnostic program: node <skill-dir>/index.js status [--client <name>]

Waiting-state coverage by client

waiting means "the agent asked you something and is blocked on your answer". workled can only light it when the client itself emits an event for the question — it cannot invent one. Coverage therefore differs per client.

Client	Waiting state	Notes
opencode	ok	—
kilo	ok	—
dsh	ok	—
pi	no	No event is fired for the option prompt
openclaw	no	No event is fired for the option prompt
hermes	partial	Normal option prompts emit nothing; permission prompts do
workbuddy	ok	-
trae-cn	ok	-

On the clients marked no (and on hermes for normal option prompts), the LED stays on thinking while a question is pending. If you want "waiting for you" to be visible there, call set_agent_state("waiting") yourself before asking the question.

Measured 2026-09-07; re-check after a client update, since this depends on each client's own hook/plugin surface.

Reference

• Macro format reference macro_format.md
• Device setup reference device_setup.md

Video Demo

https://www.bilibili.com/video/BV1FK4k6WEKe

Contributing

• Repository: https://github.com/git-hub-cloud/workled
• Issues: https://github.com/git-hub-cloud/workled/issues