Using the CLI

Launching

cortana                         # full-screen TUI; the current directory is the workspace
cortana --plain                 # line REPL (automatic when stdin/stdout isn't a terminal)
cortana --model qwen3:8b        # a different model for this session
cortana --add-dir ~/notes       # let tools also use another folder
cortana --listen                # start in hands-free voice mode

Without the symlink, run scripts/cortana from the repository or uv run python main.py. Every option is listed under Command-line flags.

MCP servers, the knowledge graph and other slow services connect in the background after the UI opens, so you can start typing straight away. /doctor checks the configured model server and reports model capabilities.

The terminal UI

The TUI is a scrolling transcript with • replies and tool calls, a Working (12s • esc to interrupt) status line and a › composer. Tool calls show what they do: a red/green diff with line numbers for edits, the start of a new file, the command for shell calls. When they finish, a one-line summary replaces the raw output, such as "Read 120 lines", "Updated app.py · +3 −1" or "Found 14 matches".

Set OLLAMA_CONTEXT_WINDOW to your server's context size to see context-used percentages. At 90% the conversation is summarized automatically and the turn continues; see Context compaction.

Permission modes

The mode decides which tool calls need your approval. Switch with Shift+Tab or /permissions auto|plan|ask, and set the default with agent.permission_mode.

In every mode, the CLI asks before a destructive or outward-facing shell command (rm, sudo, git push, git reset --hard, curl … | sh, DROP TABLE, …) and before creating or running a tool the model wrote. Answering always approves only that exact command or tool for the rest of the session. Turn this off with agent.confirm_destructive: false.

Plan, review, then build

1. Switch to plan and describe the change. The agent reads and searches, writes a plan with update_plan and summarizes it, leaving the steps open.
2. Read it with /plan (or open the Markdown file under .cortana/plans/), edit it if you like, and ask for changes until it's right.
3. Switch back to auto and say "go ahead". The agent carries the saved plan out step by step, and a turn can't end with steps left undone.

See Planning & verification for how plans and the verifier work.

Slash commands

Read-only commands (/status, /context, /usage, /diff, /plan, …) run immediately, even while a turn is in progress. Others queue behind it.

Session and model

Conversations and context

Working on code

Tools, agents and media

Learning

Shell & teach mode

Start a line with ! to run a shell command in the workspace yourself. The output is shown and sent along with your next message, so you can say "fix this" after a failing test run:

› !python -m unittest tests.test_calc
› the divide test fails, fix it

Teach mode turns a task you do yourself into a reusable skill:

› /teach release-notes write release notes from git
› !git log --oneline v1.2..HEAD
› /teach note fixes go before features
  … edit files in your editor …
› /teach stop          # shows the drafted SKILL.md
› /teach save          # keeps it under skills/learned/ (or /teach discard)

Only ! commands and file changes inside the workspace are recorded; nothing watches in the background. /teach cancel stops without drafting.

Command-line flags

scripts/cortana adds two launcher flags: --kokoro-tts (default environment, Kokoro active) and --qwen-tts (the .venv-qwen environment, Qwen active). Everything else is passed on to main.py.

Managing MCP servers

Add Model Context Protocol servers the same way as claude mcp or codex mcp. Servers connect the next time Cortana starts.

# stdio: everything after -- is the command line
cortana mcp add playwright -- npx -y @playwright/mcp@latest
cortana mcp add -e API_KEY='${MY_KEY}' myserver -- uvx my-mcp-server

# remote (Streamable HTTP by default; --transport sse for legacy servers)
cortana mcp add --transport http postman https://mcp.postman.com/minimal \
    --header 'Authorization: Bearer ${POSTMAN_API_KEY}'

cortana mcp list            # connects to each server and reports ✓/✗
cortana mcp get postman
cortana mcp remove postman

Put single quotes around ${VAR} so your shell doesn't expand it; the config then stores the reference, not the secret. Other options: --scope project|user, --description, --always-loaded and --force. See MCP servers for the config files and per-server options.