Gajendra

One clear focus across your AI tools.
One NOW. One short queue. One click back to the exact thread.

Mac setup   ·   Codex plugin   ·   User guide

_{The macOS Focus Deck · v0.4.0 · Synthetic example tasks}

Gajendra is a local-first macOS focus utility and Codex plugin for AI-agent threads. It gives you one place to decide what deserves attention across Codex, Claude Code, and other explicitly enabled local sources—then returns you to the owning tool when it is time to work.

It does not replace those tools or copy their conversations. It adds a small, quiet attention layer above them.

v0.4.0 source release and Codex plugin · Release notes · Product evals

Start here

•  On your Mac: build and open the app, then choose your local sources.
•  Inside Codex: install the plugin to use the same priorities in a panel. The native app is optional.
•  Already using it? Read the daily user guide or what changed in 0.4.0.

The native app is built from source; the release includes a Codex plugin ZIP. Both keep Gajendra's state on your Mac. Your AI tools continue to own the conversations and transcripts.

Why Gajendra exists

AI work rarely stays inside one session. A coding task may still be running in Codex, a writing task may be waiting in Claude, and a finished result may need review somewhere else. The sessions exist; the missing piece is a trusted answer to four simple questions:

• What am I doing NOW?
• What are the few things I should return to next?
• What is still Running?
• What is Ready for Review?

Gajendra keeps those answers close without becoming another project-management system.

Version 0.4.0 gives the Mac utility and Codex extension one shared view of Ready for Review, verified Needs input, Running, Your priorities, and History. Finish work and Reopen are explicit choices. An exact continuation moves priority to its selected successor and preserves the earlier chat in History. Age is only a history grouping; it never hides pending review or finishes work. See the daily workflow trial for acceptance and rollback boundaries.

Product tour

Fresh 0.4.0 captures rendered on October 7, 2026, from the real SwiftUI views. The main image uses the dark Focus Deck style; search and editing show the native light style. Every title, project, ID, and status comes from a public synthetic fixture shaped like common Codex and Claude workflows; no private thread content is used.

Focus overview	Ready for Review
Choose one current thread and keep the next few close.	Review a specific response, then mark it reviewed or Undo.

More screenshots: search, priority editing and Organizer

Search	Edit priorities

Organizer gives you the full queues, source controls and searchable history in one window.

What you can do

In the widget	Your next action
NOW and Focus	Choose one current thread and keep a short queue of what comes next.
Important	Keep work within reach without making it your current focus.
Running	See work that a provider reports as active.
Ready for Review	Open the exact response. Mark it reviewed when you are ready; Undo is available.
Finish, Reopen and History	Finish intentionally, return later, or link an exact successor while retaining the earlier chat.

Opening a thread never marks it reviewed or finished. Provider activity and your priorities stay separate.

Interaction details and provider behavior

