Documentation

Quick start

Use the supported installer on macOS or Linux, then start Talos. Windows x86_64 users can use the PowerShell installer. See Install for archives, platform support, and source builds.

curl -fsSL https://raw.githubusercontent.com/wjhuang88/talos/main/install/install.sh | sh

On a first run without a configured model, the TUI opens its model picker. In CI or another non-interactive context, use talos --no-init -p "summarize this repo".

Configuration and credentials

Talos reads ~/.talos/config.toml. You may use an inline api_key, an api_key_env environment-variable name, or ${ENV_VAR} substitution. Inline keys are persisted but masked in configuration displays and diagnostic surfaces; keep the file private.

Use talos config list, talos config get model, and talos config set model claude-sonnet-4-20250514 to manage configuration. The configuration reference lists provider, MCP, dashboard, logging, and reasoning settings. Never commit a key to a project configuration.

Providers, models, and variants

Built-in provider defaults include Anthropic and OpenAI; compatible providers can be configured with a protocol, base URL, model, and credentials. The /model picker groups recent models and providers, then models, then a variant picker only when the chosen model declares variants.

Reasoning-capable catalog entries can expose a named reasoning effort. A selected variant is stored with the provider and model; unknown or unsupported variants safely fall back with a diagnostic. Use the picker rather than inventing provider request JSON.

Modes, composer, and commands

Talos supports an interactive TUI, inline prompts, and print mode for scripting. The TUI composer wraps display-width-aware text, including CJK characters. Use Shift+Enter for a newline on terminals supporting enhanced keyboard reporting; Ctrl+J is the portable newline fallback. Plain Enter sends the prompt.

Type / to open available commands. Common entry points include /model, /connect, /help, configuration and session commands; command availability follows the live runtime.

Tools and permissions

Talos includes file, directory, search, edit, shell, code-intelligence, Git, HTTP, and web-search tools. Read-only actions may proceed under the configured policy; writes, deletes, Git writes, shell execution, network actions, and MCP tools pass through the permission pipeline.

Inspect the requested action before approving it. The Capabilities page lists the user-facing tool surface; the Safety page explains the boundary.

Sessions, storage, and memory

Local SQLite-backed sessions support history, search, cleanup, maintenance, export, and branch/fork workflows. Memory consolidation and exploration ingestion are local features; they are not a remote knowledge service. Use session commands in the TUI to inspect the commands available in your build.

Skills, MCP, and plugins

Runtime Skills are discovered from project .talos/skills/, user ~/.talos/skills/, and inherited parent project skill directories. Activate only the Skill material relevant to your task.

MCP servers support stdio, SSE, and Streamable HTTP transports and remain subject to permissions. Local read-only WASM packages can be loaded explicitly with repeatable --plugin DIRECTORY; remote plugin distribution, marketplaces, writable plugins, and automatic discovery are not shipped.

Safety boundaries

Talos is not a remote multi-user service, browser automation surface, web approval route, autonomous background daemon, or a stable 1.0 SDK. It does not bypass permission checks for write-capable tools. The optional dashboard is local and read-only by default.

See Safety for secrets, permissions, sandbox posture, and the precise non-goals. See Roadmap for the shipped/planned/research split.

Troubleshooting

• No model or credential: start the TUI and use the picker, or check talos config list; keys should display as ***.
• Terminal cannot distinguish Shift+Enter: use Ctrl+J, or run outside a terminal multiplexer with enhanced keyboard reporting enabled.
• Installer or archive problem: confirm your platform is listed on Install, then use the current GitHub Release asset.
• Need more detail: read the root README, inspect talos --help, or file an issue with command output after removing secrets.

Release and support

See Releases for the current tag and GitHub release history. Talos remains pre-1.0; verify behavior against the installed version before depending on APIs, command surfaces, or storage formats.