Session Navigation

Helm ADE organizes agent work into sessions — individual conversations with AI agents that help you plan, build, and test software. This article explains how to navigate and manage sessions using the left rail navigator.

Overview

The left rail session navigator displays all sessions for your active project, grouped by primary agent type:

• Toolkit — Configuration and customization sessions
• Planners — PRD creation and planning sessions
• Builders — Feature implementation sessions
• Testers — Automated testing and QA sessions

Each group shows an active session count badge and can be expanded or collapsed.

Understanding Session Groups

Agent Type Categories

Agent Type	Purpose	Typical Use Cases
Toolkit	Manage agent configuration and rules	Customizing prompts, updating conventions, reviewing toolkit changes
Planners	Create and refine PRDs	Writing requirements, breaking down features, estimating scope
Builders	Implement features	Coding user stories, fixing bugs, writing tests
Testers	Run automated tests	E2E testing, QA verification, regression testing

Session Status Indicators

Sessions display a colored status dot indicating their current state:

• 🟢 Green (Active) — Currently running or recently active
• 🟡 Yellow (Paused) — Temporarily paused, can be resumed
• ⚪ Gray (Completed) — Successfully finished
• 🔴 Red (Abandoned) — Stopped without completion

Active Count Badges

Each group header shows:

• Green badge — Number of active/paused sessions (work in progress)
• Gray badge — Total sessions in the group (if different from active count)

Navigating Sessions

Expanding and Collapsing Groups

Click the group header (e.g., "Builders") to expand or collapse that section. The arrow icon indicates the current state:

• ▶ Collapsed
• ▼ Expanded

Selecting a Session

Click any session name to load its conversation context into the main workspace. The selected session is highlighted with a blue background.

Finding Your Work

Sessions are sorted by most recent activity. Look for:

• Story ID badges (e.g., "US-001") to find sessions working on specific user stories
• Status indicators to identify active work
• Session names that describe the work being done

Creating New Sessions

Using the "New" Button

Each group has a "+ New [Type]" button at the bottom:

Click the button (e.g., "+ New Builder")

A new session is created automatically

The session is given a default name (e.g., "Builder Session 3")

The new session is auto-selected and opens in the workspace

Session Naming

Sessions are automatically named based on their type and count:

• "Toolkit Session 1"
• "Planner Session 2"
• "Builder Session 3"
• "Tester Session 1"

You can rename sessions later if needed.

Session Scope

Project-Scoped Sessions

In v1, all sessions are scoped to the active project. When you switch projects using the header selector:

• The session list refreshes to show sessions for the new project
• Your previously selected session is cleared
• Each project maintains its own independent set of sessions

Organization Context

Sessions are organized under projects, which belong to organizations. The hierarchy is:

Organization
└── Project
├── Toolkit Sessions
├── Planner Sessions
├── Builder Sessions
└── Tester Sessions

Best Practices

When to Create New Sessions

• New feature work — Create a new Builder session for each PRD or major feature
• Exploratory planning — Start a Planner session to draft ideas before formalizing
• Debugging — Consider a dedicated session for investigation to keep history separate

Managing Session History

• Complete sessions when work is done to keep the active list clean
• Abandon sessions that are no longer needed
• Sessions are never deleted — completed/abandoned sessions can still be viewed

Toolkit Session Tips

The Toolkit section always exists for each project. Use it to:

• Review and customize agent configurations
• Update project conventions
• Test prompt changes before applying them

Troubleshooting

"Loading sessions..." persists

Check your network connection and ensure the API server is running. Try refreshing the page.

"Select a project to view sessions" appears

You need to select a project first using the header dropdown. Sessions are project-scoped.

Sessions don't appear after switching projects

This is expected behavior. Each project has its own session list. Your previous project's sessions are still available when you switch back.

Can't find a session

Sessions are sorted by most recent activity. Check if the group is collapsed, or scroll down in long session lists.

Related Topics

• Organization and Project Switching — Learn about context switching
• Using OpenCode in Helm — Working with sessions in the workspace