Hermes Studio Help

1. Getting Started

Connecting to Hermes Gateway

Hermes Studio communicates with your AI agents through the Hermes Gateway server. Before you can use any features, you need to establish a connection.

1. Open the Settings screen by clicking the gear icon in the sidebar or pressing Ctrl+,.
2. In the Connection section, enter your Gateway URL (e.g., http://localhost:3001 or your remote server address).
3. If your gateway requires an API key, enter it in the API Key field.
4. Click Test Connection to verify connectivity.
5. A green indicator in the top bar confirms a successful connection.

First-time Setup

When you first launch Hermes Studio, a setup wizard may appear to guide you through initial configuration. If it does not appear, follow these steps:

1. Configure your gateway connection (see above).
2. Navigate to Settings and choose your preferred theme and accent color under Appearance.
3. Optionally set up your identity files (SOUL.md and persona.md) under the Identity section to personalize your AI interactions.
4. Browse the Skills registry and install any skills your workflow requires.

Navigation Overview

The left sidebar is your primary navigation. Each icon represents a major feature area:

• Chat - Direct conversations with your AI agent
• Crews - Multi-agent team management
• Conductor - Mission orchestration and monitoring
• Tasks - Kanban-style task board
• Jobs - Scheduled/cron job management
• Memory - Knowledge graph and memory files
• Skills - Skill registry and management
• Agents - Custom agent personas
• Files - File browser and editor
• Terminal - Integrated terminal
• Analytics - Usage analytics and audit logs
• Settings - App configuration

The sidebar can be collapsed by clicking the hamburger menu icon at the top. On smaller screens, it collapses automatically.

2. Chat

Starting a Conversation

The Chat screen is your primary interface for interacting with the AI agent. To start a new conversation:

1. Click the Chat icon in the sidebar to open the chat screen.
2. Type your message in the input field at the bottom of the screen.
3. Press Enter to send your message, or Shift+Enter for a new line without sending.
4. The AI will begin streaming its response in real-time.

Managing Sessions

Each conversation exists within a session. You can manage sessions using the session panel:

• Click the + button in the sessions sidebar to create a new session.
• Click on any existing session in the list to switch to it.
• Right-click a session to rename or delete it.
• Sessions persist across app restarts so you can continue conversations later.

Approvals (Approve / Deny / Always-Allow)

When the AI wants to perform an action that requires permission (like running a command, writing a file, or accessing a resource), an approval prompt appears:

• Approve - Allow this specific action once.
• Deny - Reject this action. The AI will be informed and may suggest an alternative.
• Always Allow - Approve this type of action permanently for the current session. The permission is remembered so you won't be asked again for the same tool or pattern.

File Attachments

You can attach files to your messages for the AI to analyze or work with:

1. Click the paperclip icon next to the message input.
2. Select one or more files from the file picker dialog.
3. Attached files appear as chips above the input field. Click the X on a chip to remove it.
4. Send your message as normal - the AI will have access to the file contents.

Streaming Responses

Responses stream in token-by-token for a real-time experience. While a response is streaming:

• You can click the Stop button to halt generation at any point.
• Tool calls and their results appear inline as collapsible blocks.
• Code blocks are syntax-highlighted and include a copy button.
• Markdown formatting (headings, lists, tables, links) renders automatically.

3. Crews (Multi-Agent Teams)

Creating a Crew

Crews let you organize multiple AI agents into a team that can collaborate on complex tasks. To create a new crew:

1. Navigate to the Crews screen from the sidebar.
2. Click the + New Crew button in the top-right corner.
3. Enter a name and optional description for your crew.
4. Choose whether to start from scratch or use a template.
5. Click Create to finalize.

Adding Members

After creating a crew, you need to add agent members who will participate:

1. Open your crew by clicking on it in the crew list.
2. Click Add Member in the members panel.
3. Select an agent from your available agents, or create a new one inline.
4. Assign a role to the member (e.g., Researcher, Developer, Reviewer).
5. Optionally set specific instructions that override the agent's default prompt for this crew context.

Using Templates

Templates provide pre-configured crew setups for common workflows:

• Research Team - A crew configured for deep research with specialized researcher and summarizer agents.
• Development Team - Includes architect, developer, and code reviewer agents.
• Content Team - Writer, editor, and fact-checker agents for content creation.

Select a template during crew creation to pre-populate the crew with appropriate members and settings.

Dispatching Tasks

Once your crew is set up, you can dispatch tasks to it:

1. Open the crew detail view.
2. Click Dispatch Task or use the input field at the bottom.
3. Describe what you want the crew to accomplish.
4. The task will be distributed among crew members according to their roles and the workflow configuration.

Cloning Crews

To duplicate an existing crew with all its configuration:

1. Right-click the crew in the list or click the three-dot menu on the crew card.
2. Select Clone Crew.
3. A new crew is created with the same members, roles, and settings. You can rename it and modify as needed.

Workflow Builder (DAG Editor)

The workflow builder lets you define how tasks flow between crew members using a visual directed acyclic graph (DAG):

1. Open a crew and switch to the Workflow tab.
2. Each crew member appears as a node on the canvas.
3. Drag connections between nodes to define task flow (who passes work to whom).
4. Click a connection to configure conditions or transformations.
5. Use the toolbar to add decision nodes, parallel branches, or merge points.
6. Save your workflow with the Save button or Ctrl+S.

Monitoring Crew Operations

While a crew is working, you can monitor progress:

• The crew card shows a live status indicator (idle, working, completed, errored).
• Click into the crew to see each member's current activity.
• A timeline view shows the sequence of actions and handoffs between members.
• Output from each member is displayed in their respective panel.

4. Conductor (Mission Orchestration)

Starting a Mission

The Conductor is your command center for orchestrating complex, multi-step missions. To start a new mission:

1. Navigate to the Conductor screen from the sidebar.
2. Type your mission objective in the main input field. Be as specific as possible about what you want to accomplish.
3. Click Start Mission or press Ctrl+Enter.
4. The Conductor will analyze your objective, create a plan, and begin dispatching workers.

Quick Actions (Research / Build / Review / Deploy)

For common mission types, use the quick action buttons below the input:

• Research - Launches a research-focused mission with agents configured for information gathering and synthesis.
• Build - Creates a development mission with code-writing workers and automated testing.
• Review - Starts a code review mission that examines your repository for issues, improvements, and best practices.
• Deploy - Initiates a deployment pipeline mission with pre-deployment checks and rollout steps.

Each quick action pre-configures the appropriate model, worker count, and supervision settings for that task type.

Settings (Models, Parallel Workers, Supervised Mode)

Before starting a mission, configure its parameters by clicking the gear icon next to the input:

• Model - Choose which AI model powers the mission (e.g., Claude Opus, Claude Sonnet). More capable models handle complex reasoning better but cost more.
• Parallel Workers - Set how many agents work simultaneously (1-8). More workers speed up execution but increase cost.
• Supervised Mode - When enabled, the Conductor pauses before each major action and asks for your approval. Disable for fully autonomous operation.

The Office View (3 Layouts)

The Office View is an animated visualization of your active mission. It shows workers as animated characters sitting at desks, working on their assigned subtasks. You can switch between three layouts:

• Grid Layout - Workers arranged in a grid pattern. Best for seeing many workers at once. Each worker occupies a cell showing their avatar, current task summary, and status indicator.
• Row Layout - Workers displayed in horizontal rows with more detail visible per worker. Shows expanded task descriptions and recent output snippets.
• Focus Layout - Highlights one worker at a time in a large central view with full output streaming. Other workers appear as small thumbnails on the side. Click a thumbnail to focus on a different worker.

Switch layouts using the layout toggle buttons in the top-right corner of the Office View. Workers are animated: they show a typing animation when actively generating, a thinking animation when processing, and an idle state when waiting for input.

Monitoring Workers

Each worker in the Office View displays:

• A colored status ring: blue (working), green (completed subtask), yellow (waiting for approval), red (error).
• The current subtask being worked on as a title above the worker.
• A progress indicator showing how far through the subtask they are.
• Click any worker to expand their detail panel and see full streaming output.

Pause / Resume / Abort

Control a running mission with the transport controls in the top bar:

• Pause - Temporarily halts all workers. They finish their current token generation but don't start new subtasks. Click Resume to continue.
• Resume - Resumes a paused mission from where it left off.
• Abort - Permanently stops the mission. All workers are terminated. This cannot be undone, but you can start a new mission with the same objective.

Mission History and Cost Tracking

All completed and aborted missions are saved in your mission history:

• Click the History tab to view past missions.
• Each entry shows the objective, status, duration, and total cost.
• Cost is broken down by model usage (input tokens, output tokens) per worker.
• Click a historical mission to review its full output and timeline.

5. Tasks (Kanban Board)

Creating Tasks

The Tasks screen presents a Kanban board for organizing work items. To create a new task:

1. Navigate to the Tasks screen from the sidebar.
2. Click the + button at the top of any column (Backlog, In Progress, Review, Done).
3. Enter a title for the task.
4. Optionally add a description, set priority, add tags, and assign to an agent or crew.
5. Click Create or press Enter to add the task to that column.

Drag-and-Drop Between Columns

Move tasks between columns by clicking and dragging:

1. Click and hold a task card.
2. Drag it to the desired column.
3. Release to drop it in place. The task's status updates automatically.
4. You can also reorder tasks within a column by dragging them up or down.

Priority, Tags, and Assignees

Each task can be enriched with metadata:

• Priority - Click the flag icon to cycle through priorities: None, Low, Medium, High, Critical. High and Critical tasks are visually highlighted.
• Tags - Add colored labels to categorize tasks (e.g., "bug", "feature", "docs"). Click the tag icon to add or create tags.
• Assignees - Assign tasks to specific agents or crews. Click the avatar icon and select from available agents.

Cross-linking with Crews / Conductor

Tasks can be linked to crew operations or conductor missions:

• When a Conductor mission creates subtasks, they automatically appear on the Kanban board with a link back to the mission.
• You can manually link a task to a crew by clicking Link to Crew in the task detail view.
• Linked tasks show status updates from the associated crew or mission.

6. Jobs (Cron Scheduler)

Creating Scheduled Jobs

Jobs let you schedule recurring AI tasks on a cron schedule. To create a new job:

1. Navigate to the Jobs screen from the sidebar.
2. Click + New Job in the top-right corner.
3. Enter a name and description for the job.
4. Define the prompt or task the AI should execute on each run.
5. Set the schedule (see below).
6. Configure delivery channels for output.
7. Click Create Job to save.

Schedule Presets and Custom Cron

Choose from common presets or write a custom cron expression:

• Every hour - Runs at the top of each hour.
• Every day at 9am - Daily morning execution.
• Every Monday - Weekly on Monday at midnight.
• Custom - Enter any valid cron expression (e.g., */15 * * * * for every 15 minutes).

The schedule preview below the input shows the next 5 planned execution times so you can verify your schedule is correct.

Delivery Channels

Configure where job output is sent after each run:

• In-App - Results appear in the Jobs screen run history (always enabled).
• Telegram - Send results to a Telegram chat or group.
• Discord - Post results to a Discord channel via webhook.
• Slack - Send to a Slack channel.
• Email - Email the results to specified addresses.

Triggering Jobs Manually

You don't have to wait for the schedule to test a job:

1. Find the job in the jobs list.
2. Click the Run Now button (play icon) on the job card.
3. The job executes immediately and results appear in the run history.

Monitoring Run History

Each job tracks its execution history:

• Click on a job to see its detail view with the full run history.
• Each run shows: timestamp, duration, status (success/failure), and output.
• Failed runs display error details so you can diagnose issues.
• Use the Clear History button to remove old runs if the list gets long.

7. Memory & Knowledge Graph

Browsing Memory Files

The Memory screen gives you access to the AI's persistent memory stored as structured files:

1. Navigate to the Memory screen from the sidebar.
2. The file tree on the left shows all memory files organized by category.
3. Click any file to view its contents in the main panel.
4. Memory files are typically Markdown documents containing facts, preferences, and learned context.

The Knowledge Graph Visualization

Switch to the Graph tab to see an interactive visualization of how memory entries are connected:

• Nodes represent individual memory entries or concepts.
• Edges show relationships between entries (references, dependencies, categories).
• Hover over a node to see a preview of its content.
• Click a node to open the full entry in the detail panel.
• Use scroll to zoom in/out and drag to pan the graph.
• The graph auto-layouts using a force-directed algorithm but you can drag nodes to reposition them.

Searching Entries

Use the search bar at the top of the Memory screen to find specific entries:

• Type keywords to filter the file list and highlight matching entries.
• Search looks at file names, content, and tags.
• Results update in real-time as you type.

Editing Memory

You can manually edit memory entries to correct or augment the AI's knowledge:

1. Open a memory file by clicking it in the tree.
2. Click the Edit button (pencil icon) to enter editing mode.
3. Modify the Markdown content as needed.
4. Click Save or press Ctrl+S to persist your changes.

8. Skills

Browsing the Skill Registry

Skills are modular capabilities that extend what the AI can do. To browse available skills:

1. Navigate to the Skills screen from the sidebar.
2. The registry shows all available skills as cards with their name, description, and status.
3. Use the search bar to filter skills by name or category.
4. Click a skill card to see full details including documentation and configuration options.

Installing Skills

To add a new skill to your setup:

1. Find the skill you want in the registry.
2. Click the Install button on the skill card.
3. If the skill requires configuration (API keys, parameters), a configuration form appears. Fill in the required fields.
4. Click Confirm to complete installation.
5. The skill is now available for use in conversations, crews, and missions.

Enabling / Disabling Skills

You can temporarily disable a skill without uninstalling it:

• Toggle the switch on any installed skill card to enable or disable it.
• Disabled skills remain configured but are not available to the AI.
• This is useful for troubleshooting or temporarily limiting the AI's capabilities.

9. Agents (Custom Personas)

Creating Custom Agents

Agents are custom AI personas with specific behaviors and expertise. To create one:

1. Navigate to the Agents screen from the sidebar.
2. Click + New Agent in the top-right.
3. Enter a name for the agent (e.g., "Code Reviewer", "Technical Writer").
4. Write a system prompt that defines the agent's personality, expertise, and behavior rules.
5. Customize the appearance (emoji avatar and accent color).
6. Click Create to save the agent.

Emoji and Color Customization

Make your agents visually distinct:

• Click the emoji picker to choose an avatar emoji that represents the agent's role.
• Select an accent color from the color palette. This color is used in the agent's chat bubbles, crew member indicators, and Conductor worker rings.
• Both emoji and color appear wherever the agent is referenced throughout the app.

System Prompts

The system prompt is the core of an agent's identity. Write it to define:

• Role - What the agent is (e.g., "You are a senior backend engineer specializing in distributed systems").
• Behavior - How the agent should respond (e.g., "Always suggest tests for code changes").
• Constraints - What the agent should avoid (e.g., "Never modify production configuration files").
• Tone - The communication style (e.g., "Be concise and direct. Use bullet points.").

Using Agents in Crews

Once created, agents can be assigned to crews:

• When adding members to a crew, your custom agents appear in the agent selection dropdown.
• Each agent brings its system prompt and personality to the crew context.
• You can override specific instructions per-crew without changing the agent's base configuration.

10. Files & Terminal

File Browser Navigation

The Files screen provides a full file browser for navigating your project:

• The left panel shows a file tree. Click folders to expand/collapse them.
• Click a file to open it in the editor panel on the right.
• Right-click files or folders for a context menu with options: Rename, Delete, Copy Path, New File, New Folder.
• Use the breadcrumb path at the top to navigate up the directory tree.

Editing Files (Monaco Editor)

Files open in an integrated Monaco editor (the same editor that powers VS Code):

• Full syntax highlighting for all major languages.
• IntelliSense-style autocomplete where language servers are available.
• Find and replace with Ctrl+F and Ctrl+H.
• Save files with Ctrl+S. Unsaved changes are indicated by a dot on the file tab.
• Multiple files can be open in tabs simultaneously.

Terminal Usage

The integrated terminal gives you a shell directly within Hermes Studio:

1. Navigate to the Terminal screen from the sidebar, or press Ctrl+` to toggle it as a bottom panel.
2. The terminal opens in your project's working directory.
3. Run any shell command as you would in a regular terminal.
4. Multiple terminal tabs are supported - click + to create a new tab.

11. Analytics & Audit

Event Analytics Dashboard

The Analytics screen provides insights into your AI usage patterns:

• View charts showing messages sent, tokens used, and costs over time.
• Filter by date range using the date picker in the top bar.
• Break down usage by agent, model, or session.
• Export data as CSV for further analysis.

Session History

Review all past chat sessions:

• Each session shows its start time, message count, and token usage.
• Click a session to view the full conversation transcript.
• Use the search to find sessions by content or date.

Audit Trail

The audit trail logs every significant action the AI has taken:

• File modifications, command executions, and API calls are all recorded.
• Each entry includes a timestamp, action type, details, and which agent performed it.
• Filter by action type or severity level.
• This is essential for accountability in supervised environments.

Logs Viewer

Access raw system logs for debugging and monitoring:

• Click the Logs tab within Analytics.
• Logs stream in real-time with color-coded severity (info, warning, error).
• Use the filter bar to search for specific log entries.
• Click Pause to freeze the log stream for easier reading.

12. Settings & Configuration

Connection Settings

Configure how Hermes Studio connects to your gateway:

• Gateway URL - The HTTP address of your Hermes Gateway server.
• API Key - Authentication key for secured gateways.
• Reconnect Interval - How often to retry if the connection drops (default: 5 seconds).
• WebSocket - Enable/disable WebSocket for real-time streaming (recommended: enabled).

Appearance (Themes, Accent Colors)

Customize the visual appearance of Hermes Studio:

• Theme - Choose from available dark themes. The app is designed as dark-mode only for optimal readability during extended use.
• Accent Color - Pick a primary accent color that highlights interactive elements, buttons, and active states throughout the UI.
• Font Size - Adjust the base font size for readability.
• Changes apply immediately with no restart required.

Integrations (Telegram, Discord, Slack, etc.)

Connect external services for notifications and delivery:

1. Go to Settings and open the Integrations tab.
2. Click Add Integration and select the service.
3. Follow the service-specific setup (e.g., paste a bot token for Telegram, a webhook URL for Discord).
4. Test the integration with the Send Test button.
5. Once configured, these integrations are available as delivery channels in Jobs and notifications.

MCP Servers

Manage Model Context Protocol (MCP) server connections:

• MCP servers provide additional tools and capabilities to the AI.
• Click Add MCP Server to register a new server by URL.
• Each server shows its available tools and connection status.
• Toggle servers on/off to control which tools are available.

Permissions & Security

Control what the AI is allowed to do:

• Auto-approved paths - File paths where the AI can read/write without asking permission.
• Blocked commands - Shell commands the AI is never allowed to run.
• Always-allow rules - Review and revoke previously granted always-allow permissions from chat.
• Supervised mode default - Set whether new missions start in supervised mode by default.

Identity Files (SOUL.md, persona.md)

Identity files shape the AI's core personality across all interactions:

• SOUL.md - Defines the AI's fundamental values, communication style, and behavioral principles. This is the deepest layer of personality.
• persona.md - A more surface-level personality file that defines tone, preferences, and interaction patterns.
• Edit these files in the Identity section of Settings or directly via the Files screen.
• Changes take effect in new conversations; existing sessions keep their original context.

Systemd Auto-start

Configure Hermes Gateway to start automatically with your system:

1. In Settings, find the System section.
2. Click Install Systemd Service.
3. The app generates a systemd unit file and installs it for your user.
4. Use the Enable toggle to control whether it starts on boot.
5. The Status indicator shows whether the service is currently active.

13. Keyboard Shortcuts

Hermes Studio supports keyboard shortcuts for quick navigation and common actions. Below is the full reference:

Global Navigation

Chat

Editor

Conductor

Terminal

14. Troubleshooting

Connection Issues

If the connection indicator shows red or you see "Disconnected" messages:

1. Verify your Gateway URL is correct in Settings (check for typos, correct port number).
2. Ensure the Hermes Gateway server is running. If you installed it as a systemd service, check with: systemctl --user status hermes-gateway.
3. Check that no firewall is blocking the connection port.
4. If using a remote server, ensure your network can reach it (try pinging the host).
5. Try the Test Connection button in Settings - it provides specific error messages.

Gateway Not Responding

If the gateway is reachable but not responding to requests:

• Check the gateway's own logs for errors (usually in the terminal where it's running or via journalctl --user -u hermes-gateway).
• Verify your API key is correct and has not expired.
• Restart the gateway service and try again.
• Ensure the AI provider (Anthropic, etc.) API keys configured in the gateway are valid.

Features Showing as Unavailable

If certain features appear grayed out or show "unavailable":

• Some features require specific gateway capabilities. Update your Hermes Gateway to the latest version.
• Check that required skills are installed and enabled in the Skills screen.
• Verify your gateway's configuration includes the necessary modules (e.g., the conductor module for missions).
• Ensure your connection has the appropriate permissions. Some gateways restrict features by API key scope.

Rate Limits

If you encounter rate limit errors:

• Rate limits come from the underlying AI provider (e.g., Anthropic's API limits).
• Reduce the number of parallel workers in Conductor missions.
• Space out rapid-fire chat messages.
• Consider using a lower-tier model for less critical tasks to preserve quota for important work.
• Check your AI provider's dashboard to see your current usage and limits.
• If you consistently hit limits, contact your AI provider about upgrading your tier.