[{"data":1,"prerenderedAt":416},["ShallowReactive",2],{"current-page-en-harbor-light":3},{"id":4,"title":5,"body":6,"card_image":59,"cover":59,"description":404,"extension":405,"featured":406,"layout":407,"meta":408,"navigation":406,"og_image":409,"path":410,"seo":411,"stem":412,"tags":413},"directory/en/dir/harbor-light.md","Harbor Light",{"type":7,"value":8,"toc":395},"minimal",[9,13,28,31,52,62,67,95,99,177,180,184,191,244,251,254,258,264,305,312,323,327,330,358,361,365,372,388,391],[10,11,5],"h1",{"id":12},"harbor-light",[14,15,16,20,21],"p",{},[17,18,19],"strong",{},"Download",": ",[22,23,27],"a",{"href":24,"rel":25},"https://github.com/yuanmomoya/harbor-light/releases",[26],"nofollow","GitHub Releases",[14,29,30],{},"A status light for coding agents. You can see whether Codex or Cursor is working, waiting for confirmation, or already finished, without switching back to that window.",[14,32,33,34,37,38,41,42,46,47,51],{},"Harbor Light turns live ",[17,35,36],{},"Codex"," and ",[17,39,40],{},"Cursor"," activity into a red, yellow, and green overlay you can drag across screens. It keeps a separate record for each app, project, and conversation, so several tasks can light up at once. The current version is ",[43,44,45],"code",{},"0.1.0",". It supports macOS 12+ and Windows 10/11 (x64 and ARM64). The core is Rust, with no Python or Swift runtime. Source: ",[22,48,12],{"href":49,"rel":50},"https://github.com/yuanmomoya/harbor-light",[26],".",[14,53,55,56],{"align":54},"center","\n  ",[57,58],"img",{"src":59,"width":60,"alt":61},"/projects/harbor-light/logo.png",128,"Harbor Light logo",[63,64,66],"h2",{"id":65},"what-it-does","What it does",[68,69,70,77,83,89],"ul",{},[71,72,73,76],"li",{},[17,74,75],{},"Read the state at a glance",": yellow while working, red while waiting, green when finished.",[71,78,79,82],{},[17,80,81],{},"Keep tasks separate",": watch several Codex and Cursor projects and chats at the same time. One finished task does not hide another that is still running.",[71,84,85,88],{},[17,86,87],{},"Stay out of the way",": the window stays on top, does not steal focus, and remembers where you dragged it.",[71,90,91,94],{},[17,92,93],{},"Ready after install",": it merges user-level Codex and Cursor hooks and sets itself to start at login.",[63,96,98],{"id":97},"how-to-read-the-lights","How to read the lights",[100,101,102,118],"table",{},[103,104,105],"thead",{},[106,107,108,112,115],"tr",{},[109,110,111],"th",{},"State",[109,113,114],{},"Meaning",[109,116,117],{},"Overlay",[119,120,121,133,144,155,166],"tbody",{},[106,122,123,127,130],{},[124,125,126],"td",{},"Yellow",[124,128,129],{},"The agent is thinking or running a task",[124,131,132],{},"Breathing",[106,134,135,138,141],{},[124,136,137],{},"Green",[124,139,140],{},"The current task is finished",[124,142,143],{},"Pops in, then returns to idle after about 3 seconds",[106,145,146,149,152],{},[124,147,148],{},"Red",[124,150,151],{},"Approval is needed, or an error needs attention",[124,153,154],{},"Fast blink",[106,156,157,160,163],{},[124,158,159],{},"Red and yellow",[124,161,162],{},"One task is waiting while another is still running",[124,164,165],{},"Blink together",[106,167,168,171,174],{},[124,169,170],{},"Idle",[124,172,173],{},"Nothing is active",[124,175,176],{},"All three lights stay dim",[14,178,179],{},"Drag the black capsule to place it on another screen. The window remembers that position. If a display is unplugged and the window is left off-screen, it returns to the top-right of the main display. Open the menu from the macOS menu bar, or right-click the Windows tray icon, to see the current state, reinstall hooks, or quit. The macOS menu can also toggle launch at login.",[63,181,183],{"id":182},"how-it-works","How it works",[14,185,186,187,190],{},"Codex and Cursor hooks send events to a provider adapter, which writes activity files under ",[43,188,189],{},"~/.harbor-light/activities/",". Codex rollout JSONL is a fallback. The overlay reads those files and combines them into one light.",[100,192,193,203],{},[103,194,195],{},[106,196,197,200],{},[109,198,199],{},"What is happening",[109,201,202],{},"What you see",[119,204,205,213,221,229,237],{},[106,206,207,210],{},[124,208,209],{},"Waiting, while another chat is still working",[124,211,212],{},"Red and yellow blink together",[106,214,215,218],{},[124,216,217],{},"Waiting only",[124,219,220],{},"Red blinks",[106,222,223,226],{},[124,224,225],{},"No waiting, but something is still working",[124,227,228],{},"Yellow breathes",[106,230,231,234],{},[124,232,233],{},"Nothing active, but a completion has not timed out",[124,235,236],{},"Green pops in",[106,238,239,242],{},[124,240,241],{},"Everything is idle, or completion has timed out",[124,243,176],{},[14,245,246,247,250],{},"A green completion stays out of the mix while anything is still waiting or working. The same Codex session can show up in a hook, an old status file, and a rollout log. Those records are deduped by provider and session, and ",[17,248,249],{},"hooks win",", so a fallback rollout does not turn the yellow light on during an approval.",[14,252,253],{},"When one app quits, only that app's activities are cleared. An activity with no new events for 30 minutes returns to idle.",[63,255,257],{"id":256},"download-and-install","Download and install",[14,259,260,261,51],{},"Installers are on ",[22,262,27],{"href":24,"rel":263},[26],[100,265,266,276],{},[103,267,268],{},[106,269,270,273],{},[109,271,272],{},"Platform",[109,274,275],{},"Notes",[119,277,278,290],{},[106,279,280,283],{},[124,281,282],{},"macOS 12+",[124,284,285,286,289],{},"Double-click the ",[43,287,288],{},".pkg",". It installs into Applications and configures hooks and launch at login. If it is unsigned, Control-click the package and choose Open",[106,291,292,295],{},[124,293,294],{},"Windows 10/11 x64 / ARM64",[124,296,285,297,300,301,304],{},[43,298,299],{},"setup.exe"," for your architecture. It installs for the current user under ",[43,302,303],{},"%LOCALAPPDATA%\\HarborLight"," and does not need an administrator. If SmartScreen blocks it, choose More info, then Run anyway",[14,306,307,308,311],{},"A Windows portable zip needs one install step after you unpack it: ",[43,309,310],{},"HarborLight.exe install",". That writes the hooks and the login startup entry.",[14,313,314,315,318,319,322],{},"To build from source you need Rust. On macOS, install the Xcode Command Line Tools and run ",[43,316,317],{},"make install"," in the repository. On Windows, install the MSVC Build Tools with Desktop development with C++, then run ",[43,320,321],{},"harbor-light.exe install"," after the release build.",[63,324,326],{"id":325},"hooks","Hooks",[14,328,329],{},"The installer merges user-level Codex and Cursor hooks and does not replace entries you already have. If you configure them by hand, the command must be an absolute path.",[100,331,332,342],{},[103,333,334],{},[106,335,336,339],{},[109,337,338],{},"App",[109,340,341],{},"What turns the light on",[119,343,344,351],{},[106,345,346,348],{},[124,347,36],{},[124,349,350],{},"Starting a session, submitting a prompt, or using a tool is yellow. A permission request is red. Stop or session end is green",[106,352,353,355],{},[124,354,40],{},[124,356,357],{},"Submitting a prompt is yellow. An explicit approval request, or an execution error, is red. A normal stop is green",[14,359,360],{},"Cursor does not yet expose a separate approval event. Ordinary commands are not treated as \"waiting\", so a running install does not flash red by mistake. User-level hooks watch the local agent only. This version does not configure Cloud Agent hooks.",[63,362,364],{"id":363},"uninstall","Uninstall",[14,366,367,368,371],{},"On macOS, run ",[43,369,370],{},"make uninstall"," in the repository. On Windows, remove it from Settings, or run:",[373,374,379],"pre",{"className":375,"code":376,"language":377,"meta":378,"style":378},"language-powershell shiki shiki-themes github-light github-dark","& \"$env:LOCALAPPDATA\\HarborLight\\HarborLight.exe\" uninstall\n","powershell","",[43,380,381],{"__ignoreMap":378},[382,383,386],"span",{"class":384,"line":385},"line",1,[382,387,376],{},[14,389,390],{},"Uninstall stops the app, removes launch at login, and deletes only the hook entries this tool wrote. Your other hooks stay in place.",[392,393,394],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":378,"searchDepth":396,"depth":396,"links":397},2,[398,399,400,401,402,403],{"id":65,"depth":396,"text":66},{"id":97,"depth":396,"text":98},{"id":182,"depth":396,"text":183},{"id":256,"depth":396,"text":257},{"id":325,"depth":396,"text":326},{"id":363,"depth":396,"text":364},"A status light for Codex and Cursor. See whether an agent is working, waiting, or done without switching back to the window.","md",true,"wide",{},null,"/en/dir/harbor-light",{"title":5,"description":404},"en/dir/harbor-light",[414,415],"Desktop","Status light",1791702161548]