Fully autonomous AI Agents system capable of performing complex penetration testing tasks
Go ai-agentsai-security-toolanthropicautonomous-agentsgolanggptgraphqlmulti-agent-systemoffensive-securityopen-sourceopenaipenetration-testingpenetration-testing-toolsreactsecurity-automationsecurity-testingsecurity-toolsself-hosted
Charm.sh Navigation Patterns
Comprehensive guide to implementing robust navigation systems in TUI applications.
🎯 Type-Safe Navigation with Composite ScreenIDs
Composite ScreenID Pattern
Problem: Need to pass parameters to screens (e.g., which provider to configure)
Solution: Composite ScreenIDs with § separator
// Format: "screen§arg1§arg2§..."
type ScreenID string
// Methods for parsing composite IDs
func (s ScreenID) GetScreen() string {
parts := strings.Split(string(s), "§")
return parts[0]
}
func (s ScreenID) GetArgs() []string {
parts := strings.Split(string(s), "§")
if len(parts) <= 1 {
return []string{}
}
return parts[1:]
}
// Helper for creating composite IDs
func CreateScreenID(screen string, args ...string) ScreenID {
if len(args) == 0 {
return ScreenID(screen)
}
parts := append([]string{screen}, args...)
return ScreenID(strings.Join(parts, "§"))
}
Usage Examples
// Simple screen (no arguments)
welcome := WelcomeScreen // "welcome"
// Composite screen (with arguments)
providerForm := CreateScreenID("llm_provider_form", "openai") // "llm_provider_form§openai"
// Navigation with arguments
return m, func() tea.Msg {
return NavigationMsg{
Target: CreateScreenID("llm_provider_form", "anthropic"),
Data: FormData{ProviderID: "anthropic"},
}
}
// In createModelForScreen - extract arguments
func (a *App) createModelForScreen(screenID ScreenID, data any) tea.Model {
baseScreen := screenID.GetScreen()
args := screenID.GetArgs()
switch ScreenID(baseScreen) {
case LLMProviderFormScreen:
providerID := "openai" // default
if len(args) > 0 {
providerID = args[0]
}
return NewLLMProviderFormModel(providerID, ...)
}
}
State Persistence
// Stack automatically preserves composite IDs
navigator.Push(CreateScreenID("llm_provider_form", "gemini"))
// State contains: ["welcome", "main_menu", "llm_providers", "llm_provider_form§gemini"]
// On restore: user returns to Gemini provider form, not default OpenAI
🎯 Navigation Message Pattern
NavigationMsg Structure
type NavigationMsg struct {
Target ScreenID // Can be simple or composite
GoBack bool // Return to previous screen
Data any // Optional data to pass
}
// Type-safe constants
type ScreenID string
const (
WelcomeScreen ScreenID = "welcome"
EULAScreen ScreenID = "eula"
MainMenuScreen ScreenID = "main_menu"
LLMProviderFormScreen ScreenID = "llm_provider_form"
)
Navigation Commands
// Simple navigation
return m, func() tea.Msg {
return NavigationMsg{Target: EULAScreen}
}
// Navigation with parameters
return m, func() tea.Msg {
return NavigationMsg{Target: CreateScreenID("llm_provider_form", "openai")}
}
// Go back to previous screen
return m, func() tea.Msg {
return NavigationMsg{GoBack: true}
}
// Navigation with data passing
return m, func() tea.Msg {
return NavigationMsg{
Target: CreateScreenID("config_form", "database"),
Data: ConfigData{Type: "database", Settings: currentSettings},
}
}
🎯 Navigator Implementation
Navigation Stack Management
type Navigator struct {
stack []ScreenID
stateManager StateManager
}
func NewNavigator(stateManager StateManager) *Navigator {
return &Navigator{
stack: []ScreenID{WelcomeScreen},
stateManager: stateManager,
}
}
func (n *Navigator) Push(screenID ScreenID) {
n.stack = append(n.stack, screenID)
n.persistState()
}
func (n *Navigator) Pop() ScreenID {
if len(n.stack) <= 1 {
return n.stack[0] // Can't pop last screen
}
popped := n.stack[len(n.stack)-1]
n.stack = n.stack[:len(n.stack)-1]
n.persistState()
return popped
}
func (n *Navigator) Current() ScreenID {
if len(n.stack) == 0 {
return WelcomeScreen
}
return n.stack[len(n.stack)-1]
}
func (n *Navigator) Replace(screenID ScreenID) {
if len(n.stack) == 0 {
n.stack = []ScreenID{screenID}
} else {
n.stack[len(n.stack)-1] = screenID
}
n.persistState()
}
func (n *Navigator) persistState() {
stringStack := make([]string, len(n.stack))
for i, screenID := range n.stack {
stringStack[i] = string(screenID)
}
n.stateManager.SetStack(stringStack)
}
func (n *Navigator) RestoreState() {
stringStack := n.stateManager.GetStack()
if len(stringStack) == 0 {
n.stack = []ScreenID{WelcomeScreen}
return
}
n.stack = make([]ScreenID, len(stringStack))
for i, s := range stringStack {
n.stack[i] = ScreenID(s)
}
}
🎯 Universal ESC Behavior
Global Navigation Handling
func (a *App) handleGlobalNavigation(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
switch msg.String() {
case "esc":
// Universal ESC: ALWAYS returns to Welcome screen
if a.navigator.Current().GetScreen() != string(WelcomeScreen) {
a.navigator.stack = []ScreenID{WelcomeScreen}
a.navigator.persistState()
a.currentModel = a.createModelForScreen(WelcomeScreen, nil)
return a, a.currentModel.Init()
}
case "ctrl+c":
// Global quit
return a, tea.Quit
}
return a, nil
}
// In main Update loop
func (a *App) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyMsg:
// Handle global navigation first
if newModel, cmd := a.handleGlobalNavigation(msg); cmd != nil {
return newModel, cmd
}
// Then pass to current model
var cmd tea.Cmd
a.currentModel, cmd = a.currentModel.Update(msg)
return a, cmd
case NavigationMsg:
return a.handleNavigationMsg(msg)
}
// Delegate to current model
var cmd tea.Cmd
a.currentModel, cmd = a.currentModel.Update(msg)
return a, cmd
}
🎯 Navigation Message Handling
App-Level Navigation
func (a *App) handleNavigationMsg(msg NavigationMsg) (tea.Model, tea.Cmd) {
if msg.GoBack {
if len(a.navigator.stack) > 1 {
a.navigator.Pop()
currentScreen := a.navigator.Current()
a.currentModel = a.createModelForScreen(currentScreen, msg.Data)
return a, a.currentModel.Init()
}
// Can't go back further, stay on current screen
return a, nil
}
// Forward navigation
a.navigator.Push(msg.Target)
a.currentModel = a.createModelForScreen(msg.Target, msg.Data)
return a, a.currentModel.Init()
}
func (a *App) createModelForScreen(screenID ScreenID, data any) tea.Model {
baseScreen := screenID.GetScreen()
args := screenID.GetArgs()
switch ScreenID(baseScreen) {
case WelcomeScreen:
return NewWelcomeModel(a.controller, a.styles, a.window)
case EULAScreen:
return NewEULAModel(a.controller, a.styles, a.window)
case MainMenuScreen:
selectedItem := ""
if len(args) > 0 {
selectedItem = args[0]
}
return NewMainMenuModel(a.controller, a.styles, a.window, []string{selectedItem})
case LLMProviderFormScreen:
providerID := "openai"
if len(args) > 0 {
providerID = args[0]
}
return NewLLMProviderFormModel(a.controller, a.styles, a.window, []string{providerID})
default:
// Fallback to welcome screen
return NewWelcomeModel(a.controller, a.styles, a.window)
}
}
🎯 Args-Based Model Construction
Model Constructor Pattern
// Model constructor receives args from composite ScreenID
func NewModel(
controller *controllers.StateController, styles *styles.Styles,
window *window.Window, args []string,
) *Model {
// Initialize with selection from args
selectedIndex := 0
if len(args) > 1 && args[1] != "" {
// Find matching item and set selectedIndex
for i, item := range items {
if item.ID == args[1] {
selectedIndex = i
break
}
}
}
return &Model{
controller: controller,
selectedIndex: selectedIndex,
args: args,
}
}
// No separate SetSelected* methods needed
func (m *Model) Init() tea.Cmd {
logger.Log("[Model] INIT: args=%s", strings.Join(m.args, " § "))
// Selection already set in constructor from args
m.loadData()
return nil
}
Selection Preservation Pattern
// Navigation from menu with argument preservation
func (m *MenuModel) handleSelection() (tea.Model, tea.Cmd) {
selectedItem := m.getSelectedItem()
// Create composite ScreenID with current selection for stack preservation
return m, func() tea.Msg {
return NavigationMsg{
Target: CreateScreenID(string(targetScreen), selectedItem.ID),
}
}
}
// Form navigation back - use GoBack to avoid stack loops
func (m *FormModel) saveAndReturn() (tea.Model, tea.Cmd) {
model, cmd := m.saveConfiguration()
if cmd != nil {
return model, cmd
}
// ✅ CORRECT: Use GoBack to return to previous screen
return m, func() tea.Msg {
return NavigationMsg{GoBack: true}
}
}
// ❌ WRONG: Direct navigation creates stack loops
return m, func() tea.Msg {
return NavigationMsg{Target: LLMProvidersScreen} // Creates loop!
}
🎯 Data Passing Pattern
Structured Data Transfer
// Define data structures for navigation
type FormData struct {
ProviderID string
Settings map[string]string
}
type ConfigData struct {
Type string
Settings map[string]interface{}
}
// Pass data through navigation
func (m *MenuModel) openConfiguration() (tea.Model, tea.Cmd) {
return m, func() tea.Msg {
return NavigationMsg{
Target: CreateScreenID("config_form", "database"),
Data: ConfigData{
Type: "database",
Settings: m.getCurrentSettings(),
},
}
}
}
// Receive data in target model
func NewConfigFormModel(
controller *controllers.StateController, styles *styles.Styles,
window *window.Window, args []string, data any,
) *ConfigFormModel {
configType := "default"
if len(args) > 0 {
configType = args[0]
}
var settings map[string]interface{}
if configData, ok := data.(ConfigData); ok {
settings = configData.Settings
}
return &ConfigFormModel{
configType: configType,
settings: settings,
// ...
}
}
🎯 Navigation Anti-Patterns & Solutions
❌ Common Mistakes
// ❌ WRONG: Direct navigation creates loops
func (m *FormModel) saveAndReturn() (tea.Model, tea.Cmd) {
m.saveConfiguration()
return m, func() tea.Msg {
return NavigationMsg{Target: LLMProvidersScreen} // Loop!
}
}
// ❌ WRONG: Separate SetSelected methods
func (m *Model) SetSelectedProvider(providerID string) {
// Complexity - removed in favor of args-based construction
}
// ❌ WRONG: String-based navigation (typo-prone)
return NavigationMsg{Target: "main_menu"}
// ❌ WRONG: Manual string concatenation for arguments
return NavigationMsg{Target: ScreenID("llm_provider_form/openai")}
✅ Correct Patterns
// ✅ CORRECT: GoBack navigation
func (m *FormModel) saveAndReturn() (tea.Model, tea.Cmd) {
if err := m.saveConfiguration(); err != nil {
return m, nil // Stay on form if save fails
}
return m, func() tea.Msg {
return NavigationMsg{GoBack: true} // Return to previous screen
}
}
// ✅ CORRECT: Args-based selection
func NewModel(..., args []string) *Model {
selectedIndex := 0
if len(args) > 1 && args[1] != "" {
// Set selection from args during construction
for i, item := range items {
if item.ID == args[1] {
selectedIndex = i
break
}
}
}
return &Model{selectedIndex: selectedIndex, args: args}
}
// ✅ CORRECT: Type-safe constants
return NavigationMsg{Target: MainMenuScreen}
// ✅ CORRECT: Composite ScreenID with helper
return NavigationMsg{Target: CreateScreenID("llm_provider_form", "openai")}
🎯 Navigation Stack Examples
Typical Navigation Flow
// Stack progression example:
// 1. Start: ["welcome"]
// 2. Continue: ["welcome", "main_menu"]
// 3. LLM Providers: ["welcome", "main_menu§llm_providers", "llm_providers"]
// 4. OpenAI Form: ["welcome", "main_menu§llm_providers", "llm_providers§openai", "llm_provider_form§openai"]
// 5. GoBack: ["welcome", "main_menu§llm_providers", "llm_providers§openai"]
// 6. ESC: ["welcome"]
func demonstrateNavigation() {
nav := NewNavigator(stateManager)
// Initial state
current := nav.Current() // "welcome"
// Navigate to main menu
nav.Push(CreateScreenID("main_menu", "llm_providers"))
current = nav.Current() // "main_menu§llm_providers"
// Navigate to providers list
nav.Push(CreateScreenID("llm_providers", "openai"))
current = nav.Current() // "llm_providers§openai"
// Navigate to form
nav.Push(CreateScreenID("llm_provider_form", "openai"))
current = nav.Current() // "llm_provider_form§openai"
// Go back
nav.Pop()
current = nav.Current() // "llm_providers§openai"
// ESC to home (clear stack)
nav.stack = []ScreenID{WelcomeScreen}
current = nav.Current() // "welcome"
}
State Restoration
// On app restart, navigation stack is restored with all parameters
func (a *App) initializeNavigation() {
a.navigator.RestoreState()
// User returns to exact screen with preserved selection
// e.g., "llm_provider_form§anthropic" restores Anthropic form
currentScreen := a.navigator.Current()
a.currentModel = a.createModelForScreen(currentScreen, nil)
}
This navigation system provides:
- Type Safety: Compile-time validation of screen IDs
- Parameter Preservation: Arguments maintained across navigation
- Stack Management: Proper back navigation without loops
- State Persistence: Complete navigation state restoration
- Universal Behavior: Consistent ESC and global navigation