Working with Agents

Aster supports Claude Code, Codex, OpenCode, Cursor CLI, Kimi Code, Pi, omp, and Grok Build. Settings → Agents shows each provider's icon and detected absolute CLI path, including ~/.local/bin, Homebrew, and common Node version managers when launched from Finder/Dock. Installed/Off and the switch refer specifically to Aster-managed lifecycle integration, separately from CLI detection. Expand a provider to control its quick-launch visibility and structured launch command for wrappers, environment setup, or custom executables. Installation/uninstallation changes only Aster-marked hooks/plugins, preserving user configuration; restart the Agent afterward. Grok Build uses native [[hooks.Event]] entries in ~/.grok/config.toml, independent of Claude Code. It requires Grok ≥ 1.0.25; older versions do not read config.toml hooks. User-level hooks need no /hooks-trust (that applies to project .grok/hooks/). Grok sessions do not yet appear in Agent history or Open Quickly.

• Lifecycle hooks normalize processing / idle / awaiting-input to the owning PTY, driving badges, completion/wait notifications, and prevention of sleep during processing. They do not read or save prompt bodies. Hooks first write /dev/tty; Claude Code 2.1.x hooks lack a controlling terminal, so they find the Pane device through the parent process chain without changing Claude configuration.
• The Shell menu follows Otty's structure: Rename Tab… and Set Tab Prefix… share a native dialog (prefix preselected for the latter), then Clear Screen (⌘K); CWD copy/Finder/Open In actions are disabled without reliable CWD; then Vi/Mark/Hint, read-only, and Composer; finally Git GUI-client plus Commit/Push/Pull/Fetch/Merge/Rebase actions (prefill only) and Notifications & Privileges leading to Shell settings. Open In/Git entries match the title capsule menu.
• The Shell menu's Agent submenu, such as Codex or Claude, follows the focused Pane and updates after split focus changes. Once opened, Fork stays bound to that workspace even if Settings or another window becomes foreground. Install lifecycle integration and restart the Agent to link sessions for copy ID, history, and Fork into four split directions, a new tab, or a new window. Submenu history is current-project only, using linked-session project first or Pane CWD before linkage. Use command-palette Agent History for all projects. On first loading a new Codex hook, run /hooks to review/trust Aster; the installer migrates old invalid top-level Aster hooks boolean configuration. Copy/Fork stay disabled without a trusted session ID.
• Agent history (project-scoped from the submenu, all projects from the palette) and Open Quickly search known providers' local records. Resume/Fork uses native provider commands; unsupported Fork explicitly fails. Return or Open creates a new tab named for the session, rendering its read-only transcript: your messages are light cards, replies use Markdown, and consecutive tools collapse into a summary such as Claude · 30×Bash, 26×Edit. The header shows title, session file, project, and Resume/Fork. Per-entry/total limits truncate long sessions with a note. Opening the same session again selects its existing tab.

Menu-Bar AI Usage

This feature is off by default. Enable it in Settings → Agents → AI Usage in the Menu Bar, or use View → Show AI Usage / the same command-palette action, which also enables the switch. A macOS menu-bar icon shows Claude/Codex's used percentage for the 5-hour window, or weekly if unavailable. At 80% it warns and at 95% turns red; awaiting-input Agents add a red dot.

Click for an animated floating window beneath the icon. It can be moved/resized and remembers size, but opens under the icon each time on the current display/Space and remains in front after app switching. Moving away after an icon-open, even without entering the window, or leaving after entering waits about half a second then closes; quickly returning or resizing prevents dismissal. Menu/palette-opened windows do not auto-close before the pointer has visited. Click the icon or upper-left close control to dismiss.

The window has three pages:

• Quota: cards show accounts, tiers such as Max 20x (Codex Pro shows which tier it is: Pro 100, Pro 200, or Pro 500), 5-hour/weekly/model-week usage, and reset time. Claude shares one app-wide request timeline: every 300 seconds with only the icon active, 90 while Claude runs. Codex starts codex app-server every 300 seconds for official limits; rollout files contain only the last session response, missing usage elsewhere, so they are fallback when the CLI is unavailable/too old. Cursor queries its official usage API with its own credentials for the billing-cycle proportion. Antigravity has no local quota cache and requires its running app's local service (agy stopped exposing it from 1.2.2); this path has not been verified on a real machine and may never show a card. Cursor/Antigravity depend on undocumented interfaces that may change; unavailable cards disappear without an error dialog. Other Agents do not store local subscription quotas and have no cards.
• Token: today/7 days/30 days/all totals for input, cache write/read, and output, ranked by Agent/project, with a project's past-year activity heatmap. Supported records include Claude Code, Codex, Pi, Grok Build, Gemini CLI, droid, OpenCode, Hermes, and Antigravity CLI (agy). droid lacks CWD and goes under Other; Antigravity counts agy command-line sessions only, not sessions in the Antigravity app; Cursor/Copilot/Qwen do not retain local token data. This reads only numbers, timestamps, and working directories from local session files, not conversation bodies; no network or currency conversion is used. Git worktrees combine under the main repository. The initial full scan may take a minute or two for several GB, with progress and resume after closing; later scans read additions only.
• Sessions: one card per running Agent across windows, showing awaiting-input/running/completed/idle and its Pane's whole process-tree CPU, memory, and process count. Waiting comes first; click to focus that Pane. Cards do not reorder while open, only on reopening.

The feature does not alter terminals. With the switch off it performs no work; with the floating window closed only a Claude quota request every 300 seconds remains. Token and process-usage scans run only while their corresponding page is open.

Composer, Skills, and Context Sharing

• Composer supports multiline drafts, ordinary file attachments, pinned/floating presentation, and cancel. Sending uses bracketed paste and respects read-only and paste protection. Prompt Queue dispatches automatically only on hook idle; processing/awaiting-input queue only. Without hooks, send each item manually via its left icon.
• Let Agents operate Aster: the bundled skill (aster --skill) teaches Claude Code/Codex to read neighboring Panes, start/wait for another Agent, and send keys/notifications through aster. Install it from Settings → Agents into ~/.claude/skills/aster or ~/.codex/skills/aster with a version marker; upgrades show when it needs updating. Only Aster-marked directories are managed. Your own same-name skills or symlinks are not overwritten, and uninstall removes only Aster's copy. Prompt/text/focus writes require IPC Allow Sending Input; otherwise the Agent receives write_not_allowed and asks for manual operation. The skill applies only in Aster terminals (ASTER_ENV=1).
• Send to Chat accepts terminal selection, the visible transcript, or file context. It wraps content in untrusted-context, strips terminal controls, masks common keys, and enforces a 128 KiB total budget. Aster does not claim to identify every business secret; review before sending. The terminal confirmation panel prefills the target Agent as ordinary typing; you make the final submission.