@gajae-code/coding-agent 0.4.3 → 0.4.5

package/dist/types/modes/components/hook-selector.d.ts

@@ -22,6 +22,17 @@ export interface HookSelectorOptions {
      */
     wrapFocused?: boolean;
     scrollTitleRows?: number;
+    /**
+     * Inline free-text entry for the option with this label (e.g. the ask
+     * tool's "Other (type your own)"). Selecting it keeps the title and option
+     * list on screen and opens a prompt-style editor below the list instead of
+     * replacing the whole selector. Enter submits via `onSubmit`; Escape
+     * returns to option selection.
+     */
+    customInput?: {
+        optionLabel: string;
+        onSubmit: (text: string) => void;
+    };
 }
 export declare class HookSelectorComponent extends Container {
     #private;

package/dist/types/modes/utils/abort-message.d.ts

@@ -0,0 +1,4 @@
+export declare function buildAbortDisplayMessage({ errorMessage, retryAttempt }: {
+    errorMessage?: string;
+    retryAttempt: number;
+}): string;

package/dist/types/session/session-manager.d.ts

@@ -401,6 +401,14 @@ export declare class SessionManager {
     appendCompaction<T = unknown>(summary: string, shortSummary: string | undefined, firstKeptEntryId: string, tokensBefore: number, details?: T, fromExtension?: boolean, preserveData?: Record<string, unknown>): string;
     /** Append a custom entry (for extensions) as child of current leaf, then advance leaf. Returns entry id. */
     appendCustomEntry(customType: string, data?: unknown): string;
+    /**
+     * Write mutated message entries back into the canonical entry store by id.
+     *
+     * `getBranch()` materializes resident-blob entries into copies, so in-place
+     * mutation of returned entries (e.g. pruning tool outputs) does not affect
+     * the canonical store. This applies such mutations for real.
+     */
+    applyEntryMessageUpdates(entries: readonly SessionMessageEntry[]): void;
     /**
      * Rewrite the session file after in-place entry updates.
      * Use sparingly (e.g., pruning old tool outputs).

package/dist/types/setup/hermes-setup.d.ts

@@ -0,0 +1,78 @@
+import { COORDINATOR_MCP_PROTOCOL_VERSION, COORDINATOR_MCP_SERVER_NAME } from "../coordinator/contract";
+export type HermesMutationClass = "sessions" | "questions" | "reports";
+export type HermesSetupMode = "render" | "install" | "check" | "smoke";
+export interface HermesSetupFlags {
+    json?: boolean;
+    check?: boolean;
+    smoke?: boolean;
+    install?: boolean;
+    force?: boolean;
+    root?: string[];
+    repo?: string;
+    profile?: string;
+    sessionCommand?: string;
+    noWorktree?: boolean;
+    worktreeName?: string;
+    stateRoot?: string;
+    mutation?: string[];
+    artifactByteCap?: string;
+    serverKey?: string;
+    gjcCommand?: string;
+    target?: string;
+    profileDir?: string;
+}
+export interface CoordinatorSetupSpec {
+    schemaVersion: 1;
+    coordinator: "hermes";
+    serverKey: string;
+    serverName: typeof COORDINATOR_MCP_SERVER_NAME;
+    protocolVersion: typeof COORDINATOR_MCP_PROTOCOL_VERSION;
+    gjcCommand: string;
+    args: ["mcp-serve", "coordinator"];
+    roots: string[];
+    namespace: {
+        profile?: string;
+        repo?: string;
+    };
+    sessionCommand?: string;
+    sessionCommandSource: "default" | "explicit";
+    worktree: {
+        enabled: boolean;
+        name?: string;
+    };
+    stateRoot?: string;
+    mutationPolicy: {
+        classes: HermesMutationClass[];
+        perCallConsentRequired: true;
+    };
+    artifactByteCap?: number;
+    installTarget?: {
+        kind: "profile-dir" | "config-file";
+        path: string;
+    };
+    operatorTemplateVersion: 1;
+    contractDocVersion: 1;
+}
+export interface HermesSetupResult {
+    ok: boolean;
+    mode: HermesSetupMode;
+    files_written: string[];
+    previews: Array<{
+        path: string;
+        content: string;
+    }>;
+    warnings: string[];
+    smoke: null | {
+        ok: boolean;
+        protocolVersion: string;
+        serverName: string;
+        requiredTools: string[];
+        missingTools: string[];
+    };
+}
+export declare function buildHermesSetupSpec(flags: HermesSetupFlags): CoordinatorSetupSpec;
+export declare function computeHermesSetupSignature(spec: CoordinatorSetupSpec): string;
+export declare function renderHermesServerBlock(spec: CoordinatorSetupSpec): Record<string, unknown>;
+export declare function runHermesSetup(flags: HermesSetupFlags): Promise<HermesSetupResult>;
+export declare function formatHermesSetupResult(result: HermesSetupResult): string;
+export declare function hermesSetupExitCode(error: unknown): number;

package/dist/types/task/fork-context-advisory.d.ts

@@ -0,0 +1,13 @@
+import type { ForkContextMode } from "./types";
+export interface ForkContextAdvisory {
+    recommendedMode: ForkContextMode;
+    reasons: string[];
+    estimatedClonedTokens: Record<ForkContextMode, number>;
+    callerModeRespected: true;
+}
+export declare function adviseForkContextMode(input: {
+    assignment: string;
+    context?: string;
+    explicitMode?: ForkContextMode;
+    parentContextTokens?: number;
+}): ForkContextAdvisory;

package/dist/types/task/receipt.d.ts

@@ -56,6 +56,7 @@ export interface TaskResultReceipt {
     };
     extractedToolCounts?: Record<string, number>;
     forkContext?: SingleResult["forkContext"];
+    forkContextAdvisory?: SingleResult["forkContextAdvisory"];
     roi?: TaskRoi;
 }
 /**

package/dist/types/task/render.d.ts

@@ -1,11 +1,17 @@
 import type { Component } from "@gajae-code/tui";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
-import type { TaskParams, TaskToolDetails } from "./types";
+import type { AgentProgress, TaskParams, TaskToolDetails } from "./types";
 /**
  * Render the tool call arguments.
  */
 export declare function renderCall(args: TaskParams, _options: RenderResultOptions, theme: Theme): Component;
+/**
+ * Public wrapper to render a single subagent's live `AgentProgress` for the
+ * `subagent` await panel. Reuses the internal task-progress renderer so the
+ * await panel stays at parity with the inline task panel.
+ */
+export declare function renderSubagentLiveProgress(progress: AgentProgress, expanded: boolean, theme: Theme, spinnerFrame?: number): string[];
 /**
  * Render the tool result.
  */

package/dist/types/task/roi-reconciliation.d.ts

@@ -0,0 +1,27 @@
+import type { TaskResultReceipt } from "./receipt";
+import type { SpawnPlanReceipt } from "./spawn-gate";
+/**
+ * Pure, advisory-only reconciliation between a spawn plan's inline-token promise
+ * and receipt-safe child outputs. These signals never change task success/failure
+ * semantics or runtime behavior; they only describe budget/ROI observations for
+ * model-facing summaries.
+ */
+export interface SpawnRoiChildReconciliation {
+    id: string;
+    inlineTokens: number;
+    maxInlineTokens: number;
+    overBudget: boolean;
+    overageTokens: number;
+    lowRoi: boolean;
+}
+export interface SpawnRoiReconciliation {
+    childCount: number;
+    promisedMaxInlineTokens: number;
+    children: SpawnRoiChildReconciliation[];
+    overBudgetChildIds: string[];
+    lowRoiChildIds: string[];
+    totalInlineTokens: number;
+    totalOverageTokens: number;
+    advisoryFlags: string[];
+}
+export declare function reconcileSpawnRoi(plan: SpawnPlanReceipt | undefined, receipts: readonly TaskResultReceipt[]): SpawnRoiReconciliation | undefined;

package/dist/types/task/types.d.ts

@@ -2,6 +2,7 @@ import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { Usage } from "@gajae-code/ai";
 import * as z from "zod/v4";
 import type { TaskResultReceipt } from "./receipt";
+import type { SpawnRoiReconciliation } from "./roi-reconciliation";
 import { type TaskSimpleMode } from "./simple-mode";
 import type { SpawnPlanReceipt } from "./spawn-gate";
 import type { NestedRepoPatch } from "./worktree";
@@ -413,6 +414,14 @@ export interface SingleResult {
         mode: ForkContextMode;
         clonedTokens: number;
     };
+    /**
+     * Advisory fork-context mode recommendation for this task (logged only;
+     * never changes the actual mode selection).
+     */
+    forkContextAdvisory?: {
+        recommendedMode: ForkContextMode;
+        reasons: string[];
+    };
 }
 /** Tool details for TUI rendering */
 export interface TaskToolDetails {
@@ -431,6 +440,7 @@ export interface TaskToolDetails {
         /** Advisory ids for terminal children that spent tokens without detectable output/review/changes. */
         lowRoiChildIds: string[];
     };
+    roiReconciliation?: SpawnRoiReconciliation;
     progress?: AgentProgress[];
     async?: {
         state: "running" | "paused" | "queued" | "completed" | "failed";

package/dist/types/tools/subagent-render.d.ts

@@ -0,0 +1,25 @@
+/**
+ * TUI renderer for the `subagent` tool.
+ *
+ * The await panel surfaces each awaited subagent's live streaming status at
+ * parity with the inline `task` panel by reusing `renderSubagentLiveProgress`.
+ * Falls back to a `running, no activity yet` placeholder when a live producer
+ * exists but has not emitted yet, and to a static status line when no live
+ * producer is available (resumed-from-disk or backward-compat records).
+ */
+import type { Component } from "@gajae-code/tui";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import type { SubagentToolDetails } from "./subagent";
+export declare const subagentToolRenderer: {
+    inline: boolean;
+    renderCall(_args: unknown, _options: RenderResultOptions, theme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: SubagentToolDetails;
+    }, options: RenderResultOptions, theme: Theme): Component;
+    mergeCallAndResult: boolean;
+};

package/dist/types/tools/subagent.d.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
 import * as z from "zod/v4";
-import type { AgentSource } from "../task/types";
+import type { AgentProgress, AgentSource } from "../task/types";
 import type { ToolSession } from "./index";
 declare const subagentSchema: z.ZodObject<{
     action: z.ZodEnum<{
@@ -42,6 +42,10 @@ export interface SubagentSnapshot {
     outputRef?: string;
     truncated?: boolean;
     guidance?: string;
+    /** Live streaming progress for the awaited subagent (await panel only; UI detail). */
+    progress?: AgentProgress;
+    /** True when a live in-session progress producer exists for this subagent. */
+    liveProgressAvailable?: boolean;
 }
 export interface SubagentToolDetails {
     subagents: SubagentSnapshot[];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.4.3",
+	"version": "0.4.5",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -36,6 +36,7 @@
 		"check:types": "tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
 		"test": "bun test",
+		"bench:context": "bun run bench/context-optimization.bench.ts",
 		"generate-schemas": "bun ../../scripts/generate-json-schemas.ts",
 		"check:schemas": "bun ../../scripts/generate-json-schemas.ts --check",
 		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index",
@@ -50,12 +51,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.4.3",
-		"@gajae-code/agent-core": "0.4.3",
-		"@gajae-code/ai": "0.4.3",
-		"@gajae-code/natives": "0.4.3",
-		"@gajae-code/tui": "0.4.3",
-		"@gajae-code/utils": "0.4.3",
+		"@gajae-code/stats": "0.4.5",
+		"@gajae-code/agent-core": "0.4.5",
+		"@gajae-code/ai": "0.4.5",
+		"@gajae-code/natives": "0.4.5",
+		"@gajae-code/tui": "0.4.5",
+		"@gajae-code/utils": "0.4.5",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/scripts/build-binary.ts

@@ -39,6 +39,10 @@ async function main(): Promise<void> {
 					"bun",
 					"build",
 					"--compile",
+					// Minify shrinks the bundled JS the compiled binary must parse at
+					// startup (302MB → ~114MB --help RSS measured on darwin-arm64).
+					// --keep-names below preserves identifiers for error reports.
+					"--minify",
 					"--no-compile-autoload-bunfig",
 					"--no-compile-autoload-dotenv",
 					"--no-compile-autoload-tsconfig",

package/src/async/job-manager.ts

@@ -1,5 +1,5 @@
 import { logger } from "@gajae-code/utils";
-import type { AgentSource } from "../task/types";
+import type { AgentProgress, AgentSource } from "../task/types";
 
 const DELIVERY_RETRY_BASE_MS = 500;
 const DELIVERY_RETRY_MAX_MS = 30_000;
@@ -248,6 +248,7 @@ export class AsyncJobManager {
 	#disposed = false;
 	readonly #subagentRecords = new Map<string, SubagentRecord>();
 	readonly #liveHandles = new Map<string, SubagentLiveHandle>();
+	readonly #subagentProgress = new Map<string, AgentProgress>();
 	readonly #resumeQueue: ResumeQueueEntry[] = [];
 	#resumeSeq = 0;
 	#resumeRunner?: (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined;
@@ -531,6 +532,38 @@ export class AsyncJobManager {
 		this.#liveHandles.delete(subagentId);
 	}
 
+	/**
+	 * Retain the latest live `AgentProgress` for a subagent (deep-cloned so later
+	 * mutation of the live object cannot corrupt retained state). Read by the
+	 * `subagent` await panel; cleared on terminal/cancel/purge/dispose.
+	 *
+	 * Ignored for ids without a canonical `SubagentRecord` (e.g. foreground/inline
+	 * task runs that share the executor path) so the map only holds detached
+	 * subagent progress and never accumulates untracked foreground task state.
+	 */
+	recordSubagentProgress(subagentId: string, progress: AgentProgress): void {
+		if (!this.#subagentRecords.has(subagentId)) return;
+		this.#subagentProgress.set(subagentId, structuredClone(progress));
+	}
+
+	getSubagentProgress(subagentId: string): AgentProgress | undefined {
+		return this.#subagentProgress.get(subagentId);
+	}
+
+	/**
+	 * True only when a live, in-session progress producer exists for this id: a
+	 * canonical registered record with a live handle or an in-memory running job.
+	 * False for `SubagentTool` backward-compat job synthesis and resumed-from-disk
+	 * records, which have no live producer to stream from.
+	 */
+	hasLiveSubagent(subagentId: string, filter?: AsyncJobFilter): boolean {
+		const rec = this.getSubagentRecord(subagentId, filter);
+		if (!rec) return false;
+		if (this.#liveHandles.has(rec.subagentId)) return true;
+		const job = rec.currentJobId ? this.#jobs.get(rec.currentJobId) : undefined;
+		return job?.status === "running";
+	}
+
 	/** Install the TaskTool-owned resume runner. Returns the new job id, or undefined on failure. */
 	setResumeRunner(
 		runner: (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined,
@@ -561,6 +594,7 @@ export class AsyncJobManager {
 		if (rec) {
 			rec.status = "paused";
 			this.#liveHandles.delete(rec.subagentId);
+			this.#subagentProgress.delete(rec.subagentId);
 		}
 	}
 
@@ -569,6 +603,7 @@ export class AsyncJobManager {
 		if (!rec) return;
 		rec.status = status;
 		this.#liveHandles.delete(rec.subagentId);
+		this.#subagentProgress.delete(rec.subagentId);
 	}
 
 	/** Request a graceful safe-boundary pause of a running subagent. */
@@ -626,6 +661,9 @@ export class AsyncJobManager {
 		message?: string,
 	): { ok: boolean; status?: SubagentLifecycle; jobId?: string; reason?: string } {
 		const prevJobId = rec.currentJobId;
+		// Clear any retained progress from the previous run so a resumed subagent
+		// never renders the prior run's tool/output as live before it emits again.
+		this.#subagentProgress.delete(rec.subagentId);
 		const newJobId = this.#resumeRunner?.(rec.subagentId, message, this.#resumeDescriptors.get(rec.subagentId));
 		if (!newJobId) return { ok: false, reason: "resume_failed" };
 		if (prevJobId && prevJobId !== newJobId) rec.historicalJobIds.push(prevJobId);
@@ -663,6 +701,7 @@ export class AsyncJobManager {
 			}
 			rec.status = "cancelled";
 			this.#liveHandles.delete(rec.subagentId);
+			this.#subagentProgress.delete(rec.subagentId);
 			this.#drainResumeQueue();
 			return true;
 		}
@@ -671,6 +710,7 @@ export class AsyncJobManager {
 			if (idx !== -1) this.#resumeQueue.splice(idx, 1);
 			rec.status = "cancelled";
 			rec.queued = undefined;
+			this.#subagentProgress.delete(rec.subagentId);
 			return true;
 		}
 		return false;
@@ -685,6 +725,7 @@ export class AsyncJobManager {
 				this.#liveHandles.delete(sid);
 				this.#resumeDescriptors.delete(sid);
 				this.#subagentRecords.delete(sid);
+				this.#subagentProgress.delete(sid);
 			}
 		}
 	}
@@ -1021,6 +1062,7 @@ export class AsyncJobManager {
 		this.#ownerCleanups.clear();
 		this.#subagentRecords.clear();
 		this.#liveHandles.clear();
+		this.#subagentProgress.clear();
 		this.#resumeDescriptors.clear();
 		this.#resumeQueue.length = 0;
 		this.#notifyChange();

package/src/cli/fast-help.ts

@@ -0,0 +1,80 @@
+import { APP_NAME, CONFIG_DIR_NAME } from "@gajae-code/utils/dirs";
+
+export function getExtraHelpText(): string {
+	return `Environment Variables:
+  # Core Providers
+  ANTHROPIC_API_KEY          - Anthropic Claude models
+  ANTHROPIC_OAUTH_TOKEN      - Anthropic OAuth (takes precedence over API key)
+  CLAUDE_CODE_USE_FOUNDRY    - Enable Anthropic Foundry mode (uses Foundry endpoint + mTLS)
+  FOUNDRY_BASE_URL           - Anthropic Foundry base URL (e.g., https://<foundry-host>)
+  ANTHROPIC_FOUNDRY_API_KEY  - Anthropic token used as Authorization: Bearer <token> in Foundry mode
+  ANTHROPIC_CUSTOM_HEADERS   - Extra Foundry headers (e.g., "user-id: USERNAME")
+  CLAUDE_CODE_CLIENT_CERT    - Client certificate (PEM path or inline PEM) for mTLS
+  CLAUDE_CODE_CLIENT_KEY     - Client private key (PEM path or inline PEM) for mTLS
+  NODE_EXTRA_CA_CERTS        - CA bundle path (or inline PEM) for server certificate validation
+  OPENAI_API_KEY             - OpenAI GPT models
+  GEMINI_API_KEY             - Google Gemini models
+  GITHUB_TOKEN               - GitHub Copilot (or GH_TOKEN, COPILOT_GITHUB_TOKEN)
+
+  # Additional LLM Providers
+  AZURE_OPENAI_API_KEY       - Azure OpenAI models
+  GROQ_API_KEY               - Groq models
+  CEREBRAS_API_KEY           - Cerebras models
+  XAI_API_KEY                - xAI Grok models
+  OPENROUTER_API_KEY         - OpenRouter aggregated models
+  KILO_API_KEY               - Kilo Gateway models
+  MISTRAL_API_KEY            - Mistral models
+  ZAI_API_KEY                - z.ai models (ZhipuAI/GLM)
+  MINIMAX_API_KEY            - MiniMax models
+  OPENCODE_API_KEY           - OpenCode Zen/OpenCode Go models
+  CURSOR_ACCESS_TOKEN        - Cursor AI models
+  AI_GATEWAY_API_KEY         - Vercel AI Gateway
+
+  # Cloud Providers
+  AWS_PROFILE                - AWS Bedrock (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
+  GOOGLE_CLOUD_PROJECT       - Google Vertex AI (requires GOOGLE_CLOUD_LOCATION)
+  GOOGLE_APPLICATION_CREDENTIALS - Service account for Vertex AI
+
+  # Search & Tools
+  EXA_API_KEY                - Exa web search
+  BRAVE_API_KEY              - Brave web search
+  PERPLEXITY_API_KEY         - Perplexity web search (API)
+  PERPLEXITY_COOKIES         - Perplexity web search (session cookie)
+  TAVILY_API_KEY             - Tavily web search
+  ANTHROPIC_SEARCH_API_KEY   - Anthropic search provider
+
+  # Configuration
+  GJC_CODING_AGENT_DIR       - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
+  GJC_PACKAGE_DIR            - Override package directory (for Nix/Guix store paths)
+  GJC_SMOL_MODEL              - Override smol/fast model (see --smol)
+  GJC_SLOW_MODEL              - Override slow/reasoning model (see --slow)
+  GJC_PLAN_MODEL              - Override planning model (see --plan)
+  GJC_NO_PTY                  - Disable PTY-based interactive bash execution
+  --tmux                       - Launch interactive startup inside a new tmux session
+  gjc session                  - List, inspect, create, remove, or attach tagged GJC-managed tmux sessions
+  GJC_LAUNCH_POLICY           - Launch policy for --tmux startup: tmux or direct
+  GJC_TMUX_SESSION            - Explicit tmux session name override for --tmux startup
+
+  For complete environment variable reference, see:
+  docs/environment-variables.md
+Available Tools (default-enabled unless noted):
+  read          - Read file contents
+  bash          - Execute bash commands
+  edit          - Edit files with find/replace
+  write         - Write files (creates/overwrites)
+  grep          - Search file contents
+  find          - Find files by glob pattern
+  lsp           - Language server protocol (code intelligence)
+  python        - Execute Python code (requires: ${APP_NAME} setup python)
+  notebook      - Edit Jupyter notebooks
+  inspect_image - Analyze images with a vision model
+  browser       - Browser automation (Puppeteer)
+  task          - Launch sub-agents for parallel tasks
+  todo_write    - Manage todo/task lists
+  web_search    - Search the web
+  ask           - Ask user questions (interactive mode only)
+
+Useful Commands:
+  ${APP_NAME} --list-models        - List configured provider models
+  ${APP_NAME} --help               - Show this help`;
+}

package/src/cli/setup-cli.ts

@@ -14,6 +14,12 @@ import {
 	readGjcManagedCodexHooksStatus,
 } from "../hooks/codex-native-hooks-config";
 import { theme } from "../modes/theme/theme";
+import {
+	formatHermesSetupResult,
+	type HermesSetupFlags,
+	hermesSetupExitCode,
+	runHermesSetup,
+} from "../setup/hermes-setup";
 import {
 	addApiCompatibleProvider,
 	formatProviderPresetList,
@@ -21,7 +27,7 @@ import {
 	parseProviderCompatibility,
 } from "../setup/provider-onboarding";
 
-export type SetupComponent = "defaults" | "hooks" | "provider" | "python" | "stt";
+export type SetupComponent = "defaults" | "hermes" | "hooks" | "provider" | "python" | "stt";
 
 export interface SetupCommandArgs {
 	component: SetupComponent;
@@ -36,10 +42,25 @@ export interface SetupCommandArgs {
 		apiKeyEnv?: string;
 		model?: string[];
 		modelsPath?: string;
+		smoke?: boolean;
+		install?: boolean;
+		root?: string[];
+		repo?: string;
+		profile?: string;
+		sessionCommand?: string;
+		noWorktree?: boolean;
+		worktreeName?: string;
+		stateRoot?: string;
+		mutation?: string[];
+		artifactByteCap?: string;
+		serverKey?: string;
+		gjcCommand?: string;
+		target?: string;
+		profileDir?: string;
 	};
 }
 
-const VALID_COMPONENTS: SetupComponent[] = ["defaults", "hooks", "provider", "python", "stt"];
+const VALID_COMPONENTS: SetupComponent[] = ["defaults", "hermes", "hooks", "provider", "python", "stt"];
 
 function hasProviderSetupFlags(flags: SetupCommandArgs["flags"]): boolean {
 	return (
@@ -88,6 +109,36 @@ export function parseSetupArgs(args: string[]): SetupCommandArgs | undefined {
 			flags.check = true;
 		} else if (arg === "--force" || arg === "-f") {
 			flags.force = true;
+		} else if (arg === "--smoke") {
+			flags.smoke = true;
+		} else if (arg === "--install") {
+			flags.install = true;
+		} else if (arg === "--root") {
+			flags.root = [...(flags.root ?? []), args[++i] ?? ""];
+		} else if (arg === "--repo") {
+			flags.repo = args[++i];
+		} else if (arg === "--profile") {
+			flags.profile = args[++i];
+		} else if (arg === "--session-command") {
+			flags.sessionCommand = args[++i];
+		} else if (arg === "--no-worktree") {
+			flags.noWorktree = true;
+		} else if (arg === "--worktree-name") {
+			flags.worktreeName = args[++i];
+		} else if (arg === "--state-root") {
+			flags.stateRoot = args[++i];
+		} else if (arg === "--mutation") {
+			flags.mutation = [...(flags.mutation ?? []), args[++i] ?? ""];
+		} else if (arg === "--artifact-byte-cap") {
+			flags.artifactByteCap = args[++i];
+		} else if (arg === "--server-key") {
+			flags.serverKey = args[++i];
+		} else if (arg === "--gjc-command") {
+			flags.gjcCommand = args[++i];
+		} else if (arg === "--target") {
+			flags.target = args[++i];
+		} else if (arg === "--profile-dir") {
+			flags.profileDir = args[++i];
 		} else if (arg === "--compat") {
 			flags.compat = args[++i];
 		} else if (arg === "--preset") {
@@ -177,6 +228,9 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 		case "defaults":
 			await handleDefaultsSetup(cmd.flags);
 			break;
+		case "hermes":
+			await handleHermesSetup(cmd.flags);
+			break;
 		case "hooks":
 			await handleHooksSetup(cmd.flags);
 			break;
@@ -192,6 +246,26 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 	}
 }
 
+async function handleHermesSetup(flags: HermesSetupFlags): Promise<void> {
+	try {
+		const result = await runHermesSetup(flags);
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+			return;
+		}
+		process.stdout.write(`${chalk.green(`${theme.status.success} Hermes MCP setup ready`)}\n`);
+		process.stdout.write(`${chalk.dim(formatHermesSetupResult(result))}\n`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify({ ok: false, error: message }, null, 2)}\n`);
+		} else {
+			process.stderr.write(`${chalk.red(`${theme.status.error} Hermes MCP setup failed`)}\n`);
+			process.stderr.write(`${chalk.dim(message)}\n`);
+		}
+		process.exit(hermesSetupExitCode(error));
+	}
+}
 async function handleProviderSetup(flags: {
 	json?: boolean;
 	force?: boolean;
@@ -410,6 +484,7 @@ ${chalk.bold("Usage:")}
 
 ${chalk.bold("Components:")}
   defaults  Install bundled GJC default workflow skills (default)
+  hermes   Optional: render/install a Hermes MCP bridge setup package
   hooks     Optional: install GJC native Codex UserPromptSubmit/Stop skill-state hooks
   provider  Optional: add a preset, OpenAI-compatible, or Anthropic-compatible API provider
   python    Optional: verify a Python 3 interpreter is reachable for code execution
@@ -421,6 +496,12 @@ ${chalk.bold("Provider example:")}
   ${APP_NAME} setup provider --preset glm
   MY_PROVIDER_KEY=sk-... ${APP_NAME} setup provider --compat openai --provider my-oai --base-url https://api.example.com/v1 --api-key-env MY_PROVIDER_KEY --model gpt-example
 
+${chalk.bold("Hermes example:")}
+  ${APP_NAME} setup hermes --root /path/to/repo
+  ${APP_NAME} setup hermes --root /path/to/repo --profile my-bot --repo gajae-code --profile-dir /path/to/hermes/profile --install
+  ${APP_NAME} setup hermes --root /path/to/repo --worktree-name hermes-gajae-code
+  ${APP_NAME} setup hermes --root /path/to/repo --session-command "gjc --worktree hermes-custom --model <provider/model>"
+
 ${chalk.bold("Options:")}
   -c, --check       Check if dependencies are installed without installing
   -f, --force       Overwrite existing default workflow skill files
@@ -432,6 +513,17 @@ ${chalk.bold("Options:")}
   --api-key-env     Read provider API key from this environment variable
   --model, --models Model id to add (repeat or comma-separate)
   --models-path     Override models config path
+  --smoke           Run Hermes MCP setup smoke checks
+  --install         Install generated Hermes setup files
+  --root            Allowed Hermes MCP workdir/artifact root (repeatable)
+  --profile         Hermes MCP profile namespace
+  --repo            Hermes MCP repo namespace
+  --session-command Explicit GJC session command; disables generated worktree flags
+  --no-worktree     Disable default GJC --worktree isolation for Hermes sessions
+  --worktree-name   Named GJC --worktree branch for Hermes sessions
+  --mutation        Hermes MCP mutation classes: sessions,questions,reports,all
+  --target          Hermes config file target for config-only install
+  --profile-dir     Hermes profile directory for full setup install
 
 ${chalk.bold("Examples:")}
   ${APP_NAME} setup                  Install bundled GJC default workflow skills
@@ -439,6 +531,7 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} setup defaults --check Check bundled GJC default workflow skills are installed
   ${APP_NAME} setup hooks            Install native Codex skill-state hooks
   ${APP_NAME} setup hooks --check    Check native Codex skill-state hooks
+  ${APP_NAME} setup hermes --root /path/to/repo Render a model-agnostic Hermes MCP setup preview
   ${APP_NAME} setup python           Install Python execution dependencies
   ${APP_NAME} setup stt              Install speech-to-text dependencies
   ${APP_NAME} setup stt --check      Check if STT dependencies are available