Getting started

core-agent ships a CLI (core-agent) that lands you in an in-process Bubble Tea TUI on a TTY, or runs one-shot with -p "…" in a script or CI job. This page gets you from zero to your first turn.

Install

Requires Go 1.26 or newer.

go install github.com/go-steer/core-agent/v2/cmd/core-agent@latest

The binary lands in $(go env GOBIN) (or $GOPATH/bin if GOBIN is unset). Make sure that’s on your $PATH.

Cross-compiled archives for linux/darwin × amd64/arm64 are published on the Releases page, signed via Sigstore keyless.

TAG=$(gh release view --repo go-steer/core-agent --json tagName -q .tagName)
OS=$(uname -s | tr A-Z a-z)
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
gh release download "$TAG" --repo go-steer/core-agent \
  --pattern "core-agent_${TAG#v}_${OS}_${ARCH}.tar.gz"
tar xzf "core-agent_${TAG#v}_${OS}_${ARCH}.tar.gz"
./core-agent --version

See the README’s install section for the image variants (core-agent, core-agent-slim, core-agent-tui) and floating-tag conventions. The k8s-event-watcher sidecar image now ships from go-steer/k8s-lookout.

First run — pick a provider

You need credentials for at least one model backend. Skip the tabs you don’t have keys for.

Get a key at aistudio.google.com.

export GEMINI_API_KEY=...   # or GOOGLE_API_KEY — either works
core-agent -p "what's the capital of France?"

Auto-detection picks the Gemini provider when GEMINI_API_KEY or GOOGLE_API_KEY is set and no other provider is configured.

If you have GCP infrastructure already:

gcloud auth application-default login
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=my-gcp-project
export GOOGLE_CLOUD_LOCATION=us-central1
core-agent -p "what's the capital of France?"

Get a key at console.anthropic.com.

export ANTHROPIC_API_KEY=...
core-agent --provider anthropic --model claude-opus-4-7 \
  -p "what's the capital of France?"

Use existing GCP credentials and billing for Claude:

gcloud auth application-default login
export ANTHROPIC_VERTEX_PROJECT_ID=my-gcp-project
export CLOUD_ML_REGION=us-east5
core-agent --provider anthropic-vertex --model claude-opus-4-7 \
  -p "what's 2+2?"

Multi-turn TUI

Drop the -p flag and core-agent lands in its Bubble Tea TUI (the default when stdin is a real terminal). Conversation history is preserved across turns automatically.

$ core-agent
[Bubble Tea TUI takes over the terminal]
> Remember the number 73.
Got it — I'll remember 73.
> What number did I just give you?
73.
> /quit

The TUI ships a rich slash-command surface — try /help to enumerate the catalog (/stats, /context, /compact, /done, /btw, /tools, /memory, and more).

Layer in a project — the `.agents/` directory

core-agent walks up from the current working directory looking for a folder named .agents/, much like git looks for .git. It’s the project-level home for everything core-agent reads or writes:

your-repo/
├── .agents/
│   ├── config.json          # provider, model, permissions, etc.
│   ├── mcp.json             # MCP server declarations
│   ├── skills/              # SKILL.md bundles
│   │   └── echo/SKILL.md
│   └── sessions/            # one-shot transcripts (auto-written)
└── AGENTS.md                # system prompt prefix (project-scoped)

A minimal config.json:

{
  "version": 1,
  "model": {
    "provider": "anthropic",
    "name": "claude-opus-4-7"
  }
}

core-agent picks up everything in .agents/ automatically — no flags needed.