Vizhi

Product Introduction

1. Definition: Vizhi is a local supervision and control system for the OpenAI Codex CLI, functioning as a hardware plugin for the Logitech MX Creative Keypad and a complementary browser-based dashboard. It is a technical tool in the categories of AI agent orchestration, developer productivity, and human-in-the-loop (HITL) interfaces.
2. Core Value Proposition: Vizhi exists to provide ambient, real-time oversight and control for multiple concurrent Codex CLI coding sessions. Its primary value is enabling developers to supervise AI agents without constant terminal monitoring, using a tactile keypad for instant approvals and context injection, thereby increasing productivity and control in agentic workflows.

Main Features

1. Live Six-Session Grid: A real-time status display on the Logitech MX Creative Keypad's LCD screen. It shows six Codex CLI sessions simultaneously, displaying project name, context window usage percentage, agent state (Working/Ready), and attention status (e.g., awaiting approval). This works by intercepting Codex CLI lifecycle hooks and state updates, which are then rendered on the keypad's display via the Logi Plugin Service.
2. TTY-Verified One-Press Approvals: Provides physical "Yes" and "No" keys to respond to Codex agent approval requests. The system's key innovation is TTY verification: before sending a response, Vizhi confirms the target Terminal tab's TTY identifier matches the session requesting approval. This ensures commands are delivered to the correct session even if terminal windows are rearranged, using macOS Automation and System Events for reliable focus and input injection.
3. Local, Offline Whisper Voice Prompts: Enables hands-free context and prompt input via a dedicated "Voice" key. It uses a locally installed whisper-cli (e.g., whisper-cpp) model to transcribe audio offline, ensuring privacy. The transcribed text is then delivered as a prompt or context to the active Codex session. This feature operates entirely on-device, with no cloud processing for voice data.
4. Unified Browser Dashboard: A local web interface served via Node.js that mirrors and extends keypad functionality. It provides a full-window view of all sessions, a Session Library for archiving and resuming work, browser-based voice input (using the Web Speech API), and "Quick Actions" for custom shortcuts. It syncs with the keypad via a shared local action pipeline and file-based queue system.
5. Screenshot-Plus-Voice Context: A workflow that captures a screen region and automatically stages it with a voice prompt for contextual understanding. This combines macOS Screen Recording permissions for capture with the local Whisper pipeline, allowing users to visually show and verbally explain a problem to the Codex agent in one action.

Problems Solved

1. Pain Point: Context switching and management overload when running multiple AI coding agents. Developers must manually monitor several terminal windows, track which session is requesting input, and frequently switch focus to provide approvals or guidance, breaking deep work flow.
2. Target Audience: The primary user persona is a professional software developer or engineer who uses the OpenAI Codex CLI for daily coding tasks, agent-assisted development, and prototyping. Secondary users include technical leads managing multiple agent sessions or researchers experimenting with AI-assisted workflows who require precise control and audit trails.
3. Use Cases:
   • Parallel Project Development: Supervising Codex agents working on six different features or bug fixes simultaneously, using the grid to see status and the keypad to grant file-write approvals.
   • Hands-Free Coding: Using voice prompts to iteratively refine code or add comments while keeping hands on the keyboard, or while referencing physical documentation.
   • Code Review & Debugging: Using the screenshot-plus-voice feature to capture a buggy UI component or error output and verbally instruct the agent on the required fix.
   • Session Persistence: Using the browser dashboard's Session Library to pause a complex coding session, archive it, and resume it later without losing the conversation history or context.

Unique Advantages

1. Differentiation: Unlike generic macro pads or Stream Deck setups, Vizhi is deeply integrated with the Codex CLI's internal hook system, providing live, parsed session state rather than simple button macros. Compared to other agent supervision tools like AgentDeck, Vizhi is narrowly focused on the Terminal-based Codex CLI workflow, offering a simpler, more integrated experience with features like TTY-verified delivery and a unified browser/keypad architecture.
2. Key Innovation: The shared local action pipeline is its core architectural advantage. Both the hardware keypad and browser dashboard generate normalized action records that are processed by a single router. This prevents feature drift between interfaces and uses a safe file-queue system (with actions/done/ and quarantine) to guarantee delivery and prevent blocking. This makes the system robust and allows either surface to be used interchangeably.

Frequently Asked Questions (FAQ)

1. Do I need a Logitech MX Creative Keypad to use Vizhi? No, the keypad is optional. You can use the full-featured local browser dashboard as a standalone supervision tool. A demo mode also allows you to experience the interface without any hardware or a Codex account.
2. Is my data or voice sent to the cloud? No. Vizhi operates entirely locally. Codex session data is handled by the official CLI. Voice transcription for the keypad uses a local whisper-cpp model. The browser dashboard's voice feature may use the browser's speech recognition service, which could process audio externally depending on your browser settings.
3. How does Vizhi interact with the Codex CLI? It uses Codex CLI's official lifecycle hook system. On first run, it installs a local hook into your ~/.codex/config.toml file. Codex will ask you to trust this hook once, enabling Vizhi to receive real-time session updates and send commands back.
4. Can I customize the keys and actions on the Logitech keypad? Yes. The installed .lplug4 profile provides a default layout, but you can fully customize it within Logi Options+, just like any other keypad profile. Updates to Vizhi will not overwrite your customizations.
5. What are the system requirements for Vizhi? It requires macOS (for integration with Terminal.app and Logi Options+), the OpenAI Codex CLI, and Node.js LTS for the browser dashboard. For the keypad's offline Voice feature, you need to install whisper-cli separately (e.g., via brew install whisper-cpp).