carlos

home · docs

documentation

The whole story.

carlos is a pure-Go TUI agent. Single binary around 30 MB. Local-first, multi-provider, with autonomous skill induction and first-class sub-agent supervision. These docs cover install, the core concepts (frames, permissions, sub-agents, memory), the reference surfaces (tools, slash, config), and the guides that wire them together (research, gateway, schedule).

1Get started.

2 pages

Install, onboard, and run your first chat in about five minutes.

brew

Install

Homebrew tap, pre-built tarball, or build from source. Single binary, no CGO.

 5 min

Quickstart

Eight-screen onboarding, your first chat, keys worth knowing, the headless CLI.

2Core concepts.

4 pages

The mental model. What a frame is, how the approval policy composes, how the supervisor tracks sub-agents, where memory lives.

envelope

Frames + modes

Personal plus N user-defined. Provider override, vault subtree, MCP gating, orchestrator mode.

 3 layers

Permissions

Built-in allowlist, workspace trust, session fallback. Cross-frame detector ahead of the chain.

 marquee

Sub-agent supervision

Ten-state machine, four-part contract, steer / interrupt / stop, safety rails. The event log is the source of truth.

 3 tiers

Memory

Episodic event log, FTS5-searchable summaries, slow-moving user model.

3Reference.

3 pages

Every tool, every slash command, every config key. The "what does X do" surface.

31 + MCP

Tools

Filesystem, shell, git, web, notes, introspection. Plus per-frame MCP-contributed surfaces.

 /

Slash commands

Claude Code parity verbs plus carlos-specific ones. Inline autocomplete with ghost text.

 ~/.carlos/

Config

config.yaml schema, on-disk layout, file modes, atomic writes.

4Guides.

4 pages

End-to-end usage of the surfaces that build on the core. Each guide is a worked example with the relevant CLI verbs.

6 phases

Research mode

decompose, search, fetch, read, synthesize, verify. Cited reports with stable IDs.

 SKILL.md

Skills

SKILL.md packaging, where they live, propose-don't-publish induction.

 ntfy + tg

Messaging gateway

Reach carlos from your phone. ntfy, Telegram, Signal stub, signed action tokens.

 cron + NL

Scheduled runs

Five-field cron plus a seven-form English grammar. Per-frame fires.

Worth a look.

Long-form pieces about how carlos compares to other agents.

3-up

Agent loop comparison

Claude Code, carlos, and Codex side-by-side. Where they converge and where they diverge.

 repo

The code

Open on GitHub. README has install and contributor notes; SPEC and DESIGN live in the vault.