Capability	What it is for
NOW	Keep one selected current thread visible and open it immediately. Double-click anywhere on the NOW card or select Open; NOW always belongs to open Focus work. Finish clears NOW without choosing a replacement.
Focus and Important	Maintain short ordered queues. A quick click opens; hold a card task to select and lift it, then keep dragging the visible row to reorder or change lanes. Compact priority rows rely on drag, context-menu, and accessibility actions instead of a duplicate left/right button; Running/Ready status rows retain their separate priority control. Organizer retains explicit queue controls.
Running	See provider-reported active work across every priority lane. Its highlighted count stays visible; click All priority lanes or double-click the dock header to shrink or expand the list. It is live status, not a guessed priority or a recency label; provider completion becomes Ready for Review on refresh only when valid Ready evidence is available.
Ready for Review	See provider-completed work awaiting your next input and open its exact Review or Task destination. Opening does not mark it handled. Select the green Mark reviewed action to remove only that exact response from Ready; Undo restores it, while a later response or corrected destination reappears. Running takes precedence, and an expanded compact preview shows at most five rows before routing the truthful remainder to Organizer.
Finish and Reopen	Finish removes a chat from Ready for Review and Continue, retaining its priorities and pending response evidence in History. Reopen restores pending review and Continue; selecting NOW remains explicit.
Your priorities and History	Your priorities holds open Focus and Important work. Select an exact existing successor chat in Organizer or the plugin to transfer priority, order, context, and NOW atomically. Earlier chats remain separate, searchable History with their original destinations. Titles never establish a continuation.
Needs input	Show only an explicit validated source request. Generic waiting, idle, or age is insufficient.
Search	Filter local title, project, provider, context/tag, priority, Running, and Ready metadata without copying conversation bodies.
Open and resume	Return to the source-owned thread with source-specific destination validation.
Edit and recover	Reorder, move, append, remove, make NOW, and use app-owned Undo/Redo after successful changes.
Adapt the surface	Choose Compact, Comfortable, or Expanded task layout and independently resize the widget with a slider. Choose light, dark, or system appearance, native or Focus Deck styling, and a preferred screen position.
Open quickly	The floating launcher, Dock reopen, and menu-bar item lead to the compact focus card. Organizer remains an explicit management destination. The card is prebuilt before first use, becomes pointer-ready on reveal, and queues a fresh read even when launch loading is still finishing.
Start quietly	Choose sources on first launch and enable Launch at Login only through an explicit action.

Built-in Codex, Claude Code, Cursor, and Grok adapters provide bounded thread metadata. The current local Codex app-server can additionally supply a zero-message newest-turn summary: Gajendra maps only a valid terminal completed turn to Ready for Review. An otherwise exact completedAt: null shape is candidate-local omitted evidence, so that one candidate is not Ready; malformed, private-content, completed-turn error, unsupported, or ambiguous responses fail the built-in Ready batch closed. Claude Code, Cursor, and Grok are never guessed ready from idle time, recency, or resumability. An explicitly configured bounded catalog can also supply a validated live review signal. Focused unit, native self-test, and real-window journeys cover the mixed-candidate review boundary and compact priority actions; the source project still makes no signed/notarized binary claim.

Set it up on macOS

Requirements

• macOS 13.5 or later
• Xcode or the Xcode Command Line Tools
• Node.js 20.19+ or 22.12+ for the source build
• At least one supported local AI tool whose threads you want to see

Build and open the app

git clone https://github.com/siddath/Gajendra.git gajendra
cd gajendra
git checkout v0.4.0
npm ci
npm run companion:build
open build/Gajendra.app

The first build downloads and checksum-verifies the pinned Node runtime used inside the app bundle. The running app uses that bundled runtime; it does not depend on Homebrew or a separately installed Node binary.

Choose your sources

1. On first launch, keep the local sources you want enabled.
2. Codex uses its local app-server when available. Claude Code metadata is opt-in.
3. Select Done, then single-click the floating elephant-and-lotus button to show or hide the focus card.
4. Open Settings → Manage AI tools… later to change sources or rescan them.

For the full daily workflow, interaction reference, configured review example, and troubleshooting, read the user guide.

To verify the real floating window with privacy-safe synthetic tasks, run npm run companion:ui-test; the journey includes the same task visibly moving from Running to Ready after refresh while its priority and exact destination stay unchanged. npm run companion:ui-performance-test separately enforces the measured launcher budget and checks the widget journey for SwiftUI dependency cycles.

Use the Codex extension

If you also want Gajendra's MCP tools inside Codex, with the Codex CLI available locally:

npm run install:local

This installs the local plugin from the checked-out source. Reopen Codex after updating it to refresh the loaded MCP server. Open Gajendra priorities from the plugin's sidebar entry or from a conversation's panel menu. Calling gajendra_open also works in compatible inline MCP App hosts. The extension shares the Mac app's private priority store; opening it does not reset NOW.

_{The Codex plugin UI · Same local priorities · Synthetic browser capture}

