chore: cleanup

Author: damassi

README.md

@@ -2,7 +2,7 @@
 
 A minimalist, terminal-based chat CLI built to explore the new [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) and based on [damassi/agent-chat-cli](https://github.com/damassi/agent-chat-cli). Terminal rendering is built on top of [React Ink](https://github.com/vadimdemedes/ink).
 
-Additionally, via inference, Agent Chat CLI supports lazy, turn-based MCP connections to keep token costs down. The agent will only use those MCP servers you ask about, limiting the context that is sent up to the LLM. (After an MCP server is connected it remains connected, however.)
+Additionally, via inference, Agent Chat CLI supports lazy, turn-based MCP connections to keep token costs down and performance reasonable. The agent will only use those MCP servers you ask about, limiting the context that is sent up to the LLM. (After an MCP server is connected it remains connected, however.)
 
 ## Overview
 
@@ -75,7 +75,9 @@ Run the agent in interactive terminal mode:
 bun start
 ```
 
-You'll see a prompt where you can type your questions or requests.
+You'll see a prompt where you can type your questions or requests. If you send it a general "Help!" query it will generate a help menu based upon configured MCP servers, if said MCP servers have corresponding system prompts in the `prompts` folder:
+
+<img width="813" height="590" alt="Image" src="https://github.com/user-attachments/assets/2350639a-fb12-496a-9b32-b484fc14b8af" />
 
 Type `exit` to quit.
 
@@ -115,6 +117,8 @@ const config = {
   systemPrompt: getPrompt("system.md"),
   mcpServers: {
     someMcpServer: {
+      description:
+        "A detailed description of the MCP server and its capabilities used to provide hints to inference agent",
       command: "bunx",
       args: ["..."],
       prompt: getPrompt("someMcpServer.md"),
@@ -123,6 +127,8 @@ const config = {
 }
 ```
 
+The `description` field is **critical**; it's used by the inference routing agent to determine when to invoke the server or subagent.
+
 #### Remote Prompts
 
 Prompts can be loaded from remote sources (e.g., APIs) using `getRemotePrompt`. This enables dynamic prompt management where prompts are stored in a database or CMS rather than in files.
@@ -236,8 +242,6 @@ When a user asks something like "Analyze partner churn", the routing agent will:
 2. Automatically connect to the required `salesforce` MCP server
 3. Invoke the subagent with its specialized prompt and tools
 
-The `description` field is **critical**; it's used by the routing agent to determine when to invoke the subagent.
-
 **Note:** Subagents also support remote prompts via `getRemotePrompt`, allowing you to manage agent prompts dynamically from an API or database.
 
 ### Note on Lazy MCP Server Initialization

src/hooks/useAgent.ts

@@ -117,13 +117,7 @@ export function useAgent() {
               }
 
               if (!message.is_error) {
-                actions.setStats(
-                  `Completed in ${(message.duration_ms / 1000).toFixed(
-                    2
-                  )}s | Cost: $${message.total_cost_usd.toFixed(4)} | Turns: ${
-                    message.num_turns
-                  }`
-                )
+                actions.setStats(message)
               } else {
                 actions.setStats(`[agent-cli] Error: ${message.subtype}`)
               }

src/mcp/getMcpServer.ts

@@ -5,7 +5,7 @@ import { z } from "zod"
 
 export const getMcpServer = () => {
   // Store Claude Agent SDK sessionId per-instance (not shared across threads)
-  let claudeSessionId: string | undefined
+  let sessionId: string | undefined
 
   // Map thread IDs to Claude Agent SDK session IDs for per-thread isolation
   const threadSessions = new Map<string, string>()
@@ -35,23 +35,23 @@ export const getMcpServer = () => {
       },
     },
     async ({ query }) => {
-      const existingConnectedServers = claudeSessionId
-        ? sessionConnectedServers.get(claudeSessionId)
+      const existingConnectedServers = sessionId
+        ? sessionConnectedServers.get(sessionId)
         : undefined
 
       const { response, connectedServers } = await runStandaloneAgentLoop({
         prompt: query,
         mcpServer,
-        sessionId: claudeSessionId,
+        sessionId,
         existingConnectedServers,
         onSessionIdReceived: (newSessionId) => {
-          claudeSessionId = newSessionId
+          sessionId = newSessionId
         },
       })
 
       // Update the session's connected servers
-      if (claudeSessionId) {
-        sessionConnectedServers.set(claudeSessionId, connectedServers)
+      if (sessionId) {
+        sessionConnectedServers.set(sessionId, connectedServers)
       }
 
       return {

src/store.ts

@@ -1,6 +1,7 @@
 import type {
   McpServerConfig,
   PermissionMode,
+  SDKResultMessage,
 } from "@anthropic-ai/claude-agent-sdk"
 import {
   action,
@@ -41,16 +42,17 @@ export interface ToolDenied {
 export type ChatHistoryEntry = Message | ToolUse | ToolDenied
 
 type McpServerConfigWithPrompt = McpServerConfig & {
+  /** A detailed description of the MCP server that the inference agent evaluates */
   description: string
-  prompt?: () => Promise<string>
   disallowedTools?: string[]
   enabled?: boolean
+  prompt?: () => Promise<string>
 }
 
 export interface AgentChatConfig {
   agents?: Record<string, AgentConfig>
-  disallowedTools?: string[]
   connectionTimeout?: number
+  disallowedTools?: string[]
   maxRetries?: number
   mcpServers: Record<string, McpServerConfigWithPrompt>
   model?: "sonnet" | "haiku"
@@ -61,8 +63,8 @@ export interface AgentChatConfig {
 }
 
 export interface PendingToolPermission {
-  toolName: string
   input: any
+  toolName: string
 }
 
 export interface StoreModel {
@@ -80,9 +82,9 @@ export interface StoreModel {
   stats?: string | null
 
   // Computed
-  isBooted: Computed<StoreModel, boolean>
-  availableMcpServers: Computed<StoreModel, string[]>
   availableAgents: Computed<StoreModel, string[]>
+  availableMcpServers: Computed<StoreModel, string[]>
+  isBooted: Computed<StoreModel, boolean>
 
   // Actions
   abortRequest: Action<StoreModel>
@@ -91,6 +93,7 @@ export interface StoreModel {
   appendCurrentAssistantMessage: Action<StoreModel, string>
   clearCurrentAssistantMessage: Action<StoreModel>
   clearToolUses: Action<StoreModel>
+  handleMcpServerStatus: Thunk<StoreModel, McpServerStatus[]>
   reset: Action<StoreModel>
   sendMessage: Action<StoreModel, string>
   setPendingToolPermission: Action<
@@ -105,23 +108,22 @@ export interface StoreModel {
   setIsProcessing: Action<StoreModel, boolean>
   setMcpServers: Action<StoreModel, McpServerStatus[]>
   setSessionId: Action<StoreModel, string>
-  setStats: Action<StoreModel, string | null>
-  handleMcpServerStatus: Thunk<StoreModel, McpServerStatus[]>
+  setStats: Action<StoreModel, SDKResultMessage | null | string>
 }
 
 export const AgentStore = createContextStore<StoreModel>({
   abortController: new AbortController(),
   chatHistory: [],
-  messageQueue: new MessageQueue(),
-  sessionId: undefined,
-  mcpServers: [],
-  input: "",
-  isProcessing: false,
+  config: null as unknown as AgentChatConfig,
   currentAssistantMessage: "",
   currentToolUses: [],
+  input: "",
+  isProcessing: false,
+  mcpServers: [],
+  messageQueue: new MessageQueue(),
   pendingToolPermission: undefined,
+  sessionId: undefined,
   stats: undefined,
-  config: null as unknown as AgentChatConfig,
 
   // Computed
   isBooted: computed((state) => {
@@ -187,8 +189,18 @@ export const AgentStore = createContextStore<StoreModel>({
     state.currentToolUses.push(payload)
   }),
 
-  setStats: action((state, payload) => {
-    state.stats = payload
+  setStats: action((state, message) => {
+    if (!message) {
+      state.stats = null
+      return
+    }
+
+    if (typeof message === "string") {
+      state.stats = message
+      return
+    }
+
+    state.stats = `Completed in ${(message.duration_ms / 1000).toFixed(2)}s | Cost: $${message.total_cost_usd.toFixed(4)} | Turns: ${message.num_turns}`
   }),
 
   clearCurrentAssistantMessage: action((state) => {