An AI agent for your terminal. Work on code, files and research with the model you choose.
English · 简体中文
Requires Node.js 22.19+ and an API key for your chosen provider.
npm install -g github:createpjf/cortex-cli --loglevel=error
cortexFirst launch guides you through choosing a provider, model and API key. The interface follows your system language (Chinese on a Chinese system, English otherwise); change it in /settings → Language.
Providers: Anthropic, OpenAI, Google, DeepSeek, FLock API Platform, xAI / Grok, OpenRouter, Kimi, Zhipu AI, MiniMax, Doubao, Qwen and custom OpenAI-compatible endpoints. Use /config to change connections and /model to switch models. Availability depends on your provider and account.
| Action | Shortcut or command |
|---|---|
| Send a message / add a newline | Enter / Ctrl+J |
| Choose work mode | Shift+Tab |
| Switch model / thinking level | /model / Ctrl+S |
| Find commands and skills / reference a file | Ctrl+P or / / @ |
| View agents / sessions needing attention | /agents / /inbox |
| Stop the current run / reopen a pending request | Esc / /pending |
| Resume a conversation / change settings | /resume / /settings |
| Attach an image | Ctrl+V, or drag the file into the terminal |
| Run a command on your computer | ! followed by the command |
| Write an AGENTS.md for the project | /init |
| Ask a side question without interrupting | /btw followed by the question |
| Vim input mode | /vim to turn it on or off |
| Clear the input / quit | Ctrl+C / Ctrl+C twice on an empty input |
| Suspend to the shell | Ctrl+Z, then fg |
The default mode asks for approval when needed. Plan is read-only; Auto-approve reduces prompts but retains protection for irreversible actions. Approvals open after you stop typing and take number keys, so a half-typed sentence can't answer them. Enter queues a follow-up while a run is active; Alt+Enter sends it into the current run. Stopping a run moves queued messages back to the input. /btw asks the model once using the current conversation, even during a run; the answer only appears in your transcript, the agent can't see it, and it's unavailable in conversations that used a knowledge base. With Vim mode on, Esc first switches to normal mode and a second Esc stops the run; normal mode supports hjkl, w b e, 0 $, i a o, x dd cc dw, u to undo and p to put back.
! commands run in your shell in the project folder, without the sandbox or approvals. Their output is shown in the conversation and sent along with your next message; remove it in /attachments. Use /keymap to customize bindings and /help for more.
Welcome screen, command palette and agent dashboard
Screens are rendered from the real TUI with example data.
cortex exec "Summarize this project" --output-format json
cortex review # Read-only review of uncommitted changes
cortex sessions # List saved conversations
cortex resume # Choose a conversation to resume
cortex resume --last # Continue the latest one in this folder
echo "Summarize this project" | cortex exec
cortex mcp add files -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
cortex hooks list # List hooks in global/hooks.json
cortex hooks trust 6ae5bb22 # Runs from the next run once trustedUse --output-schema schema.json to validate a JSON reply, or -o answer.md to save the final reply without overwriting an existing file. exec has no time limit unless you pass --timeout <seconds>. cortex --help lists every option.
Hooks go in global/hooks.json in the config directory, in the Claude Code format, and support UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop and SubagentStop. Only hooks you trust with cortex hooks trust <ID> run; editing a command requires trusting it again, and untrust revokes it. On macOS hooks run in a sandbox by default; on other systems they run with your user permissions. In desktop mode, trust hooks in the desktop app under Settings › Hooks.
Already using Cortex desktop? Run cortex --desktop to share its providers, permissions and conversations. Keep a compatible desktop app running. Desktop mode is unsupported on Windows and unverified on Linux; computer use requires desktop mode, interactive approval and the desktop extension.
Standalone settings and conversations live in ~/.cortex-cli-preview; appearance and language live in ~/.cortex-cli-ui.json. Model requests go to your configured provider; tools run on your computer. CORTEX_LANGUAGE=en or zh-CN overrides the saved language. NO_COLOR=1 disables colors; /motion reduces animation. Next-message predictions are beta, make an extra model request per turn, and can be disabled in /settings. When the terminal is in the background, Cortex lets you know when it needs approval or finishes a long run: a system notification in Ghostty, iTerm2, Kitty, WezTerm and Warp, a bell elsewhere. Quitting prints a short summary of time, tokens, tools and changed files. Install fd so @ searches the whole project by name; cortex doctor checks for it.
cortex update # Update from this repository
cortex doctor # Check installation and terminal
cortex --debug # Write runtime logs to logs/ in the config folder, keys hidden
npm uninstall -g cortex-cliThis is a preview; commands and settings may change. Knowledge-base local model dependencies are not included. Report reproducible problems in Issues.
MIT. This repository distributes Cortex CLI builds, documentation and images. The TypeScript source remains in the private Cortex repository; it is not published here.
Bundled components retain their own licenses, including Apache-2.0 for Cortex shared/core components. See NOTICE, third-party notices and Apache-2.0. Installed dependencies include their own license files. Terminal themes and ASCII fallback include adaptations from termcn (MIT).

