SuperShellUse SuperShell in your terminal
Install the CLI, choose a runtime, and learn the commands and permission modes.
Last updated
On this page
InstallQuick startRuntimesSlash commandsPermissions and modesHeadless runsComputer toolSubagents and feedbackInstall
macOS Apple silicon + Intel, Linux x64 + arm64. No Node needed. No SuperShell account is needed.
curl -fsSL https://supershell.ai/install | sh
supershellRun supershell update to update. Cloud is optional via /cloud.
Quick start
Open a terminal in the project you want to work on:
cd your-project
supershellChoose a runtime with /runtime, then connect a model with /login: OpenRouter, OpenAI, Anthropic, or ChatGPT/Claude sign-in. Use /model to choose a model. Run /setup to check the installation. Ask for a concrete task, such as “explain this project's test setup.”
Run /init to ask the agent to write or update the project's AGENTS.md instructions. Press Esc to interrupt. Press ! on an empty prompt to enter Bash mode.
supershell --continue
supershell --resume <id>--continue reopens the most recent conversation; --resume opens the ID you provide.
Runtimes
Run /runtime to choose which agent runs the conversation.
- SuperShell uses its own agent loop and tools with OpenRouter, OpenAI, or Anthropic models.
- Claude Code runs your installed
claude, with its own login, instructions, settings, and sessions. Sign in first withclaude auth login. - Codex runs your installed
codex app-server, with its own login and threads. Sign in first withcodex login.
A slash command that SuperShell does not recognize is passed to the selected Claude Code or Codex runtime.
Slash commands
Use /help for the full list and keyboard shortcuts.
/login,/provider,/model: set up a provider and choose a model./runtime,/thinking,/fast: choose the agent runtime, reasoning depth, and fast processing setting. Fast processing may use more quota./config,/init: open settings or update project instructions./subagents,/spawn,/agents: configure, start, and manage agents for side tasks./jobs,/tasks,/usage: inspect background shell jobs, the task board, and usage./sessions,/resume,/new: find a saved conversation or start another./mcp,/import,/instructions: manage connected tools and shared instructions./cloud,/remote: link a machine, then share or continue a conversation in Cloud./feedback: rate SuperShell or report a bug.
Skills also become slash commands: /<skill-name> [args].
Permissions and modes
Press Shift+Tab to switch between Normal, Auto, and Plan. Normal is shown as Ask in the footer.
In the SuperShell runtime, read-only tools run without asking. Other tools ask in Normal mode unless a permission rule allows them. Auto approves ordinary tool requests; special consent, such as taking over the mouse and keyboard, still requires a person.
Plan tells the agent to investigate and prepare a plan before implementation. It is an instruction to the agent, not an operating-system sandbox. Claude Code and Codex keep their own runtime settings and permission behavior.
Permission rules can be set in user, project, and local settings. Deny takes priority over allow, which takes priority over ask. Set rules in ~/.supershell/settings.json, .supershell/settings.json, or .supershell/settings.local.json as tool or tool(glob). Local settings override project settings, which override user settings; deny rules keep their priority.
Headless runs
Use -p to print an answer and exit:
supershell -p "explain src/cli.ts" --model <id>Optional flags include --provider, --agent, --thinking, --json, and --yes. Without --yes, tool calls that would ask for permission are denied. Add --yes only when you intend to allow those calls.
Computer tool
The SuperShell runtime's computer tool can work with Chrome and native apps. Chrome use requires the optional Chrome bridge. Load the SuperShell Computer extension in your Chrome profile, then use its Connect SuperShell action. Native macOS control requires the native helper and the relevant macOS privacy permissions. Browser-only use does not require those native helper permissions.
The tool sends screenshots and page text to the selected model and saves them in conversation history. Check the page for private data before asking an agent to use it.
Subagents and feedback
A conversation can start subagents on their own model or runtime. Use /subagents to configure them, /spawn to start one, and /agents to inspect, message, stop, or enter it.
Use /feedback to send a rating or bug report. Conversation sharing is a separate choice in the feedback form. Read the privacy draft for the data involved.