carlos

module

v0.3.1 Latest Latest Go to latest Published: Jun 6, 2026 License: GPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/georgebuilds/carlos

Links

Open Source Insights

README ¶

carlos

A pure-Go TUI agent. Single binary, under 16 MB.

Not strictly a coding agent. General-purpose: file system, shell, web, notes, schedules. Two headline features:

Autonomous skill induction. Carlos watches what you do and turns repeated patterns into reusable skills, which you review and edit like code.
First-class sub-agent supervision. When carlos delegates, you see every delegated agent in a live supervisor view: their intent, tool calls, progress, diffs, and spend. Join, redirect, or stop any of them mid-flight.

Plays nice with Claude Code: loads its skill library, honors your CLAUDE.md, familiar slash commands. Skills you write in either tool show up in both.

Status

Alpha. Dogfood-ready, not yet v1. Site: georgebuilds.github.io/carlos.

~1170 tests across 28 packages
Cross-compiled for darwin + linux × amd64 + arm64
Pure Go, no CGO, single binary

Install

brew install georgebuilds/tap/carlos

Or grab a tarball from Releases and drop carlos into your $PATH.

Build from source

go build ./cmd/carlos
./carlos

First launch runs a six-screen onboarding (welcome, name, provider, model, daemon enable, done). State lives in ~/.carlos/.

Multi-provider

Anthropic, OpenAI, OpenRouter, Ollama. All first-class from day one. Tool-use canonical shape is Anthropic's; adapters normalize others. Capability map honestly exposes what's lost when downgrading (caching, parallel tool use, structured output, vision).

What's inside v0

A single binary, under 16 MB.
Four providers, one shape.
A memory that lives in plain markdown. Read it in Obsidian, grep it in your shell. Specialized tools query it 10× to 100× more token-efficiently than grepping and globbing.
Work and life on separate shelves. Two contexts, never crossed.
Research that goes hard. Many readers fan out, one synthesis returns, every source on file.
Proposes new skills, never publishes them. Learned from use, kept only if you approve.
Plays nice with Claude Code.
MCP draft compliant from day one. Built against the next Model Context Protocol spec, not the old one.

Layout

cmd/carlos/      main TUI binary + daemon
internal/
  agent/         tool-use loop, event log, supervision, approval queue
  tui/           bubbletea chat / manage / onboarding views
  providers/     anthropic, openai, openrouter, ollama
  tools/         bash, file, grep, web_fetch, web_search, http_request, notes_*
  skills/        skill format, loader, induction + replay-eval
  memory/        SQLite FTS5, summarizer, user model
  notes/         Obsidian-aware vault tools (Goldmark + miniyaml)
  research/      decompose → search → fetch → read → synthesize → verify
  sandbox/       local + git-worktree
  schedule/      cron + NL grammar + scheduled-run execution
  config/        onboarding state, provider keys, user prefs
  theme/         light / dark / NO_COLOR / configurable accent
  daemon/        background scheduler (UDS + launchd/systemd)
  miniyaml/      tiny hand-rolled YAML for frontmatter
  projectctx/    per-project context (CLAUDE.md, working tree)
  gateway/       chat surface adapter
docs/            coming-soon site (served via GitHub Pages)

License

