Kheish Agent

A terminal control surface for Kheish: an AIR-inspired ASCII identity, an operator queue synchronized with the daemon, public channel activity, conversations, approvals, structured questions, and control commands.

This package is the terminal client only. It connects to an already running Kheish daemon and does not install or start the daemon itself.

Install

Requirements: Node.js 22+ and an accessible Kheish daemon.

npm install --global kheish-agent
kheish-agent --base-url http://127.0.0.1:4000

You can also try the CLI without a global installation:

npx kheish-agent --base-url http://127.0.0.1:4000

The CLI supports KHEISH_DAEMON_URL and KHEISH_DAEMON_TOKEN, so the shortest launch is:

KHEISH_DAEMON_URL=http://127.0.0.1:4000 kheish-agent

Development

Requirements: Node.js 22+ and an accessible Kheish daemon.

npm install
npm run dev -- --base-url http://127.0.0.1:4000

Enter a mission in the input at the bottom and press Enter. The CLI creates a root Kheish session, submits a detached run, and refreshes the operator queue.

• Agents are grouped by operator priority: input required, working, failed, idle, and completed. ↑ from the composer or Tab moves focus to the queue; use ↑/↓ to select an agent and Enter to open its conversation. Pressing ↓ past the final agent returns to the composer.
• Channels are daemon-owned public coordination rooms. Channel rows are selectable alongside agents; Enter opens the roots feed, and Enter on a root opens its public thread. ←/Esc returns thread → channel → overview.
• Channel feeds are polled because Kheish does not expose a Channels message stream. The CLI never invents unread counts, subscriptions, or private delivery state.
• A channel composer keeps its own draft and offers @member completion. The exact ordered member IDs are sent to Kheish; mentions prioritize responders but do not guarantee exclusive routing.
• Channel activity comes from real leases, stimuli, and thread-work. A responding-agent indicator is shown only while a non-expired daemon lease exists.
• Pausing a channel pauses new autonomous work, not human posting. The composer stays available and labels that distinction explicitly.
• In a conversation, PgUp/PgDn scroll through the history; ← from an empty composer or Esc returns to the agents. With a draft, ← keeps editing the cursor so text is never discarded accidentally.
• In a conversation, Shift+Tab cycles the real session permission mode through default, acceptEdits, and plan. The footer shows both the effective mode and whether it is inherited from the global runtime or pinned to the session. macOS reserves Cmd+Tab for application switching, so a terminal CLI cannot receive it reliably.
• Type @ in a prompt to search session-visible skills and the daemon MCP tool inventory. ↑/↓ moves through the complete result set and Tab or Enter inserts the selected prompt macro.
• The Runs view keeps active runs at the top. Use ↑/↓ to select one, Enter to open its durable activity, and ← or Esc to return to the conversation.
• In a run activity view, PgUp/PgDn scroll through the timeline, ← or Esc returns to the runs, and c returns directly to the conversation.
• In lists, confirmations, and command panels, ← follows the same Back path as Esc. Inside text, it continues moving the cursor until the first character.
• The interface uses the terminal's full dimensions. The transcript adapts to the available space, while the input remains fixed at the bottom even when displaying a long Markdown message.
• Long input stays on one line and scrolls horizontally around the cursor.
• Agent responses render Markdown, including headings, emphasis, lists, blockquotes, links, code, and tables.
• When a run is waiting for approval, the input is replaced by an Allow/Deny choice followed by an atomic review of the decisions.
• When an agent asks a question, select an answer with ↑/↓; press Space to choose multiple answers and Enter to proceed to the review.
• Ctrl+C exits.

Commands

Typing / in the input displays the commands available in the current view. Use ↑/↓ to move through the complete command set—the visible window follows the selection—then Tab to complete, Enter to run, and Esc to close the suggestions first. Prefix a message with // to send a literal slash to the agent.

