{"id":50690173,"url":"https://github.com/georgebuilds/carlos","last_synced_at":"2026-06-13T03:05:33.137Z","repository":{"id":362803416,"uuid":"1260823574","full_name":"georgebuilds/carlos","owner":"georgebuilds","description":"BYOK coding and research agent. Obsidian-compatible markdown wiki as a baked-in memory system. Isolate work from life using frames.","archived":false,"fork":false,"pushed_at":"2026-06-09T02:24:43.000Z","size":2580,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T02:26:38.770Z","etag":null,"topics":["ai-agent","anthropic","bubbletea","claude-code","coding-agent","golang","llm","mcp","obsidian","tui"],"latest_commit_sha":null,"homepage":"https://georgebuilds.github.io/carlos/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/georgebuilds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-05T23:08:48.000Z","updated_at":"2026-06-09T02:21:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/georgebuilds/carlos","commit_stats":null,"previous_names":["georgebuilds/carlos"],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/georgebuilds/carlos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgebuilds%2Fcarlos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgebuilds%2Fcarlos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgebuilds%2Fcarlos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgebuilds%2Fcarlos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/georgebuilds","download_url":"https://codeload.github.com/georgebuilds/carlos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgebuilds%2Fcarlos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34270418,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","bubbletea","claude-code","coding-agent","golang","llm","mcp","obsidian","tui"],"created_at":"2026-06-09T02:09:06.151Z","updated_at":"2026-06-13T03:05:33.094Z","avatar_url":"https://github.com/georgebuilds.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/branding/carlos-portrait.png\" alt=\"carlos\" width=\"160\"\u003e\n\u003c/p\u003e\n\n# carlos\n\nA pure-Go TUI agent. Single binary under 30 MB. No CGO. Cross-compiled for darwin + linux × amd64 + arm64.\n\nMarketing copy and feature tour live at [georgebuilds.github.io/carlos](https://georgebuilds.github.io/carlos/). This README is for getting carlos running and for Go developers who want to contribute.\n\n---\n\n## Quick start\n\n### Install\n\n```\nbrew install georgebuilds/tap/carlos\ncarlos\n```\n\nOr grab a tarball from [Releases](https://github.com/georgebuilds/carlos/releases) and drop `carlos` into your `$PATH`.\n\n### First run\n\nOnboarding takes ~30 seconds:\n\n1. Your name\n2. A provider (Anthropic, OpenAI, OpenRouter, Ollama, or Gemini) and an API key\n3. A model from a curated dropdown (OpenRouter shows live pricing)\n4. Whether to enable the background daemon (scheduled runs, gateway delivery)\n5. Optional Obsidian vault path\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/branding/screenshots/onboarding-name.png\" alt=\"carlos onboarding step 1: 'What should I call you?' with 'Boss' typed in\" width=\"640\"\u003e\n\u003c/p\u003e\n\nEverything lands in `~/.carlos/config.yaml` (mode 0600). Re-enter any single screen later with `carlos onboard --only providers` (or `models`, `daemon`, `gateway`, etc.).\n\nAfter onboarding you're in the chat TUI. Type a question. carlos answers, calls tools when needed (prompting for the risky ones), and keeps the transcript in a SQLite event log at `~/.carlos/state.db`.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/branding/screenshots/chat-greeting.png\" alt=\"carlos chat TUI on first open, greeting 'Hey Boss - what are we working on?'\" width=\"640\"\u003e\n\u003c/p\u003e\n\n### Keys worth knowing\n\n| Key | What |\n|---|---|\n| `Ctrl+F` | open the frame switcher |\n| `/help` | full slash-command list |\n| `!\u003ccmd\u003e` | run a shell command in your context |\n| `/agents` | open the sub-agent manage view |\n| `/whoami` | current frame, mode, provider, model |\n| `/permissions` | layered approval state + audit log |\n| `/mcp` | list configured MCP servers and their tools |\n\n### CLI verbs adjacent to the chat\n\n```\ncarlos please \"\u003cprompt\u003e\"         # one-shot, no TUI\ncarlos research \"\u003cquestion\u003e\"     # multi-phase deep research\ncarlos memory search \u003cquery\u003e     # FTS5 over conversation summaries\ncarlos schedule list|add|rm      # cron + natural language\ncarlos gateway test \u003cchannel\u003e    # verify ntfy / Telegram wiring\ncarlos daemon enable|disable     # background service\n```\n\nAll accept `-f \u003cframe\u003e` (or `--frame`) to scope to a specific frame. `carlos please` takes a single positional prompt; multi-word prompts must be quoted (a single hyphenated token like `say-hello` works without quotes).\n\n`carlos please` shows a live 3-row bordered status panel while it runs (current tool, streaming-text preview, tool counter + provider/model); the assistant's final reply prints below the panel on completion.\n\n`carlos research` shows a live phase tracker (decompose, search, fetch, read, synthesize, verify) and writes a cited report under `~/.carlos/frames/\u003cframe\u003e/research/`:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/branding/screenshots/research-done.png\" alt=\"carlos research finished: 1m6s elapsed, all six phases checked, saved to ~/.carlos/frames/personal/research/\" width=\"720\"\u003e\n\u003c/p\u003e\n\n---\n\n## Contributing\n\n### Prerequisites\n\n- Go toolchain version pinned by `go.mod` (currently `1.26.3`).\n- `git` on `$PATH` (the sub-agent sandbox uses `git worktree`).\n- No CGO, no system libraries.\n\n### Build and test\n\n```\ngit clone https://github.com/georgebuilds/carlos\ncd carlos\ngo test ./...\ngo build ./cmd/carlos\n./carlos\n```\n\nCross-compile checks are cheap; run them when touching anything that imports OS-specific paths:\n\n```\nGOOS=linux  GOARCH=arm64  go build ./cmd/carlos\nGOOS=darwin GOARCH=amd64  go build ./cmd/carlos\n```\n\n### Test discipline\n\n- `go test ./...` is the floor. Current count is ~3390 tests across 41 packages.\n- `go vet ./...` must be clean.\n- New code aims for 80%+ coverage on touched packages.\n- The sub-agent + daemon + event log paths have integration tests; if you touch any of them, run `go test -race ./internal/agent/... ./internal/daemon/...` at least once before pushing.\n\n### Repository layout\n\n```\ncmd/carlos/         main TUI binary + daemon entry points\ninternal/\n  agent/            tool-use loop, event log, supervision, layered approval\n  config/           ~/.carlos/config.yaml schema + onboarding state\n  daemon/           background scheduler (UDS + launchd / systemd)\n  farewell/         bordered exit-panel + brew-update probe\n  frame/            per-session frames (personal + N user-defined)\n  gateway/          chat-surface adapters (ntfy, Telegram, Signal stub)\n  mcp/              Model Context Protocol client + tool adapter\n  memory/           SQLite FTS5 + summarizer\n  miniyaml/         hand-rolled YAML for frontmatter\n  notes/            Obsidian vault index + cache (Goldmark + miniyaml)\n  projectctx/       per-project context loader (walks AGENTS.md / CLAUDE.md)\n  providers/        anthropic, openai, openrouter, ollama, gemini\n  research/         decompose → search → fetch → read → synthesize → verify\n  sandbox/          local + git-worktree execution\n  schedule/         cron + natural-language grammar\n  skills/           skill format, loader, inducer, judge, replay-eval\n  theme/            light / dark / NO_COLOR / configurable accent\n  tools/            every registered tool (notes_*, web_*, code_search, etc.)\n  tui/              bubbletea chat / manage / onboarding / slash registry\n  usershell/        `!` prefix shell driver, jobs overlay, history\n  workspace/        trusted-workspaces store + read-only bash classifier\nskills/             bundled starter skills (calendar/, ...)\ndocs/               GitHub Pages site + llms.txt\n```\n\n### Where to look when adding a feature\n\n| You want to | Look here |\n|---|---|\n| Add a tool | `internal/tools/`, register in `tools.go` |\n| Add a slash command | `internal/tui/slash/slash.go` Builtins + handler in `internal/tui/chat/` |\n| Wire an MCP server | `mcp_servers:` block in `~/.carlos/config.yaml`; client + adapter live in `internal/mcp/` |\n| Add a provider | `internal/providers/\u003cname\u003e/`, satisfy the `Provider` interface |\n| Add a frame field | `internal/frame/frame.go`, then sysprompt + render helpers |\n| Change permission rules | `internal/agent/policy.go` (`LayeredApprover`) |\n| Add an event type | `internal/agent/eventlog_sqlite.go` + state machine |\n| Add an onboarding screen | `internal/tui/onboarding/screen_*.go` + flow wiring |\n\n### House conventions\n\n- Single immutable event log is the source of truth. The projection replays from it.\n- Atomic writes for any file containing user state: `temp + fsync + rename`. See `internal/config/config.go:Save` for the canonical recipe.\n- File modes: `0700` directories, `0600` secret-bearing files (`config.yaml`, `state.db`, `trusted-workspaces.json`, artifact blobs), `0644` elsewhere.\n- Prefer editing existing files to creating new ones.\n- Default to no comments; add one only when the WHY is non-obvious.\n\n### Release flow\n\nA `v*` tag push fires `.github/workflows/release.yml` which runs goreleaser to build the four-arch tarballs, drafts a GitHub release, and bumps `georgebuilds/homebrew-tap/Formula/carlos.rb`. Publish the draft when ready (`gh release edit v0.X.Y --draft=false`).\n\n---\n\n## License\n\nGPL-3.0-or-later. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgebuilds%2Fcarlos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeorgebuilds%2Fcarlos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgebuilds%2Fcarlos/lists"}