First five minutes.
Onboarding takes about thirty seconds. The chat TUI greets you by the name you give it, calls tools when needed, and persists the transcript to a SQLite event log.
Onboarding eight screens
Full-screen alt-screen with a crispy outer border in brand blue. A persistent left rail carries the carlos portrait, the brand wordmark, and a step indicator. The right pane is the active screen. Every screen has a sensible default; press Enter to accept and move on.
- Name. "What should I call you?" Defaults to
Boss, or$USERwhen reasonable. - Provider configuration. For each of
anthropic,openai,openrouter,ollama,gemini:yconfigure now,llater,nskip. Provide an API key, or the Ollama base URL. At least one provider must be configured before you can exit. - Default model pick. One per configured provider. OpenRouter shows live pricing and context columns via a cached
/api/v1/modelsfetch (24h cache, 800ms timeout fallback). - Skills convention.
.agents/skills/(open standard, default) or.claude/skills/. This determines where carlos writes new skills; both paths are read regardless. - Daemon. Install a launch agent (macOS
launchd, Linuxsystemd --user) for scheduled runs and gateway delivery. Defaults to no. - Gateway (optional). ntfy, Telegram, or Signal stub. Defaults to "set up later";
carlos gateway addruns the same wizard standalone. - Vault (optional). Obsidian-flavored notes location. Defaults to
~/.carlos/vault/. - Done. "Ready, Boss." plus the path to your new config file.
carlos onboard --only <screen> jumps back into one screen without touching the rest of your config. Useful when you want to add a provider, change the skills path, or flip the daemon on.
Minimum terminal is 80x24. Below that, onboarding renders a one-line "needs at least 80x24" message instead of a broken layout. Resize your window and re-run.
Your first chat
After onboarding, you land in the chat TUI. The composer sits at the bottom. Type, press Enter to send; carlos answers, streams tool calls as they happen, and renders the final turn as markdown via glamour.
The empty-state shows the cap mascot, a greeting using the name you picked, and four example prompts. The "thinking" indicator (bouncing dots, elapsed timer after 3s) covers the gap between submit and the first model token.
Keys worth knowing
| key | what it does |
|---|---|
| Ctrl+F | open the frame switcher (full-screen 3x2 takeover) |
| Alt+M | toggle mouse capture (for terminal text selection on Ghostty) |
!<cmd> |
run a shell command in your context; output enters the conversation |
/help |
full slash-command list, bordered overlay parsed from the registry |
/agents |
switch focus to the manage view (sub-agent supervisor) |
/whoami |
current frame, mode, provider, and model in one line |
/permissions |
layered approval state plus audit log |
/mcp |
configured MCP servers and their tools |
The full list, with arguments and registry-level descriptions, lives in the slash reference.
Shell prefix
!<cmd> runs in your user shell context; output enters the conversation as context for the next turn. Backgrounded jobs land in the /jobs overlay; /fg <id> and /bg <id> move them around.
# peek at the tree, hand it to carlos as context !ls -la ~/Code/carlos # long-running build, sent to the background !go test ./... &
Headless: carlos please
For shell aliases and scripts, carlos please takes a single positional prompt and prints the final reply. A live three-row bordered status panel shows the current tool, a streaming-text preview, and a tool counter plus provider/model identifier. When carlos finishes, the panel collapses and the reply prints below.
carlos please "summarize ~/notes/today.md"
Multi-word prompts must be quoted. Useful flags:
| flag | what |
|---|---|
-y, --yes |
auto-approve every tool call; no stderr prompts |
-p <name>, --provider <name> |
override default provider for this run |
-m <id>, --model <id> |
override default model for this run |
-f <name>, --frame <name> |
run inside a named frame |
alias ?='carlos please' in your .zshrc turns the whole headless verb into one keystroke. Combine with -y for ambient scripts you trust.
Other CLI verbs
carlos research "<question>" # six-phase deep research, cited report carlos memory search <query> # FTS5 over conversation summaries (per-frame with -f) carlos schedule list|add|rm # cron + natural-language grammar carlos gateway add # wizard: ntfy / Telegram / Signal carlos gateway test <channel> # send a fixed envelope through one adapter carlos daemon enable|disable # background service
All verbs accept -f <frame> to scope memory, history, and config overrides to a specific frame.