go-steer/core-agent

A production-grade Go substrate for multi-turn LLM agents, built on the Google Agent Development Kit. Ships the wiring — providers, MCP, skills, permissions, durable sessions, remote attach, an in-process Bubble Tea TUI, and a headless CLI — so downstream projects can focus on their own tools and product logic.
**📚 Full documentation: go-steer.github.io/core-agent**
---
Features
**Runtime**
- Multi-turn conversation via ADK's runner.Runner; parallel tool-call dispatch.
- In-process Bubble Tea TUI as the default TTY surface; --no-tui line REPL fallback; slim build (-tags no_tui) drops the TUI tree entirely.
- autonomous.Run for unattended workers with turn / token / cost / wallclock budgets and model-driven termination; autonomous.Resume picks up from a durable checkpoint after a crash.
- Long-session survivability: automatic post-turn compaction at ~85% context utilization, subtasks with agentic_* tool wrappers that keep bulk tool output out of the parent's context, and task-boundary checkpoints via mark_task_done. See Context management.
**Providers**
- Gemini API (GEMINI_API_KEY / GOOGLE_API_KEY) and Vertex AI (ADC + GOOGLE_CLOUD_PROJECT) with server-side GoogleSearch and URLContext wired up.
- Anthropic Claude via api.anthropic.com (ANTHROPIC_API_KEY) and via Vertex AI (ADC + ANTHROPIC_VERTEX_PROJECT_ID) as a native model.LLM adapter.
- Mock providers for credential-free testing: --provider=echo and --provider=scripted --script=path.jsonl; --record-to=path.jsonl captures any real session for later replay.
- model.builtin_tools gates each provider's server-side built-ins (web_search, url_context, code_execution) under one provider-neutral, tri-state set of names — the defaults differ per provider, so this is what makes an internet-reachability posture survive a provider switch. Distinct from --no-builtin-tools below, which is core-agent's own catalog. The startup summary names the effective set.
**Instructions, tools, MCP, skills**
- AGENTS.md primary + AGENTS.d/*.md overlay directory + @include directive for composable, multi-file system instructions; three scopes (user ~/.core-agent/, user-home ~/.agents/, project) concatenated in order, with CLAUDE.md / GEMINI.md fallbacks.
- Built-in tool catalog covering files (read_file, read_many_files, view_file_outline — a file's declaration skeleton without the bodies, parsed for Go, write_file, edit_file, delete_file, stat, list_dir), search (glob, grep), data + network (json_query, fetch_url), shell (bash), planning (todo, opt-in record_plan), verification (wait_and_verify — bounded, read-only poll-until-condition, no shell required), and interactive prompting (opt-in ask_user). Disable the whole suite with --no-builtin-tools or specific entries with --disable-tools=bash,write_file.
- MCP servers declared in .agents/mcp.json (project) and/or ~/.agents/mcp.json (portable user scope); stdio and Streamable HTTP transports (including remote MCP with Google OAuth); tools are namespaced ( _ ) and route through the permission gate.
- Claude-compatible skills auto-discovered from .agents/skills/ /SKILL.md (project), ~/.agents/skills/ (portable user), and ~/.core-agent/skills/ (legacy user-global fallback). A skill may declare requires: [shell, kubectl, gcloud] in its frontmatter; one whose requirements this runtime can't meet is withheld from the toolset at startup and named on stderr, instead of instructing the model to do something a distroless image cannot do.
**Permissions**
- ask / allow / yolo modes (plus an experimental auto, where an approver model decides some calls before a person is asked) with pattern-based allow/deny lists, path-scope enforcement on file tools, URL-scope allowlist for fetch_url, and a non-overridable bash denylist that catches rm -rf /-class mistakes.
- **Plan-first enforcement** (permissions.plan_mode + record_plan tool + /replan slash): under required, denies mutating tool calls until the model has recorded a plan for the current turn — turns "research → approve → execute" from a prompt convention into a substrate primitive. Under advisory (v2.9+) the plan artifact is still recorded but nothing is blocked, for unattended runs with no operator to approve.