agent-glance

⚠️ WIP — Work in Progress. This package is under active development. Expect breaking changes, rough edges, and bugs. Not production-ready. Pin a specific version if you depend on it, and please file issues for anything you hit.

An MCP server that provides a shared HUD — the glance — across AI agent sessions. Multiple clients (Claude Code sessions, Codex, etc.) attach to one running server instead of spawning one per client, so every session sees and can update the same on-screen surface.

Requirements

• macOS (the HUD and menu-bar status item are macOS-only for now)
• Node.js 18+

Install

Run the installer — it delegates to add-mcp so you can choose supported clients interactively:

npx agent-glance install

For non-interactive global installation to all supported agents:

npx agent-glance install -y --all

Once added, restart your agent. The first tool call spawns the daemon; subsequent sessions attach to the same daemon and share the HUD.

Usage

Inside any connected session, ask the agent to use one of the glance tools:

• "Write to the glance: # Build status\n✅ Tests passing" → calls write_glance
• "Hide the glance HUD." → calls hide_glance
• "Read the current glance buffer." → calls read_glance
• "Edit the glance: replace failing with passing." → calls edit_glance (requires a prior read_glance in the same session)

The HUD anchor (top-right / top-left / bottom-right / bottom-left / follow-cursor / hide) is controlled from the macOS menu-bar status item that appears when the daemon starts.

Local development

git clone https://github.com/dyingg/agent-glance.git
cd agent-glance
npm install
npm run build
npm link
claude mcp add agent-glance -- agent-glance

How it works

Client #1 ──stdio──▶ adapter ─┐
Client #2 ──stdio──▶ adapter ─┼──▶ Unix socket ──▶ daemon  (one process)
Codex     ──stdio──▶ adapter ─┘

agent-glance uses a singleton daemon + stdio adapter pattern. One compiled binary plays two roles, dispatched by the AGENT_GLANCE_ROLE env var: unset → adapter (what the MCP client launches), daemon → the long-running server the adapter spawns on first use. The daemon owns the glance window state and uses bind() on its socket path as its lock, so simultaneous adapter launches cannot produce two daemons.

Tools

Tool	Description
write_glance	Replace the glance HUD contents with a new body (markdown/text).
hide_glance	Hide the glance window without clearing its buffer.
read_glance	Read back the current glance buffer (used as a gate before editing).
edit_glance	Apply an Edit-style string-replace patch to the glance buffer (read-before-edit enforced).

Development

npm run build      # tsc → dist/
npm test           # vitest run
npm run test:watch

Environment variables

Variable	Default	Purpose
AGENT_GLANCE_SOCKET	platform-specific	Socket/pipe path
AGENT_GLANCE_PIDFILE	next to socket	Pidfile written on daemon bind
AGENT_GLANCE_IDLE_MS	30000	Ms after last client disconnect before daemon exits
AGENT_GLANCE_ROLE	unset	Set to daemon to run as daemon (internal)
AGENT_GLANCE_HUD_MODE	unset	Glance HUD lifecycle mode
AGENT_GLANCE_HUD_DISABLED	unset	Disable the glance HUD entirely
AGENT_GLANCE_STATUS_DISABLED	unset	Disable the menu-bar status item
AGENT_GLANCE_CONFIG	platform-specific	Config file path

License

MIT