README

core/agent

AI agent orchestration platform for the Core ecosystem — dispatch, verify, sync, fleet — with first-class Claude / Codex / Hermes / Google provider integrations.

What it is

A single Go binary that runs as an MCP server (stdio for Claude Code integration, HTTP for cross-agent communication) plus a CLI that dispatches work across multiple AI providers.

The binary ships under two names — core-agent (legacy) and lthn-agent (the lthn-{mlx,cuda,amd,agent} family naming per plans/project/lthn/RFC.system-architecture.md). The binary detects its invocation name from argv[0] and identifies accordingly in version output, banners, and admin token prefixes. Either build name produces the same behaviour; lthn-agent is the forward-going family-consistent name.

It owns:

• Dispatch — fan out a Mantis ticket to a sandboxed worker (Claude / Codex / Hermes / Google) running in .core/workspace/.
• Fleet sync — pull / merge / push across the Core ecosystem repos per agents.yaml.
• OpenBrain — durable memory + cross-agent messaging via Postgres + Qdrant + Ollama (homelab stack).
• Provider integrations — per-provider plugin trees under provider/{claude,codex,hermes,google}/. Claude's tree is the most fleshed out (8 plugins shipped via Claude Code marketplace).

Repository Layout

agent/
├── go/                          Go module — module path: dappco.re/go/agent
│   ├── cmd/core-agent/          Binary entry point (mcp + serve) —
│   │                              builds `core-agent` or `lthn-agent`
│   │                              via `go build -o lthn-agent ./cmd/core-agent/`
│   ├── pkg/agentic/             Dispatch, prep, verify, scan, remote, mirror, plans/phases/sessions
│   ├── pkg/brain/               OpenBrain client (recall, remember, forget, list, messaging)
│   ├── pkg/lemma/               Local lthn-mlx client — chat sessions + /v1/admin control
│   ├── pkg/chathistory/         Per-user portable DuckDB chat archive
│   ├── pkg/monitor/             Background monitor + repo sync
│   ├── pkg/runner/              Local + container runners + dispatch queue
│   ├── pkg/setup/               Project detection + .core/ scaffolding
│   ├── pkg/lib/                 Embedded personas, prompt + flow + workspace templates
│   └── pkg/messages/            Typed IPC message definitions
├── php/                         PHP package — Laravel module + Boot, Actions,
│                                Agentic for the lthn.ai hosted service
├── provider/
│   ├── claude/                  Claude Code plugin sources (marketplace at
│   │   ├── core/                .claude-plugin/marketplace.json)
│   │   ├── core-go/             — 8 plugins: core, core-go, core-php,
│   │   ├── core-php/            devops, infra, research, hermes_runner_mcp,
│   │   ├── devops/              camofox_mcp
│   │   ├── infra/
│   │   ├── research/
│   │   ├── hermes_runner_mcp/
│   │   ├── camofox_mcp/
│   │   └── plugins/             marketplace-flavoured subset
│   ├── codex/                   codex-cli configs + harness
│   ├── hermes/                  Hermes plugin sources + skills
│   └── google/                  Google Gemini integration scaffolding
├── vm/docker/                   Containerised dev stack (Dockerfile + compose)
├── .core/                       Runtime workspace seed (agents.yaml + workspace.yaml)
├── docs/                        RFCs, onboarding, audits
├── go.work + external/          Dev workspace mode (see CLAUDE.md)
├── Taskfile.yaml                Build orchestration (module-graph refresh, etc.)
└── module-graph.json            Authoritative dappco.re/go/* dep snapshot

Quickstart

As a Go module

go get dappco.re/go/agent@latest

As a binary

cd go
go install ./cmd/core-agent/
core-agent mcp        # MCP stdio mode for Claude Code
core-agent serve      # HTTP daemon mode

As a Claude Code plugin marketplace

claude plugin marketplace add https://github.com/dappcore/agent
claude plugin install core-agent

The provider/claude/* tree is the source for the plugins. The .claude-plugin/marketplace.json at repo root publishes them.

Build + Test

cd go
GOWORK=off go test -count=1 ./...
GOWORK=off go vet ./...
golangci-lint run --timeout=5m --tests=false ./...
bash /Users/snider/Code/core/go/tests/cli/v090-upgrade/audit.sh .

Cross-compile for Charon (homelab Linux box):

cd go
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o core-agent-linux ./cmd/core-agent/

module-graph.json at repo root is the authoritative dappco.re/go/* dep snapshot — regenerate via task module-graph:refresh after dep bumps.

Configuration

Runtime config lives at .core/agents.yaml (also extracted into ~/Code/.core/agents.yaml on first run via core-agent setup). Tunes dispatch concurrency, default agent type, container runtime, image, GPU passthrough, and per-provider quotas.

The repo seeds workspace template at .core/workspace.yaml — extracted into per-task workspaces under ~/Code/.core/workspace/<task>/.

CI

• Internal (homelab, full sonar.lthn.sh detail): Woodpecker pipeline defined in .woodpecker.yml.
• Public (badges + mirror analytics): GitHub Actions workflow at .github/workflows/ci.yml — pushes coverage to Codecov + analysis to SonarCloud.

Branch Model

• dev — active development. All Cladius / codex lane work lands here first.
• main — squash-stable. Promoted via the squash-and-push gate on the public mirror only.

Licence

EUPL-1.2 — see LICENCE.

Authorship

Maintained by Cladius (Snider's in-house Opus persona) via the agent/cladius workspace at forge.lthn.sh/agent/cladius. Most substantive commits land via the codex lane pattern documented in factory/. Per-provider integration owners:

• claude/ Cladius
• codex/ Codex (cloud) + Cyclops (lane runner persona)
• hermes/ Hermes (homelab agent at chat.lthn.sh)
• google/ reserved for Gemini integration