Nexus Engine

Open-source Go runtime for AI agents
One runtime. Any LLM. Any language. Any deployment.

---

Terminal UI

nexus chat drops you into a full-featured terminal interface built for long-running agent sessions.

Welcome — up and running in 10 seconds	Settings panel — every shortcut, one keystroke away (ctrl+p)
Model selection — switch across 20+ models in 2 keystrokes	Provider config — API keys encrypted, scoped per provider
Agent at work — full reasoning trace, thinking blocks + tool calls	Streaming results — streamed responses with markdown + tool timings

Keyboard shortcuts: ctrl+p settings · ctrl+m model · ctrl+s sessions · ctrl+, provider config · ctrl+shift+c copy selection · ctrl+c cancel/quit

Clipboard note (Linux): selection copy works best when wl-clipboard (Wayland) or xclip/xsel (X11) is installed. Without a system clipboard backend, Nexus can request terminal clipboard access but cannot guarantee a real system copy.

Compaction note: transcript compaction is automatic today. A dedicated manual compact action is planned for the TUI once the runtime exposes a real manual-compaction hook.

---

Three ways to use it

1. CLI — nexus

An AI agent in your terminal. Multi-provider, local-first, skills-aware.

Build from source

git clone https://github.com/EngineerProjects/nexus-engine
cd nexus-engine
make build           # produces bin/nexus and bin/nexus-grpc

Add bin/ to your PATH, or copy bin/nexus to /usr/local/bin:

export PATH="$PATH:$(pwd)/bin"
# or
sudo cp bin/nexus /usr/local/bin/nexus

Configure a provider

# Set your API key and default model
nexus config --provider anthropic --api-key sk-ant-...
nexus config --model anthropic:claude-sonnet-4-20250514

# Check current config
nexus config --print

Run

nexus chat                                   # interactive TUI session
nexus run "list all TODO comments in this codebase"  # one-shot task
nexus sessions list                          # browse past sessions
nexus sessions list --status active          # active sessions only
nexus help                                   # full command reference

Sessions are persisted locally in SQLite. Skills are loaded from .nexus/skills/ in your project. The full tool set is available — file edits, sandboxed bash, web search, browser, MCP servers, sub-agents.

---

2. gRPC server

Run nexus-engine as a gRPC service and generate clients for any language.

# Development
ANTHROPIC_API_KEY=sk-ant-... go run ./cmd/grpc

# From build
ANTHROPIC_API_KEY=sk-ant-... ./bin/nexus-grpc

Server starts on :50051. The contract lives in pkg/grpc/proto/nexus.proto. Generate a client for Python, TypeScript, Java, Rust, or any gRPC-supported language:

# Python
python -m grpc_tools.protoc -I pkg/grpc/proto --python_out=. --grpc_python_out=. nexus.proto

# TypeScript
npx grpc-tools --js_out=. --grpc_out=. pkg/grpc/proto/nexus.proto

One runtime. Every language.

---

3. Go SDK

Embed the full runtime in your own Go application.

go get github.com/EngineerProjects/nexus-engine/pkg/sdk

import "github.com/EngineerProjects/nexus-engine/pkg/sdk"

client, err := sdk.NewClient(&sdk.ClientConfig{
    APIKey: os.Getenv("ANTHROPIC_API_KEY"),
    Model:  sdk.ModelIdentifier{Provider: "anthropic", Model: "claude-sonnet-4-20250514"},
})
if err != nil {
    log.Fatal(err)
}
defer client.Close()

session, _ := client.CreateSession(ctx)
resp, _ := session.SubmitMessage(ctx, "Write a Go HTTP handler for /health")
fmt.Println(resp.Content)

---

Capabilities

Capability	Details
Multi-provider	15 providers: Anthropic, OpenAI, Gemini, Mistral, DeepSeek, Ollama, OpenRouter, AWS Bedrock, GCP Vertex, Azure Foundry, Codex, MiniMax, Z.ai, OpenCode, Cloudflare Workers AI
60+ built-in tools	File read/write/patch, bash (Landlock sandbox on Linux), web search, web fetch, browser (Playwright), grep/glob, LSP, sub-agents, RAG, tasks, memory, worktree, notebooks, image generation, TTS/STT
MCP client	Universal MCP client — plug in any MCP server (GitHub, Postgres, Slack, Docker, Notion, …)
Skills	Markdown instruction files injected into the system prompt — encode your team's conventions and domain expertise
Execution modes	execute (default), plan (review before act), pair_programming (collaborative)
Permission engine	Per-tool deny rules, auto-mode LLM classifier, configurable per session (auto / acceptEdits / onRequest / bypass / never)
Session persistence	SQLite-backed multi-turn sessions, resumable across restarts
Streaming	Text chunks + structured runtime events (tool calls, plan events, permission requests, token usage)
Long-context compaction	Automatic context compression when approaching the model's window (configurable threshold)
Observability	Prometheus metrics + OpenTelemetry tracing (OTLP gRPC export, no-op when endpoint not set)

