Here's a well-structured feature rdequest for Hermes integration in Archon:

Problem

What problem are you trying to solve? Archon currently only supports Claude Code and Codex as AI assistants, limiting users to proprietary, cloud-based solutions. This creates several issues:

• Vendor lock-in: Users cannot easily switch between different LLM providers
• Privacy concerns: All code must be sent to external APIs (Anthropic or OpenAI)
• Cost constraints: No option for cost-effective local models or alternative cloud providers
• Flexibility: Cannot leverage the 200+ models available through OpenRouter or local models via Ollama

Who experiences it?

• Developers wanting to use local LLMs for privacy/compliance reasons
• Teams with budget constraints seeking cheaper alternatives (e.g., DeepSeek, Qwen)
• Users in regions with restricted access to Claude/OpenAI
• Organizations requiring on-premise AI solutions
• Developers wanting to experiment with multiple model providers in their workflows

How often does it come up?

• Every time a user wants to run Archon but doesn't have Claude Code or Codex credentials
• When users hit rate limits or quotas with their current provider
• When organizations evaluate Archon for adoption but have compliance requirements preventing external API usage
• Daily for developers who prefer open-source, self-hosted solutions

Proposed Solution

Add Hermes Agent as a third AI assistant provider in Archon, alongside Claude Code and Codex. Hermes Agent is an open-source AI agent framework by Nous Research that:

• Supports 15+ LLM providers (OpenAI, Anthropic, OpenRouter, Kimi, MiniMax, etc.)
• Works with any OpenAI-compatible endpoint (including Ollama for local models)
• Has built-in tool execution capabilities (terminal, file operations, web browsing)
• Provides persistent memory and self-improving skills
• Is MIT licensed and fully self-hostable

This would position Archon as the most flexible AI coding workflow engine, supporting proprietary (Claude, Codex), community-driven (Pi), and fully open-source (Hermes) options.

User Flow

Before (current)

1. User wants to use Archon
2. User must have either:
   - Claude Pro/Max subscription + Claude Code setup
   - OR Codex credentials
3. [!] If user has neither, they cannot use Archon at all
4. [!] If user wants to use local models (Ollama), no option available
5. [!] If user wants to switch providers mid-workflow, limited to Claude/Codex only

After (proposed)

1. User wants to use Archon
2. User runs: archon init
3. [+] Setup wizard now shows three options:
   - Claude Code (cloud, subscription-based)
   - Codex (cloud, API-based)
   - Hermes Agent (flexible: cloud OR local)
4. [+] If user selects Hermes:
   a. Install Hermes Agent automatically OR detect existing installation
   b. Run hermes setup wizard (or import existing Hermes config)
   c. User chooses their provider:
      - OpenRouter (200+ models, single API key)
      - Local Ollama (privacy, zero cost)
      - OpenAI, Anthropic, or any OpenAI-compatible endpoint
5. [+] Set in .archon/config.yaml:
   assistant: hermes
   assistants:
     hermes:
       model: "qwen2.5-coder:32b"  # or any model
       endpoint: "http://localhost:11434/v1"  # or cloud API
6. User runs workflows normally with `archon workflow run <name>`
7. [+] Workflows can override provider per-node:
   nodes:
     - name: code-review
       provider: hermes
       model: "claude-opus-4-6"  # via OpenRouter
     - name: implement
       provider: hermes
       model: "qwen2.5-coder:32b"  # local Ollama

Alternatives Considered

Why Hermes is the right choice:

• Open source (MIT license) - aligns with Archon's community values
• Already has tool execution, memory, and skills - matches Claude Code/Codex feature parity
• Multi-provider by design - future-proofs Archon against provider changes
• Active development by Nous Research (reputable team)
• Growing community adoption

Scope

Package(s) likely affected:

• core - New HermesClient implementation of IAssistantClient
• workflows - Update provider type unions and validation schemas
• server - Config schema updates for Hermes provider
• cli - Setup wizard enhancements for Hermes installation
• web - Provider dropdown UI updates

Breaking change? No

• Purely additive feature
• Existing Claude/Codex workflows unaffected
• Old config files still valid

Database changes needed? No

• Conversation/workflow schemas already support arbitrary provider strings
• No new fields required

New external dependencies? Yes

• Hermes Agent Python package (installed as separate CLI tool, not npm dependency)
• OR TypeScript/JavaScript client library if we build a native integration
• Likely approach: Shell out to hermes CLI similar to how we shell out to claude CLI

Security Considerations

New permissions/capabilities? Yes

• Hermes has extensive tool access (file system, terminal, web browsing)
• Same security model as Claude Code/Codex but worth documenting

New external network calls? Yes

• Calls to user-configured LLM endpoints (OpenRouter, OpenAI, Anthropic, etc.)
• All controlled by user's Hermes configuration

Secrets/tokens handling? Yes

• Hermes stores API keys in ~/.hermes/auth.json and ~/.hermes/.env
• Archon should NOT handle Hermes API keys directly
• Let Hermes manage its own auth (same pattern as Claude Code global auth)

Security approach:

