> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase23-session01-claude-code-agent-route/spec.md). # Session Specification **Session ID**: `phase23-session01-claude-code-agent-route` **Phase**: 23 - Non-Hermes Routes, Polish And Closeout **Status**: Not Started **Created**: 2026-06-02 *** ## 1. Session Overview This session starts Phase 23 by adding the missing Claude Code local-agent route at `/agents/claude-code`. The route should reuse the current AIOS Mission Control implementation and existing Hermes bridge safety model instead of copying the old v2.3 route API verbatim. The v2.3 source route was a thin page that passed `agent="claude-code"` into `HermesMissionControl` and applied a blue visual skin. AIOS has since evolved: `HermesMissionControl` now lives at `src/components/hermes/hermes-mission-control.tsx` and receives typed `missions`, `admin`, and `demoMode` props from the page layer. This session adapts the intended Claude Code experience to the current hook-driven API. The result should be a focused local-agent page, a sidebar entry next to Hermes and OpenClaw, route metadata and route-tree registration through normal TanStack tooling, and tests proving that the route does not introduce unsafe write, spawn, polling, or private-data paths. *** ## 2. Objectives 1. Add `/agents/claude-code` as a real AI OS local-agent route using the shared Mission Control surface. 2. Adapt Mission Control presentation for Claude Code with typed copy and blue skin behavior while preserving the existing Hermes bridge/admin safety boundaries. 3. Wire the route into the sidebar Agents section with the Claude logo and accessible navigation behavior. 4. Add focused tests for route metadata, safe bridge reuse, route states, sidebar navigation, and generated route-tree registration. *** ## 3. Prerequisites ### Required Sessions * [x] `phase19-session01-mission-control-write` - Provides Mission Control, mission read state, and admin-gated mission writes. * [x] `phase19-session02-documents-gallery-write` - Provides the current Hermes admin hook pattern and shared route safety context. * [x] `phase20-session02-cleanup-parity-signoff` - Provides parity sign-off for the long-tail Hermes surface used as the safety baseline. * [x] `phase21-session03-authoritative-claude-usage-oauth` - Provides the Claude Code privacy posture for keeping credentials script-only and browser output bounded. * [x] `phase22-session03-setup-wizard-dream-sources-strip` - Provides current host home and Dream source placement context for the home-placement deferral decision. ### Required Tools/Knowledge * React 19 route/component conventions. * TanStack Router file-route naming and generated route-tree workflow. * Existing `useHermes` and `useHermesAdmin` hook contracts. * Existing `HermesMissionControl` props and admin-gated mutation behavior. * Existing route and sidebar test helpers. * v2.3 source route at `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/agents.claude-code.tsx`. ### Environment Requirements * No live Hermes install, Claude Code install, or admin mode is required for tests. * The route must degrade safely through loading, setup-required, offline, token-failure, endpoint-error, empty, and demo states. * `src/routeTree.gen.ts` must be updated by normal TanStack code generation, not by hand editing. *** ## 4. Scope ### In Scope (MVP) * AI OS users can open `/agents/claude-code` - Implement a route file that mounts a Claude Code Mission Control page. * AI OS users can reach Claude Code from the Agents sidebar - Add the Claude logo entry next to Hermes and OpenClaw with blue tone styling. * AI OS reuses shared Mission Control behavior - Use the existing `useHermes`, `useHermesAdmin`, and `HermesMissionControl` contracts instead of adding new bridge endpoints. * AI OS shows Claude Code presentation copy - Add typed presentation configuration for Claude Code labels, prompt-copy feedback, and route headings where the shared component needs agent-specific language. * AI OS applies a blue local-agent skin - Reuse the Hermes route shell and override route-scoped tokens/selectors without importing unrelated v2.3 monolith code. * AI OS records the home-placement decision - Add implementation notes that either point to an existing Mission Control home slot or defer home placement because the current home information architecture has no such slot. * AI OS validates route registration - Regenerate and test route-tree output through normal tooling. ### Out of Scope (Deferred) * New Claude Code bridge endpoints, spawn behavior, shell execution, git writes, workspace writes, or remote Codex support - Reason: this session is a route/presentation reuse pass only. * Reworking Hermes Mission Control beyond the typed presentation hook needed by Claude Code - Reason: Phase 19 owns Mission Control behavior. * Rebranding AI OS around Claude Code - Reason: Claude Code is a host cockpit local-agent surface, not the product identity. * Hand-editing `src/routeTree.gen.ts` - Reason: TanStack Router owns this file. * Adding home Mission Control placement when no current AIOS home slot exists - Reason: the PRD allows documented deferral when the current home IA does not support the placement cleanly. *** ## 5. Technical Approach ### Architecture Create a focused Claude Code page component under the Hermes component area so it can reuse the existing Hermes hook/admin contracts and Mission Control section without duplicating bridge logic. The page should follow the current Hermes read-only page pattern: call `useHermes`, call `useHermesAdmin` with the resolved token, derive demo views when demo mode is active, and render explicit state banners before the shared Mission Control section. Extend `HermesMissionControl` only where the current component needs agent-specific presentation. A small typed config such as `missionControlAgent="hermes" | "claude-code"` is acceptable when it changes labels, copied-prompt text, actor wording, or feedback copy. It must not change query keys, endpoint paths, token headers, mutation gating, duplicate-trigger prevention, or redaction behavior. Add `src/routes/agents.claude-code.tsx` as a thin TanStack route mount point with AI OS metadata. Let TanStack code generation update `src/routeTree.gen.ts` after the route exists. Update the route-tree test expectations, but do not manually patch generated route-tree internals. ### Design Patterns * Route as mount point: Route file declares metadata and renders the page component. * Hook-layer data ownership: Route/page reads through `useHermes` and `useHermesAdmin`; components do not fetch ad hoc bridge data. * Typed presentation config: Agent-specific copy is explicit and exhaustive instead of scattered string checks. * Scoped skin: Blue styling remains under `.claude-code-agent-route` and the existing Hermes route shell selectors. * Typed degradation over throws: Missing bridge data produces bounded UI states. * Safety reuse over new capability: The route reuses existing admin gating and does not add endpoint or execution surfaces. ### Technology Stack * React 19.2.0 for route and component rendering. * TypeScript 6.0.3 for typed presentation config and props. * TanStack Router 1.170.4 and TanStack Start 1.168.6 for file-route behavior. * React Query 5.100.10 through existing Hermes hooks. * Tailwind CSS 4.2.1 and route-scoped CSS in `src/styles.css`. * lucide-react 1.16.0 and existing `src/assets/claude-logo.png`. * Vitest 4.1.6 and Testing Library for route, sidebar, component, and route-tree checks. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ---------------------------------------------------- | ---------------------------------------------------------------------------- | ---------- | | `src/components/hermes/claude-code-mission-page.tsx` | Claude Code page adapter that reuses Hermes hooks/admin and Mission Control. | \~220 | | `src/routes/agents.claude-code.tsx` | TanStack file route for `/agents/claude-code`. | \~25 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- | | `src/components/hermes/hermes-mission-control.tsx` | Add typed agent presentation config without changing bridge behavior. | \~80 | | `src/components/hermes/__tests__/hermes-mission-control.test.tsx` | Cover Claude Code presentation copy and unchanged write gating. | \~60 | | `src/styles.css` | Add route-scoped Claude Code blue skin that reuses Hermes shell structure. | \~90 | | `src/components/app-sidebar.tsx` | Add Claude Code entry next to Hermes and OpenClaw. | \~20 | | `src/components/__tests__/app-sidebar.test.tsx` | Cover Claude Code link rendering, active state, and agent count. | \~40 | | `src/routes/__tests__/agents.test.tsx` | Add Claude Code route metadata and state coverage using existing bridge mocks. | \~130 | | `src/routes/__tests__/route-tree.test.ts` | Add `/agents/claude-code` to generated route expectations. | \~10 | | `src/routeTree.gen.ts` | Generated route registration from TanStack tooling only. | generated | | `.spec_system/specs/phase23-session01-claude-code-agent-route/implementation-notes.md` | Record source anchors, safety reuse, route-tree generation, and home-placement decision. | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `/agents/claude-code` renders through the shared Mission Control surface. * [ ] Route metadata identifies Claude Code as an AI OS local-agent page, not as AI OS product rebranding. * [ ] The route uses Claude Code presentation copy and a blue skin. * [ ] Sidebar navigation reaches `/agents/claude-code` and marks it active. * [ ] The page handles loading, setup-required, offline, token-failure, endpoint-error, empty, and demo states without crashing. * [ ] No route code calls new Claude-specific bridge endpoints or bypasses the existing Mission Control safety gate. * [ ] Route tree registration is produced by normal TanStack tooling. * [ ] Implementation notes record whether home placement was implemented or intentionally deferred. ### Testing Requirements * [ ] Mission Control presentation tests written and passing. * [ ] Claude Code route tests written and passing. * [ ] Sidebar tests updated and passing. * [ ] Route-tree test updated and passing. * [ ] Focused typecheck/build validation passes or records actionable gaps. * [ ] Manual route smoke completed for `/agents/claude-code`. ### Non-Functional Requirements * [ ] Browser-visible output exposes no raw credentials, bearer tokens, private local paths, raw prompt payloads, or unbounded bridge errors. * [ ] New UI text fits mobile and desktop layouts without overlap. * [ ] No new heavy dependencies or route-level dynamic imports expand the base bundle unnecessarily. * [ ] Existing Hermes route behavior remains unchanged except for the typed presentation prop default. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Generated files are produced by tooling, not hand-edited. *** ## 8. Implementation Notes ### Key Considerations * The v2.3 route import path and component API are stale for AIOS. The current Mission Control component lives under `src/components/hermes/` and receives hook-supplied props. * Route-tree output must be generated after the new route file exists. * The current home page has Dream, usage, Hermes signal, skills, memory, integrations, workspaces, activity, and setup surfaces but no established Mission Control slot. Home placement should be deferred unless implementation finds a clean current slot. * Reuse `src/assets/claude-logo.png` instead of introducing new image assets. ### Potential Challenges * Current Mission Control copy is Hermes-specific: Mitigate with a small typed presentation config and default `hermes` behavior. * Generated route tree may not update in isolated test runs: Mitigate by running the normal TanStack build/dev codegen path and updating the route-tree test only after generated output exists. * Blue skin could fight Hermes route CSS: Mitigate by applying `.hermes-agent-route` and `.claude-code-agent-route` together, then adding scoped token overrides. * Route tests may be slow if they cover every bridge endpoint: Mitigate by reusing the existing `agents.test.tsx` fetch mocks and focusing assertions on state behavior and endpoint boundaries. ### Relevant Considerations * \[P04] **Hermes bridge guardrails must stay intact**: Claude Code route reuse must keep loopback/token/admin gates and avoid new bridge or execution paths. * \[P01] **3D vendor chunk budget**: This route should not add new heavy assets or vendor imports. * \[P08] **Local agent privacy boundary**: Browser output may expose sanitized state and labels only. * \[P00] **Do not document planned features as implemented**: Implementation notes should distinguish route reuse from any deferred Claude-specific runtime capability. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Route state gaps could leave users with a blank page during bridge loading, offline, token-failure, or setup-required conditions. * Presentation changes could accidentally widen Mission Control write behavior or bypass duplicate-trigger protection. * Generated route-tree handling could become brittle if the generated file is edited by hand. * Sidebar additions could create inaccessible image-only navigation if labels and active states are not preserved. *** ## 9. Testing Strategy ### Unit Tests * Add Mission Control tests for Claude Code presentation labels while verifying existing disabled/demo/admin-gated write behavior remains intact. * Add sidebar tests for the Claude Code agent link, active styling, and accessible label. * Update route-tree test expectations after generated route registration. ### Integration Tests * Extend `src/routes/__tests__/agents.test.tsx` to render the Claude Code page through existing Hermes bridge mocks. * Verify live, setup-required, demo, loading, endpoint-error, offline, and token-failure states. * Assert the route uses existing Hermes bridge/token/admin endpoint paths and does not call new unsafe Claude-specific routes. ### Manual Testing * Run the dev server and open `/agents/claude-code`. * Confirm the sidebar entry is reachable and active. * Confirm the page remains usable without a live Hermes install by opening demo mode or setup-required states. * Confirm text and sidebar layout remain usable at mobile and desktop widths. ### Edge Cases * Browser offline before any bridge fetch. * Token endpoint failure after status succeeds. * Hermes setup missing or unconfigured. * Empty mission list. * Admin disabled while mission reads succeed. * Demo mode returning bounded sample missions only. * Very long mission labels still bounded by existing Mission Control behavior. *** ## 10. Dependencies ### External Libraries * No new external libraries. ### Other Sessions * **Depends on**: `phase19-session01-mission-control-write`, `phase19-session02-documents-gallery-write`, `phase20-session02-cleanup-parity-signoff`, `phase21-session03-authoritative-claude-usage-oauth`, `phase22-session03-setup-wizard-dream-sources-strip` * **Depended by**: `phase23-session03-non-hermes-parity-documentation-closeout` *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase23-session01-claude-code-agent-route/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.