Both surfaces can first show a labeled neutral cached view, then refresh from providers. While visible, they check local revisions about every five seconds and request source refreshes about every thirty seconds. Provider latency still applies. Optional plugin lifecycle hooks can invalidate completion reuse sooner, but require explicit host review and trust; ordinary polling still works when hooks are skipped. This is a custom local plugin, not an OpenAI first-party feature.

Version 0.4.0 shares a private session backend between the Mac app and plugin. Prepared reads and local changes use its catalog; provider discovery runs separately. Codex listing uses its supported metadata-only API with periodic full reconciliation. Cutting repeated provider scans and retaining metadata drove the improvement:

Operation	Before → after, median	Reduction
Refresh	15.05 s → 0.80 s	94.7%
Local changes	15.92 s → 0.11 s	99.3%

Three local runs per operation. These are backend timings, including CLI process overhead, not popup latency guarantees. See the performance receipt for scope and rollback.

Sources must be available on the Mac where the MCP server runs. If a source cannot load, its diagnostic and the count of unavailable saved priorities remain visible. Archived provider tasks can be absent from active results while their saved Gajendra choices remain intact. Do not reset the store to fix a blank view. See the extension recovery notes.

Development with evals

npm run build && npm run evals runs seven synthetic product scenarios for cache reuse, concurrent intent, review/Undo, Finish/Reopen/continuation, private saved metadata, and MCP/native consistency. CI and the release gauntlet run them too. Every case has an explicit acceptance criterion and a machine-readable outcome; measured timings stay separate from correctness. See the eval-driven development workflow and contribution guide.

Local-first privacy

• Provider products continue to own sessions, credentials, prompts, transcripts, and source files.
• The authoritative store retains namespaced IDs, priority order, bounded context/source preferences, explicit completion IDs, continuation relationships, NOW-selection state, revisions, and bounded idempotency/review receipts. No provider text enters this store.
• Separate private disposable caches may hold rendered titles/project labels and validated completion metadata; they never hold prompts, transcripts, credentials, commands, review results, or raw responses.
• Optional trusted lifecycle hooks write one invalidation token. They never finish work or steer Codex.
• Every source is explicit and bounded. There is no arbitrary filesystem crawl or shell discovery.
• Open actions revalidate source-specific URL schemes immediately before launch.

The private default state path is:

~/Library/Application Support/Gajendra/gajendra.v2.json

See Security and thread-source boundaries for the complete contract.

Verify a checkout

npm run check
npm run test:e2e
npm run companion:test
npm run companion:build
npm run companion:ui-test
npm run companion:validate
npm run companion:bundle-readiness

Regenerate the public synthetic screenshot suite and screenshot-led hero with:

npm run launch:assets
npm run validate:launch-assets

The repository's current evidence and remaining release gates are recorded in Status and the release checklist. The launch decision and rejected claims are captured in the adversarial launch review.

Release boundary

The public v0.4.0 source and Codex plugin ZIP are available from the release page. The native macOS app is built from source; no notarized native installer is included. Source/browser checks, product evals, native builds and narrow CUA journeys have separate receipts. The current gauntlet is partial, with three native AX-driver gates not run. Developer ID signing, notarization, stapling, Gatekeeper and clean-Mac distribution proof remain separate requirements.

The retained mobile work is a documentation-only protocol and security plan, not a shipped iOS or Android companion. See the mobile plan.

Project guides

• User guide
• Architecture
• macOS companion contract
• Thread sources
• Compatibility
• Release checklist
• Support

Use GitHub Discussions for support and private security reporting for vulnerabilities.

Updating to 0.4.0

The native app and Codex plugin now share prepared metadata and durable work state, with explicit Finish/Reopen, exact continuation links, review Retry/Undo and restrained pointer feedback. See release changes and known limits, Codex plugin setup, privacy information, and directory submission readiness.

This is a community repository plugin. Official directory review and a notarized native download are separate remaining steps. When updating a locally built native app, quit it and replace the whole app bundle with a fresh copy; do not overwrite a running bundle's signed runtime in place. Retain your user-state backup separately from the app binaries.