1. Recommended mode: HERMES_USE_GLOBAL_AUTH=true - use Hermes's existing auth
2. Explicit mode: Users can set provider-specific env vars if needed (OPENROUTER_API_KEY, etc.)
3. Archon reads Hermes config but doesn't store sensitive credentials
4. Document security best practices for Hermes tool access in workflows

Definition of Done

Core Integration:

• HermesClient implements IAssistantClient interface
• Client can start Hermes sessions and stream responses
• Client maps Hermes events (text_delta, tool_execution) to Archon's MessageChunk format
• Client propagates cwd, model selection, system prompts correctly

Configuration:

• Add hermes to ProviderType union in core/types
• Support assistant: hermes in .archon/config.yaml
• Support Hermes-specific config options:

  assistants:  hermes:    model: "qwen2.5-coder:32b"    provider: "ollama"  # or "openrouter", "openai", etc.    endpoint: "http://localhost:11434/v1"  # optional override
  

• DEFAULT_AI_ASSISTANT=hermes environment variable support

CLI Setup:

• archon init wizard includes Hermes option
• Auto-detect existing Hermes installation
• Offer to install Hermes if not present
• Validate Hermes config before completing setup

Workflows:

• Per-node provider: hermes overrides work correctly
• Per-node model: selection passes through to Hermes
• Abort/interrupt signal handling works
• Hermes tool execution appears in workflow logs

Testing:

• Unit tests for HermesClient message streaming
• Integration test: run simple workflow with Hermes
• Test provider switching (Claude → Hermes mid-workflow)
• Test with local Ollama endpoint
• Test with OpenRouter cloud endpoint
• E2E test in CI with mocked Hermes responses

Documentation:

• Update AI Assistants page with Hermes section
• Add Hermes to comparison table (Claude vs Codex vs Hermes)
• Document recommended models for different use cases
• Add troubleshooting section for common Hermes issues
• Update homepage to mention "3 AI providers" instead of "2"

Nice-to-haves (not blocking):

• Web UI shows Hermes provider option in settings
• Workflow Builder supports Hermes provider selection
• Example workflows using Hermes with local models
• Performance benchmarks (Hermes vs Claude vs Codex)

Additional Context:

Hermes GitHub: https://github.com/NousResearch/hermes-agent
Hermes Docs: https://hermes-agent.nousresearch.com/docs
Similar integration reference: Issue #965 (Pi coding agent integration)

This feature would make Archon accessible to a much broader audience and align it with the open-source ecosystem's values while maintaining support for users who prefer commercial providers.

Problem

What problem are you trying to solve?
Archon currently only supports Claude Code and Codex as AI assistants, limiting users to proprietary, cloud-based solutions. This creates several issues:

• Vendor lock-in: Users cannot easily switch between different LLM providers
• Privacy concerns: All code must be sent to external APIs (Anthropic or OpenAI)
• Cost constraints: No option for cost-effective local models or alternative cloud providers
• Flexibility: Cannot leverage the 200+ models available through OpenRouter or local models via Ollama

Who experiences it?

• Developers wanting to use local LLMs for privacy/compliance reasons
• Teams with budget constraints seeking cheaper alternatives (e.g., DeepSeek, Qwen)
• Users in regions with restricted access to Claude/OpenAI
• Organizations requiring on-premise AI solutions
• Developers wanting to experiment with multiple model providers in their workflows

How often does it come up?

• Every time a user wants to run Archon but doesn't have Claude Code or Codex credentials
• When users hit rate limits or quotas with their current provider
• When organizations evaluate Archon for adoption but have compliance requirements preventing external API usage
• Daily for developers who prefer open-source, self-hosted solutions

Proposed Solution

Add Hermes Agent as a third AI assistant provider in Archon, alongside Claude Code and Codex. Hermes Agent is an open-source AI agent framework by Nous Research that:

• Supports 15+ LLM providers (OpenAI, Anthropic, OpenRouter, Kimi, MiniMax, etc.)
• Works with any OpenAI-compatible endpoint (including Ollama for local models)
• Has built-in tool execution capabilities (terminal, file operations, web browsing)
• Provides persistent memory and self-improving skills
• Is MIT licensed and fully self-hostable

This would position Archon as the most flexible AI coding workflow engine, supporting proprietary (Claude, Codex), community-driven (Pi), and fully open-source (Hermes) options.

User Flow

Before (current)

1. User wants to use Archon
2. User must have either:
   - Claude Pro/Max subscription + Claude Code setup
   - OR Codex credentials
3. [!] If user has neither, they cannot use Archon at all
4. [!] If user wants to use local models (Ollama), no option available
5. [!] If user wants to switch providers mid-workflow, limited to Claude/Codex only

After (proposed)

1. User wants to use Archon
2. User runs: archon init
3. [+] Setup wizard now shows three options:
   - Claude Code (cloud, subscription-based)
   - Codex (cloud, API-based)
   - Hermes Agent (flexible: cloud OR local)
