Documentation
¶
Overview ¶
Package waiting records which Claude Code sessions are waiting for the owner's permission. Claude Code's own hooks (aimux remote hooks notify) write one marker file per waiting session and remove it once Claude goes on; aimux remote serve reads the markers for the session list and pushes one notification per new marker. Markers live in ~/.aimux/waiting (directory 0700, files 0600) and never hold more than Claude Code's short notification line.
Index ¶
- Constants
- Variables
- func CommandBinary(command string) (string, bool)
- func Dir(home string) string
- func Events() []string
- func HandleHook(dir string, in io.Reader, now time.Time) error
- func HookCommand(binary string) string
- func List(dir string) map[string]Waiting
- func Remove(dir, sessionID string) error
- func Write(dir, sessionID, message string, now time.Time) error
- type Change
- type Entry
- type State
- type Tracker
- type Waiting
Constants ¶
const ( // SetEvent marks a session as waiting, with SetMatcher. SetEvent = "Notification" SetMatcher = "permission_prompt" )
The hook events and fields below are Claude Code's, as documented at https://code.claude.com/docs/en/hooks (formerly https://docs.claude.com/en/docs/claude-code/hooks). Every event's stdin JSON carries session_id, transcript_path and hook_event_name (and agent_id inside a subagent); Notification adds message, an optional title and notification_type, and its matcher filters on that type. A permission_prompt notification fires once the prompt has waited about six seconds, so a prompt answered at the Mac right away sends nothing. PermissionRequest fires before the dialog shows (and also in sessions that cannot show one), which would push for prompts the owner is already answering, so it is not used.
const KindPermission = "permission"
KindPermission: Claude Code shows a permission prompt.
const MaxMessage = 200
MaxMessage is the longest message a marker keeps, in runes.
const MissFor = 5 * time.Second
MissFor is how long a session whose process aimux never saw must be missing from the registry before its marker goes, so one unreadable registry file (caught mid-rewrite) does not remove it.
const SkipOlderAtStart = 2 * time.Minute
SkipOlderAtStart: on the first Poll, markers older than this count as already pushed, so restarting the server does not push them again.
const StaleAfter = 30 * time.Second
StaleAfter is how long a marker of a session that is not open may stay: long enough for Claude's registry to show a session that just started.
const TranscriptGrace = 2 * time.Second
TranscriptGrace: a transcript written later than this after the prompt was reported means the session moved on (a tool ran after an answer, or Esc wrote "[Request interrupted by user]").
Variables ¶
var ClearEvents = []string{"PostToolUse", "PostToolUseFailure", "UserPromptSubmit", "Stop", "SessionEnd"}
ClearEvents end the wait: a tool ran (allowed) or failed, the owner sent a prompt, the turn ended, or the session closed. A tool event from a subagent does not clear the main thread's prompt. A prompt denied with Esc fires none of these (an interrupt has no Stop); the server drops that marker once the session's transcript is written after the prompt (Tracker.Current).
Functions ¶
func CommandBinary ¶
CommandBinary is the binary an aimux hook command runs, unquoted; false for any other command.
func Events ¶
func Events() []string
Events are the hook events aimux installs, in the order it adds them.
func HandleHook ¶
HandleHook applies one hook call, read from in, to the markers in dir. Events it does not know change nothing.
func HookCommand ¶
HookCommand is the hook command for the aimux binary at binary, quoted for the shell when it needs to be.
Types ¶
type Change ¶
Change is what Install or Uninstall did, by event. Backup is the copy of the settings made before writing; empty when nothing was written or there was no file.
type State ¶
type State struct {
Installed, Missing, Commands []string
}
State is what Status found: the events with aimux's hook, the events without, and the distinct commands those hooks run.
type Tracker ¶
type Tracker struct {
Dir string
Live func() map[string]int // session id -> pid, e.g. LocalIndex.TerminalPIDs
Now func() time.Time // nil: time.Now
Alive func(pid int) bool // nil: signal 0 to the pid
// ReadOnly: never delete a marker, only leave out the ones that do not
// count. For the TUI and the dashboard, whose Live may leave out a
// harness the owner disabled there, so "not open" is no proof the
// session closed; remote serve's Tracker (every harness) cleans up.
ReadOnly bool
// contains filtered or unexported fields
}
Tracker reads the markers for aimux remote serve. Only sessions Live reports (open in a terminal) count; markers of sessions that closed, and of sessions whose transcript moved on since the prompt, are removed. Poll is the push loop's view of what changed.
func (*Tracker) Poll ¶
Poll compares Current with the previous Poll: the markers that appeared and the ones that went (answered, replaced by a newer prompt, or their session closed). The first Poll reports the current markers except those older than SkipOlderAtStart, which a previous server run already pushed.
type Waiting ¶
type Waiting = sessionstate.Wait
Waiting is what a session waits for. It is the session list's `waiting` and the session state service's marker input (sessionstate.Wait).