How the TALOS CLI works

The TALOS CLI is a coding agent in your terminal: it reads, edits and runs code in your project, on the model you choose. The npm package is talos-code; the command it installs is talos.

Three promises shape it: every tool asks before it acts unless you allowed it, every file it changes can be restored, and every session can be resumed.

Three ways to run it

You run	You get
talos	The interactive screen in the current folder; a prompt, if given, is the first message.
talos -p "…"	One task without the screen (headless): the answer is printed, and the run ends.
talos -p "…" --json	The same, with one JSON result at the end — or --output-format stream-json for one JSON event per line.

Everything else is a subcommand: talos <family> <operation>, from talos session list to talos doctor. Every family is in the CLI reference.

A headless run cannot ask you anything: an action that needs your approval is denied, and the run says so. It stops after 180 seconds unless --timeout says otherwise. See Run a task without the screen.

The project folder

TALOS works in one project folder — the current one, or --project <path>. The first time, it asks whether you trust the folder: a project’s hooks, MCP servers, plugins and commands are code, and none of them loads in a folder you did not trust. talos project status says what is trusted and why. See Extensions.

What stays on your machine

There is no telemetry. Nothing is sent anywhere except:

• your prompts and the files TALOS reads, to the provider you chose;
• the public model catalog at models.dev, for context windows and prices, cached for 4 hours — turn it off with talos config set catalog.modelsDev false or TALOS_MODELS_DEV=off;
• the npm registry, only when you run talos update.

Configuration, sessions, checkpoints and logs stay on your machine:

	Windows	macOS / Linux
Configuration	%APPDATA%\TALOS-CLI	~/.config/talos-cli
Sessions, checkpoints, logs	%LOCALAPPDATA%\TALOS-CLI	~/.local/state/talos-cli

Every folder and file is listed in Files.

Where to go next

• Permissions — what TALOS may do without asking.
• Sessions, context and undo — resuming, compaction, checkpoints.
• Models and providers — cloud and local models, and where keys are kept.
• Extensions — MCP servers, hooks, plugins and your own commands.