4. [+] If user selects Hermes:
   a. Install Hermes Agent automatically OR detect existing installation
   b. Run hermes setup wizard (or import existing Hermes config)
   c. User chooses their provider:
      - OpenRouter (200+ models, single API key)
      - Local Ollama (privacy, zero cost)
      - OpenAI, Anthropic, or any OpenAI-compatible endpoint
5. [+] Set in .archon/config.yaml:
   assistant: hermes
   assistants:
     hermes:
       model: "qwen2.5-coder:32b"  # or any model
       endpoint: "http://localhost:11434/v1"  # or cloud API
6. User runs workflows normally with `archon workflow run <name>`
7. [+] Workflows can override provider per-node:
   nodes:
     - name: code-review
       provider: hermes
       model: "claude-opus-4-6"  # via OpenRouter
     - name: implement
       provider: hermes
       model: "qwen2.5-coder:32b"  # local Ollama

Alternatives Considered

Why Hermes is the right choice:

• Open source (MIT license) - aligns with Archon's community values
• Already has tool execution, memory, and skills - matches Claude Code/Codex feature parity
• Multi-provider by design - future-proofs Archon against provider changes
• Active development by Nous Research (reputable team)
• Growing community adoption

Scope

Package(s) likely affected:

• core - New HermesClient implementation of IAssistantClient
• workflows - Update provider type unions and validation schemas
• server - Config schema updates for Hermes provider
• cli - Setup wizard enhancements for Hermes installation
• web - Provider dropdown UI updates

Breaking change? No

• Purely additive feature
• Existing Claude/Codex workflows unaffected
• Old config files still valid

Database changes needed? No

• Conversation/workflow schemas already support arbitrary provider strings
• No new fields required

New external dependencies? Yes

• Hermes Agent Python package (installed as separate CLI tool, not npm dependency)
• OR TypeScript/JavaScript client library if we build a native integration
• Likely approach: Shell out to hermes CLI similar to how we shell out to claude CLI

Security Considerations

New permissions/capabilities? Yes

• Hermes has extensive tool access (file system, terminal, web browsing)
• Same security model as Claude Code/Codex but worth documenting

New external network calls? Yes

• Calls to user-configured LLM endpoints (OpenRouter, OpenAI, Anthropic, etc.)
• All controlled by user's Hermes configuration

Secrets/tokens handling? Yes

• Hermes stores API keys in ~/.hermes/auth.json and ~/.hermes/.env
• Archon should NOT handle Hermes API keys directly
• Let Hermes manage its own auth (same pattern as Claude Code global auth)

Security approach:

1. Recommended mode: HERMES_USE_GLOBAL_AUTH=true - use Hermes's existing auth
2. Explicit mode: Users can set provider-specific env vars if needed (OPENROUTER_API_KEY, etc.)
3. Archon reads Hermes config but doesn't store sensitive credentials
4. Document security best practices for Hermes tool access in workflows

Definition of Done

Core Integration:

• HermesClient implements IAssistantClient interface
• Client can start Hermes sessions and stream responses
• Client maps Hermes events (text_delta, tool_execution) to Archon's MessageChunk format
• Client propagates cwd, model selection, system prompts correctly

Configuration:

• Add hermes to ProviderType union in core/types
• Support assistant: hermes in .archon/config.yaml
• Support Hermes-specific config options:

  assistants:
    hermes:
      model: "qwen2.5-coder:32b"
      provider: "ollama"  # or "openrouter", "openai", etc.
      endpoint: "http://localhost:11434/v1"  # optional override

• DEFAULT_AI_ASSISTANT=hermes environment variable support

CLI Setup:

• archon init wizard includes Hermes option
• Auto-detect existing Hermes installation
• Offer to install Hermes if not present
• Validate Hermes config before completing setup

Workflows:

• Per-node provider: hermes overrides work correctly
• Per-node model: selection passes through to Hermes
• Abort/interrupt signal handling works
• Hermes tool execution appears in workflow logs

Testing:

• Unit tests for HermesClient message streaming
• Integration test: run simple workflow with Hermes
• Test provider switching (Claude → Hermes mid-workflow)
• Test with local Ollama endpoint
• Test with OpenRouter cloud endpoint
• E2E test in CI with mocked Hermes responses

Documentation:

• Update [AI Assistants](https://archon.diy/getting-started/ai-assistants/) page with Hermes section
• Add Hermes to comparison table (Claude vs Codex vs Hermes)
• Document recommended models for different use cases
• Add troubleshooting section for common Hermes issues
• Update homepage to mention "3 AI providers" instead of "2"

Nice-to-haves (not blocking):

• Web UI shows Hermes provider option in settings
• Workflow Builder supports Hermes provider selection
• Example workflows using Hermes with local models
• Performance benchmarks (Hermes vs Claude vs Codex)

Additional Context:

Hermes GitHub: https://github.com/NousResearch/hermes-agent
Hermes Docs: https://hermes-agent.nousresearch.com/docs
Similar integration reference: Issue #965 (Pi coding agent integration)

This feature would make Archon accessible to a much broader audience and align it with the open-source ecosystem's values while maintaining support for users who prefer commercial providers.