GPL-3.0-or-later. See LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
carlos command Phase 8a + 8b: carlos daemon + schedule CLI surfaces.	Phase 8a + 8b: carlos daemon + schedule CLI surfaces.
internal
agent Phase 7 slice 7e — apply handler.	Phase 7 slice 7e — apply handler.
config Package config owns the on-disk schema for ~/.carlos/config.yaml.	Package config owns the on-disk schema for ~/.carlos/config.yaml.
daemon Daemon-side wiring for the messaging gateway.	Daemon-side wiring for the messaging gateway.
gateway Package gateway provides the messaging-gateway broker and adapter contract that lets carlos talk to ntfy, Telegram, Signal, and a future custom HITL side-app over the same canonical envelope.	Package gateway provides the messaging-gateway broker and adapter contract that lets carlos talk to ntfy, Telegram, Signal, and a future custom HITL side-app over the same canonical envelope.
gateway/approvals Package approvals bridges the agent.ApprovalQueue to the gateway Broker.	Package approvals bridges the agent.ApprovalQueue to the gateway Broker.
gateway/fake Package fake provides a deterministic in-memory gateway.Adapter used by broker tests and by downstream packages (approvals router, daemon-side integration) to exercise the gateway loop end-to-end without a real platform behind it.	Package fake provides a deterministic in-memory gateway.Adapter used by broker tests and by downstream packages (approvals router, daemon-side integration) to exercise the gateway loop end-to-end without a real platform behind it.
gateway/ntfy Package ntfy implements the gateway.Adapter for ntfy.sh.	Package ntfy implements the gateway.Adapter for ntfy.sh.
gateway/signal Package signal is the Signal-channel gateway.Adapter.	Package signal is the Signal-channel gateway.Adapter.
gateway/telegram Package telegram implements the gateway.Adapter contract on top of the Telegram Bot API.	Package telegram implements the gateway.Adapter contract on top of the Telegram Bot API.
memory Package memory — see schema.go for the doc comment that anchors the package.	Package memory — see schema.go for the doc comment that anchors the package.
miniyaml Package miniyaml is a tiny YAML subset parser tailored to carlos's actual usage.	Package miniyaml is a tiny YAML subset parser tailored to carlos's actual usage.
notes Package notes is the Obsidian-flavored markdown indexer that backs the notes_* tool family.	Package notes is the Obsidian-flavored markdown indexer that backs the notes_* tool family.
projectctx Package projectctx discovers and loads per-project agent context files (AGENTS.md / CLAUDE.md and their `.agents/` `.claude/` namespaced variants) so the model sees a project's house rules without the user having to copy-paste them every session.	Package projectctx discovers and loads per-project agent context files (AGENTS.md / CLAUDE.md and their `.agents/` `.claude/` namespaced variants) so the model sees a project's house rules without the user having to copy-paste them every session.
providers
providers/anthropic Package anthropic implements a pure-Go streaming client for the Anthropic Messages API.	Package anthropic implements a pure-Go streaming client for the Anthropic Messages API.
providers/fake Package fake is a deterministic provider used by Phase 1 preflight tests.	Package fake is a deterministic provider used by Phase 1 preflight tests.
providers/gemini Package gemini implements a pure-Go streaming client for Google's Generative Language API via its OpenAI-compatible endpoint at https://generativelanguage.googleapis.com/v1beta/openai/.	Package gemini implements a pure-Go streaming client for Google's Generative Language API via its OpenAI-compatible endpoint at https://generativelanguage.googleapis.com/v1beta/openai/.
providers/oacompat Package oacompat implements the OpenAI Chat Completions wire protocol shared by carlos's `openai` and `openrouter` providers.	Package oacompat implements the OpenAI Chat Completions wire protocol shared by carlos's `openai` and `openrouter` providers.
providers/ollama Package ollama implements a pure-Go streaming client for the Ollama /api/chat endpoint.	Package ollama implements a pure-Go streaming client for the Ollama /api/chat endpoint.
providers/openai Package openai implements a pure-Go streaming client for the OpenAI Chat Completions API.	Package openai implements a pure-Go streaming client for the OpenAI Chat Completions API.
providers/openrouter Package openrouter implements a pure-Go streaming client for the OpenRouter chat-completions endpoint.	Package openrouter implements a pure-Go streaming client for the OpenRouter chat-completions endpoint.
research Phase 11 slice 11d — research as sub-agent.	Phase 11 slice 11d — research as sub-agent.
sandbox Package sandbox provides execution backends for carlos sub-agents.	Package sandbox provides execution backends for carlos sub-agents.
schedule Package schedule owns carlos's scheduled-run vocabulary:	Package schedule owns carlos's scheduled-run vocabulary:
skills curator.go — staleness sweep over the active skill library.	curator.go — staleness sweep over the active skill library.
skills/skillwire metrics.go — skill-induction instrumentation.	metrics.go — skill-induction instrumentation.
theme Package theme is the single source of truth for the colors every TUI surface (chat, manage, onboarding) renders with.	Package theme is the single source of truth for the colors every TUI surface (chat, manage, onboarding) renders with.
tools Package tools — HTTPRequestTool.	Package tools — HTTPRequestTool.
tui
tui/chat TUIApprover bridges agent.Run's synchronous Approver interface to the chat TUI's asynchronous render/keypress loop.	TUIApprover bridges agent.Run's synchronous Approver interface to the chat TUI's asynchronous render/keypress loop.
tui/chatglue Package chatglue wires the chat TUI to a real provider + tool loop.	Package chatglue wires the chat TUI to a real provider + tool loop.
tui/diff Package diff renders unified-diff text into a lipgloss-styled string for the manage focus pane.	Package diff renders unified-diff text into a lipgloss-styled string for the manage focus pane.
tui/manage Package manage is the bubbletea sub-agent supervision TUI — the marquee surface from SPEC § Manage mode.	Package manage is the bubbletea sub-agent supervision TUI — the marquee surface from SPEC § Manage mode.
tui/onboarding Package onboarding owns the six-screen first-run flow and the portrait protocol cascade.	Package onboarding owns the six-screen first-run flow and the portrait protocol cascade.
tui/slash Package slash owns carlos's TUI slash-command vocabulary.	Package slash owns carlos's TUI slash-command vocabulary.
usershell Package usershell implements the `!`-prefix feature: shell commands the USER types in the chat composer, run in their own context (not the agent's sandboxed bash tool), with output added to the conversation as context for the next model turn.	Package usershell implements the `!`-prefix feature: shell commands the USER types in the chat composer, run in their own context (not the agent's sandboxed bash tool), with output added to the conversation as context for the next model turn.