---

Supported providers

Provider ID	Service	Auth
anthropic	Anthropic	ANTHROPIC_API_KEY
openai	OpenAI	OPENAI_API_KEY
gemini	Google Gemini	GOOGLE_API_KEY
mistral	Mistral AI	MISTRAL_API_KEY
deepseek	DeepSeek	DEEPSEEK_API_KEY
ollama	Ollama (local)	none
openrouter	OpenRouter	OPENROUTER_API_KEY
bedrock	AWS Bedrock	AWS_ACCESS_KEY_ID + region
vertex	GCP Vertex AI	ANTHROPIC_VERTEX_PROJECT_ID + region
foundry	Azure AI Foundry	ANTHROPIC_FOUNDRY_API_KEY
codex	ChatGPT Pro (OAuth)	device-code flow
minimax	MiniMax	MINIMAX_API_KEY
z-ai	Z.ai	Z_AI_API_KEY
opencode	OpenCode Zen	OPENCODE_API_KEY
workers-ai	Cloudflare Workers AI	CLOUDFLARE_API_KEY

Full model listings and capabilities: docs/providers.md.

---

Quick start

# 1. Clone and build
git clone https://github.com/EngineerProjects/nexus-engine
cd nexus-engine
make build                    # → bin/nexus  and  bin/nexus-grpc
export PATH="$PATH:$(pwd)/bin"

# 2. Set your API key and model
nexus config --provider anthropic --api-key sk-ant-...
nexus config --model anthropic:claude-sonnet-4-20250514

# 3. Start chatting
nexus chat

# One-shot task in the current directory
nexus run "list all TODO comments in this codebase"

# Start the gRPC server (port 50051)
ANTHROPIC_API_KEY=sk-ant-... ./bin/nexus-grpc

No API key? Use Ollama for free local inference: nexus config --provider ollama --model ollama:llama3.2 (requires Ollama running locally)

---

Skills

Skills are Markdown files that encode expertise injected into the agent's system prompt at runtime.

.nexus/skills/
  go-conventions.md     # "always use context.Context as the first parameter..."
  git-workflow.md       # "never commit to main, always open a PR, squash before merge..."
  security-rules.md     # "never log secrets, validate all external input at boundaries..."

---

MCP

Any MCP server is immediately usable — no additional development needed.

client, _ := sdk.NewClient(&sdk.ClientConfig{
    MCPServers: []sdk.MCPServerConfig{
        {Name: "github",   Command: "npx", Args: []string{"-y", "@modelcontextprotocol/server-github"}},
        {Name: "postgres", Command: "npx", Args: []string{"-y", "@modelcontextprotocol/server-postgres", "postgresql://..."}},
        {Name: "slack",    Command: "npx", Args: []string{"-y", "@modelcontextprotocol/server-slack"}},
    },
})

---

Architecture

Full architecture diagrams (Mermaid): docs/vision/diagrams.md.

---

Building a product on top

nexus-engine is the open-source core runtime — no users, no billing, no access control.

If you need multi-user auth, organizations, workspaces, per-user provider credentials, and a REST/SSE HTTP API, those live in nexus-product — a private product layer built on top of this engine.

---

Documentation

Doc	What it covers
Vision & Roadmap	Project idea, design principles, Level 1→2→3 roadmap
Architecture	System design, layer diagrams, query loop state machine
SDK Guide	ClientConfig, sessions, streaming, callbacks, MCP
Tools	Built-in tools reference, permission pipeline
Providers	Multi-provider routing, retry, circuit breaker
Prompt System	Section assembly, stage overlays, cache control
Skills	Skills system, loading order, injection
Transports & Setup	gRPC setup, proto codegen, env vars
Multi-Agent Teams	Agent profiles, mailbox, dispatcher, TeamBus

---

Development

make build       # build CLI and gRPC binaries → bin/
make test        # run all tests
make test-race   # run tests with race detector
make lint        # golangci-lint
make hooks       # install git pre-commit hooks (run once after cloning)

See CONTRIBUTING.md for the full contribution guide.

---

Security

To report a vulnerability, see SECURITY.md.

---

License

Apache 2.0