PhotonShell User Guide
Welcome to PhotonShell, a next-generation terminal emulator that combines powerful terminal capabilities with AI assistance, advanced SSH management, and enterprise-grade safety features.
Table of Contents
Introduction
PhotonShell is designed to transform your command-line experience. It's not just a terminal; it's an intelligent workspace that helps you write better commands, understand complex outputs, and manage remote connections securely.
Core Functionalities
Terminal Emulation
At its heart, PhotonShell provides a robust terminal experience based on xterm.js.
- Multiple Tabs: Work on different tasks simultaneously.
- Open new tabs with
Ctrl/Cmd + Tor the+button. - Switch tabs with
Ctrl/Cmd + 1through9. - Close tabs with
Ctrl/Cmd + W.
- Open new tabs with
- Rich Support: Full support for standard shell applications, colors, and mouse events.
AI Assistant
PhotonShell integrates AI directly into your workflow.
- Chat Interface: Access a dedicated AI chat pane.
- Composer Mode: Toggle the AI Composer with
Ctrl/Cmd + Ifor focused interactions. - Autonomous Mode: The AI can execute commands on your behalf (with your confirmation).
- Inline Completions: As you type in the terminal, press
Tabto get AI-powered command suggestions.
Safety & Security
PhotonShell includes a safety engine to prevent accidents.
- Risk Assessment: The application analyzes commands for execution before they run.
- Secret Redaction: Sensitive information in output is automatically detected and redacted.
Plans & Billing
Built-in AI Provider
PhotonShell comes with a built-in AI provider called Photon AI. This allows you to start using AI features immediately without needing to configure your own API keys.
- Zero Configuration: Works out of the box for all users.
- Privacy First: Your code and commands are processed securely.
- Credits System: Usage is tracked via "AI Calls" and "Tokens", which reset monthly based on your plan.
Subscription Tiers
Free Plan
€0/month
- ✓ Full Terminal Features
- ✓ 200 AI Calls / month
- ✓ Local MCP Tools
- ✓ Community Support
Starter Plan
Recommended$10/month
- ✓ Everything in Free
- ✓ 2,000 AI Calls / month
- ✓ BYO API Key (Unlimited)
- ✓ Priority Support
BYO API Key allows you to plug in your own OpenAI or Anthropic API keys. This bypasses the Photon AI limits, giving you unlimited usage billed directly by the provider.
Detailed Feature Guide
AI Chat & Autonomous Mode
The AI Chat pane is your copilot.
- Providers & Models: Switch between different AI providers (e.g., OpenAI, Anthropic) and models directly from the chat header.
- Composer: Use
Ctrl/Cmd + Ito open the AI Composer for a focused chat experience. - Autonomous Execution: When you ask the AI to perform a task (e.g., "List all git branches"), it can generate the command and execute it for you.
- Confirmation: For safety, the AI will ask for your confirmation before executing any command.
Enhanced Explain
Located in the Explain/Teach view, this feature provides deep insights into various content types.
- Types: You can ask for explanations of:
- Shell Commands: Understand what a complex command does before running it.
- Error Messages: Paste an error to get a diagnosis and fix.
- Git Diff: Understand changes in your code.
- File Content: Get a summary or analysis of a file.
- Depth: Choose between "Brief", "Detailed", or "Comprehensive" explanations.
- Context: You can optionally provide JSON context (like working directory or last commands) for better accuracy.
Inline Completions
While typing in the terminal, PhotonShell offers intelligent suggestions.
- Trigger: Suggestions appear automatically as you type.
- Navigation:
TaborEnter: Accept the selected suggestion.Arrow Up/Down: Cycle through available suggestions.Esc: Dismiss suggestions.
Configuration Reference
Access the Settings view (Ctrl/Cmd + ,) to customize every aspect of PhotonShell.
AI Providers
Configure the AI services that power the chat and inline completions.
- Provider ID: Internal identifier (e.g.,
openai). - Name: Display name (e.g.,
OpenAI). - Base URL: API endpoint (e.g.,
https://api.openai.com/v1). - API Key Reference: Name of the environment variable containing the API key (e.g.,
OPENAI_API_KEY). - Limits: Set rate limits to control usage (Requests/Min, Tokens/Hour, etc.).
- Models: Define available models (e.g.,
gpt-5.1,claude-4.5-opus) with their specific context sizes and max tokens.
MCP Servers
Extend PhotonShell's capabilities with Model Context Protocol servers.
- Transport Type:
stdio(local process),websocket, ortcp. - Command/Args: For
stdio, the command to run the server (e.g.,npx,uv) and its arguments. - URL: For
websocket/tcp, the connection URL.
Safety & Security
Manage the safety engine that protects your system.
- Enable Safety Features: Master switch for all safety checks.
- Risk Assessment: Analyzes commands for potential danger before execution.
- Require Approval: Forces user confirmation for high-risk operations.
- Allowed/Blocked Commands: Whitelist or blacklist specific commands.
- Policy File: Path to an external JSON policy file.
- Audit Logging: Record all safety-related events.
Terminal Settings
Customize the look and feel of the terminal.
- Shell: Path to your preferred shell (e.g.,
/bin/zsh). - Font Family/Size: Typography settings.
- Scrollback Lines: How far back you can scroll in history.
- Theme: Visual theme (
Dark,Light,Photon Dark). - Behavior: Toggle
Blink Cursor,Enable Bell, andCopy on Select. - Environment Variables: Set custom env vars for terminal sessions.
User Interface
General UI preferences.
- Window Size: Default dimensions and
Remember Window Sizeoption. - Display: Toggle
Menu Bar,Status Bar,Line Numbers, andWord Wrap. - Font/Tab Size: Global UI typography settings.
Agent Configuration
Fine-tune the autonomous AI agent.
- Enable Agent: Master switch for agentic features.
- Limits:
Max Steps,Max Duration, andMax Output Size. - Capabilities: Grant or revoke permissions for
Shell Execution,MCP Tools,File System, andNetwork Access. - Sandbox Mode: Run the agent in a restricted environment.
- Working Directory: Default workspace for the agent.
Privacy
Control your data.
- Redact Secrets: Automatically mask API keys and secrets in logs/output.
- Local Storage Only: Prevent any data from leaving your machine (disables telemetry).
- Data Retention: How long to keep history (e.g.,
30d). - Telemetry: Opt-in/out of sharing usage stats and crash reports.
Logging
Application system logs.
- Level:
Debug,Info,Warn,Error. - Format:
JSONorText. - Output:
Standard OutputorFile. - Rotation: Configure max size, backups, and age of log files.
Tips & Tricks
Keyboard Shortcuts
These are the currently active shortcuts in the application:
General
- Open Settings Ctrl/Cmd + ,
- Toggle Sidebar Ctrl/Cmd + /
- Toggle Composer Ctrl/Cmd + I
- Shortcuts Guide F1
Terminal
- New Tab Ctrl/Cmd + T
- Close Tab Ctrl/Cmd + W
- Switch Tab Ctrl/Cmd + 1-9
- Toggle Search Ctrl/Cmd + F
- Clear Output Ctrl/Cmd + K
Search
- Find Next Enter
- Find Previous Shift + Enter
- Close Search Esc