Frequently Asked Questions

General

What is Shell App?

Shell App is an integrated terminal application within FlowState that provides a full-featured terminal experience. Built with xterm.js, it offers session persistence, context-aware sessions linked to your projects and tasks, and seamless integration with the FlowState ecosystem.

Who should use this app?

Shell App is designed for:

What makes Shell App different from a regular terminal?

Shell App provides unique benefits:

1. Session Persistence - Sessions survive page refreshes and reconnections
2. Context Linking - Associate terminals with projects, milestones, and tasks
3. Cross-Device Access - Sessions sync via RxDB replication
4. Integrated Workflow - Access terminal alongside FlowState apps via bottom panel
5. Unified Interface - No need to switch between apps and external terminals

Sessions

How many sessions can I have open at once?

There is no hard limit on sessions. However, for optimal performance:

• Active terminals consume memory on both client and server
• Recommend keeping 5-10 active sessions maximum
• Close sessions you're not actively using
• Archived sessions don't consume active resources

What happens to my session when I close the browser?

Your session persists! When you return:

1. The session metadata is stored in RxDB
2. The shell process may continue running on the server (depending on configuration)
3. You can reconnect and view scrollback history
4. If the process exited, you'll see the exit status and can create a new session

Can I share sessions with team members?

Currently, sessions are user-specific and scoped to your account. However:

• Sessions are associated with shared entities (projects, tasks)
• Command output can be logged for team visibility (feature dependent on configuration)
• Future versions may support session sharing

How do I rename a session?

1. Right-click on the session in the sidebar
2. Select Rename
3. Enter the new name
4. Press Enter or click Save

Alternatively, use the rename action in the session menu.

What's the difference between "Close" and "Delete"?

Terminal Features

What keyboard shortcuts are available?

Standard terminal shortcuts also work within the terminal (Ctrl+C, Ctrl+D, etc.).

Does Shell App support colors and formatting?

Yes! Shell App uses xterm.js which provides full ANSI escape code support:

• 16 colors, 256 colors, and true color (24-bit)
• Bold, italic, underline, strikethrough
• Cursor positioning and control sequences
• Most terminal applications display correctly

Can I use vim/nano/emacs in Shell App?

Yes, full-screen terminal applications work in Shell App:

vim filename.txt
nano config.yml
htop

The terminal properly handles:

• Alternate screen buffer
• Mouse events (if enabled in the app)
• All cursor movements and screen updates

How do I copy and paste in the terminal?

Copy:

• Select text with mouse
• Ctrl+Shift+C (Linux/Windows) or Cmd+C (macOS)
• Or right-click and select Copy

Paste:

• Ctrl+Shift+V (Linux/Windows) or Cmd+V (macOS)
• Or right-click and select Paste

Context Linking

What is context-aware session linking?

You can associate terminal sessions with FlowState entities:

Workspace
  └── Project
       └── Milestone
            └── Task

This helps you:

• Organize terminals by project
• Track which commands were run for specific tasks
• Filter sessions by context
• Maintain audit trails of development work

Do I have to link sessions to a project?

No, linking is optional. You can:

• Create sessions with just a workspace
• Add project/milestone/task associations later
• Use sessions without any context for quick tasks

Can I change the context of an existing session?

Yes, you can update session context:

1. Select the session
2. Click the edit/settings icon
3. Modify the workspace, project, milestone, or task
4. Save changes

Technical

Which browsers are supported?

Shell App works best on modern browsers:

Does Shell App work offline?

Partially:

• Works offline: Viewing session list, session metadata
• Requires connection: Active terminal I/O, creating new sessions, executing commands

The shell server must be reachable for terminal functionality.

Is Shell App secure?

Yes, Shell App implements several security measures:

Note: The terminal executes commands with the permissions of the shell server process.

Can I use Shell App in Electron?

Yes! Shell App works in both web and Electron:

In Electron, the shell server URL is automatically configured.

What shell does Shell App use?

Shell App spawns the default shell configured on the server:

• Linux: Usually /bin/bash or /bin/zsh
• macOS: Usually /bin/zsh
• Windows: PowerShell or CMD (via WSL for better experience)

The shell inherits environment variables from the server process.

Troubleshooting Quick Reference

Why can't I connect?

Check these common causes:

1. Shell server not running
2. Wrong server URL in settings
3. Firewall blocking port 3001
4. Network connectivity issues

See Troubleshooting for detailed solutions.

Why is my terminal slow?

Try these fixes:

1. Clear terminal buffer (Ctrl+K / Cmd+K)
2. Close unused sessions
3. Check network latency
4. Reduce output from commands

Why did my session disappear?

Possible reasons:

1. Server was restarted (clears active processes)
2. Session was deleted
3. Viewing different workspace
4. RxDB sync issue (try refreshing)

Still Have Questions?

If your question isn't answered here:

• Check Troubleshooting for common issues
• Review Features for detailed capability documentation
• Check Getting Started for setup guidance
• Contact FlowState support for additional help