Skip to content

About

An AI agent for your terminal. Bring your own model, work on code and files.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

28 Commits

Folders and files

Repository files navigation

Cortex CLI

An AI agent for your terminal. Work on code, files and research with the model you choose.

English · 简体中文

MIT license Node.js 22.19 or later Preview

Cortex CLI: tool activity, parallel agents and a suggested next message

Get started

Requires Node.js 22.19+ and an API key for your chosen provider.

npm install -g github:createpjf/cortex-cli --loglevel=error
cortex

First 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.

In a conversation

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 Cortex welcome screen with the CX dot-matrix mark

Command palette Agent dashboard

Screens are rendered from the real TUI with example data.

Scripts and integrations

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 trusted

Use --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.

Settings and updates

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-cli

This is a preview; commands and settings may change. Knowledge-base local model dependencies are not included. Report reproducible problems in Issues.

License and repository scope

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).

About

An AI agent for your terminal. Bring your own model, work on code and files.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors