Trinetra

---

Why

You start a long task in Claude Code or Codex, pick it up on your phone with Remote Control, close the lid and walk away. Then the MacBook sleeps and the session dies.

caffeinate and Amphetamine fix half of that. They don't know when your agents are done, and on battery they can't stop lid-close sleep. So you either babysit a timer or leave the Mac awake all night.

Trinetra (Sanskrit for "three-eyed") watches your agents through their own hooks. While one is working, or a timer you set is running, it holds the Mac awake, with the lid closed if you want. When the work is done it lets go, and your Mac sleeps like it always did.

Features

👁 Agent-aware	Awake exactly while Claude Code, Codex / ChatGPT, Gemini CLI or Cursor is working, plus a 3-minute grace period. Nothing to remember to turn off
💻 Lid closed, on battery	Keeps the Mac awake with the lid shut, through a tiny privileged helper you approve once. Turns itself off when the work ends
🧭 Live agent list	Every open session in the menu: agent, project, state and what it's doing right now ("Editing AppModel.swift", "Running swift", "Waiting for your approval")
📝 Session summaries	What each agent did: prompts, files edited and read, commands run, searches, approvals, active time. In the menu and in trinetra summary
🔋 Battery saved	How long agents kept the Mac awake today, the battery that cost, and an estimate of battery saved by sleeping as soon as the work ended
⏱ Timers	30m · 1h · 2h · 4h · Until I stop, for builds, downloads or anything without hooks
▶️ Wrap any command	trinetra run -- ./train.sh holds the Mac awake for exactly as long as the command runs
🛡 Safe by default	10 % battery floor, thermal cutout, 12 h cap. Normal sleep comes back if the app quits, crashes or goes quiet for 2 minutes
🌙 Calm	An animated third eye in the menu bar: open while holding, a blink now and then, closed when idle. Respects Reduce Motion
🩺 System monitor (module)	CPU per core, GPU, memory and pressure, temperatures, battery health and cycles, power draw, network and disk, with sparklines, plus the CPU each agent and its commands use. Optional readout next to the eye
🔔 Health alerts (module)	A notification when the Mac stays busy, runs hot, gets throttled, runs short of memory or disk, or the battery gets low
🧩 Modules	A full Mac toolkit is on the way as switch-on modules: Finder cut and paste, clipboard history, window snapping, a volume mixer, a command bar, screenshots, a cleaner, fan control and more. All off by default. See the roadmap
🔒 Private	No telemetry, no network calls, no prompt text stored. Ever

Trinetra does not relay prompts or approve permissions. Claude and ChatGPT already do that well. It only makes sure the Mac stays awake for them.

Agent hooks

Coding agents can run a command when something happens: a prompt is sent, a tool is about to run, the turn ends. Trinetra adds one tiny command to each of those moments:

trinetra hook <agent> <state>      # e.g. trinetra hook claude working

It reads the event the agent passes on stdin, writes one line to a local session file, and exits 0 in milliseconds. It never blocks, never answers a permission prompt and never fails the agent, whatever goes wrong.

What gets hooked

Agent	Config file	Working	Waiting for you	Idle / ended
Claude Code	~/.claude/settings.json	UserPromptSubmit PreToolUse	Notification (permission)	SessionStart Stop Notification (idle) / SessionEnd
Codex / ChatGPT	~/.codex/hooks.json	UserPromptSubmit PreToolUse PostToolUse	PermissionRequest	SessionStart Stop Interrupt / SessionEnd
Gemini CLI	~/.gemini/settings.json	BeforeAgent BeforeTool AfterTool	Notification	SessionStart AfterAgent / SessionEnd
Cursor	~/.cursor/hooks.json	beforeSubmitPrompt afterFileEdit afterShellExecution postToolUse	–	sessionStart stop / sessionEnd

What each state drives

State	Mac	Menu	Summary
Working	Held awake (lid closed too, if lid mode is on)	Green dot + current activity, e.g. "Editing LidGuard.swift"	Counts the prompt, edit, read, command, search or web lookup
Waiting for you	Held awake, so your phone can still approve	Orange dot, "Waiting for your approval"	Counts an approval
Idle	Released after the 3-minute grace period	Grey dot, "Waiting for your next prompt"	Closes the turn and its active time
Ended	Released	Moves to "Earlier today"	Final summary kept for 24 h

If an agent crashes without saying goodbye, Trinetra notices the process is gone and lets go anyway.

Installing them safely

trinetra hooks install claude      # or codex, gemini, cursor
trinetra hooks uninstall claude

• Backs up first. The original file is saved as <file>.trinetra.bak before the first change.
• Leaves your hooks alone. Only Trinetra's own entries are added or removed. Your other hooks, matchers and settings stay exactly as they were.
• Refuses broken files. If the config isn't valid JSON, nothing is changed and you're told why.
• Idempotent. Running install twice gives the same file. Uninstall removes every trace, including empty groups it created.
• Codex asks you to trust new hooks once: run /hooks inside Codex after installing.
• Cursor gets observational events only. Its permission hooks expect a JSON answer, and Trinetra never answers for you.

This is what install adds to Claude Code's settings, next to anything already there:

"UserPromptSubmit": [
  { "hooks": [{ "type": "command", "command": "/Users/you/.local/bin/trinetra hook claude working", "timeout": 5 }] }
]

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