Autocomplete selections use @skill:<name> and @mcp:<qualified-tool>. Before submission, the CLI expands selected tags into explicit instructions while preserving the original prompt. Skills still activate through the model's use_skill tool, and MCP entries remain runtime inventory subject to session scopes, credentials, permissions, and provider availability; the CLI never calls an MCP tool directly from autocomplete.

• /help displays commands and keyboard shortcuts.
• /agents returns to the agent table.
• /channels [filter] opens the complete public channel list; /channels create <title> creates a room with the local human operator and opens it.
• /channel info, /channel members, /channel work, and /channel activity inspect the open channel's exact daemon state.
• /channel pause and /channel resume control new autonomous work. Human messages remain allowed while paused.
• /channel add <agent-id|session-id|name> adds a session member whose display name follows the agent; /channel remove <member-id> removes a direct member.
• /channel react <message-id> <emoji> and /channel unreact <message-id> <emoji> mutate a public reaction as the local operator.
• /new <mission> starts a new root agent.
• /status displays daemon readiness, route, model, and counters.
• /runtime [filter] displays every value in the daemon's read-only runtime snapshot; use ↑/↓ or PgUp/PgDn to scroll.
• /skills [filter] lists the global catalog from the Agents view, or the skills actually visible to the session from a conversation. The agent remains responsible for activation through use_skill.
• /mcp [servers|tools] [filter] displays the daemon's global MCP inventory. Session scopes may further reduce this surface.
• /rename <name> renames the current agent using the effective name returned by Kheish.
• /stop or /cancel asks for confirmation and then cancels only the current agent's active run.
• /runs displays the runs for the current conversation.
• /logs [run-id] opens the activity for the active run, the latest run, or a specific run. /activity is an alias.
• /memory displays the learnings and recovered runs currently eligible for the conversation before final prompt packing, with visible skills kept separate.
• /memory context [next-input] previews the daemon-ranked projection for a possible next input. /memory search [query] browses the wider session-visible memory surface; /memory <query> is the short form.
• In a conversation, a leading # stores the remaining text as an active session-scoped preference without starting a run. Use \# to send a literal leading hash; memories are applied to future relevant messages.
• Kheish creates and publishes a learning in two daemon operations. If daemon learning automation resolves the candidate first, the save can fail safely; the CLI keeps the complete draft and reports the recoverable candidate ID.
• /goal displays the session's durable goal and its usage.
• /goal start [--budget N] <objective> creates a goal only when the session does not already have one.
• /goal pause prevents future continuations without interrupting the current run; /goal resume resumes a paused goal.
• /goal stop asks for confirmation, interrupts the session, and leaves the goal paused. /goal complete asks for confirmation and marks it as achieved once the session is idle.
• /goal clear asks for confirmation and then removes the goal if its identifier and version have not changed.
• /personas [filter] opens the global persona catalog. /personas create, /personas show <id>, /personas edit <id>, and /personas delete <id> open the corresponding guided screen.
• Persona souls support multiline editing, Ctrl+G for $VISUAL/$EDITOR, and Ctrl+I to import a Markdown file. The editor sends only changed fields and keeps its draft after API errors.
• Catalog deletion requires the exact persona ID and performs fresh best-effort version and bound-session checks. The daemon API has no atomic compare-and-delete, so concurrent updates or bindings can still race it. Connector and Kheishfile references cannot be fully discovered, and reusing a deleted ID can alias older frozen snapshots; the screen warns before deletion.
• /persona [filter] lists personas and the currently bound snapshot; /persona show <id> displays its details.
• /persona use <id> binds the current version of a persona to an idle session; /persona rebind refreshes the current binding to the latest catalog version; /persona clear removes the binding after confirmation.

Persona catalog records are mutable, while sessions retain immutable snapshots. Editing or deleting a catalog record never rewrites an existing session automatically. Persona souls, metadata, and default-skill arguments are persisted operator data and must not contain secrets.

An unknown command remains local: it is never sent as a message or mission.

Verification

npm run check
npm run build

Conversation events and interaction state are refreshed from the daemon. Responses are always sent to the exact suspended run.

License

Apache-2.0. See LICENSE.